afs-core 0.1.0__py3-none-any.whl

afs_core/__init__.py

@@ -0,0 +1,9 @@
+"""agentic-fs core: contracts, DTOs, the key scheme, and the error vocabulary.
+
+Depends on pydantic only — importable without the server. (``afs_core.testing``
+is intentionally not imported here: it depends on pytest and is opt-in.)
+"""
+
+from afs_core import contracts, errors, keys, models
+
+__all__ = ["contracts", "errors", "keys", "models"]

afs_core/contracts/__init__.py

@@ -0,0 +1,11 @@
+"""The agentic-fs contracts: async ``typing.Protocol`` interfaces (plan §5).
+
+Structural — adopters implement without importing our hierarchy. Each is proven
+by a conformance kit in :mod:`afs_core.testing`.
+"""
+
+from afs_core.contracts.catalog import CatalogStore
+from afs_core.contracts.normalize import NormalizationError, Normalizer
+from afs_core.contracts.objects import ObjectStore
+
+__all__ = ["CatalogStore", "NormalizationError", "Normalizer", "ObjectStore"]

afs_core/contracts/catalog.py

@@ -0,0 +1,90 @@
+"""The ``CatalogStore`` contract (plan §5.1).
+
+One contract covers entries + control records + checkpoints + scratch quota, so a
+self-hoster swaps **one** stateful dependency. Structural ``Protocol``, async.
+Certify an impl with ``CatalogStoreConformance`` (afs_core.testing); DynamoDB and
+Postgres are the two reference implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from afs_core.models import (
+    CatalogEntry,
+    ExtractionState,
+    NamespaceRecord,
+    Page,
+    PrincipalRecord,
+    ScratchUsage,
+    SyncCheckpoint,
+    TenantRecord,
+)
+
+
+@runtime_checkable
+class CatalogStore(Protocol):
+    # -- entries (derived index of S3; healable FROM S3) --
+    async def put_entry(self, entry: CatalogEntry) -> None: ...
+
+    async def get_entry(self, tenant_id: str, namespace: str, path: str) -> CatalogEntry | None: ...
+
+    async def delete_entry(
+        self, tenant_id: str, namespace: str, path: str, *, hard: bool = False
+    ) -> None:
+        """Tombstone (soft) by default; ``hard=True`` removes the row entirely."""
+        ...
+
+    async def list_entries(
+        self,
+        tenant_id: str,
+        namespace: str,
+        *,
+        prefix: str = "",
+        include_deleted: bool = False,
+        cursor: str | None = None,
+        limit: int = 1000,
+    ) -> Page[CatalogEntry]: ...
+
+    async def find_by_checksum(self, tenant_id: str, checksum: str) -> list[CatalogEntry]: ...
+
+    async def set_extraction(
+        self, tenant_id: str, namespace: str, path: str, state: ExtractionState
+    ) -> None: ...
+
+    async def list_by_extraction_status(
+        self, status: str, *, cursor: str | None = None, limit: int = 100
+    ) -> Page[CatalogEntry]: ...
+
+    async def tree_version(self, tenant_id: str, namespace: str) -> str:
+        """A token bumped on any write to the namespace — the tree-cache key."""
+        ...
+
+    # -- control records (tenants / namespaces / principals) --
+    async def put_tenant(self, tenant: TenantRecord) -> None: ...
+    async def get_tenant(self, tenant_id: str) -> TenantRecord | None: ...
+    async def list_tenants(
+        self, *, cursor: str | None = None, limit: int = 100
+    ) -> Page[TenantRecord]: ...
+
+    async def put_namespace(self, ns: NamespaceRecord) -> None: ...
+    async def get_namespace(self, tenant_id: str, name: str) -> NamespaceRecord | None: ...
+    async def list_namespaces(self, tenant_id: str) -> list[NamespaceRecord]: ...
+    async def delete_namespace(self, tenant_id: str, name: str) -> None: ...
+
+    async def put_principal(self, p: PrincipalRecord) -> None: ...
+    async def get_principal(self, tenant_id: str, principal_id: str) -> PrincipalRecord | None: ...
+    async def list_principals(self, tenant_id: str) -> list[PrincipalRecord]: ...
+
+    # -- connector checkpoints --
+    async def get_checkpoint(self, tenant_id: str, connector_id: str) -> SyncCheckpoint | None: ...
+    async def put_checkpoint(
+        self, tenant_id: str, connector_id: str, cp: SyncCheckpoint
+    ) -> None: ...
+
+    # -- scratch quota (atomic; raises QuotaExceededError) --
+    async def adjust_scratch_usage(
+        self, tenant_id: str, principal_id: str, *, delta_bytes: int, delta_objects: int
+    ) -> ScratchUsage: ...
+
+    async def get_scratch_usage(self, tenant_id: str, principal_id: str) -> ScratchUsage: ...

afs_core/contracts/normalize.py

@@ -0,0 +1,40 @@
+"""The ``Normalizer`` contract (plan §5.4) — the extractor/parser seam.
+
+A normalizer turns one raw document into normalized per-page markdown. It is the
+*only* place document parsing lives: text_native, docling, llamaparse, and any
+custom parser are all just `Normalizer`s. The `ExtractionPipeline` (in
+afs-server) orders them into a ladder, applies a quality gate, and degrades to
+`catalog_only` — none of which a normalizer needs to know about.
+
+Adding your own: implement this Protocol, certify it against
+`afs_core.testing.NormalizerConformance`, register it via the `afs.normalizers`
+entry-point group, and name it in the extraction ladder. No core changes.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from afs_core.models import NormalizedDocument, SourceDocument
+
+
+class NormalizationError(Exception):
+    """A normalizer couldn't parse the document. Carries a closed-vocabulary
+    ``reason`` (events v1) so the pipeline can record why and try the next rung."""
+
+    def __init__(self, reason: str, message: str | None = None) -> None:
+        self.reason = reason
+        super().__init__(message or reason)
+
+
+@runtime_checkable
+class Normalizer(Protocol):
+    name: str
+
+    def accepts(self, doc: SourceDocument) -> bool:
+        """Whether this normalizer claims the document (by MIME/extension)."""
+        ...
+
+    async def normalize(self, doc: SourceDocument) -> NormalizedDocument:
+        """Parse ``doc`` into per-page markdown, or raise ``NormalizationError``."""
+        ...

