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

code_atlas/domains/resolution.py

@@ -0,0 +1,65 @@
+"""Estado de resolução de alvos de relações de domínio (lf-0110).
+
+Reutiliza o vocabulário ``ResolutionStatus`` (resolved / ambiguous /
+unresolved / external) e ``ConfidenceClass`` — nenhum valor novo.
+
+Invariantes (spec Cycle 7 — "estados honestos de resolução"):
+
+- ``resolved`` exige ``target`` (identidade canônica do alvo);
+- ``ambiguous`` exige ≥2 candidatos — nunca "resolved por sorte";
+- ``external`` pode carregar ``target`` (identidade conhecida, fora do
+  snapshot — ex.: ARN de recurso real, tabela de outro repo federado);
+- ``inferred`` **nunca** é promovida a ``resolved`` — evidência inferida
+  no máximo sustenta ``ambiguous``/``external``/``unresolved``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from code_atlas.contracts.enums import ConfidenceClass, ResolutionStatus
+from code_atlas.contracts.models import _coerce
+from code_atlas.domains.identity import DomainIdentity
+
+
+@dataclass(frozen=True)
+class DomainResolution:
+    """Desfecho tipado da resolução de um alvo de relação de domínio."""
+
+    status: ResolutionStatus
+    confidence_class: ConfidenceClass
+    resolver: str                       # id do adapter/resolver produtor
+    target: DomainIdentity | None = None
+    candidates: tuple[DomainIdentity, ...] = field(default_factory=tuple)
+    unresolved_text: str = ""           # alvo textual preservado
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "status", _coerce(ResolutionStatus, self.status, "status")
+        )
+        object.__setattr__(
+            self,
+            "confidence_class",
+            _coerce(ConfidenceClass, self.confidence_class, "confidence_class"),
+        )
+        if not self.resolver:
+            raise ValueError("domain resolution requires resolver provenance")
+        if self.status is ResolutionStatus.RESOLVED and self.target is None:
+            raise ValueError("resolved status requires target identity")
+        if (
+            self.status is ResolutionStatus.AMBIGUOUS
+            and len(self.candidates) < 2
+        ):
+            raise ValueError("ambiguous status requires >=2 candidates")
+        if (
+            self.status in (ResolutionStatus.UNRESOLVED,)
+            and self.target is not None
+        ):
+            raise ValueError("unresolved status cannot carry a target")
+        if (
+            self.confidence_class is ConfidenceClass.INFERRED
+            and self.status is ResolutionStatus.RESOLVED
+        ):
+            raise ValueError(
+                "inferred evidence can never be reported resolved"
+            )

code_atlas/domains/spark/__init__.py

@@ -0,0 +1,31 @@
+"""Adapter de domínio ``pyspark`` — linhagem estática de DataFrames.
+
+Implementação de ``factory/specs/inbox/lf-0112-cycle7-pyspark-adapter.md``
+(Cycle 7, Phase 4). Análise ``ast`` stdlib pura — sem regex-parser,
+sem execução de código, sem dependência de ``pyspark`` instalado.
+
+Costuras públicas:
+
+- ``PySparkAdapter`` — facade ``DomainAdapter``;
+- ``extract(request, version, base)`` — driver por request;
+- ``delegate_sql_literal`` — costura ``spark.sql(literal)`` → adapter
+  ``sql`` (lf-0111).
+"""
+
+from code_atlas.domains.spark.adapter import (
+    ADAPTER_VERSION,
+    DOMAIN_ID,
+    PySparkAdapter,
+    satisfies_protocol,
+)
+from code_atlas.domains.spark.extract import extract
+from code_atlas.domains.spark.sqllit import delegate_sql_literal
+
+__all__ = [
+    "ADAPTER_VERSION",
+    "DOMAIN_ID",
+    "PySparkAdapter",
+    "delegate_sql_literal",
+    "extract",
+    "satisfies_protocol",
+]

code_atlas/domains/spark/adapter.py

@@ -0,0 +1,146 @@
+"""``PySparkAdapter`` — adapter de domínio PySpark (lf-0112, Cycle 7 Ph.4).
+
+Linhagem estática de DataFrames sobre artefatos ``.py`` — análise
+``ast`` pura, zero execução, zero imports de ``pyspark``:
+
+- sessões: ``spark``/``spark_session``/``sparkSession`` implícitas
+  (notebook), ``SparkSession.builder…getOrCreate()``,
+  ``getActiveSession()`` e ``self.spark``;
+- leituras: ``spark.read.table|parquet|csv|json|jdbc|format(…).load``,
+  ``spark.table`` — tabelas de catálogo e paths nunca se confundem;
+- SQL: ``spark.sql("literal")`` delega ao parser/extrator do adapter
+  ``sql`` (lf-0111) — CTEs colapsam, ``SELECT *`` é diagnóstico, e o
+  resultado é re-ancorado na transformação do call-site;
+- transforms: ``select/filter/join/groupBy/agg/union/withColumn/
+  dropDuplicates/withColumnRenamed`` + família completa de ops
+  ``DataFrame → DataFrame``;
+- writes: ``df.write.parquet|saveAsTable|insertInto|mode(…).<fmt>``,
+  ``df.writeTo(t).<terminal>`` (Iceberg-style, ``iceberg_table``);
+- honestidade: alvos dinâmicos (``f-string``, variáveis não-literal),
+  receivers desconhecidos e SQL dinâmico viram ``to_unresolved`` +
+  diagnóstico — nenhuma relação fabricada, nenhum ``resolved`` local.
+
+Leitura de artefatos (mesmo desenho do ``SqlDomainAdapter``):
+``base_path`` resolve os paths relativos de ``DiscoveredArtifact``;
+``None`` trata os paths como estão. O adapter nunca lê fora do
+request, nunca executa jobs e nunca abre rede.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from code_atlas.contracts.enums import ConfidenceClass, EdgeKind
+from code_atlas.domains.contracts import (
+    ArtifactSupport,
+    ConfidenceModel,
+    DiscoveryRule,
+    DomainDiagnostic,
+    DomainExtractionRequest,
+    DomainExtractionResult,
+)
+from code_atlas.domains.model import DomainEntityKind, DomainRelationKind
+from code_atlas.domains.spark.extract import extract as _extract
+
+DOMAIN_ID = "pyspark"
+ADAPTER_VERSION = "0.1.0"
+
+
+class PySparkAdapter:
+    """Adapter ``pyspark`` — linhagem estática de DataFrames."""
+
+    def __init__(self, base_path: str | Path | None = None) -> None:
+        self._base = (
+            Path(base_path) if base_path is not None else Path.cwd()
+        )
+
+    # -- contrato ------------------------------------------------------
+
+    @property
+    def domain_id(self) -> str:
+        return DOMAIN_ID
+
+    @property
+    def adapter_version(self) -> str:
+        return ADAPTER_VERSION
+
+    def supported_artifacts(self) -> ArtifactSupport:
+        return ArtifactSupport(extensions=frozenset({".py"}))
+
+    def entity_kinds(self) -> frozenset[DomainEntityKind]:
+        return frozenset(
+            {
+                DomainEntityKind.DATA_TABLE,
+                DomainEntityKind.DATA_VIEW,
+                DomainEntityKind.DATA_COLUMN,
+                DomainEntityKind.ICEBERG_TABLE,
+                DomainEntityKind.DATA_TRANSFORMATION,
+                DomainEntityKind.SPARK_JOB,
+            }
+        )
+
+    def relation_kinds(self) -> frozenset[str]:
+        return frozenset(
+            {
+                str(DomainRelationKind.READS_FROM),
+                str(DomainRelationKind.WRITES_TO),
+                str(DomainRelationKind.TRANSFORMS),
+                str(DomainRelationKind.DERIVES_FROM),
+                # job CONTAINS transformation — vocabulário estrutural
+                # compartilhado (EdgeKind) permitido pelo schema v9
+                str(EdgeKind.CONTAINS),
+            }
+        )
+
+    def confidence_model(self) -> ConfidenceModel:
+        # Extração estritamente evidence-first: o que o AST não
+        # estabelece sai como diagnóstico/unresolved — nunca promovido.
+        return ConfidenceModel(
+            ceiling=ConfidenceClass.SYNTACTIC,
+            default=ConfidenceClass.SYNTACTIC,
+            allows_inferred=False,
+            notes="static PySpark DataFrame lineage; dynamic sql/paths/"
+            "unresolvable receivers are diagnosed, never resolved",
+        )
+
+    def discovery_rules(self) -> tuple[DiscoveryRule, ...]:
+        return (
+            DiscoveryRule(
+                glob="*.py",
+                artifact_kind="pyspark-job",
+                notes=(
+                    "Python files are scanned for SparkSession usage "
+                    "(spark.read/spark.sql/df.write) — non-Spark .py "
+                    "files are ignored silently"
+                ),
+            ),
+        )
+
+    # -- extract ---------------------------------------------------------
+
+    def extract(
+        self, request: DomainExtractionRequest
+    ) -> DomainExtractionResult:
+        try:
+            return _extract(
+                request, self.adapter_version, self._base
+            )
+        except Exception as exc:  # última linha de defesa — nunca levanta
+            return DomainExtractionResult(
+                domain_id=self.domain_id,
+                adapter_version=self.adapter_version,
+                diagnostics=(
+                    DomainDiagnostic(
+                        code="adapter-failure",
+                        severity="error",
+                        message=f"pyspark adapter failure: {exc!r}",
+                        adapter_id=self.domain_id,
+                    ),
+                ),
+            )
+
+
+def satisfies_protocol() -> PySparkAdapter:
+    """Smoke check para tests: a instância satisfaz ``DomainAdapter``."""
+    adapter: PySparkAdapter = PySparkAdapter()
+    return adapter

