audit(reproducibility): close the DL reproducibility contract & record pipeline identity in evidence

[FabioLeitao]

Context

Reproducibility audit of the detection path, prompted by review of the public "deterministic / reproducible" messaging. This is not a demonstrated divergence — it is a gap in closing the contract "same input + YAML → same evidence" for the DL path, across installs/platforms. The deterministic core (regex/rules + Clojure sidecar) is not in question.

Verified against the authoritative repo via gh api (not a local clone).

Findings

1. DL model loaded by name only — no revision/hash/local_files_only/device/dtype/determinism

• core/dl_backend.py:39 → DEFAULT_EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
• core/dl_backend.py:92 → self._embedder = _SentenceTransformer(embedding_model)
• Absent: revision=, local_files_only, weight sha256 verification, fixed device/dtype, torch.use_deterministic_algorithms, seeds (Python/NumPy/Torch), PYTHONHASHSEED, deterministic cuDNN.
• Surfaces: (a) upstream model-repo mutation; (b) CPU/CUDA float variation; (c) tokenization/embedding drift across versions.

2. Numeric/DL deps unpinned (>=, not ==)

• pyproject.toml: numpy>=2.4.6, pandas>=3.0.3, scipy>=1.17.0, scikit-learn>=1.9.0, dl = ["sentence-transformers>=5.5.1"].
• A future reinstall (pipx) may resolve different versions → different tokenization/embeddings/math.

3. Silent fallback changes the pipeline with no signal

• core/dl_backend.py:85,91-100 → init wrapped in try/except Exception sets self._ready = False (does not raise).
• core/detector.py:1225-1227 → constructs DLClassifier; drops it when not is_ready.
• core/detector.py:1438,1516 → DL used only if self._dl_classifier.is_ready.
• Result: host A (model loads) runs regex+ml+DL; host B (load fails) runs regex+ml. Both complete; results may differ — unrecorded. Legitimate graceful degradation, but it must appear in the evidence contract.

4. Evidence does not record pipeline identity (repo-wide)

• Absent across the repo: backends_active, regex_backend, ml_backend, embedding_revision, embedding_sha256, degradation_mode, dependency_lock (only reason_code exists, in core/extras_runtime.py, for extras).
• An operator comparing two runs cannot tell from the evidence that they compared different pipelines.

5. Current gate neither exercises DL nor validates cross-host output parity

• Gate scripts are supply-chain/security (grype, docker-scout, trailer-attest, tripwire) — not output parity across hosts.
• The dl extra does not appear in scripts/ or .github/ → the gate does not install/exercise DL. Cross-host DL reproducibility is unvalidated.

Impact on the public claim

We cannot certify "same input + YAML → same bytes" for the DL path across machines/reinstalls/dates. The deterministic core (regex/rules) holds. Public messaging ("byte-for-byte", "deterministic AI" spanning ML/DL) overreaches until the DL contract closes — the marketing site is being adjusted in parallel to "reproducible under pinned config; no LLM decides findings on the critical path".

The test bench already exists: Maestro + LabOp

