ltcai 11.2.0 → 11.4.0

package/lattice_brain/graph/retrieval_vector/status.py

@@ -0,0 +1,374 @@
+"""What the vector index currently knows, and what it still owes.
+
+``index_status`` / ``vector_freshness`` / ``vector_queue`` — the honesty
+surface that reports coverage, staleness, and pending work rather than
+letting a half-built index look complete. Moved verbatim out of
+``retrieval_vector.py`` (v11.3.0 decomposition).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# ruff: noqa: F403,F405
+from .._kg_common import *  # noqa: F403,F401
+from ..vector_index import VectorEmbedQueue
+
+# Typing-only base (runtime value is `object`, so the store's MRO is
+# unchanged). Reporting on the index means asking the halves that build and
+# query it — source items and incremental indexing from .indexing, the
+# fingerprint it reaches through, and the backend selection from .search. They
+# are named as bases rather than re-declared, so the signatures cannot drift.
+if TYPE_CHECKING:
+    from .indexing import _VectorIndexingMixin
+    from .search import _VectorSearchMixin
+
+    class _Core(_VectorIndexingMixin, _VectorSearchMixin):
+        """The sibling halves this one reaches through ``self``."""
+else:
+    _Core = object
+
+
+class _VectorStatusMixin(_Core):
+    """Vector index status/freshness. Composed into the public mixin."""
+
+    def index_status(self) -> Dict[str, Any]:
+        storage_capabilities = None
+        try:
+            storage_capabilities = self.storage_engine.capabilities().as_dict()
+        except Exception as exc:
+            storage_capabilities = {
+                "engine": "sqlite",
+                "available": False,
+                "reason": str(exc),
+            }
+        with self._connect() as conn:
+            vector_counts = {
+                row["item_type"]: row["count"]
+                for row in conn.execute(
+                    "SELECT item_type, COUNT(*) AS count FROM vector_embeddings GROUP BY item_type"
+                )
+            }
+            # Materialised on purpose, unlike the rebuild path: status walks
+            # this set twice (once for ids, once to classify each item) and
+            # reports a count, none of which a one-shot iterator can serve.
+            source_items = list(self._iter_vector_source_items(conn))
+            vector_rows = {
+                row["item_id"]: row
+                for row in conn.execute(
+                    """
+                        SELECT item_id, text_hash, embedding_dim, embedding_model, indexed_at
+                        FROM vector_embeddings
+                        """
+                ).fetchall()
+            }
+            latest_rows = conn.execute(
+                """
+                    SELECT id, operation, status, requested_at, started_at, completed_at,
+                           items_total, items_indexed, items_skipped, error_message, metadata_json
+                    FROM vector_index_operations
+                    ORDER BY requested_at DESC, id DESC
+                    LIMIT 5
+                    """
+            ).fetchall()
+        missing = stale = ready = 0
+        source_item_ids = {str(item["item_id"]) for item in source_items}
+        backlog_by_type: Dict[str, int] = {}
+        backlog_reasons: Dict[str, int] = {}
+        backlog_samples: List[Dict[str, Any]] = []
+
+        def add_backlog(item: Dict[str, Any], reason: str) -> None:
+            item_type = str(item.get("item_type") or "unknown")
+            backlog_by_type[item_type] = backlog_by_type.get(item_type, 0) + 1
+            backlog_reasons[reason] = backlog_reasons.get(reason, 0) + 1
+            if len(backlog_samples) >= 20:
+                return
+            backlog_samples.append(
+                {
+                    "item_id": item.get("item_id"),
+                    "item_type": item_type,
+                    "source_node": item.get("source_node"),
+                    "reason": reason,
+                    "metadata": {
+                        key: value
+                        for key, value in dict(item.get("metadata") or {}).items()
+                        if key in {"node_type", "source", "conversation_id", "parent_source_node"}
+                    },
+                }
+            )
+
+        for item in source_items:
+            vector_row = vector_rows.get(item["item_id"])
+            expected_hash = _sha256_text(_clean_text(item["text"]))
+            if not vector_row:
+                missing += 1
+                add_backlog(item, "missing_vector")
+            elif (
+                vector_row["text_hash"] != expected_hash
+                or vector_row["embedding_dim"] != self._embedding_model.dim
+                or vector_row["embedding_model"] != self._embedding_model.model_id
+            ):
+                stale += 1
+                reason = "text_changed"
+                if vector_row["embedding_model"] != self._embedding_model.model_id:
+                    reason = "model_changed"
+                elif vector_row["embedding_dim"] != self._embedding_model.dim:
+                    reason = "dimension_changed"
+                add_backlog(item, reason)
+            else:
+                ready += 1
+        pending = missing + stale
+        orphaned_items = max(0, len(set(vector_rows) - source_item_ids))
+        coverage_ratio = round(ready / len(source_items), 6) if source_items else 1.0
+        latest_completed = None
+        for row in latest_rows:
+            if row["status"] == "completed":
+                latest_completed = row
+                break
+        latency_budget: Dict[str, Any] = {
+            "target_rebuild_ms": 10_000,
+            "last_rebuild_duration_ms": None,
+            "last_items_per_second": None,
+            "within_target": None,
+        }
+        if latest_completed is not None:
+            metadata = _safe_loads(latest_completed["metadata_json"])
+            duration_ms = metadata.get("duration_ms")
+            items_total = int(latest_completed["items_total"] or 0)
+            if isinstance(duration_ms, (int, float)) and duration_ms > 0:
+                latency_budget.update(
+                    {
+                        "last_rebuild_duration_ms": round(float(duration_ms), 2),
+                        "last_items_per_second": round(items_total / (float(duration_ms) / 1000.0), 2),
+                        "within_target": float(duration_ms) <= 10_000,
+                    }
+                )
+        embedder_status = self.embedder_fingerprint_status()
+        return {
+            "status": "ready" if pending == 0 else "needs_reindex",
+            "embedder": embedder_status,
+            "storage": {
+                "db_path": str(self.db_path),
+                "backend": "sqlite",
+                "embedding_model": self._embedding_model.model_id,
+                "embedding_dim": self._embedding_model.dim,
+                # Honest capability report: trigram FTS5 keyword index, or
+                # LIKE-scan fallback when this SQLite build lacks it.
+                "fts_enabled": bool(getattr(self, "_fts_enabled", False)),
+                "engine": storage_capabilities,
+                "vector_search_backend": (
+                    storage_capabilities.get("vector_backend")
+                    if isinstance(storage_capabilities, dict)
+                    else "bruteforce-cosine"
+                ),
+                "vector_search_mode": (
+                    (storage_capabilities.get("metadata") or {}).get("vector_mode")
+                    if isinstance(storage_capabilities, dict)
+                    else "fallback"
+                ),
+                "sqlite_vec_ann_available": (
+                    bool((storage_capabilities.get("metadata") or {}).get("sqlite_vec_ann_available"))
+                    if isinstance(storage_capabilities, dict)
+                    else False
+                ),
+                # v11.1.0: which in-process index scores a search, and — when
+                # the configured one could not be used — the reason it was
+                # substituted, so an unavailable optional extra is visible
+                # here instead of only showing up as "search feels slow".
+                "vector_index": self._vector_index_selection().as_dict(),
+            },
+            "source_items": len(source_items),
+            "indexed_items": sum(vector_counts.values()),
+            "ready_items": ready,
+            "missing_items": missing,
+            "stale_items": stale,
+            "pending_items": pending,
+            "by_item_type": vector_counts,
+            "scale": {
+                "version": 1,
+                "coverage_ratio": coverage_ratio,
+                "coverage_percent": round(coverage_ratio * 100.0, 2),
+                "source_items": len(source_items),
+                "ready_items": ready,
+                "pending_items": pending,
+                "missing_items": missing,
+                "stale_items": stale,
+                "orphaned_items": orphaned_items,
+                "backlog_by_item_type": backlog_by_type,
+                "backlog_reasons": backlog_reasons,
+                "backlog_samples": backlog_samples,
+                "incremental_reindex_recommended": pending > 0,
+                # A stale embedder means every old-model row must be re-embedded;
+                # only a full rebuild (which re-records the fingerprint) heals it.
+                "full_rebuild_recommended": bool(
+                    orphaned_items > 0 or embedder_status["stale_embedder"]
+                ),
+                "latency_budget": latency_budget,
+            },
+            "operations": [
+                {
+                    "id": row["id"],
+                    "operation": row["operation"],
+                    "status": row["status"],
+                    "requested_at": row["requested_at"],
+                    "started_at": row["started_at"],
+                    "completed_at": row["completed_at"],
+                    "items_total": row["items_total"],
+                    "items_indexed": row["items_indexed"],
+                    "items_skipped": row["items_skipped"],
+                    "error_message": row["error_message"],
+                    "metadata": _safe_loads(row["metadata_json"]),
+                }
+                for row in latest_rows
+            ],
+        }
+
+    def vector_freshness(self) -> Dict[str, Any]:
+        """Compact vector-index freshness summary for API surfaces (v9.8.0).
+
+        Reduces :meth:`index_status` (``pending = missing + stale``) to the
+        fixed contract ``{"status", "pending_items", "total_items", "detail"}``
+        with ``status`` in ``ready`` / ``pending`` / ``stale_embedder`` /
+        ``unavailable``. ``stale_embedder`` (review Wave 2.2) is reported only
+        when the recorded embedder fingerprint differs from the current
+        embedder AND rows indexed under the old model still exist — the index
+        needs a full rebuild, not an incremental sync.
+
+        Never raises: environments where the embedding provider or index
+        storage cannot be used report ``"unavailable"`` with the cause in
+        ``detail`` instead of surfacing an exception to the API layer.
+        """
+        try:
+            status = self.index_status()
+        except Exception as exc:  # noqa: BLE001 — freshness must degrade, not fail
+            return {
+                "status": "unavailable",
+                "pending_items": 0,
+                "total_items": 0,
+                "detail": f"vector index status unavailable: {exc}",
+            }
+        return self._vector_freshness_summary(status)
+
+    def _vector_freshness_summary(self, status: Dict[str, Any]) -> Dict[str, Any]:
+        """The freshness reduction of an already-read :meth:`index_status`.
+
+        Split out so :meth:`vector_freshness_breakdown` can report both shapes
+        from one index scan; ``index_status`` walks every source item, and
+        calling it twice to answer one question about freshness would double
+        the most expensive read in this module.
+        """
+        pending = int(status.get("pending_items") or 0)
+        total = int(status.get("source_items") or 0)
+        embedder = status.get("embedder") or {}
+        if embedder.get("stale_embedder"):
+            old_model_rows = 0
+            try:
+                with self._connect() as conn:
+                    old_model_rows = int(
+                        conn.execute(
+                            "SELECT COUNT(*) AS c FROM vector_embeddings "
+                            "WHERE embedding_model<>? OR embedding_dim<>?",
+                            (
+                                self._embedding_model.model_id,
+                                int(self._embedding_model.dim),
+                            ),
+                        ).fetchone()["c"]
+                    )
+            except Exception:  # noqa: BLE001 — keep the existing statuses on failure
+                old_model_rows = 0
+            if old_model_rows > 0:
+                recorded = embedder.get("recorded") or {}
+                return {
+                    "status": "stale_embedder",
+                    "pending_items": pending,
+                    "total_items": total,
+                    "detail": (
+                        f"embedding model changed ({recorded.get('model_id')} → "
+                        f"{self._embedding_model.model_id}); {old_model_rows} indexed "
+                        "rows still use the previous model — run a full vector index rebuild"
+                    ),
+                }
+        if pending > 0:
+            return {
+                "status": "pending",
+                "pending_items": pending,
+                "total_items": total,
+                "detail": (
+                    f"{pending} of {total} items are missing or stale in the vector index"
+                ),
+            }
+        detail = (
+            "vector index is up to date"
+            if total
+            else "vector index is empty (no indexable items yet)"
+        )
+        return {
+            "status": "ready",
+            "pending_items": 0,
+            "total_items": total,
+            "detail": detail,
+        }
+
+    @property
+    def vector_queue(self) -> VectorEmbedQueue:
+        """This store's durable pending-embed backlog (created on demand).
+
+        Built lazily rather than in ``__init__`` so opening a graph never
+        creates a table nobody asked for, and hung off the store so the
+        ingestion pipeline and the freshness report share one backlog instead
+        of each keeping a private view of it.
+        """
+        queue = getattr(self, "_vector_queue", None)
+        if queue is None:
+            queue = VectorEmbedQueue(
+                db_path=self.db_path, indexer=self.index_node_incremental
+            )
+            self._vector_queue = queue
+        return queue
+
+    def vector_freshness_breakdown(self) -> Dict[str, Any]:
+        """The four numbers behind :meth:`vector_freshness` (v11.1.0).
+
+        ``vector_freshness()`` answers one question — *is the index behind?* —
+        and its four keys are a frozen wire contract that surfaces already
+        read, so this is a sibling rather than an extension of it. The split
+        matters because "12 pending" hides two different situations: twelve
+        items never embedded (a new import) and twelve items whose text
+        changed under an existing embedding (edits). Only the second means
+        current answers are quietly wrong.
+
+        ``queued`` counts the durable background backlog
+        (:class:`~lattice_brain.graph.vector_index.VectorEmbedQueue`), and is
+        ``None`` when that queue has no database to persist to — never ``0``,
+        which would claim an empty backlog nobody measured.
+
+        Never raises: an unreadable index reports ``status="unavailable"``
+        with the cause in ``detail`` and zeroed counts.
+        """
+        status: Dict[str, Any] = {}
+        summary: Dict[str, Any]
+        try:
+            status = self.index_status()
+        except Exception as exc:  # noqa: BLE001 — freshness must degrade, not fail
+            summary = {
+                "status": "unavailable",
+                "pending_items": 0,
+                "total_items": 0,
+                "detail": f"vector index status unavailable: {exc}",
+            }
+        else:
+            summary = self._vector_freshness_summary(status)
+        breakdown: Dict[str, Any] = {
+            "status": summary["status"],
+            "detail": summary["detail"],
+            "embedded": int(status.get("ready_items") or 0),
+            "pending": int(summary["pending_items"]),
+            "missing": int(status.get("missing_items") or 0),
+            "stale": int(status.get("stale_items") or 0),
+            "total": int(summary["total_items"]),
+            "queued": None,
+        }
+        queue = self.vector_queue
+        if queue.available:
+            breakdown["queued"] = int(queue.pending_count())
+        return breakdown

package/lattice_brain/ingestion/__init__.py

@@ -0,0 +1,130 @@
+"""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.
+
+Web ingestion seam
+------------------
+The graph layer never fetches or parses the web. Fetching, rendering,
+readability extraction, and parse quality are the responsibility of the
+*upstream* capture surfaces (browser extension, tools layer, MCP servers):
+they hand this module already-extracted text. :meth:`IngestionPipeline.
+ingest_web_page` is the convenience wrapper for that hand-off — it normalizes
+``(url, extracted_text)`` into an ``IngestionItem(source_type="web_url")`` and
+routes it through the exact same :meth:`IngestionPipeline.ingest` door as every
+other source. If the extracted text is bad, fix the extractor upstream; the
+pipeline will not attempt network access or HTML parsing.
+
+Folder ingestion (:meth:`IngestionPipeline.ingest_folder`) walks a local
+directory, honors a gitignore-like ``.latticeignore`` file at the root
+(blank lines, ``#`` comments, ``fnmatch`` glob patterns, ``dir/`` suffix for
+directories), always skips common noise (``.git``, ``node_modules``,
+``__pycache__``, virtualenvs, ``dist``, hidden entries by default), applies
+size/extension filters, and either ingests inline or schedules through the
+existing :class:`BackgroundIngestionQueue`.
+
+Split into cohesive submodules in v11.3.0 (no behaviour change): ``constants``
+(routing tables + gates), ``quality`` (advisory scoring), ``models`` (item and
+result), ``hashing``, ``folder_scan`` (``.latticeignore``), and the three mixins
+``routing`` / ``folders`` / ``jobs_api`` that ``pipeline`` composes into
+``IngestionPipeline``. This module re-exports every name the single file
+exposed, so ``lattice_brain.ingestion.X`` keeps working.
+"""
+
+from __future__ import annotations
+
+# The single file had no ``__all__``, so its public surface was "every module
+# global" — including the names it imported for its own use. Every re-export
+# below therefore uses the redundant-alias form: it reproduces exactly that
+# surface, and it marks each name as deliberate rather than a leftover import.
+#
+# Stubbing note: rebinding one of these *here* changes only this module's name.
+# The submodule that calls it holds its own reference, so a test standing in for
+# a helper patches the submodule that uses it.
+from ..gates import FeatureGate as FeatureGate
+from ..ingestion_jobs import JOB_ERRORS_CAP as JOB_ERRORS_CAP
+from ..ingestion_jobs import BackgroundIngestionJob as BackgroundIngestionJob
+from ..ingestion_jobs import BackgroundIngestionQueue as BackgroundIngestionQueue
+from ..multimodal import AUDIO_EXTENSIONS as AUDIO_EXTENSIONS
+from ..multimodal import DEFAULT_KEYFRAMES as DEFAULT_KEYFRAMES
+from ..multimodal import IMAGE_EXTENSIONS as IMAGE_EXTENSIONS
+from ..multimodal import MODALITY_AUDIO as MODALITY_AUDIO
+from ..multimodal import MODALITY_IMAGE as MODALITY_IMAGE
+from ..multimodal import MODALITY_VIDEO as MODALITY_VIDEO
+from ..multimodal import VIDEO_EXTENSIONS as VIDEO_EXTENSIONS
+from ..multimodal import VIDEO_UNAVAILABLE_DETAIL as VIDEO_UNAVAILABLE_DETAIL
+from ..multimodal import ImageFacts as ImageFacts
+from ..multimodal import MultimodalPorts as MultimodalPorts
+from ..multimodal import audio_quality_score as audio_quality_score
+from ..multimodal import detect_modality as detect_modality
+from ..multimodal import extract_image_facts as extract_image_facts
+from ..multimodal import ffmpeg_available as ffmpeg_available
+from ..multimodal import image_quality_score as image_quality_score
+from ..multimodal import read_video_facts as read_video_facts
+from ..multimodal import transcribe_audio as transcribe_audio
+from ..multimodal import video_frame_dir as video_frame_dir
+from ..multimodal import video_quality_score as video_quality_score
+from ..multimodal import write_image_memory as write_image_memory
+from ..multimodal import write_video_memory as write_video_memory
+from ..quiet import quiet as quiet
+from ..runtime.hooks import dispatch_tool as dispatch_tool
+from ..utils import utc_now_iso as utc_now_iso
+from .constants import _MEMORY_NODE_TYPES as _MEMORY_NODE_TYPES
+from .constants import ALLOW_MULTIMODAL_ENV as ALLOW_MULTIMODAL_ENV
+from .constants import ALLOW_VIDEO_ENV as ALLOW_VIDEO_ENV
+from .constants import AUDIO_NODE_TYPE as AUDIO_NODE_TYPE
+from .constants import AUDIO_SOURCE_TYPES as AUDIO_SOURCE_TYPES
+from .constants import AUTO_VECTOR_INDEX_ENV as AUTO_VECTOR_INDEX_ENV
+from .constants import AUTO_VECTOR_INDEX_GATE as AUTO_VECTOR_INDEX_GATE
+from .constants import CHAT_SOURCE_TYPES as CHAT_SOURCE_TYPES
+from .constants import DEFAULT_FOLDER_EXTENSIONS as DEFAULT_FOLDER_EXTENSIONS
+from .constants import DEFAULT_MAX_FILE_BYTES as DEFAULT_MAX_FILE_BYTES
+from .constants import DEFAULT_MAX_TEXT_BYTES as DEFAULT_MAX_TEXT_BYTES
+from .constants import FILE_SOURCE_TYPES as FILE_SOURCE_TYPES
+from .constants import FOLDER_CODE_EXTENSIONS as FOLDER_CODE_EXTENSIONS
+from .constants import FOLDER_DEFAULT_SKIP_DIRS as FOLDER_DEFAULT_SKIP_DIRS
+from .constants import FOLDER_DOCUMENT_EXTENSIONS as FOLDER_DOCUMENT_EXTENSIONS
+from .constants import FOLDER_MULTIMODAL_EXTENSIONS as FOLDER_MULTIMODAL_EXTENSIONS
+from .constants import FOLDER_TEXT_EXTENSIONS as FOLDER_TEXT_EXTENSIONS
+from .constants import FOLDER_VIDEO_EXTENSIONS as FOLDER_VIDEO_EXTENSIONS
+from .constants import IMAGE_SOURCE_TYPES as IMAGE_SOURCE_TYPES
+from .constants import LATTICEIGNORE_FILENAME as LATTICEIGNORE_FILENAME
+from .constants import MEMORY_SOURCE_TYPES as MEMORY_SOURCE_TYPES
+from .constants import MULTIMODAL_GATE as MULTIMODAL_GATE
+from .constants import TEXT_SOURCE_TYPES as TEXT_SOURCE_TYPES
+from .constants import VIDEO_GATE as VIDEO_GATE
+from .constants import VIDEO_SOURCE_TYPES as VIDEO_SOURCE_TYPES
+from .folder_scan import _load_latticeignore as _load_latticeignore
+from .folder_scan import _matches_ignore as _matches_ignore
+from .folders import IngestionFolderMixin as IngestionFolderMixin
+from .hashing import _file_digest as _file_digest
+from .hashing import content_hash_text as content_hash_text
+from .jobs_api import IngestionJobsMixin as IngestionJobsMixin
+from .models import IngestionItem as IngestionItem
+from .models import IngestionResult as IngestionResult
+from .pipeline import VECTOR_TICK_LIMIT as VECTOR_TICK_LIMIT
+from .pipeline import IngestionPipeline as IngestionPipeline
+from .quality import _BOILERPLATE_LINE_MARKERS as _BOILERPLATE_LINE_MARKERS
+from .quality import _CAPTURE_REASON_LABELS as _CAPTURE_REASON_LABELS
+from .quality import _WEB_SOURCE_TYPES as _WEB_SOURCE_TYPES
+from .quality import CAPTURE_SUGGESTIONS_THIN as CAPTURE_SUGGESTIONS_THIN
+from .quality import QUALITY_HIGH_THRESHOLD as QUALITY_HIGH_THRESHOLD
+from .quality import QUALITY_LOW_THRESHOLD as QUALITY_LOW_THRESHOLD
+from .quality import QUALITY_LOW_WARNING as QUALITY_LOW_WARNING
+from .quality import _quality_level as _quality_level
+from .quality import assess_extraction_quality as assess_extraction_quality
+from .quality import capture_quality_verdict as capture_quality_verdict
+from .routing import IngestionRoutingMixin as IngestionRoutingMixin

package/lattice_brain/ingestion/_contract.py

@@ -0,0 +1,90 @@
+"""The seam the three ingestion mixins share.
+
+``IngestionPipeline`` is assembled from the routing, folder and jobs mixins.
+Each of them reads constructor state it does not own and calls back into
+``ingest`` — the point of the split is that "how one picture is stored" and
+"how a folder is walked" stop sharing a thousand-line file, not that they stop
+sharing ``self``.
+
+Typing-only, exactly like :mod:`lattice_brain.graph._kg_contract`: at runtime
+the mixins alias it to ``object``, so the MRO and every method resolution stay
+byte-for-byte what the single-file class had. Adding a cross-mixin call without
+declaring it here is a type error.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..ingestion_jobs import BackgroundIngestionJob, BackgroundIngestionQueue
+from ..multimodal import MultimodalPorts
+from .models import IngestionItem, IngestionResult
+
+
+class IngestionCore:
+    """What any ingestion mixin may assume about ``self``.
+
+    Never instantiated and never inherited at runtime — see the module
+    docstring. Members are declared, not implemented: the implementation lives
+    in ``pipeline.py`` or in whichever mixin owns it.
+    """
+
+    # ── State owned by IngestionPipeline.__init__ ────────────────────────────
+    _kg: Any
+    _hooks: Any
+    _enable: bool
+    _audit: Optional[Any]
+    _max_text_bytes: int
+    _pipeline_name: str
+    _bg_queue: BackgroundIngestionQueue
+    _auto_vector_index_opt_in: bool
+    _multimodal_opt_in: bool
+    _multimodal: MultimodalPorts
+    _keyframes: int
+
+    # ── pipeline.py: the gates, resolved when they are asked ─────────────────
+    @property
+    def _allow_multimodal(self) -> bool:
+        raise NotImplementedError
+
+    @property
+    def _allow_video(self) -> bool:
+        raise NotImplementedError
+
+    # ── pipeline.py: the one door every mixin routes back through ────────────
+    def available(self) -> bool:
+        raise NotImplementedError
+
+    def ingest(
+        self, item: IngestionItem, *, user_email: Optional[str] = None
+    ) -> IngestionResult:
+        raise NotImplementedError
+
+    # ── routing.py: reached from the folder walk and the modality doors ──────
+    def _resolve_file_path(self, item: IngestionItem) -> Path:
+        raise NotImplementedError
+
+    # ── folders.py: the folder-scan allow-list the multimodal gates widen ────
+    def _folder_extensions(self) -> frozenset:
+        raise NotImplementedError
+
+    # ── jobs_api.py: scheduling, reached from the folder walk ────────────────
+    def schedule_background(
+        self,
+        items: List[IngestionItem],
+        *,
+        incremental: bool = True,
+        user_email: Optional[str] = None,
+    ) -> BackgroundIngestionJob:
+        raise NotImplementedError
+
+    def run_background_job(
+        self, job_id: str, *, user_email: Optional[str] = None
+    ) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def _execute_background_job(
+        self, job: BackgroundIngestionJob, *, user_email: Optional[str] = None
+    ) -> Dict[str, Any]:
+        raise NotImplementedError