afs_core/contracts/objects.py

@@ -0,0 +1,44 @@
+"""The ``ObjectStore`` contract (plan §5.2).
+
+Structural ``Protocol`` — adopters implement it without importing our hierarchy
+or depending on ``afs-server``. S3 is the only production impl; the protocol
+exists so MinIO/LocalStack back local dev and an in-memory fake backs tests.
+Certify any impl with ``ObjectStoreConformance`` (afs_core.testing).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from afs_core.models import ObjectStat, Page, PresignedPut
+
+
+@runtime_checkable
+class ObjectStore(Protocol):
+    async def get(self, key: str, *, start: int | None = None, end: int | None = None) -> bytes:
+        """Fetch an object, optionally a byte range ``[start, end]`` (inclusive)."""
+        ...
+
+    async def put(
+        self, key: str, body: bytes, *, content_type: str | None = None
+    ) -> ObjectStat: ...
+
+    async def delete(self, key: str) -> None: ...
+
+    async def delete_prefix(self, prefix: str) -> int:
+        """Delete every object under ``prefix``; returns the count removed."""
+        ...
+
+    async def stat(self, key: str) -> ObjectStat | None:
+        """Metadata for ``key``, or ``None`` if it does not exist."""
+        ...
+
+    async def list(
+        self, prefix: str, *, cursor: str | None = None, limit: int = 1000
+    ) -> Page[ObjectStat]: ...
+
+    async def presigned_put(
+        self, key: str, *, content_type: str, max_bytes: int, expires_in: int = 900
+    ) -> PresignedPut: ...
+
+    async def presigned_get(self, key: str, *, expires_in: int = 300) -> str: ...

afs_core/errors.py

@@ -0,0 +1,212 @@
+"""The closed error vocabulary and the ``AfsError`` hierarchy.
+
+Every error agentic-fs raises across the wire carries a code from the closed
+:class:`ErrorCode` enum and serializes to an RFC 9457 ``application/problem+json``
+envelope. The vocabulary is closed on purpose: clients (and the MCP tool layer)
+can branch on a small, stable set of codes instead of parsing prose.
+
+Design note — **misses are 404, never 403** (plan §4.1): a caller must not be
+able to tell "exists but forbidden" from "does not exist", or they could
+enumerate tenants/namespaces/documents. So the not-found errors below all map to
+404 and there is intentionally no 403 for resource access.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+
+class ErrorCode(StrEnum):
+    """Closed vocabulary of machine-readable error codes."""
+
+    # Request / validation
+    VALIDATION_ERROR = "validation_error"
+    INVALID_KEY = "invalid_key"
+    INVALID_NAMESPACE = "invalid_namespace"
+
+    # Not found (also used to hide forbidden — see module docstring)
+    NOT_FOUND = "not_found"
+    TENANT_NOT_FOUND = "tenant_not_found"
+    NAMESPACE_NOT_FOUND = "namespace_not_found"
+    DOCUMENT_NOT_FOUND = "document_not_found"
+
+    # AuthN / AuthZ
+    UNAUTHENTICATED = "unauthenticated"
+    INSUFFICIENT_SCOPE = "insufficient_scope"
+
+    # Read-path / capability
+    CATALOG_ONLY = "catalog_only"
+    SEARCH_NOT_ENABLED = "search_not_enabled"
+    BUDGET_EXCEEDED = "budget_exceeded"
+
+    # Write-path / quota
+    QUOTA_EXCEEDED = "quota_exceeded"
+    PAYLOAD_TOO_LARGE = "payload_too_large"
+    CONFLICT = "conflict"
+
+    # Extraction
+    EXTRACTION_FAILED = "extraction_failed"
+
+    # Catch-all
+    INTERNAL = "internal"
+
+
+class AfsError(Exception):
+    """Base for every agentic-fs error.
+
+    Carries a closed :class:`ErrorCode`, an HTTP status, and an optional
+    ``detail`` map; serializes to an RFC 9457 problem object via
+    :meth:`to_problem`.
+    """
+
+    code: ErrorCode = ErrorCode.INTERNAL
+    http_status: int = 500
+    title: str = "Internal error"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        detail: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message or self.title
+        self.detail = detail or {}
+        super().__init__(self.message)
+
+    def to_problem(self, *, instance: str | None = None) -> dict[str, Any]:
+        """Render as an RFC 9457 ``application/problem+json`` object."""
+        problem: dict[str, Any] = {
+            "type": f"https://agentic-fs.dev/errors/{self.code.value}",
+            "title": self.title,
+            "status": self.http_status,
+            "code": self.code.value,
+            "detail": self.message,
+        }
+        if instance is not None:
+            problem["instance"] = instance
+        problem.update(self.detail)
+        return problem
+
+
+# --- 4xx: client ---------------------------------------------------------------
+
+
+class ValidationError(AfsError):
+    code = ErrorCode.VALIDATION_ERROR
+    http_status = 400
+    title = "Validation error"
+
+
+class InvalidKeyError(ValidationError):
+    code = ErrorCode.INVALID_KEY
+    title = "Invalid object key"
+
+
+class InvalidNamespaceError(ValidationError):
+    code = ErrorCode.INVALID_NAMESPACE
+    title = "Invalid namespace"
+
+
+class UnauthenticatedError(AfsError):
+    code = ErrorCode.UNAUTHENTICATED
+    http_status = 401
+    title = "Unauthenticated"
+
+
+class InsufficientScopeError(AfsError):
+    code = ErrorCode.INSUFFICIENT_SCOPE
+    http_status = 403
+    title = "Insufficient scope"
+
+
+class NotFoundError(AfsError):
+    """Generic 404. Also the disguise for forbidden resource access (§4.1)."""
+
+    code = ErrorCode.NOT_FOUND
+    http_status = 404
+    title = "Not found"
+
+
+class TenantNotFoundError(NotFoundError):
+    code = ErrorCode.TENANT_NOT_FOUND
+    title = "Tenant not found"
+
+
+class NamespaceNotFoundError(NotFoundError):
+    code = ErrorCode.NAMESPACE_NOT_FOUND
+    title = "Namespace not found"
+
+
+class DocumentNotFoundError(NotFoundError):
+    code = ErrorCode.DOCUMENT_NOT_FOUND
+    title = "Document not found"
+
+
+class ConflictError(AfsError):
+    code = ErrorCode.CONFLICT
+    http_status = 409
+    title = "Conflict"
+
+
+class PayloadTooLargeError(AfsError):
+    code = ErrorCode.PAYLOAD_TOO_LARGE
+    http_status = 413
+    title = "Payload too large"
+
+
+class QuotaExceededError(AfsError):
+    code = ErrorCode.QUOTA_EXCEEDED
+    http_status = 429
+    title = "Quota exceeded"
+
+
+class BudgetExceededError(AfsError):
+    code = ErrorCode.BUDGET_EXCEEDED
+    http_status = 422
+    title = "Budget exceeded"
+
+
+class CatalogOnlyError(AfsError):
+    """The document exists and is cite-able, but its contents aren't readable yet."""
+
+    code = ErrorCode.CATALOG_ONLY
+    http_status = 422
+    title = "Document is catalog-only"
+
+
+class SearchNotEnabledError(AfsError):
+    code = ErrorCode.SEARCH_NOT_ENABLED
+    http_status = 422
+    title = "Search is not enabled"
+
+
+# --- 5xx: server ---------------------------------------------------------------
+
+
+class ExtractionFailedError(AfsError):
+    code = ErrorCode.EXTRACTION_FAILED
+    http_status = 500
+    title = "Extraction failed"
+
+
+__all__ = [
+    "AfsError",
+    "BudgetExceededError",
+    "CatalogOnlyError",
+    "ConflictError",
+    "DocumentNotFoundError",
+    "ErrorCode",
+    "ExtractionFailedError",
+    "InsufficientScopeError",
+    "InvalidKeyError",
+    "InvalidNamespaceError",
+    "NamespaceNotFoundError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "QuotaExceededError",
+    "SearchNotEnabledError",
+    "TenantNotFoundError",
+    "UnauthenticatedError",
+    "ValidationError",
+]

