Fase 4: Deduplicacao de Armazenamento

2026-02-15

Quando multiplas tesseras compartilham a mesma foto, o mesmo clipe de audio ou +os mesmos dados de fragmento, a camada de armazenamento antiga mantinha copias +separadas de cada. Em um no armazenando milhares de tesseras para a rede, essa +duplicacao se acumula rapidamente. A Fase 4 continua com deduplicacao de +armazenamento: um armazenamento enderecavel por conteudo (CAS) que garante que +cada dado unico seja armazenado exatamente uma vez em disco, independentemente +de quantas tesseras o referenciam.

O design e simples e comprovado: hash do conteudo com BLAKE3, usar o hash como +nome do arquivo e manter uma contagem de referencias no SQLite. Quando duas +tesseras incluem a mesma foto de 5 MB, um arquivo existe em disco com +refcount 2. Quando uma tessera e deletada, o refcount cai para 1 e o arquivo +permanece. Quando a ultima referencia e liberada, uma varredura periodica limpa +o orfao.

O que foi construido

Migracao do esquema CAS (tesseras-storage/migrations/004_dedup.sql) — Tres +novas tabelas:

cas_objects — rastreia cada objeto no armazenamento: hash BLAKE3 (chave +primaria), tamanho em bytes, contagem de referencias e timestamp de criacao
blob_refs — mapeia identificadores logicos de blobs (hash da tessera + hash +da memoria + nome do arquivo) para hashes CAS, substituindo a convencao antiga +de caminhos no sistema de arquivos
fragment_refs — mapeia identificadores logicos de fragmentos (hash da +tessera + indice do fragmento) para hashes CAS, substituindo o antigo layout +do diretorio fragments/

Indices nas colunas de hash garantem lookups O(1) durante leituras e contagem de +referencias.

CasStore (tesseras-storage/src/cas.rs) — O motor central de armazenamento +enderecavel por conteudo. Arquivos sao armazenados sob um diretorio de prefixo +de dois niveis: <raiz>/<prefixo-hex-2-chars>/<hash-completo>.blob. O +armazenamento fornece cinco operacoes:

put(hash, data) — escreve dados em disco se ainda nao presente, incrementa o +refcount. Retorna se ocorreu um hit de deduplicacao.
get(hash) — le dados do disco pelo hash
release(hash) — decrementa o refcount. Se chegar a zero, o arquivo em disco +e deletado imediatamente.
contains(hash) — verifica existencia sem ler
ref_count(hash) — retorna a contagem de referencias atual

Todas as operacoes sao atomicas dentro de uma unica transacao SQLite. O refcount +e a fonte de verdade — se o refcount diz que o objeto existe, o arquivo deve +estar em disco.

FsBlobStore com CAS (tesseras-storage/src/blob.rs) — Reescrito para +delegar todo armazenamento ao CAS. Quando um blob e escrito, seu hash BLAKE3 e +computado e passado para cas.put(). Uma linha em blob_refs mapeia o caminho +logico (tessera + memoria + arquivo) para o hash CAS. Leituras buscam o hash CAS +via blob_refs e leem de cas.get(). Deletar uma tessera libera todas as suas +referencias de blob em uma unica transacao.

FsFragmentStore com CAS (tesseras-storage/src/fragment.rs) — Mesmo padrao +para fragmentos codificados com erasure coding. O checksum BLAKE3 de cada +fragmento ja e computado durante a codificacao Reed-Solomon, entao e usado +diretamente como chave CAS. A verificacao de fragmentos agora checa o hash CAS +ao inves de recomputar do zero — se o CAS diz que os dados estao intactos, +estao.

Coletor de lixo sweep (cas.rs:sweep()) — Uma passagem periodica de GC que +trata tres casos limite que o caminho normal de refcount nao consegue:

Arquivos orfaos — arquivos em disco sem linha correspondente em +cas_objects. Pode acontecer apos um crash durante escrita. Arquivos com +menos de 1 hora sao pulados (periodo de graca para escritas em andamento); +orfaos mais antigos sao deletados.
Refcounts vazados — linhas em cas_objects com refcount zero que nao +foram limpas (ex: se o processo morreu entre decrementar e deletar). Essas +linhas sao removidas.
Idempotente — executar sweep duas vezes produz o mesmo resultado.

O sweep e conectado ao loop de reparo existente em tesseras-replication, entao +roda automaticamente a cada 24 horas junto com as verificacoes de saude dos +fragmentos.

Migracao do layout antigo (tesseras-storage/src/migration.rs) — Uma +estrategia de migracao copy-first que move dados do layout antigo baseado em +diretorios (blobs/<tessera>/<memoria>/<arquivo> e +fragments/<tessera>/<indice>.shard) para o CAS. A migracao:

