code-atlas-forge 1.1.0__py3-none-any.whl

code_atlas/domains/evidence.py

@@ -0,0 +1,57 @@
+"""Evidência de fatos de domínio (lf-0110, Cycle 7).
+
+Nenhum tipo novo: evidência de domínio **é** ``EvidenceRecord`` — a mesma
+tabela ``evidence``, o mesmo envelope (extractor + versão + content_hash +
+span). O que muda é a convenção de identificação do produtor:
+
+- ``extractor`` = ``domain:<domain_id>`` (ex.: ``domain:sql``);
+- ``extractor_version`` = ``adapter_version`` do adapter;
+- ``resolver_id``/``resolver_version``/``evidence_tier`` preenchidos só
+  quando a evidência veio de um resolvedor (mesma semântica de lf-0035);
+- ``content_hash`` = sha256 do artefato observado — casa 1:1 com o
+  arquivo do inventário (evidence-first: nenhum fato sem trecho real).
+"""
+
+from __future__ import annotations
+
+from code_atlas.parsers.contracts import EvidenceRecord, SourceSpan
+
+# Alias documentado — evidência de domínio reutiliza o envelope canônico.
+DomainEvidence = EvidenceRecord
+
+DOMAIN_EXTRACTOR_PREFIX = "domain:"
+
+
+def domain_extractor_id(domain_id: str) -> str:
+    """``extractor`` canônico de um adapter de domínio."""
+    return f"{DOMAIN_EXTRACTOR_PREFIX}{domain_id}"
+
+
+def evidence_record(
+    *,
+    adapter_domain: str,
+    adapter_version: str,
+    path: str,
+    content_hash: str,
+    span: SourceSpan | None = None,
+    notes: str = "",
+    resolver_id: str = "",
+    resolver_version: str = "",
+    evidence_tier: int = 0,
+    index_hash: str = "",
+    validation_status: str = "",
+) -> EvidenceRecord:
+    """Fábrica tipada de ``EvidenceRecord`` com convenção de domínio."""
+    return EvidenceRecord(
+        path=path,
+        span=span,
+        content_hash=content_hash,
+        extractor=domain_extractor_id(adapter_domain),
+        extractor_version=adapter_version,
+        notes=notes,
+        resolver_id=resolver_id,
+        resolver_version=resolver_version,
+        evidence_tier=evidence_tier,
+        index_hash=index_hash,
+        validation_status=validation_status,
+    )

code_atlas/domains/identity.py

