Function insert_first_seen 

pub fn insert_first_seen<K, E, S>(
    seen: &mut HashSet<K, S>,
    key: K,
    on_duplicate: impl FnOnce() -> E,
) -> Result<(), E>
where
    K: Hash + Eq,
    S: BuildHasher,

Bracket a per-list uniqueness gate with the shared “insert into seen; caller-shaped Err on the second occurrence” gate every declaration-order-preserving Vec-authored slot in caixa-core carries. Delegates to std::collections::HashSet::insert verbatim (which returns true on first insertion, false on repeat), then invokes the caller’s on_duplicate closure only on the duplicate arm — keeping the hot path (the unique case) allocation-free.

The ten existing call sites — crate::AplicacaoSpec::validate’s four per-list uniqueness gates (:membros :caixa → crate::AplicacaoError::MembroDuplicate, :placement :clusters → crate::AplicacaoError::PlacementClusterDuplicate, :entrada :paths → crate::AplicacaoError::EntradaPathDuplicate, :contratos on the six-tuple typed-edge identity key → crate::AplicacaoError::ContratoDuplicate), crate::SupervisorSpec::validate on :children :caixa (crate::SupervisorError::DuplicateChildCaixa), crate::manifest::Caixa’s four per-list uniqueness gates (crate::manifest::Caixa::validate_deps on :deps and :deps-dev → crate::DepError::DuplicateNome, crate::manifest::Caixa::validate_code_paths on :bibliotecas/:exe/:servicos → crate::ManifestError::CodePathDuplicate, crate::manifest::Caixa::validate_etiquetas on :etiquetas → crate::ManifestError::EtiquetaDuplicate, crate::manifest::Caixa::validate_autores on :autores → crate::ManifestError::AutorDuplicate), and crate::dep::Dep’s crate::DepError::CaracteristicaDuplicate gate on :caracteristicas — each formerly inlined the same three- line

if !seen.insert(key) {
    return Err(<Variant> { … });
}

shape by hand, differing only in the seen-set key type and the caller’s thiserror variant. Lifting to one canonical entry-point closes the drift footgun structurally: a future tightening of the per-list uniqueness discipline (a declaration-order pin on the reported entry index, an instrumentation hook for the operator’s audit trail, the M4 CR materializer’s admission-webhook per-list invariant) reaches every consumer by one edit at this helper, not a coordinated rewrite across every per-list gate in the crate. The per-axis error variants remain the source of truth for each axis’s remediation prose — this helper only sequences the insert-and-check pair.

Same set-not-multiset discipline every peer Duplicate* variant documents. The typed key K is generic so both &str-shaped callers (nine sites) and the tuple-shaped crate::AplicacaoError::ContratoDuplicate typed-edge identity carrier route through one helper; the caller owns the enum variant

• its self-locating discriminator fields, this helper only sequences the insert-and-check pair in canonical insert → on_duplicate order. Sibling to the peer require_positive_bounded_* / require_positive_canonical_bounded_duration / require_valid_versao_requirement / require_valid_dns_1123_label helpers on the same closure-based caller-error-variant discipline.

Errors

Returns on_duplicate() when key was already in seen (the std::collections::HashSet::insert call returns false); returns Ok(()) otherwise.