Verifica a versao de armazenamento em storage_meta (versao 1 = layout +antigo, versao 2 = CAS)
Percorre os diretorios antigos blobs/ e fragments/
Computa hashes BLAKE3 e insere no CAS via put() — duplicatas sao +automaticamente deduplicadas
Cria entradas correspondentes em blob_refs / fragment_refs
Remove diretorios antigos somente apos todos os dados estarem seguros no CAS
Atualiza a versao de armazenamento para 2

A migracao roda na inicializacao do daemon, e idempotente (segura para +re-executar) e reporta estatisticas: arquivos migrados, duplicatas encontradas, +bytes economizados.

Metricas Prometheus (tesseras-storage/src/metrics.rs) — Dez novas metricas +para observabilidade:

+ + + + + + + + + + +

Metrica	Descricao
`cas_objects_total`	Total de objetos unicos no CAS
`cas_bytes_total`	Total de bytes armazenados
`cas_dedup_hits_total`	Numero de escritas que encontraram um objeto existente
`cas_bytes_saved_total`	Bytes economizados por deduplicacao
`cas_gc_refcount_deletions_total`	Objetos deletados quando refcount chegou a zero
`cas_gc_sweep_orphans_cleaned_total`	Arquivos orfaos removidos pelo sweep
`cas_gc_sweep_leaked_refs_cleaned_total`	Linhas de refcount vazadas limpas
`cas_gc_sweep_skipped_young_total`	Orfaos jovens pulados (periodo de graca)
`cas_gc_sweep_duration_seconds`	Tempo gasto no sweep GC

Testes baseados em propriedades — Dois testes proptest verificam invariantes +do CAS sob entradas aleatorias:

refcount_matches_actual_refs — apos N operacoes aleatorias de put/release, o +refcount sempre corresponde ao numero real de referencias pendentes
cas_path_is_deterministic — o mesmo hash sempre produz o mesmo caminho no +sistema de arquivos

Atualizacao de testes de integracao — Todos os testes de integracao em +tesseras-core, tesseras-replication, tesseras-embedded e tesseras-cli +atualizados para os novos construtores com CAS. Testes de deteccao de +adulteracao atualizados para funcionar com o layout de diretorio CAS.

347 testes passam em todo o workspace. Clippy limpo com -D warnings.

Decisoes de arquitetura

BLAKE3 como chave CAS: o hash de conteudo que ja computamos para +verificacao de integridade serve tambem como chave de deduplicacao. Nenhuma +etapa adicional de hashing — o hash computado durante create ou replicate +e reutilizado como endereco CAS.
Refcount SQLite ao inves de reflinks do sistema de arquivos: consideramos +usar copy-on-write no nivel do sistema de arquivos (reflinks em btrfs/XFS), +mas isso amarraria o Tesseras a sistemas de arquivos especificos. Refcounting +em SQLite funciona em qualquer sistema de arquivos, incluindo FAT32 em +pendrives baratos e ext4 em Raspberry Pis.
Diretorios de prefixo hexadecimal de dois niveis: armazenar todos os +objetos CAS em um diretorio plano desaceleraria sistemas de arquivos com +milhoes de entradas. A divisao <prefixo 2 chars>/ limita qualquer diretorio +individual a ~65k entradas antes de um segundo nivel ser necessario. Isso +segue a abordagem usada pelo object store do Git.
Periodo de graca para arquivos orfaos: o sweep GC pula arquivos com menos +de 1 hora para evitar deletar objetos sendo escritos por uma operacao +concorrente. Esta e uma escolha pragmatica — troca uma pequena janela de +potenciais orfaos por seguranca contra crashes sem exigir fsync ou commit de +duas fases.
Migracao copy-first: a migracao copia dados para o CAS antes de remover +diretorios antigos. Se o processo for interrompido, os dados antigos +permanecem intactos e a migracao pode ser re-executada. Isso e mais lento que +mover arquivos mas garante zero perda de dados.
Sweep no loop de reparo: ao inves de adicionar um timer separado de GC, o +sweep CAS aproveita o loop de reparo existente de 24 horas. Isso mantem o +daemon simples — um unico ciclo de manutencao em segundo plano cuida tanto da +saude dos fragmentos quanto da limpeza de armazenamento.

O que vem a seguir

Fase 4 continuacao — auditorias de seguranca, empacotamento para OS +(Alpine, Arch, Debian, OpenBSD, FreeBSD)
Fase 5: Exploracao e Cultura — navegador publico de tesseras por +era/localizacao/tema/idioma, curadoria institucional, integracao genealogica +(FamilySearch, Ancestry), exportacao para midia fisica (M-DISC, microfilme, +papel livre de acido com QR), contexto assistido por IA

A deduplicacao de armazenamento completa a historia de eficiencia de +armazenamento do Tesseras. Um no que armazena fragmentos para milhares de +usuarios — comum para nos institucionais e nos completos sempre ligados — agora +paga o custo de disco apenas por dados unicos. Combinado com codificacao de +apagamento Reed-Solomon (que ja minimiza redundancia no nivel da rede), o +sistema alcanca armazenamento eficiente tanto nas camadas local quanto +distribuida.

+ +