The required "subprocess × reinstall × platform, byte-for-byte" test is a Maestro job over the min-spec gate hosts (alpine musl/no-AVX, T14 glibc/AVX, pi3b aarch64, Void, Zorin). alpine-emachines is the canary: torch/sentence-transformers most likely does not load there → silent fallback → a different pipeline than T14. Closing this contract = make the gate read the canary (the min-spec's long-intended 2nd axis, now named: reproducibility contract).

Acceptance criteria

• Pin the model by immutable revision=<commit-sha>; add local_files_only for governed/air-gapped runs; verify weight sha256 before load.
• Fix device (cpu default) and dtype (float32); torch.use_deterministic_algorithms(True); set Python/NumPy/Torch seeds + PYTHONHASHSEED; deterministic cuDNN when CUDA.
• Exact-pin the dl extra + numeric deps (or a lockfile) + dependency_lock_sha256.
• Record full pipeline identity in every evidence artifact: backends_active; regex_backend/ml_backend/dl_backend: active|unavailable; embedding_model/embedding_revision/embedding_sha256; device; dtype; config_sha256; dependency_lock_sha256. On fallback: dl_backend: unavailable, degradation_mode: regex+ml, reason_code: MODEL_LOAD_FAILED (no sensitive content/stack).
• Test: subprocess × reinstall × platform comparing canonical output byte-for-byte (or documented tolerance) — as a Maestro job over the gate hosts.
• Concurrency / input-ordering test (connector/worker ordering can change final output even when each classifier is deterministic).
• Verify/record current gate behavior: does smoke run the dl extra? does evidence now record backends per host?
• Widen automated proof of ML (TF-IDF + RF) determinism.
• Until closed: scope the claim (docs + site) to the deterministic core; DL = "reproducible under pinned config".
• Create docs/plans/PLAN_DL_REPRODUCIBILITY.md with <!-- plans-hub-summary: ... -->; run python scripts/plans_hub_sync.py --write; add a docs/plans/PLANS_TODO.md entry.

Not in question (still correct)

• "No LLM / no generative / no hallucination on the critical path"
• "No proprietary black box"
• Regex/rules: deterministic by nature

---

Read-only audit (Claude Code). Evidence via gh api on the authoritative repo. Implementation: Cursor.

[FabioLeitao]

Dimensão air-gap do achado 1 e onde encaixar a verificação (30/set) — complemento, não duplicata

Verificado por gh api no origin, hoje:

• core/dl_backend.py passa o nome sentence-transformers/all-MiniLM-L6-v2 ao SentenceTransformer(...). Uma busca de código por HF_HUB_OFFLINE, local_files_only, TRANSFORMERS_OFFLINE e SENTENCE_TRANSFORMERS_HOME não achou nada. Não executei o DL sem rede: baixar os pesos do Hugging Face Hub quando não há cache nem caminho local é o comportamento padrão da biblioteca (não observado aqui). Sem rede e sem cache pré-populado, o init falha e cai no fallback silencioso do achado 3: o scan termina normal, sem DL.
• docs/TROUBLESHOOTING.md cobre air-gap para wheels (wheelhouse com SHA256SUMS, musl, x86-64-v1), mas uma busca por sentence, huggingface e HF_ nesse arquivo não achou nada: a fonte dos pesos do DL não está no roteiro de air-gap.
• --validate-config (main.py, tests/test_main_validate_config.py; [P2] cli: add --validate-config — structural + env-var dry-run without scanning #520, [P1][enhancement] --validate-config poderia checar dependencia opcional do driver (ex: psycopg2), nao so nome/schema #1246) já é um preflight offline que confere dependência opcional de driver.

Por que importa: quem lê README e docs (inclusive agentes de IA que resumem o repo) conclui "roda em air-gap, zero dependência externa". Só é verdade se o extra dl não for usado ou se os pesos vierem de caminho local com revisão e sha256 fixos.

Sugestões (recomendatório):

1. Estender o --validate-config (ou a saída do --explain, [P2][feat][trust] --explain / dry-run do scan-plan — mostrar O QUE/ONDE vai escanear + custo ANTES de tocar no dado #1099) para o DL: sentence-transformers presente? pesos resolvíveis localmente? revisão fixada? Saída "air-gap ready: sim/não + motivos", sem flag novo.
2. Caminho local + revisão/sha256 como forma suportada de air-gap (local_files_only), uma linha no TROUBLESHOOTING, e a degradação registrada no recibo (achado 4).
3. Uma entrada em docs/CLAIMS.yml para o claim de air-gap, com esse predicado, para o teste anti-overclaim ([P2·G2·U2] feat(ci): test_claims_consistency — pytest determinístico anti-overclaim (invariante connector↔tier + manifesto CLAIMS.yml) #894) barrar texto que ultrapasse o contrato.
4. Critério adicional: scan completo numa VM sem rede, no banco de testes já nomeado aqui (Maestro/LabOp, junto do canário alpine).
5. Empréstimo antes de construir: o Latent Lynx (retrieval local, air-gapped, ainda scaffold; o primer fala em "mesmo encoder pequeno, dois papéis") usa o mesmo encoder em outro stack. Vale avaliar servir o DL do Boar por ele (pin do modelo, sem torch no min-spec). Ressalvas: não li a API do Lynx; stack numérica diferente ⇒ embeddings não idênticos ⇒ o classificador logístico precisa de retreino e teste de paridade. Avaliação, não decisão.

🤖 Claude (Opus 4.8, T14, auditor RO). Tom recomendatório; nada implementado.

[FabioLeitao]

Quem provisiona os pesos do DL, e quando o "silencioso" vale (30/set) — complemento

Verificado por gh api no origin, hoje:

• O repositório não contém nenhum artefato de modelo (busca por .safetensors, .onnx, .gguf, .pt, .pkl, .joblib: nada). O extra dl (pyproject.toml) é só a biblioteca (sentence-transformers>=5.5.1); os pesos do encoder MiniLM não vêm no pacote.
• As imagens publicadas não têm o DL: Dockerfile e Dockerfile.nogil instalam requirements.txt (sem sentence-transformers nem torch) e só os extras [sql-community,mssql,oracle], por desenho de imagem enxuta ([P1][packaging][docker] Imagem publicada não instala os extras do pyproject — 11 de 18 incompletos (pymssql, shares, nosql, compressed, dataformats, richmedia, dl, bigdata, grc-dashboard) #1399, [P1][1.8.x][packaging][ci] EXTRAS_MANIFEST.json + --check-extras + guarda no docker-image-smoke.sh — impedir a divergência artefato × pyproject de voltar #1401).
• O DL tem duas condições: dl_terms configurados (em deploy/config.example.yaml estão comentados; config/boar_config.yaml não tem chave de ML/DL) e o extra instalado. Em configuração padrão o DL nem é construído, então não há falha a esconder. O silencioso só vale para quem instalou [dl] e configurou dl_terms.
• Não há "pesos treinados" para provisionar além do encoder: o classificador logístico é treinado a cada início, a partir dos termos (random_state=42), e nada é persistido. Os learned patterns (core/learned_patterns.py) são termos, não pesos: são gravados num YAML compatível com ml_patterns_file para a próxima corrida.
• Assimetria ML × DL: o ML loga um aviso quando degrada ("ML terms include only one class ... skipping ML training"); o DL descarta o erro (_ = str(model_err)) e detector.py só zera _dl_classifier quando is_ready é falso, sem log.

Sugestões (recomendatório):

1. Quem provisiona o encoder: o pipeline de release. Baixar sentence-transformers/all-MiniLM-L6-v2 numa revisão fixa, calcular o sha256 e publicar como asset com SHA256SUMS, no mesmo padrão do wheelhouse já hospedado (TROUBLESHOOTING). Conferir a licença do modelo antes de redistribuir (não verifiquei). A config passa a apontar para a pasta local, com local_files_only (achado 1).
2. Falha alta, não silenciosa: logar a exceção como o ML faz e registrar dl: UNAVAILABLE + reason_code + degradation no recibo (é o item de "degraded-mode" da audit(detection-validity): ground-truth corpus, per-engine ablation, calibration & provenance (promote deferred plan) #1452).
3. Air-gap: o asset de pesos viaja como bundle offline, verificado por hash no destino (o courier proposto no Maestro, Send-Bytes Fase 2).

🤖 Claude (Opus 4.8, T14, auditor RO). Tom recomendatório; nada executado nem baixado.

[FabioLeitao]

Ponteiro (30/set), corrigido: o achado 1 desta issue (modelo por nome, sem opção de config) é o pré-requisito de qualquer DL para quem usa Docker. A imagem canônica (cp314t, distroless, ADR-0091) não inclui o [dl]. O torch tem wheel cp314t (PyPI e índice CPU do PyTorch), mas tokenizers e safetensors só publicam wheels abi3, que não carregam em build free-threaded: esses dois são o bloqueio real, e entram no wheelhouse próprio. Detalhe e critérios de aceite na #2024. O invariante do PLAN_PACKAGING_EXTRAS ("never omit embeddings in silence") reforça o item de falha alta desta issue.

Corrigido em 30/set: a versão anterior deste comentário afirmava, por engano meu, que o torch não tinha wheel cp314t.

🤖 Claude (Opus 4.8, T14, auditor RO). Tom recomendatório.