code_atlas/domains/spark/emit.py

@@ -0,0 +1,344 @@
+"""Sink de emissão do adapter ``domains.spark`` (lf-0112, Phase 4).
+
+Acumulador **por request** (não por arquivo): entidades dedupam por
+``logical_key`` com evidência unida e o atributo ``roles`` fundido
+(``read``/``write``); relações dedupam por ``(tipo, origem, alvo)``
+acumulando evidência — mesma disciplina dos sinks ``sql``/``api``.
+
+Também mantém os índices de linhagem do domínio:
+
+- ``sources``: para cada transformação materializada, o conjunto de
+  fontes terminais (tabelas/paths) que a alimentam — base do colapso
+  ``sink DERIVES_FROM fonte`` nos writes;
+- ``view_sources``: fontes terminais de temp views registradas —
+  ``FROM v`` dentro de literais ``spark.sql`` colapsa além do alias.
+
+Resolução honesta: alvo ``to_identity`` sai sem ``resolution`` (o
+coordinator resolve pela ocorrência no snapshot); ``to_unresolved``
+carrega ``DomainResolution(UNRESOLVED, syntactic)`` — nunca ``resolved``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from code_atlas.contracts.enums import ConfidenceClass, ResolutionStatus
+from code_atlas.domains.contracts import (
+    DomainDiagnostic,
+    DomainExtractionRequest,
+    DomainExtractionResult,
+    ExtractedDomainEntity,
+    ExtractedDomainRelation,
+)
+from code_atlas.domains.evidence import domain_extractor_id, evidence_record
+from code_atlas.domains.identity import DomainIdentity
+from code_atlas.domains.model import DomainEntityKind
+from code_atlas.domains.resolution import DomainResolution
+from code_atlas.parsers.contracts import EvidenceRecord, SourceSpan
+
+DOMAIN_ID = "pyspark"
+
+_DIAG_CAP = 60  # diagnósticos por request — depois vira resumo
+
+_SCHEME_RE = re.compile(r"^([a-zA-Z][a-zA-Z0-9+.-]*)://")
+_BACKTICK_RE = re.compile(r"^`(.*)`$")
+
+
+def split_table_name(literal: str) -> tuple[str, ...] | None:
+    """``"cat.db.t"`` → partes; backticks por segmento são removidos.
+
+    ``None`` quando o literal é vazio ou carrega marcador dinâmico
+    (``${}``/``{{}}``) — o caller emite ``to_unresolved``, nunca fabrica.
+    """
+    lit = literal.strip()
+    if not lit or "${" in lit or "{{" in lit:
+        return None
+    parts: list[str] = []
+    for raw in lit.split("."):
+        p = raw.strip()
+        m = _BACKTICK_RE.match(p)
+        if m:
+            p = m.group(1)
+        if not p:
+            return None
+        parts.append(p)
+    return tuple(parts)
+
+
+def uri_scheme(literal: str) -> str:
+    """Esquema de URI do path (``s3a``, ``hdfs``, ``file``) ou ``""``."""
+    m = _SCHEME_RE.match(literal.strip())
+    return m.group(1).lower() if m else ""
+
+
+@dataclass
+class _EntAcc:
+    entity: ExtractedDomainEntity
+    ev: set[int] = field(default_factory=set)
+    roles: set[str] = field(default_factory=set)
+    # mesmo objeto dict passado ao ExtractedDomainEntity — mutável
+    # (a entidade expõe Mapping; aqui vive a visão de escrita)
+    attrs: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class _RelAcc:
+    rel: ExtractedDomainRelation
+    ev: set[int] = field(default_factory=set)
+
+
+class Sink:
+    """Acumulador determinístico da saída de ``extract``."""
+
+    def __init__(
+        self, request: DomainExtractionRequest, adapter_version: str
+    ) -> None:
+        self.request = request
+        self.version = adapter_version
+        self.entities: dict[str, _EntAcc] = {}
+        self.relations: dict[tuple[str, str, str], _RelAcc] = {}
+        self.evidence: list[EvidenceRecord] = []
+        self._evidx: dict[tuple[str, int], int] = {}
+        self.diagnostics: list[DomainDiagnostic] = []
+        self._truncated = 0
+        self.stats: dict[str, int] = {}
+        self.sources: dict[str, set[str]] = {}
+        self.view_sources: dict[str, set[str]] = {}
+        self._diag_seen: set[tuple[str, str]] = set()
+
+    # -- evidência / diagnóstico ----------------------------------------
+
+    def evi(
+        self,
+        path: str,
+        sha: str,
+        span: SourceSpan | None,
+        notes: str = "",
+    ) -> int:
+        """Evidência dedup por ``(path, start_byte)`` → índice no envelope."""
+        key = (path, span.start_byte if span else -1)
+        idx = self._evidx.get(key)
+        if idx is not None:
+            return idx
+        self.evidence.append(
+            evidence_record(
+                adapter_domain=DOMAIN_ID,
+                adapter_version=self.version,
+                path=path,
+                content_hash=sha,
+                span=span,
+                notes=notes,
+            )
+        )
+        idx = len(self.evidence) - 1
+        self._evidx[key] = idx
+        return idx
+
+    def diag(
+        self, code: str, severity: str, message: str, path: str = ""
+    ) -> None:
+        if (code, message) in self._diag_seen:
+            return
+        self._diag_seen.add((code, message))
+        if len(self.diagnostics) >= _DIAG_CAP:
+            self._truncated += 1
+            return
+        self.diagnostics.append(
+            DomainDiagnostic(
+                code=code, severity=severity, message=message,
+                path=path, adapter_id=DOMAIN_ID,
+            )
+        )
+
+    def bump(self, stat: str, n: int = 1) -> None:
+        self.stats[stat] = self.stats.get(stat, 0) + n
+
+    def set_entity_attr(self, key: str, name: str, value: str) -> None:
+        """Escreve atributo numa entidade já registrada (``logical_key``)."""
+        acc = self.entities.get(key)
+        if acc is not None:
+            acc.attrs[name] = value
+
+    # -- identidades ------------------------------------------------------
+
+    def table_ident(self, parts: tuple[str, ...]) -> DomainIdentity:
+        """catalog/namespace/qualified_name a partir das partes do nome."""
+        req = self.request
+        if len(parts) >= 3:
+            catalog, namespace, name = (
+                parts[0], ".".join(parts[1:-1]), parts[-1]
+            )
+        elif len(parts) == 2:
+            catalog, namespace, name = "", parts[0], parts[1]
+        else:
+            catalog, namespace, name = "", "", parts[0]
+        return DomainIdentity(
+            domain=DOMAIN_ID, repository=req.repository, root=req.root,
+            catalog=catalog, namespace=namespace,
+            environment=req.environment, qualified_name=name,
+        )
+
+    def path_ident(self, literal: str) -> DomainIdentity:
+        """Entidade de path (s3/hdfs/file) — NUNCA confundida com tabela.
+
+        ``qualified_name`` é o literal verbatim (sem namespace/catalog
+        de tabela); ``uri_scheme`` vai para os atributos da entidade.
+        """
+        req = self.request
+        return DomainIdentity(
+            domain=DOMAIN_ID, repository=req.repository, root=req.root,
+            environment=req.environment, qualified_name=literal.strip(),
+        )
+
+    def transform_ident(self, path: str, anchor: str) -> DomainIdentity:
+        """Entidade ``data_transformation`` — âncora ``<var>@<line>``."""
+        req = self.request
+        return DomainIdentity(
+            domain=DOMAIN_ID, repository=req.repository, root=req.root,
+            environment=req.environment,
+            qualified_name=f"{path}#{anchor}",
+        )
+
+    def retag(self, ident: DomainIdentity) -> DomainIdentity:
+        """Mesma posição de identidade, domínio ``pyspark``.
+
+        Usado no remap da delegação ``spark.sql``: o adapter ``sql``
+        emite ``domain="sql"`` — o contrato exige que tudo que este
+        adapter emite carregue ``domain="pyspark"``.
+        """
+        return DomainIdentity(
+            domain=DOMAIN_ID, repository=ident.repository,
+            root=ident.root, catalog=ident.catalog,
+            namespace=ident.namespace, environment=ident.environment,
+            qualified_name=ident.qualified_name,
+        )
+
+    # -- entidades / relações --------------------------------------------
+
+    def add_entity(
+        self,
+        ident: DomainIdentity,
+        kind: DomainEntityKind,
+        name: str,
+        *,
+        path: str = "",
+        span: SourceSpan | None = None,
+        content_hash: str = "",
+        attributes: dict[str, str] | None = None,
+        roles: tuple[str, ...] = (),
+        evidence: tuple[int, ...] = (),
+    ) -> DomainIdentity:
+        """Registra entidade; dedup por ``logical_key`` funde evidência."""
+        key = ident.logical_key()
+        acc = self.entities.get(key)
+        if acc is not None:
+            acc.ev.update(evidence)
+            acc.roles.update(roles)
+            # primeira observação vence por chave (``via`` registra a
+            # API que primeiro revelou a entidade); chaves novas entram
+            for k, v in (attributes or {}).items():
+                acc.attrs.setdefault(k, v)
+            return ident
+        attrs = dict(attributes or {})
+        acc = _EntAcc(
+            entity=ExtractedDomainEntity(
+                identity=ident, kind=kind, name=name, path=path,
+                span=span, content_hash=content_hash,
+                attributes=attrs, evidence=(),
+            ),
+            ev=set(evidence),
+            roles=set(roles),
+            attrs=attrs,
+        )
+        self.entities[key] = acc
+        return ident
+
+    def add_rel(
+        self,
+        rtype: str,
+        from_i: DomainIdentity,
+        *,
+        path: str,
+        to_i: DomainIdentity | None = None,
+        to_text: str = "",
+        span: SourceSpan | None = None,
+        evidence: tuple[int, ...] = (),
+        resolution: DomainResolution | None = None,
+    ) -> None:
+        """Relação dedup por (tipo, origem, alvo); evidência acumula."""
+        to_key = to_i.logical_key() if to_i is not None else f"text:{to_text}"
+        key = (rtype, from_i.logical_key(), to_key)
+        acc = self.relations.get(key)
+        if acc is not None:
+            acc.ev.update(evidence)
+            return
+        if resolution is None and to_i is None:
+            resolution = DomainResolution(
+                status=ResolutionStatus.UNRESOLVED,
+                confidence_class=ConfidenceClass.SYNTACTIC,
+                resolver=domain_extractor_id(DOMAIN_ID),
+                unresolved_text=to_text,
+            )
+        self.relations[key] = _RelAcc(
+            rel=ExtractedDomainRelation(
+                relation_type=rtype, path=path,
+                from_identity=from_i, to_identity=to_i,
+                to_unresolved=to_text, resolution=resolution,
+                span=span, evidence=(),
+            ),
+            ev=set(evidence),
+        )
+
+    # -- fechamento ---------------------------------------------------------
+
+    def finish(self) -> None:
+        if self._truncated:
+            self.diagnostics.append(
+                DomainDiagnostic(
+                    code="diagnostics-truncated", severity="info",
+                    message=(
+                        f"{self._truncated} further diagnostics "
+                        f"suppressed (cap {_DIAG_CAP})"
+                    ),
+                    path="", adapter_id=DOMAIN_ID,
+                )
+            )
+
+    def result(self) -> DomainExtractionResult:
+        entities = []
+        for acc in self.entities.values():
+            attrs = dict(acc.attrs)
+            if acc.roles:
+                attrs["roles"] = ",".join(sorted(acc.roles))
+            entities.append(
+                ExtractedDomainEntity(
+                    identity=acc.entity.identity, kind=acc.entity.kind,
+                    name=acc.entity.name, path=acc.entity.path,
+                    span=acc.entity.span,
+                    content_hash=acc.entity.content_hash,
+                    attributes=attrs, evidence=tuple(sorted(acc.ev)),
+                )
+            )
+        relations = [
+            ExtractedDomainRelation(
+                relation_type=acc.rel.relation_type, path=acc.rel.path,
+                from_identity=acc.rel.from_identity,
+                from_symbol=acc.rel.from_symbol,
+                to_identity=acc.rel.to_identity,
+                to_symbol=acc.rel.to_symbol,
+                to_unresolved=acc.rel.to_unresolved,
+                resolution=acc.rel.resolution,
+                span=acc.rel.span, evidence=tuple(sorted(acc.ev)),
+            )
+            for acc in self.relations.values()
+        ]
+        return DomainExtractionResult(
+            domain_id=DOMAIN_ID,
+            adapter_version=self.version,
+            entities=tuple(entities),
+            relations=tuple(relations),
+            evidence=tuple(self.evidence),
+            diagnostics=tuple(self.diagnostics),
+            stats=dict(self.stats),
+        )

code_atlas/domains/spark/extract.py

@@ -0,0 +1,108 @@
+"""Driver de extração por request do domínio ``pyspark`` (lf-0112).
+
+Ordem determinística: artefatos ordenados por ``path``; cada ``.py`` é
+lido uma vez (utf-8, bytes decodificados) e percorrido pelo walker
+AST. Falhas de leitura/decodificação viram diagnóstico; exceção
+inesperada do walker vira ``adapter-crash`` (error) — o adapter nunca
+propaga exceção para o coordinator.
+
+Isolamento: só lê os paths declarados em ``request.artifacts`` sob
+``base_path``; não escreve no disco, não executa código, não abre
+conexões.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from code_atlas.discovery.scanner import (
+    artifact_path_confined,
+    read_file_verified,
+)
+from code_atlas.domains.contracts import (
+    DomainExtractionRequest,
+    DomainExtractionResult,
+)
+from code_atlas.domains.spark.emit import Sink
+from code_atlas.domains.spark.walk import _Walker
+
+_MAX_BYTES = 2 * 1024 * 1024  # 2 MiB — acima disso: diagnóstico, skip
+
+
+def _read_artifact(
+    base_path: Path, rel_path: str, sink: Sink
+) -> tuple[str, str] | None:
+    """Lê o artefato → ``(texto, sha256-bytes)``; ``None`` + diag em falha."""
+    base = base_path.resolve()
+    # containment por pathlib — ``startswith`` em string aceitaria irmãos
+    # com prefixo comum (``/repo-evil`` sob ``/repo``); absoluto e ``..``
+    # no path do request são igualmente hostis (lf-c8 F7).
+    p = artifact_path_confined(rel_path, base)
+    if p is None:
+        sink.diag(
+            "artifact-outside-root", "warning",
+            f"{rel_path}: artifact path escapes repository root",
+            rel_path,
+        )
+        return None
+    raw = read_file_verified(p, base)
+    if raw is None:
+        sink.diag(
+            "read-error", "error",
+            "cannot read artifact: unsafe or vanished", rel_path,
+        )
+        return None
+    if len(raw) > _MAX_BYTES:
+        sink.diag(
+            "artifact-too-large", "info",
+            f"skipping {rel_path}: {len(raw)} bytes > {_MAX_BYTES}",
+            rel_path,
+        )
+        return None
+    sha = hashlib.sha256(raw).hexdigest()
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        sink.diag(
+            "decode-error", "error",
+            f"artifact is not valid utf-8: {exc}", rel_path,
+        )
+        return None
+    return text, sha
+
+
+def extract(
+    request: DomainExtractionRequest,
+    adapter_version: str,
+    base_path: Path,
+) -> DomainExtractionResult:
+    """Percorre ``request.artifacts`` (somente ``.py``) e extrai linhagem."""
+    sink = Sink(request, adapter_version)
+    for art in sorted(request.artifacts, key=lambda a: a.path):
+        if not art.path.lower().endswith(".py"):
+            sink.diag(
+                "unsupported-artifact", "info",
+                f"{art.path}: adapter extracts only Python (.py) "
+                f"artifacts — {art.artifact_kind or 'unknown'} skipped",
+                art.path,
+            )
+            sink.bump("files_skipped")
+            continue
+        got = _read_artifact(base_path, art.path, sink)
+        if got is None:
+            sink.bump("files_unreadable")
+            continue
+        text, sha = got
+        sink.bump("files_seen")
+        try:
+            _Walker(sink, art.path, sha, text).run()
+        except Exception as exc:  # honestidade: crash vira diagnóstico
+            sink.diag(
+                "adapter-crash", "error",
+                f"{type(exc).__name__} while walking {art.path}: {exc}",
+                art.path,
+            )
+            sink.bump("parse_errors")
+    sink.finish()
+    return sink.result()