afs_core/keys.py

@@ -0,0 +1,271 @@
+"""The single definition of the S3 key scheme (plan §3.2).
+
+Nothing else in agentic-fs concatenates an object key — every consumer builds,
+parses, and validates through here. The scheme is **channel-first** so that one
+EventBridge rule (``prefix: tenants/``) feeds extraction, Bedrock KB syncs from a
+prefix containing only embeddable text, and lifecycle rules are plain prefix
+rules (plan §3.1):
+
+    tenants/{tenant}/{namespace}/{relpath}                  raw canonical documents
+    scratch/{tenant}/{principal}/{relpath}                  agent scratch (TTL'd)
+    derived/text/{tenant}/{ns}/{doc_id}/{page:04d}.md       extracted text layer
+    derived/text/{tenant}/{ns}/{doc_id}/{page:04d}.md.metadata.json   KB sidecar
+    derived/meta/{tenant}/{ns}/{doc_id}/manifest.json       extraction manifest
+    derived/tree/{tenant}/{ns}.json.zst                     path-tree artifact
+
+``parse_key`` returns ``None`` for anything nonconforming — it never guesses.
+``is_indexable`` is the one predicate every consumer (cataloger, extractor,
+index-sync, tree builder, search scope) uses to exclude ``scratch/`` and
+``derived/``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+
+from afs_core.errors import InvalidKeyError
+
+PAGE_DIGITS = 4
+MAX_PAGE = 10**PAGE_DIGITS - 1
+
+# Lowercase slugs for tenant / namespace / principal ids.
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+# doc_id is a ULID (uppercase Crockford base32) or similar opaque id.
+_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+# Segments a relpath may never contain (traversal + channel words + dotfiles).
+_RESERVED_SEGMENTS = frozenset({"", ".", "..", "tenants", "scratch", "derived"})
+
+_TREE_SUFFIX = ".json.zst"
+_TEXT_SUFFIX = ".md"
+_METADATA_SUFFIX = ".metadata.json"
+_MANIFEST_NAME = "manifest.json"
+
+
+class Channel(StrEnum):
+    """Top-level key channels."""
+
+    ORIGINAL = "original"  # tenants/
+    SCRATCH = "scratch"  # scratch/
+    DERIVED_TEXT = "derived_text"  # derived/text/
+    DERIVED_META = "derived_meta"  # derived/meta/
+    DERIVED_TREE = "derived_tree"  # derived/tree/
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedKey:
+    """The structured decomposition of a conforming key.
+
+    Fields not relevant to a channel stay ``None`` (e.g. an ORIGINAL key has no
+    ``doc_id``; a DERIVED_TREE key has no ``path``).
+    """
+
+    channel: Channel
+    tenant_id: str
+    namespace: str | None = None
+    path: str | None = None
+    principal_id: str | None = None
+    doc_id: str | None = None
+    page: int | None = None
+    is_metadata: bool = False
+
+
+# --- validation helpers --------------------------------------------------------
+
+
+def _is_slug(value: str) -> bool:
+    return bool(_SLUG_RE.fullmatch(value))
+
+
+def _is_id(value: str) -> bool:
+    return bool(_ID_RE.fullmatch(value))
+
+
+def _relpath_ok(relpath: str) -> bool:
+    if not relpath or relpath.startswith("/"):
+        return False
+    return all(
+        seg not in _RESERVED_SEGMENTS and not seg.startswith("_") for seg in relpath.split("/")
+    )
+
+
+def validate_slug(value: str, *, field: str) -> str:
+    if not _is_slug(value):
+        raise InvalidKeyError(
+            f"{field} must be a lowercase slug", detail={"field": field, "value": value}
+        )
+    return value
+
+
+def validate_id(value: str, *, field: str) -> str:
+    if not _is_id(value):
+        raise InvalidKeyError(
+            f"{field} must be alphanumeric", detail={"field": field, "value": value}
+        )
+    return value
+
+
+def validate_relpath(relpath: str) -> str:
+    """Reject traversal, absolute paths, reserved/dotfile segments. One code path."""
+    if not _relpath_ok(relpath):
+        raise InvalidKeyError("invalid relpath", detail={"relpath": relpath})
+    return relpath
+
+
+def _validate_page(page: int) -> int:
+    if not (0 <= page <= MAX_PAGE):
+        raise InvalidKeyError(f"page must be in [0, {MAX_PAGE}]", detail={"page": page})
+    return page
+
+
+# --- builders ------------------------------------------------------------------
+
+
+def originals_key(tenant_id: str, namespace: str, path: str) -> str:
+    validate_slug(tenant_id, field="tenant_id")
+    validate_slug(namespace, field="namespace")
+    validate_relpath(path)
+    return f"tenants/{tenant_id}/{namespace}/{path}"
+
+
+def scratch_key(tenant_id: str, principal_id: str, path: str) -> str:
+    validate_slug(tenant_id, field="tenant_id")
+    validate_slug(principal_id, field="principal_id")
+    validate_relpath(path)
+    return f"scratch/{tenant_id}/{principal_id}/{path}"
+
+
+def derived_text_key(tenant_id: str, namespace: str, doc_id: str, page: int) -> str:
+    validate_slug(tenant_id, field="tenant_id")
+    validate_slug(namespace, field="namespace")
+    validate_id(doc_id, field="doc_id")
+    _validate_page(page)
+    return f"derived/text/{tenant_id}/{namespace}/{doc_id}/{page:0{PAGE_DIGITS}d}{_TEXT_SUFFIX}"
+
+
+def derived_text_metadata_key(tenant_id: str, namespace: str, doc_id: str, page: int) -> str:
+    return derived_text_key(tenant_id, namespace, doc_id, page) + _METADATA_SUFFIX
+
+
+def derived_meta_key(tenant_id: str, namespace: str, doc_id: str) -> str:
+    validate_slug(tenant_id, field="tenant_id")
+    validate_slug(namespace, field="namespace")
+    validate_id(doc_id, field="doc_id")
+    return f"derived/meta/{tenant_id}/{namespace}/{doc_id}/{_MANIFEST_NAME}"
+
+
+def tree_key(tenant_id: str, namespace: str) -> str:
+    validate_slug(tenant_id, field="tenant_id")
+    validate_slug(namespace, field="namespace")
+    return f"derived/tree/{tenant_id}/{namespace}{_TREE_SUFFIX}"
+
+
+# --- parsing -------------------------------------------------------------------
+
+
+def parse_key(key: str) -> ParsedKey | None:
+    """Decompose a key, or return ``None`` if it doesn't conform. Never guesses."""
+    if key.startswith("derived/tree/"):
+        return _parse_tree(key.removeprefix("derived/tree/"))
+    if key.startswith("derived/text/"):
+        return _parse_text(key.removeprefix("derived/text/"))
+    if key.startswith("derived/meta/"):
+        return _parse_meta(key.removeprefix("derived/meta/"))
+    if key.startswith("scratch/"):
+        return _parse_scratch(key.removeprefix("scratch/"))
+    if key.startswith("tenants/"):
+        return _parse_original(key.removeprefix("tenants/"))
+    return None
+
+
+def _parse_tree(rest: str) -> ParsedKey | None:
+    segs = rest.split("/")
+    if len(segs) != 2 or not segs[1].endswith(_TREE_SUFFIX):
+        return None
+    tenant, ns = segs[0], segs[1].removesuffix(_TREE_SUFFIX)
+    if not (_is_slug(tenant) and _is_slug(ns)):
+        return None
+    return ParsedKey(Channel.DERIVED_TREE, tenant_id=tenant, namespace=ns)
+
+
+def _parse_text(rest: str) -> ParsedKey | None:
+    segs = rest.split("/")
+    if len(segs) != 4:
+        return None
+    tenant, ns, doc_id, filename = segs
+    is_metadata = filename.endswith(_METADATA_SUFFIX)
+    base = filename.removesuffix(_METADATA_SUFFIX) if is_metadata else filename
+    if not base.endswith(_TEXT_SUFFIX):
+        return None
+    page_str = base.removesuffix(_TEXT_SUFFIX)
+    if not (page_str.isdigit() and len(page_str) == PAGE_DIGITS):
+        return None
+    if not (_is_slug(tenant) and _is_slug(ns) and _is_id(doc_id)):
+        return None
+    return ParsedKey(
+        Channel.DERIVED_TEXT,
+        tenant_id=tenant,
+        namespace=ns,
+        doc_id=doc_id,
+        page=int(page_str),
+        is_metadata=is_metadata,
+    )
+
+
+def _parse_meta(rest: str) -> ParsedKey | None:
+    segs = rest.split("/")
+    if len(segs) != 4 or segs[3] != _MANIFEST_NAME:
+        return None
+    tenant, ns, doc_id, _ = segs
+    if not (_is_slug(tenant) and _is_slug(ns) and _is_id(doc_id)):
+        return None
+    return ParsedKey(Channel.DERIVED_META, tenant_id=tenant, namespace=ns, doc_id=doc_id)
+
+
+def _parse_scratch(rest: str) -> ParsedKey | None:
+    segs = rest.split("/")
+    if len(segs) < 3:
+        return None
+    tenant, principal, relpath = segs[0], segs[1], "/".join(segs[2:])
+    if not (_is_slug(tenant) and _is_slug(principal) and _relpath_ok(relpath)):
+        return None
+    return ParsedKey(Channel.SCRATCH, tenant_id=tenant, principal_id=principal, path=relpath)
+
+
+def _parse_original(rest: str) -> ParsedKey | None:
+    segs = rest.split("/")
+    if len(segs) < 3:
+        return None
+    tenant, ns, relpath = segs[0], segs[1], "/".join(segs[2:])
+    if not (_is_slug(tenant) and _is_slug(ns) and _relpath_ok(relpath)):
+        return None
+    return ParsedKey(Channel.ORIGINAL, tenant_id=tenant, namespace=ns, path=relpath)
+
+
+def is_indexable(key: str) -> bool:
+    """True only for raw canonical documents under ``tenants/`` (plan §3.2).
+
+    The single predicate that excludes ``scratch/`` and ``derived/`` from the
+    cataloger, extractor, index-sync, tree builder, and search scope.
+    """
+    parsed = parse_key(key)
+    return parsed is not None and parsed.channel is Channel.ORIGINAL
+
+
+__all__ = [
+    "Channel",
+    "ParsedKey",
+    "derived_meta_key",
+    "derived_text_key",
+    "derived_text_metadata_key",
+    "is_indexable",
+    "originals_key",
+    "parse_key",
+    "scratch_key",
+    "tree_key",
+    "validate_id",
+    "validate_relpath",
+    "validate_slug",
+]