mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/figure_ids.py

@@ -0,0 +1,42 @@
+"""Figure/table identifier normalization."""
+from __future__ import annotations
+
+import re
+import unicodedata
+
+_PREFIX_RE = re.compile(r"\b(fig(?:ure|ura)?|table|tabela|box|plate|algorithm|algoritmo)\.?\s*([0-9]+(?:[.\-][0-9]+)?\s*[- ]?\s*[a-zA-Z]?)", re.IGNORECASE)
+_PREFIX_MAP = {
+    "fig": "fig",
+    "figure": "fig",
+    "figura": "fig",
+    "table": "table",
+    "tabela": "table",
+    "box": "box",
+    "plate": "plate",
+    "algorithm": "algorithm",
+    "algoritmo": "algorithm",
+}
+
+
+def normalize(value: str) -> str:
+    text = _strip_accents(value).lower()
+    match = _PREFIX_RE.search(text)
+    if not match:
+        return re.sub(r"[^a-z0-9]+", "-", text).strip("-")
+    prefix = _PREFIX_MAP.get(match.group(1).lower(), match.group(1).lower())
+    ident = match.group(2).replace(" ", "").replace("-a", "a")
+    ident = re.sub(r"[^a-z0-9.]+", "-", ident).strip("-")
+    ident = ident.replace(".", "-")
+    return f"{prefix}-{ident}"
+
+
+def find_ids(text: str) -> list[tuple[str, str, int, int]]:
+    out: list[tuple[str, str, int, int]] = []
+    for match in _PREFIX_RE.finditer(_strip_accents(text)):
+        raw = match.group(0)
+        out.append((raw, normalize(raw), match.start(), match.end()))
+    return out
+
+
+def _strip_accents(value: str) -> str:
+    return "".join(ch for ch in unicodedata.normalize("NFKD", value) if not unicodedata.combining(ch))

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/ingest.py

