ltcai 3.5.0 → 3.6.0

package/latticeai/api/browser.py

@@ -0,0 +1,217 @@
+"""Browser & web ingestion — Knowledge Graph inputs, not standalone features.
+
+v3.6.0 Knowledge Graph First: a public URL or an open browser tab is just another
+source that converges into the Knowledge Graph through the unified ingestion
+pipeline. Everything runs on the **local runtime** — the server fetches/reads
+locally, stores into local SQLite, and never uploads to a cloud service.
+
+Two layers, both feeding ``IngestionPipeline.ingest``:
+
+* ``POST /api/browser/read-url`` — the runtime fetches a public URL locally,
+  extracts readable text, stores it as ``source_type=web_url``. Fails gracefully
+  on blocked / login-required pages.
+* ``POST /api/browser/ingest-current-tab`` — accepts a payload from the local
+  browser extension (url/title/text/selected_text/html), sanitizes + size-limits
+  it, stores it as ``source_type=browser_tab``.
+"""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+from typing import Any, Callable, Optional, Tuple
+from urllib.parse import urlparse
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from latticeai.services.ingestion import IngestionItem
+
+MAX_TAB_BYTES = 4 * 1024 * 1024          # 4 MB per captured tab payload
+MAX_URL_FETCH_BYTES = 4 * 1024 * 1024    # 4 MB cap on a fetched page
+URL_FETCH_TIMEOUT = 12.0                  # seconds
+
+
+class BrowserFetchError(Exception):
+    """A URL could not be fetched (blocked, login-required, timeout, too big)."""
+
+
+# ── readable-text extraction ─────────────────────────────────────────────────
+_SKIP_TAGS = {"script", "style", "noscript", "template", "svg", "head"}
+
+
+class _TextExtractor(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._skip_depth = 0
+        self._chunks: list[str] = []
+        self.title: str = ""
+        self._in_title = False
+
+    def handle_starttag(self, tag, attrs):
+        if tag in _SKIP_TAGS:
+            self._skip_depth += 1
+        if tag == "title":
+            self._in_title = True
+
+    def handle_endtag(self, tag):
+        if tag in _SKIP_TAGS and self._skip_depth > 0:
+            self._skip_depth -= 1
+        if tag == "title":
+            self._in_title = False
+        if tag in {"p", "div", "br", "li", "h1", "h2", "h3", "h4", "section", "article"}:
+            self._chunks.append("\n")
+
+    def handle_data(self, data):
+        if self._in_title:
+            self.title += data
+        if self._skip_depth == 0:
+            text = data.strip()
+            if text:
+                self._chunks.append(text)
+
+    def text(self) -> str:
+        raw = " ".join(self._chunks)
+        # collapse runs of whitespace while keeping paragraph breaks
+        lines = [ln.strip() for ln in raw.replace("\r", "").split("\n")]
+        return "\n".join([ln for ln in lines if ln]).strip()
+
+
+def extract_readable_text(html: str) -> Tuple[str, str]:
+    """Return (title, readable_text) from an HTML string. Never raises."""
+    parser = _TextExtractor()
+    try:
+        parser.feed(html or "")
+    except Exception:  # noqa: BLE001 — malformed HTML must still yield best-effort text
+        pass
+    return parser.title.strip(), parser.text()
+
+
+def _default_fetch_url(url: str) -> Tuple[str, str]:
+    """Fetch a public URL on the local runtime and extract readable text.
+
+    Raises :class:`BrowserFetchError` on any non-success (blocked, login wall,
+    timeout, oversized, non-HTML) so the route can fail gracefully.
+    """
+    import httpx
+
+    try:
+        with httpx.Client(
+            follow_redirects=True, timeout=URL_FETCH_TIMEOUT,
+            headers={"User-Agent": "LatticeAI-local/3.6 (+local-first knowledge graph)"},
+        ) as client:
+            resp = client.get(url)
+    except httpx.HTTPError as exc:
+        raise BrowserFetchError(f"Could not reach the page: {exc}") from exc
+
+    if resp.status_code in (401, 403):
+        raise BrowserFetchError("The page is login-required or blocked (HTTP %s)." % resp.status_code)
+    if resp.status_code >= 400:
+        raise BrowserFetchError(f"The page returned HTTP {resp.status_code}.")
+    content_type = resp.headers.get("content-type", "")
+    if content_type and "html" not in content_type and "text" not in content_type:
+        raise BrowserFetchError(f"Unsupported content type: {content_type or 'unknown'}.")
+    body = resp.text or ""
+    if len(body.encode("utf-8", "ignore")) > MAX_URL_FETCH_BYTES:
+        body = body.encode("utf-8", "ignore")[:MAX_URL_FETCH_BYTES].decode("utf-8", "ignore")
+    title, text = extract_readable_text(body)
+    return (title or url, text)
+
+
+def _validate_http_url(url: str) -> str:
+    url = (url or "").strip()
+    if not url:
+        raise HTTPException(status_code=400, detail="url is required.")
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise HTTPException(status_code=400, detail="Only http(s) URLs are supported.")
+    if not parsed.netloc:
+        raise HTTPException(status_code=400, detail="Malformed URL.")
+    return url
+
+
+# ── request models ───────────────────────────────────────────────────────────
+class ReadUrlRequest(BaseModel):
+    url: str
+    workspace_id: Optional[str] = None
+
+
+class IngestTabRequest(BaseModel):
+    url: str
+    title: Optional[str] = None
+    text: Optional[str] = None
+    selected_text: Optional[str] = None
+    html: Optional[str] = None
+    captured_at: Optional[str] = None
+    workspace_id: Optional[str] = None
+
+
+def create_browser_router(
+    *,
+    pipeline: Any,
+    require_user: Callable[[Request], str],
+    fetch_url: Optional[Callable[[str], Tuple[str, str]]] = None,
+    max_tab_bytes: int = MAX_TAB_BYTES,
+) -> APIRouter:
+    router = APIRouter()
+    _fetch = fetch_url or _default_fetch_url
+
+    def _require_pipeline():
+        if pipeline is None or not pipeline.available():
+            raise HTTPException(status_code=503, detail="Knowledge Graph ingestion is disabled.")
+
+    @router.post("/api/browser/read-url")
+    async def read_url(req: ReadUrlRequest, request: Request):
+        """Fetch a public URL locally and ingest it as a web_url source."""
+        user = require_user(request)
+        _require_pipeline()
+        url = _validate_http_url(req.url)
+        try:
+            title, text = _fetch(url)
+        except BrowserFetchError as exc:
+            # Graceful failure — not a 5xx; the page was simply unreadable.
+            raise HTTPException(status_code=422, detail=str(exc))
+        if not (text or "").strip():
+            return {"status": "empty", "source_type": "web_url", "url": url,
+                    "detail": "No readable text was extracted from the page."}
+        res = pipeline.ingest(
+            IngestionItem(
+                source_type="web_url", title=title, text=text, source_uri=url,
+                owner=user, workspace_id=req.workspace_id,
+            ),
+            user_email=user,
+        )
+        return res.as_dict()
+
+    @router.post("/api/browser/ingest-current-tab")
+    async def ingest_current_tab(req: IngestTabRequest, request: Request):
+        """Ingest a payload captured from the local browser extension."""
+        user = require_user(request)
+        _require_pipeline()
+        url = _validate_http_url(req.url)
+        # Sanitize: reject an oversized payload before doing any work.
+        for value in (req.text, req.html, req.selected_text):
+            if value and len(value.encode("utf-8", "ignore")) > max_tab_bytes:
+                raise HTTPException(status_code=413, detail="Captured payload is too large.")
+        text = (req.text or "").strip()
+        if not text and req.html:
+            _title, text = extract_readable_text(req.html)
+        if not text:
+            text = (req.selected_text or "").strip()
+        if not text:
+            raise HTTPException(status_code=400, detail="No text, html, or selected_text provided.")
+        res = pipeline.ingest(
+            IngestionItem(
+                source_type="browser_tab",
+                title=req.title or url,
+                text=text,
+                source_uri=url,
+                captured_at=req.captured_at,
+                owner=user,
+                workspace_id=req.workspace_id,
+                metadata={"has_selection": bool(req.selected_text)},
+            ),
+            user_email=user,
+        )
+        return res.as_dict()
+
+    return router

package/latticeai/api/portability.py

@@ -0,0 +1,93 @@
+"""Knowledge Graph portability routes — local export / import / backup / restore.
+
+Reads (export, status) require a signed-in user. Mutating operations (import,
+backup, restore, file export) require admin because the graph is machine-global,
+not workspace-scoped. Nothing here touches a cloud service.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+
+class ImportRequest(BaseModel):
+    artifact: dict
+    mode: str = "merge"
+    dry_run: bool = False
+
+
+class BackupRequest(BaseModel):
+    path: Optional[str] = None
+
+
+class RestoreRequest(BaseModel):
+    path: str
+    verify: bool = True
+
+
+def create_portability_router(
+    *,
+    service: Any,
+    require_user: Callable[[Request], str],
+    require_admin: Callable[[Request], Any],
+) -> APIRouter:
+    router = APIRouter()
+
+    def _require_service():
+        if service is None or not service.available():
+            raise HTTPException(status_code=503, detail="Knowledge Graph is disabled.")
+
+    @router.get("/api/knowledge-graph/portability")
+    async def portability_status(request: Request):
+        require_user(request)
+        _require_service()
+        return service.snapshot_metadata()
+
+    @router.get("/api/knowledge-graph/provenance")
+    async def recent_provenance(request: Request, limit: int = 50, source_type: Optional[str] = None):
+        """Recent ingestions (provenance trail) for the ingestion-sources UI."""
+        require_user(request)
+        _require_service()
+        return service.recent_ingestions(limit=limit, source_type=source_type)
+
+    @router.post("/api/knowledge-graph/export")
+    async def export_graph(request: Request):
+        """Logical JSON export of the whole graph (read-only)."""
+        require_user(request)
+        _require_service()
+        return service.export()
+
+    @router.post("/api/knowledge-graph/export-file")
+    async def export_graph_file(request: Request):
+        require_admin(request)
+        _require_service()
+        return service.export_to_file()
+
+    @router.post("/api/knowledge-graph/import")
+    async def import_graph(req: ImportRequest, request: Request):
+        require_admin(request)
+        _require_service()
+        try:
+            return service.import_data(req.artifact, mode=req.mode, dry_run=req.dry_run)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc))
+
+    @router.post("/api/knowledge-graph/backup")
+    async def backup_graph(req: BackupRequest, request: Request):
+        require_admin(request)
+        _require_service()
+        return service.backup(req.path)
+
+    @router.post("/api/knowledge-graph/restore")
+    async def restore_graph(req: RestoreRequest, request: Request):
+        require_admin(request)
+        _require_service()
+        try:
+            return service.restore(req.path, verify=req.verify)
+        except (ValueError, FileNotFoundError) as exc:
+            raise HTTPException(status_code=400, detail=str(exc))
+
+    return router

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "3.5.0"
+MARKETPLACE_VERSION = "3.6.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent")
 
 

package/latticeai/core/multi_agent.py

@@ -14,7 +14,7 @@ from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
 
-MULTI_AGENT_VERSION = "3.5.0"
+MULTI_AGENT_VERSION = "3.6.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/core/workspace_os.py

@@ -18,7 +18,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "3.5.0"
+WORKSPACE_OS_VERSION = "3.6.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/server_app.py

@@ -120,7 +120,11 @@ from latticeai.core.builtin_hooks import register_builtin_hook_runners
 from latticeai.api.agent_registry import create_agent_registry_router
 from latticeai.core.agent_registry import AgentRegistry
 from latticeai.api.memory import create_memory_router
+from latticeai.api.browser import create_browser_router
+from latticeai.api.portability import create_portability_router
 from latticeai.services.memory_service import MemoryService
+from latticeai.services.ingestion import IngestionPipeline
+from latticeai.services.kg_portability import KGPortabilityService
 from latticeai.services.tool_dispatch import (
     LOCAL_WRITE_BLOCKED_PREFIXES as _LOCAL_WRITE_BLOCKED_PREFIXES,
     TOOL_GOVERNANCE,
@@ -322,6 +326,23 @@ MEMORY_SERVICE = MemoryService(
     enable_graph=ENABLE_GRAPH,
     history_file=HISTORY_FILE,
 )
+# ── v3.6.0 unified ingestion pipeline: the single write-side seam into the
+# Knowledge Graph. Every new source (web URL, browser tab, …) flows through this
+# so pre_tool/post_tool hooks fire on ingestion and provenance is captured
+# uniformly. Existing direct ingest callers keep working; new paths converge here.
+INGESTION_PIPELINE = IngestionPipeline(
+    KNOWLEDGE_GRAPH,
+    hooks=HOOKS_REGISTRY,
+    enable_graph=ENABLE_GRAPH,
+    audit=lambda action, detail, user: append_audit_event(action, user_email=user, **detail),
+)
+# ── v3.6.0 Knowledge Graph portability: local export / import / backup / restore.
+# The graph is the user's durable asset, so it must be portable with no cloud.
+KG_PORTABILITY = KGPortabilityService(
+    knowledge_graph=KNOWLEDGE_GRAPH,
+    data_dir=DATA_DIR,
+    enable_graph=ENABLE_GRAPH,
+)
 
 def _require_graph():
     if not ENABLE_GRAPH or KNOWLEDGE_GRAPH is None:
@@ -1508,6 +1529,17 @@ app.include_router(create_memory_router(
     append_audit_event=append_audit_event,
 ))
 
+app.include_router(create_browser_router(
+    pipeline=INGESTION_PIPELINE,
+    require_user=require_user,
+))
+
+app.include_router(create_portability_router(
+    service=KG_PORTABILITY,
+    require_user=require_user,
+    require_admin=require_admin,
+))
+
 app.include_router(create_garden_router(gardener=gardener, require_user=require_user))
 app.include_router(create_setup_router(model_router=router, require_user=require_user))
 

package/latticeai/services/ingestion.py

@@ -0,0 +1,271 @@
+"""Unified ingestion pipeline — the single write-side seam into the Knowledge Graph.
+
+v3.6.0 Knowledge Graph First principle: *no data source bypasses the Knowledge
+Graph and no source creates an isolated silo*. Every source — local files,
+connected folders, PDFs/Markdown/text/code, web URLs, browser tabs — is
+normalized into one :class:`IngestionItem` and pushed through one
+:meth:`IngestionPipeline.ingest` entrypoint:
+
+    Source → normalize → content hash → (file | text) ingest → provenance
+
+The pipeline is deliberately thin. It owns normalization, idempotency reporting,
+provenance capture, and — crucially — routing every ingest through the shared
+``dispatch_tool`` lifecycle so ``pre_tool``/``post_tool`` hooks fire on data
+ingestion exactly as they do on tool calls. The heavy graph construction lives in
+:class:`knowledge_graph.KnowledgeGraphStore` (``ingest_document`` for files,
+``ingest_source`` for text/web), which this module composes rather than
+re-implements.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.hooks import dispatch_tool
+
+# Source types that arrive as a file on disk (read via ingest_document).
+FILE_SOURCE_TYPES = frozenset({"file", "local_file", "upload", "pdf"})
+# Source types that arrive as extracted text (read via ingest_source).
+TEXT_SOURCE_TYPES = frozenset(
+    {"web_url", "browser_tab", "text", "markdown", "note", "code", "clipboard"}
+)
+
+DEFAULT_MAX_TEXT_BYTES = 5 * 1024 * 1024  # 5 MB of extracted text per item
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class IngestionItem:
+    """A single thing to ingest, normalized across every source type."""
+
+    source_type: str
+    title: Optional[str] = None
+    text: Optional[str] = None          # text/web sources
+    path: Optional[str] = None          # file sources
+    source_uri: Optional[str] = None
+    mime_type: Optional[str] = None
+    owner: Optional[str] = None
+    workspace_id: Optional[str] = None
+    permissions: Optional[Dict[str, Any]] = None
+    captured_at: Optional[str] = None
+    modified_at: Optional[str] = None
+    conversation_id: Optional[str] = None
+    agent_used: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class IngestionResult:
+    """The outcome of one ingestion, including provenance and idempotency."""
+
+    status: str                         # ok | unavailable | blocked | failed
+    source_type: str
+    node_id: Optional[str] = None
+    source_node_id: Optional[str] = None
+    content_hash: Optional[str] = None
+    title: Optional[str] = None
+    chunk_ids: List[str] = field(default_factory=list)
+    chunk_count: int = 0
+    duplicate: bool = False
+    embedded: bool = False
+    indexing_status: str = "pending"    # indexed | skipped | failed | pending
+    provenance_id: Optional[str] = None
+    detail: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "status": self.status,
+            "source_type": self.source_type,
+            "node_id": self.node_id,
+            "source_node_id": self.source_node_id,
+            "content_hash": self.content_hash,
+            "title": self.title,
+            "chunk_ids": self.chunk_ids,
+            "chunk_count": self.chunk_count,
+            "duplicate": self.duplicate,
+            "embedded": self.embedded,
+            "indexing_status": self.indexing_status,
+            "provenance_id": self.provenance_id,
+            "detail": self.detail,
+        }
+
+
+class IngestionPipeline:
+    """Single normalized entrypoint that feeds every source into the graph."""
+
+    def __init__(
+        self,
+        knowledge_graph: Any,
+        *,
+        hooks: Any = None,
+        enable_graph: bool = True,
+        audit: Optional[Any] = None,
+        max_text_bytes: int = DEFAULT_MAX_TEXT_BYTES,
+        pipeline_name: str = "unified-ingestion",
+    ) -> None:
+        self._kg = knowledge_graph
+        self._hooks = hooks
+        self._enable = bool(enable_graph)
+        self._audit = audit
+        self._max_text_bytes = int(max_text_bytes)
+        self._pipeline_name = pipeline_name
+
+    def available(self) -> bool:
+        return self._enable and self._kg is not None
+
+    # ── public API ───────────────────────────────────────────────────────────
+    def ingest(self, item: IngestionItem, *, user_email: Optional[str] = None) -> IngestionResult:
+        """Normalize, hash, route through dispatch_tool, and record provenance."""
+        source_type = str(item.source_type or "text").strip()
+        if not self.available():
+            return IngestionResult(
+                status="unavailable", source_type=source_type,
+                indexing_status="skipped",
+                detail="Knowledge Graph is disabled (LATTICEAI_ENABLE_GRAPH).",
+            )
+
+        captured_at = item.captured_at or _now_iso()
+        owner = item.owner or user_email
+        tool_name = f"kg_ingest.{source_type}"
+        # Only the keys are read by the hook payload, so this dict is safe/cheap.
+        args = {
+            "source_type": source_type,
+            "source_uri": item.source_uri,
+            "owner": owner,
+            "workspace_id": item.workspace_id,
+        }
+
+        def _run() -> Dict[str, Any]:
+            if source_type in FILE_SOURCE_TYPES or (item.path and not item.text):
+                return self._ingest_file(item, source_type=source_type, owner=owner, captured_at=captured_at)
+            return self._ingest_text(item, source_type=source_type, owner=owner, captured_at=captured_at)
+
+        try:
+            raw = dispatch_tool(
+                self._hooks, tool_name, args, _run,
+                user_email=user_email, workspace_id=item.workspace_id, source="ingestion",
+            )
+        except PermissionError as exc:
+            return IngestionResult(
+                status="blocked", source_type=source_type,
+                indexing_status="skipped", detail=str(exc),
+            )
+        except FileNotFoundError as exc:
+            return IngestionResult(
+                status="failed", source_type=source_type,
+                indexing_status="failed", detail=str(exc),
+            )
+        except Exception as exc:  # noqa: BLE001 — surface as a failed result, never crash the caller
+            return IngestionResult(
+                status="failed", source_type=source_type,
+                indexing_status="failed", detail=str(exc),
+            )
+
+        node_id = raw.get("node_id")
+        content_hash = raw.get("content_hash") or raw.get("sha256")
+        chunk_ids = list(raw.get("chunk_ids") or [])
+        embedded = bool(self._kg.node_is_embedded(node_id)) if node_id else False
+        title = raw.get("title") or item.title
+
+        prov = self._kg.record_provenance(
+            node_id=node_id,
+            source_type=source_type,
+            pipeline=self._pipeline_name,
+            source_uri=item.source_uri,
+            content_hash=content_hash,
+            title=title,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            embedded=embedded,
+            linked=bool(raw.get("source_node_id")),
+            duplicate=bool(raw.get("duplicate")),
+            agent_used=item.agent_used,
+            chunk_count=len(chunk_ids),
+            permissions=item.permissions,
+            metadata=item.metadata,
+        )
+        if self._audit is not None:
+            try:
+                self._audit(
+                    "kg_ingest",
+                    {
+                        "source_type": source_type, "node_id": node_id,
+                        "content_hash": content_hash, "duplicate": bool(raw.get("duplicate")),
+                    },
+                    user_email,
+                )
+            except Exception:  # noqa: BLE001 — audit must never break ingestion
+                pass
+
+        return IngestionResult(
+            status="ok",
+            source_type=source_type,
+            node_id=node_id,
+            source_node_id=raw.get("source_node_id"),
+            content_hash=content_hash,
+            title=title,
+            chunk_ids=chunk_ids,
+            chunk_count=len(chunk_ids),
+            duplicate=bool(raw.get("duplicate")),
+            embedded=embedded,
+            indexing_status="indexed",
+            provenance_id=prov.get("id"),
+        )
+
+    # ── routing helpers ──────────────────────────────────────────────────────
+    def _ingest_text(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        text = item.text or ""
+        if len(text.encode("utf-8", "ignore")) > self._max_text_bytes:
+            raise ValueError(
+                f"Text payload exceeds the {self._max_text_bytes // (1024 * 1024)}MB ingestion limit."
+            )
+        title = item.title or item.source_uri or source_type
+        return self._kg.ingest_source(
+            source_type=source_type,
+            title=title,
+            text=text,
+            source_uri=item.source_uri,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            conversation_id=item.conversation_id,
+            metadata={"mime_type": item.mime_type, **(item.metadata or {})},
+        )
+
+    def _ingest_file(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        if not item.path:
+            raise ValueError("File ingestion requires a path.")
+        path = Path(item.path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        return self._kg.ingest_document(
+            path,
+            original_filename=item.title or path.name,
+            mime_type=item.mime_type,
+            uploader=owner,
+            conversation_id=item.conversation_id,
+            extracted=item.metadata.get("extracted") if item.metadata else None,
+            source_type=source_type,
+            source_uri=item.source_uri or str(path),
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+        )
+
+
+def content_hash_text(text: str) -> str:
+    """Canonical content hash for a text payload (matches store hashing scheme)."""
+    return hashlib.sha256((text or "").encode("utf-8", "ignore")).hexdigest()