@@ -0,0 +1,149 @@
+"""Identidade canônica de entidades de domínio (lf-0110, Cycle 7).
+
+Regra inegociável: duas entidades com o mesmo nome em escopos distintos
+NÃO podem colidir — duas tabelas ``orders`` em catálogos diferentes, dois
+``aws_s3_bucket.logs`` em contas/regiões distintas têm identidades
+diferentes. A chave canônica é posicional e **escapada por segmento**
+(percent-encoding), portanto separadores dentro de um componente
+(``:``, ``/``, ``.``) nunca se confundem com o separador estrutural.
+
+Componentes, em ordem fixa:
+
+1. ``domain`` — id do domínio do adapter (``sql``, ``terraform``, …);
+2. ``repository`` — ``identity_key`` lógica do repositório (lf-0021);
+3. ``root`` — sub-raiz dentro do repo/monorepo (``""`` = raiz);
+4. ``catalog`` — catálogo/conta/região/projeto que qualifica o
+   namespace (ex.: ``glue:123456789012:us-east-1``, ``aws:…:eu-west-1``);
+5. ``namespace`` — prefixo intermediário (schema, database, module);
+6. ``environment`` — qualificador opcional (``dev``/``prod``); ``""``
+   quando o adapter não distingue ambientes;
+7. ``qualified_name`` — nome qualificado definido pelo adapter;
+8. ``snapshot`` — escopo opcional de revisão (commit/digest); ``""``
+   para identidade **lógica** (vale por repositório, como ``symbols``).
+
+``identity_key`` persistida usa sempre a forma lógica (``snapshot=""``);
+a ocorrência por snapshot é quem carrega o vínculo temporal — mesmo
+desenho de ``symbols``/``symbol_occurrences``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_SCHEME = "dom"
+_SEP = "/"
+
+# Percent-encoding próprio: ``urllib.parse`` é proibido fora de ``api/``
+# (auditoria de rede lf-0086). Safe-set = RFC 3986 unreserved.
+_SAFE = frozenset(
+    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-~"
+)
+
+
+def _enc(part: str) -> str:
+    """Escapa um segmento — todo byte fora do safe-set vira ``%XX``.
+
+    Cobre ``:``, ``/``, ``.``, espaço e UTF-8 multibyte: separadores
+    estruturais nunca se confundem com conteúdo do componente.
+    """
+    out: list[str] = []
+    for b in part.encode("utf-8"):
+        ch = chr(b)
+        out.append(ch if ch in _SAFE else f"%{b:02X}")
+    return "".join(out)
+
+
+def _dec(part: str) -> str:
+    """Inverso de ``_enc`` — ``%XX`` malformado é literal, nunca crash."""
+    out = bytearray()
+    i, n = 0, len(part)
+    while i < n:
+        ch = part[i]
+        if ch == "%" and i + 3 <= n:
+            try:
+                out.append(int(part[i + 1:i + 3], 16))
+                i += 3
+                continue
+            except ValueError:
+                pass
+        out.extend(ch.encode("utf-8"))
+        i += 1
+    return out.decode("utf-8")
+
+
+@dataclass(frozen=True)
+class DomainIdentity:
+    """Identidade canônica completa de uma entidade de domínio.
+
+    Campos são ``strip()``ados em ``__post_init__``; capitalização é
+    **preservada** (política de case é do adapter — identificadores SQL
+    quoted são case-sensitive e adapters não devem fundir nomes reais
+    distintos).
+    """
+
+    domain: str           # id do domínio produtor (adapter.domain_id)
+    repository: str       # identity_key lógica do repositório (lf-0021)
+    qualified_name: str   # nome qualificado definido pelo adapter
+    root: str = ""        # sub-raiz no monorepo; "" = raiz do repo
+    catalog: str = ""     # catálogo/conta/região (qualificador superior)
+    namespace: str = ""   # schema/database/módulo (qualificador inferior)
+    environment: str = "" # qualificador opcional de ambiente
+    snapshot: str = ""    # escopo de revisão; "" = identidade lógica
+
+    def __post_init__(self) -> None:
+        for f in ("domain", "repository", "qualified_name", "root",
+                  "catalog", "namespace", "environment", "snapshot"):
+            object.__setattr__(self, f, getattr(self, f).strip())
+        for f in ("domain", "repository", "qualified_name"):
+            if not getattr(self, f):
+                raise ValueError(f"domain identity requires {f}")
+
+    def _segments(self, *, include_snapshot: bool) -> tuple[str, ...]:
+        seg = (
+            self.domain, self.repository, self.root, self.catalog,
+            self.namespace, self.environment, self.qualified_name,
+        )
+        if include_snapshot:
+            return (*seg, self.snapshot)
+        return seg
+
+    def canonical_key(self) -> str:
+        """Chave canônica completa (inclui ``snapshot`` quando presente).
+
+        Formato posicional ``dom:<seg>/<seg>/…`` com cada segmento
+        percent-encodado — colisão só se **todos** os componentes forem
+        idênticos.
+        """
+        segs = "/".join(_enc(s) for s in self._segments(include_snapshot=True))
+        return f"{_SCHEME}:{segs}"
+
+    def logical_key(self) -> str:
+        """Chave lógica (sem ``snapshot``) — identidade por repositório."""
+        segs = "/".join(_enc(s) for s in self._segments(include_snapshot=False))
+        return f"{_SCHEME}:{segs}"
+
+    def logical(self) -> DomainIdentity:
+        """Identidade lógica equivalente (``snapshot=""``)."""
+        if not self.snapshot:
+            return self
+        return DomainIdentity(
+            domain=self.domain, repository=self.repository,
+            qualified_name=self.qualified_name, root=self.root,
+            catalog=self.catalog, namespace=self.namespace,
+            environment=self.environment,
+        )
+
+    def display(self) -> str:
+        """Forma legível para humanos (não usada como chave)."""
+        head = ".".join(p for p in (self.catalog, self.namespace) if p)
+        qname = f"{head}.{self.qualified_name}" if head else self.qualified_name
+        env = f"@{self.environment}" if self.environment else ""
+        return f"{self.domain}:{qname}{env}"
+
+    @staticmethod
+    def parse_key(key: str) -> tuple[str, ...] | None:
+        """Decodifica os segmentos de uma chave ``dom:…``; None se inválida."""
+        if not key.startswith(f"{_SCHEME}:"):
+            return None
+        body = key[len(_SCHEME) + 1:]
+        return tuple(_dec(seg) for seg in body.split(_SEP))

code_atlas/domains/model.py

@@ -0,0 +1,202 @@
+"""Modelo unificado de entidades/relações de domínio (lf-0110, Cycle 7).
+
+Vocabulário fechado do prompt Cycle 7 (Phases 1+2): adapters extraem
+**somente** estes kinds — qualquer extensão exige spec + ADR. ``TESTS`` e
+``REFERENCES`` são compartilhados com ``EdgeKind`` (mesmo valor semântico).
+
+``REPOSITORY``/``PROJECT`` aqui são entidades de **domínio** (ex.: um repo
+federado referenciado por um workflow CI/CD), distintos de
+``NodeKind.REPOSITORY`` — nó do grafo de código já coberto pelo modelo de
+símbolos. Camadas diferentes, tabelas diferentes.
+
+Persistência (ADR-0010): entidades de domínio NÃO reutilizam a tabela
+``symbols`` — a identidade delas inclui ``catalog``/``namespace``/
+``environment``, que o UNIQUE de ``symbols`` (repo, language, qname, kind)
+não consegue expressar (duas tabelas ``orders`` de catálogos distintos
+colidiriam). Schema dedicado na migração v9.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from code_atlas.contracts.enums import ConfidenceClass, EdgeKind, ResolutionStatus
+from code_atlas.contracts.models import _coerce
+from code_atlas.domains.identity import DomainIdentity
+
+
+class DomainEntityKind(StrEnum):
+    """Tipos de entidade de domínio (prompt Cycle 7 — vocabulário fechado)."""
+
+    DATA_TABLE = "data_table"
+    DATA_COLUMN = "data_column"
+    DATA_VIEW = "data_view"
+    DATA_TRANSFORMATION = "data_transformation"
+    DATA_PIPELINE = "data_pipeline"
+    SPARK_JOB = "spark_job"
+    GLUE_JOB = "glue_job"
+    DATA_CATALOG = "data_catalog"
+    ICEBERG_TABLE = "iceberg_table"
+    API_ENDPOINT = "api_endpoint"
+    API_SERVICE = "api_service"
+    API_CONTRACT = "api_contract"
+    TERRAFORM_RESOURCE = "terraform_resource"
+    TERRAFORM_MODULE = "terraform_module"
+    IAM_ROLE = "iam_role"
+    CICD_WORKFLOW = "cicd_workflow"
+    CICD_JOB = "cicd_job"
+    REPOSITORY = "repository"  # entidade de federação (lf-0118), ≠ NodeKind
+    PROJECT = "project"
+
+
+class DomainRelationKind(StrEnum):
+    """Relações de domínio (prompt Cycle 7 — vocabulário fechado)."""
+
+    READS_FROM = "READS_FROM"
+    WRITES_TO = "WRITES_TO"
+    TRANSFORMS = "TRANSFORMS"
+    DERIVES_FROM = "DERIVES_FROM"
+    DEPENDS_ON = "DEPENDS_ON"
+    CALLS_ENDPOINT = "CALLS_ENDPOINT"
+    IMPLEMENTS_CONTRACT = "IMPLEMENTS_CONTRACT"
+    PROVISIONS = "PROVISIONS"
+    USES_RESOURCE = "USES_RESOURCE"
+    ASSUMES_ROLE = "ASSUMES_ROLE"
+    TRIGGERS = "TRIGGERS"
+    DEPLOYS = "DEPLOYS"
+    TESTS = "TESTS"          # valor compartilhado com EdgeKind.TESTS
+    REFERENCES = "REFERENCES"  # valor compartilhado com EdgeKind.REFERENCES
+
+
+# Vocabulário aceito em domain_relations.type: as relações de domínio mais
+# o vocabulário estrutural (CONTAINS módulo→recurso, IMPORTS de tf module…).
+DOMAIN_RELATION_TYPES: frozenset[str] = frozenset(
+    {str(k) for k in DomainRelationKind} | {str(k) for k in EdgeKind}
+)
+
+
+@dataclass(frozen=True)
+class DomainEntity:
+    """Entidade lógica de domínio — estável por repositório.
+
+    ``id`` é a row id em ``domain_entities`` (``None`` = a persistir);
+    ``attributes`` carrega observáveis específicos do domínio (ddl
+    resumido, tipo de recurso, provider) como strings — nada de blobs
+    arbitrários nem segredos.
+    """
+
+    identity: DomainIdentity
+    kind: DomainEntityKind
+    name: str
+    attributes: Mapping[str, str] = field(default_factory=dict)
+    id: int | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "kind", _coerce(DomainEntityKind, self.kind, "kind")
+        )
+        if not self.name.strip():
+            raise ValueError("domain entity requires name")
+        object.__setattr__(
+            self,
+            "attributes",
+            {str(k): str(v) for k, v in self.attributes.items()},
+        )
+
+    @property
+    def domain(self) -> str:
+        return self.identity.domain
+
+    @property
+    def qualified_name(self) -> str:
+        return self.identity.qualified_name
+
+    def identity_key(self) -> str:
+        """Chave lógica persistida em ``domain_entities.identity_key``."""
+        return self.identity.logical_key()
+
+
+@dataclass(frozen=True)
+class DomainEntityOccurrence:
+    """Ocorrência de uma entidade num snapshot (span/hash da ocorrência).
+
+    ``source_file_id=None`` é permitido apenas para entidades sintetizadas
+    por derivação declarada (ex.: catálogo agregado) — o caso normal é
+    evidence-first: entidade observada num arquivo do inventário.
+    """
+
+    snapshot_id: int
+    entity_id: int
+    source_file_id: int | None
+    id: int | None = None
+    span_start: int | None = None
+    span_end: int | None = None
+    line: int | None = None
+    col: int | None = None
+    content_hash: str | None = None
+    attributes: Mapping[str, str] = field(default_factory=dict)
+    extraction_status: str = "extracted"  # extracted | partial | failed
+
+
+@dataclass(frozen=True)
+class DomainRelation:
+    """Aresta de domínio com proveniência obrigatória (espelha ``Relation``).
+
+    Endpoints podem ser ocorrências de entidade de domínio OU de símbolo
+    de código — a ponte código↔domínio (lf-0117/0120) precisa das duas
+    direções sem nova migração. Exige-se ≥1 endpoint de origem e ≥1 alvo
+    (ou ``to_unresolved`` honesto).
+
+    Invariante inegociável (spec): evidência ``inferred`` NUNCA é
+    promovida a ``resolved``.
+    """
+
+    snapshot_id: int
+    relation_type: str
+    resolver: str
+    confidence_class: ConfidenceClass
+    resolution_status: ResolutionStatus
+    id: int | None = None
+    from_entity_occ_id: int | None = None
+    from_symbol_occ_id: int | None = None
+    to_entity_occ_id: int | None = None
+    to_symbol_occ_id: int | None = None
+    to_unresolved: str | None = None
+    evidence_ids: tuple[int, ...] = ()
+
+    def __post_init__(self) -> None:
+        t = str(self.relation_type)
+        if t not in DOMAIN_RELATION_TYPES:
+            raise ValueError(f"invalid relation_type: {self.relation_type!r}")
+        object.__setattr__(self, "relation_type", t)
+        object.__setattr__(
+            self,
+            "confidence_class",
+            _coerce(ConfidenceClass, self.confidence_class, "confidence_class"),
+        )
+        object.__setattr__(
+            self,
+            "resolution_status",
+            _coerce(ResolutionStatus, self.resolution_status, "resolution_status"),
+        )
+        if self.from_entity_occ_id is None and self.from_symbol_occ_id is None:
+            raise ValueError("domain relation requires a from endpoint")
+        if (
+            self.to_entity_occ_id is None
+            and self.to_symbol_occ_id is None
+            and not self.to_unresolved
+        ):
+            raise ValueError(
+                "domain relation requires to endpoint or to_unresolved"
+            )
+        if not self.resolver:
+            raise ValueError("domain relation requires resolver provenance")
+        if (
+            self.confidence_class is ConfidenceClass.INFERRED
+            and self.resolution_status is ResolutionStatus.RESOLVED
+        ):
+            raise ValueError(
+                "inferred evidence can never be reported resolved"
+            )