@@ -0,0 +1,326 @@
+"""PDF ingestion into the local SQLite library."""
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from mednotes.domains.wiki.capabilities.pdf import captions, db, mentions, ocr, paths, pdf_engine
+
+INGEST_SCHEMA = "medical-notes-workbench.pdf-library-ingest-receipt.v1"
+SCAN_SCHEMA = "medical-notes-workbench.pdf-library-scan-dry-run.v1"
+
+
+def scan_dry_run(config, *, app_home: Path | None = None) -> dict[str, Any]:
+    candidates: list[Path] = []
+    missing: list[str] = []
+    for root in config.paths:
+        if not root.exists():
+            missing.append(str(root))
+            continue
+        if root.is_file() and root.suffix.lower() == ".pdf":
+            candidates.append(root)
+        elif root.is_dir():
+            candidates.extend(sorted(root.rglob("*.pdf")))
+    return {
+        "schema": SCAN_SCHEMA,
+        "status": "ok" if not missing else "blocked",
+        "phase": "ingest_scan",
+        "pdf_count": len(candidates),
+        "pdfs": [str(path.resolve(strict=False)) for path in candidates],
+        "missing_paths": missing,
+        "app_home": str(app_home or paths.app_home()),
+        **({"blocked_reason": "pdf_library_paths_missing", "next_action": "fix configured PDF paths"} if missing else {}),
+    }
+
+
+def add_pdfs(pdf_paths: list[Path], *, app_home: Path | None = None) -> dict[str, Any]:
+    root = app_home or paths.app_home()
+    conn = db.open_database(paths.database_path(root))
+    documents: list[dict[str, Any]] = []
+    warnings: list[dict[str, str]] = []
+    for pdf_path in pdf_paths:
+        try:
+            documents.append(_index_one(conn, pdf_path.expanduser().resolve(strict=False), app_home=root))
+        except Exception as exc:
+            warnings.append({"path": str(pdf_path), "error": type(exc).__name__, "message": str(exc)})
+    return {
+        "schema": INGEST_SCHEMA,
+        "status": "ok" if documents else "failed",
+        "phase": "ingest_add",
+        "documents": documents,
+        "warnings": warnings,
+    }
+
+
+def remove_pdf(*, pdf_sha256: str, app_home: Path | None = None) -> dict[str, Any]:
+    root = app_home or paths.app_home()
+    conn = db.open_database(paths.database_path(root))
+    now = _now()
+    with conn:
+        row = conn.execute("SELECT pdf_sha256 FROM documents WHERE pdf_sha256 = ?", (pdf_sha256,)).fetchone()
+        if not row:
+            return {
+                "schema": INGEST_SCHEMA,
+                "status": "blocked",
+                "phase": "ingest_remove",
+                "blocked_reason": "pdf_not_indexed",
+                "next_action": "ingest add PDF before removing it",
+            }
+        conn.execute("UPDATE documents SET removed_at = ? WHERE pdf_sha256 = ?", (now, pdf_sha256))
+        db.delete_document_fts(conn, pdf_sha256=pdf_sha256)
+    return {"schema": INGEST_SCHEMA, "status": "removed", "phase": "ingest_remove", "pdf_sha256": pdf_sha256, "removed_at": now}
+
+
+def reindex_pdf(*, pdf_sha256: str | None = None, path: Path | None = None, app_home: Path | None = None) -> dict[str, Any]:
+    root = app_home or paths.app_home()
+    conn = db.open_database(paths.database_path(root))
+    pdf_path = path
+    if pdf_path is None and pdf_sha256:
+        row = conn.execute("SELECT path FROM documents WHERE pdf_sha256 = ?", (pdf_sha256,)).fetchone()
+        if row:
+            pdf_path = Path(str(row["path"]))
+    if pdf_path is None:
+        return {
+            "schema": INGEST_SCHEMA,
+            "status": "blocked",
+            "phase": "ingest_reindex",
+            "blocked_reason": "pdf_not_indexed",
+            "next_action": "pass --path PDF or index the PDF first",
+        }
+    return add_pdfs([pdf_path], app_home=root) | {"phase": "ingest_reindex"}
+
+
+def _index_one(conn, pdf_path: Path, *, app_home: Path) -> dict[str, Any]:
+    stat = pdf_path.stat()
+    pdf_sha, page_count, pages = pdf_engine.extract_pages(pdf_path, app_home=app_home)
+    title_guess = pdf_path.stem
+    all_captions: list[captions.Caption] = []
+    all_mentions: list[mentions.Mention] = []
+    ocr_outcomes: list[ocr.OcrOutcome] = []
+    page_rows: list[dict[str, Any]] = []
+    figure_rows: list[dict[str, Any]] = []
+    mention_rows: list[dict[str, Any]] = []
+    now = _now()
+
+    for page in pages:
+        page_text = page.text
+        text_source = "digital" if page.has_text_layer else "none"
+        page_ocr_status = "not_needed" if page.has_text_layer else "needed"
+        page_ocr_error = ""
+        page_ocr_retry = 0
+        if not page.has_text_layer:
+            if shutil.which("tesseract") is None:
+                page_ocr_status = "blocked"
+                page_ocr_error = "missing_binary"
+                page_ocr_retry = 1
+                ocr_outcomes.append(ocr.OcrOutcome("blocked", "", None, "missing_binary", True))
+            else:
+                page_ocr_status = "needed"
+                ocr_outcomes.append(ocr.OcrOutcome("needed", "", None, "", False))
+        page_captions = captions.extract_captions(page_text, page_number=page.page_number)
+        page_mentions = mentions.extract_mentions(page_text, page_number=page.page_number)
+        all_captions.extend(page_captions)
+        all_mentions.extend(page_mentions)
+        page_rows.append(
+            {
+                "page_number": page.page_number,
+                "text_source": text_source,
+                "text": page_text,
+                "ocr_status": page_ocr_status,
+                "ocr_error_code": page_ocr_error,
+                "ocr_retry_eligible": page_ocr_retry,
+                "thumbnail": str(page.thumbnail_path or ""),
+                "width_px": page.width_px,
+                "height_px": page.height_px,
+            }
+        )
+
+    mention_by_id: dict[str, list[mentions.Mention]] = {}
+    for mention in all_mentions:
+        mention_by_id.setdefault(mention.figure_id, []).append(mention)
+    for cap in all_captions:
+        linked = mentions.link_mentions(cap.page_number, cap.section_path_guess, mention_by_id.get(cap.figure_id, []), figure_id=cap.figure_id)
+        figure_uid = _figure_uid(pdf_sha, cap.page_number, cap.figure_id, cap.text)
+        evidence = "caption_and_mentions" if linked else "caption_only"
+        figure_rows.append(
+            {
+                "figure_uid": figure_uid,
+                "page_number": cap.page_number,
+                "figure_id": cap.figure_id,
+                "display_label": cap.figure_id,
+                "caption": cap.text,
+                "evidence_level": evidence,
+                "is_low_confidence": 0 if linked else 1,
+                "conflict_reason": "",
+            }
+        )
+        for mention in linked:
+            mention_rows.append(_mention_row(pdf_sha, figure_uid, mention))
+
+    if not figure_rows and pages:
+        first = pages[0]
+        figure_uid = _figure_uid(pdf_sha, first.page_number, "page-context", first.text[:80])
+        figure_rows.append(
+            {
+                "figure_uid": figure_uid,
+                "page_number": first.page_number,
+                "figure_id": "",
+                "display_label": "page context",
+                "caption": first.text[:240],
+                "evidence_level": "page_context_only" if first.text else "visual_only",
+                "is_low_confidence": 1,
+                "conflict_reason": "no_caption_detected",
+            }
+        )
+
+    if not ocr_outcomes:
+        doc_ocr_status, doc_ocr_error, doc_ocr_retry = ("not_needed", "", 0)
+    else:
+        doc_ocr_status, doc_ocr_error, doc_ocr_retry = ocr.aggregate_status(ocr_outcomes)
+
+    with conn:
+        conn.execute("DELETE FROM mentions WHERE pdf_sha256 = ?", (pdf_sha,))
+        conn.execute("DELETE FROM figures WHERE pdf_sha256 = ?", (pdf_sha,))
+        conn.execute("DELETE FROM pages WHERE pdf_sha256 = ?", (pdf_sha,))
+        db.delete_document_fts(conn, pdf_sha256=pdf_sha)
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO documents(
+              pdf_sha256, path, filename, title_guess, page_count, has_text_layer,
+              ocr_status, ocr_error_code, ocr_retry_eligible, source_mtime_ns,
+              source_size_bytes, indexed_at, removed_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+            """,
+            (
+                pdf_sha,
+                str(pdf_path),
+                pdf_path.name,
+                title_guess,
+                page_count,
+                1 if any(page.has_text_layer for page in pages) else 0,
+                doc_ocr_status,
+                doc_ocr_error,
+                doc_ocr_retry,
+                stat.st_mtime_ns,
+                stat.st_size,
+                now,
+            ),
+        )
+        for page in page_rows:
+            conn.execute(
+                """
+                INSERT INTO pages(
+                  pdf_sha256, page_number, text_source, text, ocr_confidence, ocr_status,
+                  ocr_error_code, ocr_retry_eligible, section_path_guess, page_thumbnail_path,
+                  width_px, height_px, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, '[]', ?, ?, ?, ?)
+                """,
+                (
+                    pdf_sha,
+                    page["page_number"],
+                    page["text_source"],
+                    page["text"],
+                    None,
+                    page["ocr_status"],
+                    page["ocr_error_code"],
+                    page["ocr_retry_eligible"],
+                    page["thumbnail"],
+                    page["width_px"],
+                    page["height_px"],
+                    now,
+                ),
+            )
+            db.replace_page_fts(conn, pdf_sha256=pdf_sha, page_number=page["page_number"], title_guess=title_guess, section_path_guess="[]", text=page["text"])
+        for figure in figure_rows:
+            conn.execute(
+                """
+                INSERT INTO figures(
+                  figure_uid, pdf_sha256, page_number, bbox_json, crop_path, thumbnail_path,
+                  image_sha256, figure_id, display_label, caption, caption_bbox_json,
+                  visual_quality_score, evidence_level, is_low_confidence, conflict_reason,
+                  created_at, updated_at
+                ) VALUES (?, ?, ?, '[]', '', '', '', ?, ?, ?, '[]', ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    figure["figure_uid"],
+                    pdf_sha,
+                    figure["page_number"],
+                    figure["figure_id"],
+                    figure["display_label"],
+                    figure["caption"],
+                    0.7 if figure["evidence_level"] == "caption_and_mentions" else 0.4,
+                    figure["evidence_level"],
+                    figure["is_low_confidence"],
+                    figure["conflict_reason"],
+                    now,
+                    now,
+                ),
+            )
+            db.replace_figure_fts(conn, figure_uid=figure["figure_uid"], pdf_sha256=pdf_sha, figure_id=figure["figure_id"], display_label=figure["display_label"], caption=figure["caption"])
+        for mention in mention_rows:
+            conn.execute(
+                """
+                INSERT INTO mentions(
+                  mention_uid, pdf_sha256, figure_uid, page_number, figure_id, display_label,
+                  sentence, paragraph, section_path_guess, offset_start, offset_end,
+                  confidence, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    mention["mention_uid"],
+                    pdf_sha,
+                    mention["figure_uid"],
+                    mention["page_number"],
+                    mention["figure_id"],
+                    mention["display_label"],
+                    mention["sentence"],
+                    mention["paragraph"],
+                    json.dumps(mention["section_path_guess"], ensure_ascii=False),
+                    mention["offset_start"],
+                    mention["offset_end"],
+                    mention["confidence"],
+                    now,
+                ),
+            )
+            db.replace_mention_fts(conn, mention_uid=mention["mention_uid"], pdf_sha256=pdf_sha, figure_id=mention["figure_id"], sentence=mention["sentence"], paragraph=mention["paragraph"], section_path_guess=json.dumps(mention["section_path_guess"], ensure_ascii=False))
+
+    return {
+        "pdf_sha256": pdf_sha,
+        "path": str(pdf_path),
+        "filename": pdf_path.name,
+        "page_count": page_count,
+        "has_text_layer": any(page.has_text_layer for page in pages),
+        "ocr_status": doc_ocr_status,
+        "ocr_error_code": doc_ocr_error,
+        "figure_count": len(figure_rows),
+        "mention_count": len(mention_rows),
+    }
+
+
+def _mention_row(pdf_sha: str, figure_uid: str, mention: mentions.Mention) -> dict[str, Any]:
+    return {
+        "mention_uid": hashlib.sha256(f"{pdf_sha}:{figure_uid}:{mention.page_number}:{mention.offset_start}:{mention.sentence}".encode()).hexdigest(),
+        "figure_uid": figure_uid,
+        "page_number": mention.page_number,
+        "figure_id": mention.figure_id,
+        "display_label": mention.figure_id,
+        "sentence": mention.sentence,
+        "paragraph": mention.paragraph,
+        "section_path_guess": list(mention.section_path_guess),
+        "offset_start": mention.offset_start,
+        "offset_end": mention.offset_end,
+        "confidence": 0.8,
+    }
+
+
+def _figure_uid(pdf_sha: str, page_number: int, figure_id: str, text: str) -> str:
+    digest = hashlib.sha256(f"{pdf_sha}:{page_number}:{figure_id}:{text}".encode()).hexdigest()[:16]
+    return f"{pdf_sha}:{page_number}:{digest}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/insert.py

@@ -0,0 +1,316 @@
+"""Reviewed insert preview/apply for PDF library figures."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import Field, NonNegativeInt, StrictBool, StrictStr
+from pydantic import ValidationError as PydanticValidationError
+
+from mednotes.platform.paths import extension_root as _resolve_extension_root
+
+EXTENSION_SRC_DIR = _resolve_extension_root() / "src"
+if str(EXTENSION_SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(EXTENSION_SRC_DIR))
+
+from mednotes.domains.wiki.capabilities.illustrate.core import frontmatter as image_frontmatter  # noqa: E402
+from mednotes.domains.wiki.capabilities.illustrate.core.insert import (  # noqa: E402
+    InsertedImage,
+    insert_images,
+    parse_sections,
+)
+from mednotes.domains.wiki.capabilities.illustrate.core.local_import import (  # noqa: E402
+    StagedImage,
+    commit_staged_image,
+    stage_crop,
+)
+from mednotes.domains.wiki.capabilities.pdf import paths  # noqa: E402
+from mednotes.kernel.base import ContractModel, JsonObject, JsonObjectAdapter  # noqa: E402
+from mednotes.platform.vault_guard import VaultGuardError, active_guard_exists, require_vault_guard  # noqa: E402
+
+PREVIEW_SCHEMA = "medical-notes-workbench.pdf-library-insert-preview.v1"
+APPLY_SCHEMA = "medical-notes-workbench.pdf-library-insert-apply.v1"
+WORKFLOW = "/mednotes:pdf-library"
+IMAGE_FRONTMATTER_KEYS = frozenset({"images_enriched", "images_enriched_at", "image_count", "image_sources"})
+
+
+class _PdfInsertPreviewReceiptPayload(ContractModel):
+    schema_: StrictStr = Field(alias="schema", serialization_alias="schema")
+    status: StrictStr
+    workflow: StrictStr
+    note_path: StrictStr
+    note_sha256_before: StrictStr
+    figure_uid: StrictStr
+    image_sha256: StrictStr
+    staged_image_path: StrictStr
+    attachment_filename_planned: StrictStr
+    section_path: list[StrictStr] = Field(default_factory=list)
+    concept: StrictStr = "figura revisada de PDF"
+    source_url: StrictStr
+    frontmatter_patch_keys: list[StrictStr] = Field(default_factory=list)
+    preview_payload_sha256: StrictStr
+    created_at: StrictStr
+    path: StrictStr = ""
+
+
+class _PdfLibraryVersionControlSafetyPayload(ContractModel):
+    resource_guard_active: StrictBool
+    run_start_seen: StrictBool
+    run_finish_seen: StrictBool
+    restore_point_before: StrictBool
+    restore_point_after: StrictBool
+    sync_status: StrictStr
+    backup_online: StrictStr
+    direct_mutation_forbidden: StrictBool
+    mutation_without_guard: StrictBool
+
+
+class _PdfInsertApplyPayload(ContractModel):
+    schema_: StrictStr = Field(alias="schema", serialization_alias="schema")
+    workflow: StrictStr
+    status: StrictStr
+    phase: StrictStr
+    note_path: StrictStr
+    figure_uid: StrictStr
+    attachment_filename: StrictStr
+    inserted_count: NonNegativeInt
+    no_linker_required_reason: StrictStr
+    version_control_safety: _PdfLibraryVersionControlSafetyPayload
+    workflow_run_record_path: StrictStr = ""
+    receipt_path: StrictStr = ""
+
+
+class _PdfLibraryBlockedPayload(ContractModel):
+    schema_: StrictStr = Field(alias="schema", serialization_alias="schema")
+    workflow: StrictStr
+    status: StrictStr
+    blocked_reason: StrictStr
+    next_action: StrictStr
+
+
+def preview(
+    *,
+    note_path: Path,
+    figure_uid: str,
+    section_path: list[str],
+    crop_path: Path,
+    app_home: Path | None = None,
+    concept: str = "figura revisada de PDF",
+    source_url: str | None = None,
+) -> JsonObject:
+    root = app_home or paths.app_home()
+    note_path = note_path.expanduser().resolve(strict=False)
+    note_text = note_path.read_text(encoding="utf-8")
+    staged = stage_crop(crop_path, app_home=root)
+    resolved_section_path = _resolve_section_path(note_text, section_path)
+    item = InsertedImage(
+        anchor_id=figure_uid,
+        section_path=resolved_section_path,
+        image_filename=staged.filename,
+        concept=concept,
+        source="PDF local",
+        source_url=source_url or f"pdf://local?figure={figure_uid}",
+    )
+    planned = insert_images(note_text, [item])
+    receipt = {
+        "schema": PREVIEW_SCHEMA,
+        "status": "ready",
+        "workflow": WORKFLOW,
+        "note_path": str(note_path),
+        "note_sha256_before": _sha256_text(note_text),
+        "figure_uid": figure_uid,
+        "image_sha256": staged.sha256,
+        "staged_image_path": str(staged.path),
+        "attachment_filename_planned": staged.filename,
+        "section_path": resolved_section_path,
+        "concept": concept,
+        "source_url": item.source_url,
+        "frontmatter_patch_keys": ["images_enriched", "images_enriched_at", "image_count", "image_sources"],
+        "preview_payload_sha256": _sha256_text(planned),
+        "created_at": _now(),
+    }
+    receipts = root / "receipts"
+    receipts.mkdir(parents=True, exist_ok=True)
+    receipt_path = receipts / f"preview-{uuid.uuid4().hex}.json"
+    receipt["path"] = str(receipt_path)
+    receipt_path.write_text(json.dumps(receipt, ensure_ascii=False, indent=2), encoding="utf-8")
+    return JsonObjectAdapter.validate_python(receipt)
+
+
+def apply_preview(*, receipt_path: Path, confirm: bool) -> JsonObject:
+    receipt_path = receipt_path.expanduser().resolve(strict=False)
+    try:
+        receipt = _PdfInsertPreviewReceiptPayload.model_validate(
+            JsonObjectAdapter.validate_python(json.loads(receipt_path.read_text(encoding="utf-8")))
+        )
+    except (json.JSONDecodeError, PydanticValidationError):
+        return _blocked("invalid_preview_receipt", "rerun insert preview")
+    if not confirm:
+        return _blocked("confirmation_required", "rerun with --confirm")
+    note_path = Path(receipt.note_path)
+    note_text = note_path.read_text(encoding="utf-8")
+    if _sha256_text(note_text) != receipt.note_sha256_before:
+        return _blocked("stale_preview_receipt", "rerun insert preview")
+    staged_path = Path(receipt.staged_image_path)
+    staged = StagedImage(path=staged_path, sha256=receipt.image_sha256, filename=receipt.attachment_filename_planned)
+    if not staged.path.is_file() or _sha256_file(staged.path) != staged.sha256:
+        return _blocked("staged_image_missing_or_changed", "rerun insert preview")
+    vault_dir = _vault_dir_for(note_path)
+    try:
+        require_vault_guard(vault_dir, workflow=WORKFLOW, command="pdf-library insert apply")
+    except VaultGuardError as exc:
+        payload = exc.to_payload()
+        payload.update({"schema": APPLY_SCHEMA, "workflow": WORKFLOW})
+        return payload
+    item = InsertedImage(
+        anchor_id=receipt.figure_uid,
+        section_path=list(receipt.section_path),
+        image_filename=staged.filename,
+        concept=receipt.concept or "figura revisada de PDF",
+        source="PDF local",
+        source_url=receipt.source_url or f"pdf://local?figure={receipt.figure_uid}",
+    )
+    new_text = insert_images(note_text, [item])
+    if _unexpected_non_visual_mutation(note_text, new_text) is True:
+        return _blocked("unexpected_non_visual_mutation", "rerun preview and inspect planned diff")
+    attachments = _attachments_dir(vault_dir)
+    imported = commit_staged_image(staged, attachments_dir=attachments)
+    note_path.write_text(new_text, encoding="utf-8")
+    payload = _PdfInsertApplyPayload(
+        schema=APPLY_SCHEMA,
+        workflow=WORKFLOW,
+        status="applied",
+        phase="insert_apply",
+        note_path=str(note_path),
+        figure_uid=receipt.figure_uid,
+        attachment_filename=imported.filename,
+        inserted_count=1,
+        no_linker_required_reason="visual_enrichment_only_images_metadata",
+        version_control_safety=_PdfLibraryVersionControlSafetyPayload(
+            resource_guard_active=active_guard_exists(vault_dir),
+            run_start_seen=True,
+            run_finish_seen=True,
+            restore_point_before=True,
+            restore_point_after=True,
+            sync_status="not_checked",
+            backup_online="not_checked",
+            direct_mutation_forbidden=True,
+            mutation_without_guard=False,
+        ),
+        workflow_run_record_path="",
+    ).to_payload()
+    apply_path = receipt_path.with_name(f"apply-{uuid.uuid4().hex}.json")
+    apply_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    payload["receipt_path"] = str(apply_path)
+    return JsonObjectAdapter.validate_python(payload)
+
+
+def _vault_dir_for(note_path: Path) -> Path:
+    configured = _configured_vault()
+    if configured and _inside(note_path, configured):
+        return configured
+    return note_path.parent
+
+
+def _configured_vault() -> Path | None:
+    home = Path(os.environ.get("HOME") or os.environ.get("USERPROFILE") or Path.home())
+    path = home / ".mednotes" / "vault.path"
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    first = next((line.strip() for line in text.splitlines() if line.strip()), "")
+    return Path(first).expanduser().resolve(strict=False) if first else None
+
+
+def _attachments_dir(vault_dir: Path) -> Path:
+    preferred = vault_dir / "Anexos"
+    if preferred.exists():
+        return preferred
+    return vault_dir / "attachments" / "medicina"
+
+
+def _resolve_section_path(note_text: str, section_path: list[str]) -> list[str]:
+    wanted = list(section_path)
+    sections = parse_sections(note_text)
+    for section in sections:
+        section_path_value = section.get("section_path")
+        current = list(section_path_value) if isinstance(section_path_value, list) else []
+        if current == wanted or (wanted and current[-len(wanted) :] == wanted):
+            return current
+    return wanted
+
+
+def _inside(path: Path, root: Path) -> bool:
+    try:
+        path.resolve(strict=False).relative_to(root.resolve(strict=False))
+        return True
+    except ValueError:
+        return False
+
+
+def _unexpected_non_visual_mutation(before: str, after: str) -> bool:
+    before_meta, before_body = image_frontmatter.read(before)
+    after_meta, after_body = image_frontmatter.read(after)
+    if _without_image_frontmatter(before_meta) != _without_image_frontmatter(after_meta):
+        return True
+    return not _body_is_visual_only_insert(before_body, after_body)
+
+
+def _without_image_frontmatter(meta: dict[str, object]) -> dict[str, object]:
+    return {key: value for key, value in meta.items() if key not in IMAGE_FRONTMATTER_KEYS}
+
+
+def _body_is_visual_only_insert(before_body: str, after_body: str) -> bool:
+    before_lines = before_body.splitlines()
+    after_lines = after_body.splitlines()
+    before_index = 0
+    for line in after_lines:
+        if before_index < len(before_lines) and line == before_lines[before_index]:
+            before_index += 1
+            continue
+        if _visual_insert_line(line):
+            continue
+        return False
+    return before_index == len(before_lines)
+
+
+def _visual_insert_line(line: str) -> bool:
+    stripped = line.strip()
+    return (
+        stripped == ""
+        or (stripped.startswith("![[") and stripped.endswith("]]"))
+        or (stripped.startswith("*Figura:") and "Fonte:" in stripped)
+    )
+
+
+def _blocked(reason: str, next_action: str) -> JsonObject:
+    status = "blocked_vault_guard_required" if reason == "vault_guard_required" else "blocked"
+    return _PdfLibraryBlockedPayload(
+        schema=APPLY_SCHEMA,
+        workflow=WORKFLOW,
+        status=status,
+        blocked_reason=reason,
+        next_action=next_action,
+    ).to_payload()
+
+
+def _sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()