code_atlas/domains/registry.py

@@ -0,0 +1,250 @@
+"""Registro de adaptadores de domínio (lf-0110, Cycle 7).
+
+**Registro explícito** (mesmo desenho de ``ResolverRegistry``, ADR-0010):
+nenhum adapter é ativado por padrão, nenhum código de terceiros é
+carregado por varredura automática. ``discover_entrypoints`` existe como
+mecanismo **opt-in** — só roda quando o caller invoca explicitamente.
+
+Semântica honesta de ausência: domínio não registrado NÃO é erro de
+extração — adapters são opcionais (spec). ``get`` devolve ``None``;
+``require`` levanta exceção tipada para quem precisa do domínio.
+Adapters desabilitados produzem **nada**: ``enabled()`` os exclui e
+``require`` recusa.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import re
+from collections.abc import Callable
+
+from code_atlas.domains.contracts import DomainAdapter
+
+ENTRYPOINT_GROUP = "code_atlas.domain_adapters"
+
+
+class AdapterRegistryError(Exception):
+    """Falha de registro/lookup de adapter de domínio."""
+
+
+class UnknownDomainError(AdapterRegistryError):
+    """Domínio requerido não está registrado."""
+
+
+class AdapterDisabledError(AdapterRegistryError):
+    """Domínio registrado mas desabilitado — não produz extração."""
+
+
+class DuplicateAdapterError(AdapterRegistryError):
+    """Par (domain_id, adapter_version) já registrado."""
+
+
+def _version_key(version: str) -> tuple[tuple[int, ...], str]:
+    """Chave de ordenação semver-ish: segmentos numéricos + tiebreak lexical."""
+    nums = tuple(int(p) for p in re.findall(r"\d+", version))
+    return (nums, version)
+
+
+def _check_adapter(adapter: DomainAdapter) -> None:
+    """Validação mínima do contrato no momento do registro."""
+    if not isinstance(adapter, DomainAdapter):
+        raise AdapterRegistryError(
+            f"object does not satisfy DomainAdapter: {adapter!r}"
+        )
+    if not adapter.domain_id.strip():
+        raise AdapterRegistryError("adapter requires non-empty domain_id")
+    if not adapter.adapter_version.strip():
+        raise AdapterRegistryError(
+            f"adapter {adapter.domain_id!r} requires non-empty version"
+        )
+    adapter.entity_kinds()      # materializa — valida early
+    adapter.relation_kinds()
+    adapter.confidence_model()
+
+
+class DomainRegistry:
+    """Registro explícito de adapters de domínio com versionamento.
+
+    ``register`` nunca substitui silenciosamente: mesmo ``domain_id`` com
+    versões distintas convivem (rastreabilidade de upgrade); mesma versão
+    registrada duas vezes é ``DuplicateAdapterError``.
+    """
+
+    def __init__(self) -> None:
+        self._adapters: dict[str, dict[str, DomainAdapter]] = {}
+        self._disabled: set[str] = set()
+        self._entrypoint_errors: list[str] = []
+
+    # --- registro ----------------------------------------------------
+
+    def register(self, adapter: DomainAdapter, *, enabled: bool = True) -> None:
+        """Registra ``adapter``; ``enabled=False`` registra desabilitado."""
+        _check_adapter(adapter)
+        versions = self._adapters.setdefault(adapter.domain_id, {})
+        if adapter.adapter_version in versions:
+            raise DuplicateAdapterError(
+                f"adapter already registered: "
+                f"{adapter.domain_id}@{adapter.adapter_version}"
+            )
+        versions[adapter.adapter_version] = adapter
+        if not enabled:
+            self._disabled.add(adapter.domain_id)
+
+    def unregister(self, domain_id: str, version: str | None = None) -> bool:
+        """Remove ``version`` (ou todas quando ``None``). True se removeu."""
+        versions = self._adapters.get(domain_id)
+        if not versions:
+            return False
+        if version is None:
+            del self._adapters[domain_id]
+            self._disabled.discard(domain_id)
+            return True
+        if version not in versions:
+            return False
+        del versions[version]
+        if not versions:
+            del self._adapters[domain_id]
+            self._disabled.discard(domain_id)
+        return True
+
+    def discover_entrypoints(
+        self, group: str = ENTRYPOINT_GROUP
+    ) -> int:
+        """Carrega adapters declarados via ``entry_points`` instalados.
+
+        **Opt-in explícito** — nunca chamado automaticamente (ADR-0010):
+        importar código de terceiros é decisão do caller, não do
+        registry. Cada entry point deve resolver para um
+        ``DomainAdapter`` ou uma fábrica ``() -> DomainAdapter``.
+        Falhas são registradas em ``entrypoint_errors`` e não abortam
+        os demais. Retorna quantos adapters foram registrados.
+        """
+        loaded = 0
+        for ep in importlib.metadata.entry_points(group=group):
+            try:
+                target = ep.load()
+                adapter: DomainAdapter = (
+                    target() if callable(target) else target
+                )
+                self.register(adapter)
+            except Exception as exc:  # diagnóstico honesto, não crash
+                self._entrypoint_errors.append(f"{ep.name}: {exc}")
+                continue
+            loaded += 1
+        return loaded
+
+    @property
+    def entrypoint_errors(self) -> tuple[str, ...]:
+        return tuple(self._entrypoint_errors)
+
+    # --- enable / disable --------------------------------------------
+
+    def enable(self, domain_id: str) -> None:
+        if domain_id not in self._adapters:
+            raise UnknownDomainError(f"domain not registered: {domain_id!r}")
+        self._disabled.discard(domain_id)
+
+    def disable(self, domain_id: str) -> None:
+        if domain_id not in self._adapters:
+            raise UnknownDomainError(f"domain not registered: {domain_id!r}")
+        self._disabled.add(domain_id)
+
+    def is_enabled(self, domain_id: str) -> bool:
+        return (
+            domain_id in self._adapters and domain_id not in self._disabled
+        )
+
+    # --- lookup --------------------------------------------------------
+
+    def _pick(self, domain_id: str, version: str | None) -> DomainAdapter | None:
+        versions = self._adapters.get(domain_id)
+        if not versions:
+            return None
+        if version is not None:
+            return versions.get(version)
+        if len(versions) == 1:
+            return next(iter(versions.values()))
+        # versão mais alta por ordenação semver-ish — determinístico
+        return versions[max(versions, key=_version_key)]
+
+    def get(
+        self, domain_id: str, version: str | None = None
+    ) -> DomainAdapter | None:
+        """Adapter registrado (habilitado ou não); ``None`` se ausente.
+
+        ``version=None`` retorna a maior versão registrada.
+        """
+        return self._pick(domain_id, version)
+
+    def require(
+        self, domain_id: str, version: str | None = None
+    ) -> DomainAdapter:
+        """Adapter **habilitado** ou exceção tipada e honesta.
+
+        - não registrado → ``UnknownDomainError``;
+        - registrado mas desabilitado → ``AdapterDisabledError``;
+        - versão inexistente → ``UnknownDomainError`` com detalhe.
+        """
+        versions = self._adapters.get(domain_id)
+        if not versions:
+            raise UnknownDomainError(f"domain not registered: {domain_id!r}")
+        if domain_id in self._disabled:
+            raise AdapterDisabledError(f"domain disabled: {domain_id!r}")
+        adapter = self._pick(domain_id, version)
+        if adapter is None:
+            raise UnknownDomainError(
+                f"version not registered: {domain_id!r}@{version!r}"
+            )
+        return adapter
+
+    # --- inventário ------------------------------------------------------
+
+    def versions(self, domain_id: str) -> tuple[str, ...]:
+        """Versões registradas do domínio, ordenadas."""
+        versions = self._adapters.get(domain_id, {})
+        return tuple(sorted(versions, key=_version_key))
+
+    def domains(self) -> tuple[str, ...]:
+        return tuple(sorted(self._adapters))
+
+    def adapters(self) -> tuple[DomainAdapter, ...]:
+        """Todos os adapters registrados (habilitados e desabilitados)."""
+        return tuple(
+            a for versions in self._adapters.values() for a in versions.values()
+        )
+
+    def enabled(self) -> tuple[DomainAdapter, ...]:
+        """Adapters habilitados — maior versão por domínio.
+
+        É o conjunto de extração: domínio desabilitado ou não registrado
+        produz exatamente zero entidades/relações.
+        """
+        out: list[DomainAdapter] = []
+        for domain_id in sorted(self._adapters):
+            if domain_id in self._disabled:
+                continue
+            picked = self._pick(domain_id, None)
+            if picked is not None:
+                out.append(picked)
+        return tuple(out)
+
+    def discovery_candidates(self, paths: list[str]) -> dict[str, list[str]]:
+        """Mapa ``domain_id → paths`` suportados pelos adapters habilitados.
+
+        Filtro puro por ``ArtifactSupport`` — não executa adapters.
+        """
+        out: dict[str, list[str]] = {}
+        for adapter in self.enabled():
+            support = adapter.supported_artifacts()
+            out[adapter.domain_id] = [p for p in paths if support.matches(p)]
+        return out
+
+
+def default_registry(
+    factories: tuple[Callable[[], DomainAdapter], ...] = (),
+) -> DomainRegistry:
+    """Constrói um registry populado por fábricas explícitas do caller."""
+    reg = DomainRegistry()
+    for f in factories:
+        reg.register(f())
+    return reg