27 KiB
Impl: C244 — Filtro "Pessoa pública" por reconhecimento facial no álbum
Status: aprovado (modo autônomo) — hard-stops registrados: migração de schema, contrato público, Consent/LGPD Atualizado em: 2026-10-01 Issue: #1416 Intenção: docs/plans/album-pessoa-facial.md Appetite restante: herdado (~2–3 dias eng + curadoria dos descritores + aval jurídico registrado). A derivação em leitura elimina o reprocessamento dos 18k rostos, então o appetite cabe com folga; nenhum corte de aceite.
Leitura da intenção
- Outcome: a faceta
pessoado álbum/fotos?pessoa=<slug>passa a listar as fotos em que a figura pública realmente aparece (pelo índice facial do C240), não as fotos em que o nome foi escrito na ficha; "Quem aparece" no card/overlay mostra só figuras curadas reconhecidas; nenhuma superfície nomeia terceiros nem mostra score; sem Consent do aviso ou sem curadoria, a faceta fica vazia (fail-closed). - O que NÃO negociar: identificação biométrica apenas do catálogo curado de figuras públicas, com aval jurídico registrado; nunca terceiros; opt-out ("Minha presença") e remoção de foto continuam; despublicar foto tira-a da faceta imediatamente;
?pessoacontinua sendo a chave da URL; Consent fail-closed por chave estável (busca-selfie-indice);catalog.people(texto) não governa mais o filtro. - O que reavaliar: a "Direção no codebase" da intenção propõe estender
faces:indexpara gravar o vínculo e criar um marker novo de revisão das figuras, com reprocessamento dos 18k rostos — a abordagem recomendada (A) substitui isso por derivação em tempo de leitura sobre o índice existente, sem tocar no lote e sem marker. Também caem: o "vínculo foto↔figura no lote" e qualquer uso depublicFigureCatalog/resolvePublicFigureNamecomo origem da faceta.
Abordagem recomendada
flowchart LR
F[faceFigure: referências curadas] --> R[faceFigureReads]
I[archivePhotoFace: 18k descritores anônimos] --> R
R -->|unstable_cache tag archivePhotos| M[mapa foto -> figuras]
C[Consent busca-selfie-indice] -->|gate fail-closed FORA do cache| M
M --> A[getApprovedArchivePhotoAlbumItems]
P[archivePhoto aprovadas] --> A
A --> U["/fotos: faceta, Quem aparece, lightbox"]
H1[hooks ArchivePhoto] -->|bust archivePhotos| R
H2[hooks FaceFigure] -->|bust archivePhotos| R
O[opt-out leave-index] -->|deleteFaceDescriptorMatches + bust| R
CLI[faces:index / faces:enroll-figure] -->|runbook: /api/revalidate?tag=archivePhotos| R
Opções consideradas: A (vínculo derivado em leitura + collection curada faceFigure) | B (vínculo materializado nas linhas do índice com marker de revisão e passe de rematch) | C (matching por request / uma query por figura / pgvector) | D (manter o texto como fonte e só anotar rostos).
Recomendação: A — porque reusa o índice e o cache do C240 como fonte única (o vínculo não pode divergir do índice), mantém as linhas archivePhotoFace anônimas, dispensa schema de vínculo/marker/reprocessamento, e o custo só aparece na revalidação da tag (não por request): no cenário-teto do catálogo (~58 figuras × ≤8 referências × ~18k descritores ≈ 8M distâncias de 128 floats ≈ 10⁹ operações, ordem de ~1–2 s por revalidação; com 1–3 referências por figura, bem menos). O resultado é cacheado em unstable_cache sem TTL, então o custo é pago uma vez por bust, nunca por visita; o loadFaceDescriptorIndex com TTL de 60 s absorve a releitura do índice.
Rejeitadas: B — acrescenta schema novo, marker de revisão das figuras, caminho de reprocessamento de 18k rostos e um segundo fluxo de purge/opt-out; C — a página é dinâmica (searchParams), o custo por request seria inútil; pgvector já foi rejeitado no C229 (Postgres vanilla); D — contradiz a decisão do dono (2026-10-01) registrada na intenção.
Componentes / mudanças
FaceFigure(src/collections/FaceFigure.ts, novo) — slugfaceFigure, labels "Figura pública"/"Figuras públicas",admin.group: 'Comunicação',useAsTitle: 'name',admin.descriptiondeclarando o aval jurídico e que cada referência é curada/auditável e nunca inclui terceiros. AccesspayloadAdminOnlynas 4 operações (precedentes:src/collections/ArchivePhotoFace.ts:31-36,src/collections/Consent.ts:99-104). Campos:name(text, required, unique),slug(text, required, unique, index; hook beforeValidate que aplicaslugify— padrãosrc/collections/Tag.ts:63-72— e deriva denamequando vazio; é o valor de?pessoa=<slug>, origem pública),fullName(text opcional, proveniência),active(checkbox, defaulttrue, index),referencesarray "Descritores de referência" (maxRows: 8) comvector(json, hidden, readOnly),model(text, readOnly),source(text "Origem", required),addedAt(date, readOnly). HooksafterChange/afterDelete→revalidateArchivePhotosListing()(src/utilities/documents.ts:57), porque o mapa de matches é cacheado sob a tagarchivePhotos. Registro emsrc/payload.config.ts(junto deArchivePhotoFace, linha 143).src/lib/faceFigureCatalog.ts(novo, puro/client-safe) — tiposFaceFigure/FaceFigureReference/FaceFigureMatch/PhotoFigureMatch; filtra poractive === truee por referência commodel === FACE_SEARCH_MODEL(src/lib/faceSearch.ts:24) ereadFaceVectorválido (faceSearch.ts:54);findFaceFigureMatches({ figures, descriptors, maxDistance = FACE_SEARCH_MAX_DISTANCE })(faceSearch.ts:31) casa cada referência comfindFaceDescriptorPhotoIds(faceSearch.ts:96) e devolve por figura{ slug, name, photoIds }— dedupe por foto, sem score/percentual/distância por shape, figuras ordenadas por slug,photoIdsna ordem do índice;groupFaceFigureMatchesByPhoto(matches)(pivô puro) devolve[{ photoId, figures: [{ slug, name }] }]ordenado porphotoIde figuras por slug. Sem I/O e semserver-only(unit-testável, comoarchivePhotoPublicCatalog.ts).src/utilities/faceIndex/faceFigureReads.ts(novo,server-only) — carrega figuras ativas (payload.findemfaceFigure,where active=true,select name/slug/references,overrideAccess: truecom a mesma justificativa de leitura anônima defaceDescriptorReads.ts:14-25) e reusaloadFaceDescriptorIndex(payload)(faceDescriptorReads.ts:88, cache in-process TTL 60 s já existente); aplica o matcher puro e o pivô. O núcleo vai emunstable_cache(fn, ['archive-photo-figures'], { tags: [getCollectionListingTag('archivePhoto')] })(documents.ts:41) e devolve estrutura serializável (PhotoFigureMatch[]— nuncaMap). ExportaloadApprovedPhotoFigureMap(payload): o gate do Consent fica FORA do cache —getConsentByKey(payload, FACE_INDEX_CONSENT_KEY)(src/utilities/campaignConsent.ts:72; chaveFACE_INDEX_CONSENT_KEYemsrc/lib/campaignConsentKeys.ts:44) ausente →[](sem nomes), e o provisionamento vale imediatamente; o núcleo computa mesmo sem Consent. Falha do núcleo (ex.: teto defensivo do índice) →[](fail-closed; a faceta some, o álbum continua).src/utilities/archivePhotos/archivePhotoReads.ts— mantémarchivePhotoPublicSelect,findApprovedArchivePhotos,getCachedApprovedArchivePhotos(:39-55),getApprovedArchivePhotoItems(:58),getApprovedArchivePhotoById(:68) ehasPublishedArchivePhotos(:74) intactos e sem matching/Consent — são o caminho quente do endpointPOST /api/fotos/selfie(src/app/(frontend)/api/fotos/selfie/route.ts:106) e da rota de mídia/fotos/[id]/midia(viagetApprovedArchivePhotoByIdemsrc/app/(frontend)/fotos/[id]/midia/route.ts:40). Nova funçãogetApprovedArchivePhotoAlbumItems(), usada só por/fotos/page.tsx: busca os docs crus no cache existente, faz o merge do mapaphotoId → [{ slug, name }]no source antes detoArchivePhotoPublicItem.generateMetadatacontinua comhasPublishedArchivePhotos.src/lib/archivePhotoPublicCatalog.ts— remove o import deresolvePublicFigureName(:22) e a funçãoarchivePhotoPublicPeople(:186-197).ArchivePhotoPublicItem.peoplepassa destring[]para{ slug, name }[](tipoArchivePhotoPublicPersonexportado);ArchivePhotoPublicSourceganhafigures?: readonly ArchivePhotoPublicPerson[] | null(novo campo de merge, opcional).toArchivePhotoPublicItem(:264) derivapeoplederecord.figures(dedupe por slug, ordem estável), nunca mais decatalog.people— que permanece no source apenas como conteúdo da ficha/searchText, com comentário explícito de que não governa o filtro.archivePhotoAlbumFacets(:337),filterArchivePhotoAlbumItems(:415) earchivePhotoAlbumHeading(:441) usamitem.peoplediretamente; a chave?pessoa=<slug>não muda, e para os nomes do roster o slug continuaslugify(name)(mesmos valores de URL de hoje).- Migration:
pnpm migrate:create add_face_figure(collection nova + tabela do array de referências), depois do rebase emmain;src/migrations/index.tsentra no mesmo commit;pnpm generate:typesatualizapayload-types.ts(commitado). Migration aditiva; nunca editar migrations antigas. - Access / Consent: sem helper novo —
payloadAdminOnlyreusado (src/utilities/campaignAccess.ts:18); nenhuma chave de Consent nova; o gate público éFACE_INDEX_CONSENT_KEY(busca-selfie-indice), fail-closed, resolvido fora do cache. - Bust de cache:
deleteFaceDescriptorMatches(faceDescriptorReads.ts:119) passa a chamarrevalidateArchivePhotosListing()logo apósinvalidateFaceDescriptorIndex()(o mapa curado éunstable_cachesem TTL — sem o bust ele ficaria stale indefinidamente); os int specs que tocam esse caminho já mockamnext/cache(tests/int/faceSearchApi.int.spec.ts:8-12,tests/int/faceDescriptorIndex.int.spec.ts:8-10). O lotefaces:indexe o enrollment rodam fora do Next → bust no runbook viaPOST /api/revalidate?tag=archivePhotos(allowlist emAGENTS-public.md:58; precedentescripts/publish-archive-photos.mjs:201). Os hooks deArchivePhoto(src/collections/ArchivePhoto.ts:276-282) e deFaceFigurecobrem edição de curadoria/ciclo de vida. - Consent (hard-stop registrado): em
scripts/lib/faceConsentTexts.mjs(parágrafos:44-49), o aviso hoje diz "sem qualquer identificação de quem aparece" e "nunca é usado para identificar, nomear ou listar terceiros" — com o C244 isso fica incorreto. Proposta: substituir o parágrafo 2 (:46) e inserir um parágrafo novo depois dele:- Parágrafo 2 novo: "O índice serve para localizar fotos: encontrar as fotos da própria pessoa que faz a busca e alimentar o filtro "Pessoa pública" do álbum. Esse filtro identifica exclusivamente as figuras públicas do catálogo curado e aprovado do mandato (com aval jurídico registrado); qualquer rosto fora desse catálogo continua anônimo no índice, sem nome e sem vínculo com cadastro, e nunca é usado para identificar, nomear ou listar terceiros, nem cruza os dados biométricos com contatos, lideranças ou apoiadores."
- Parágrafo novo: "O catálogo de figuras é curado e auditável: cada figura tem descritores de referência de retratos oficiais/arquivo do mandato, revisados por curadoria humana, e pode ser desativada a qualquer momento. A retirada continua valendo para qualquer pessoa: usa-se "Minha presença" para sair do índice, o canal do álbum para pedir a remoção de uma foto e o mesmo canal para retirar uma figura do catálogo."
- A chave não muda;
pnpm seed:face-consentsrecria/atualiza a linha por chave (scripts/seed-face-consents.mjs:63-90). O runbook tem o re-seed como pré-condição antes de qualquer enrollment (senão o aviso em produção fica desatualizado com a faceta no ar).
- CLI de enrollment:
scripts/enroll-face-figure.mjs+ parser/plano puroscripts/lib/faceFigurePlan.mjs+ scriptfaces:enroll-figurenopackage.json(padrão dofaces:index,package.json:42-44:cross-env NODE_OPTIONS="--no-deprecation --import=tsx/esm --import=./scripts/seed-loader.mjs" node ...). Args:--figure <slug>,--name "Nome",--full-name,--image <path>(repetível),--replace,--apply,--out <dir>,--help. Plan/dry-run default, sem engine e sem escrita;--applyexigeFACE_FIGURE_CONFIRM=1(assertWriteConfirm,scripts/lib/cli.mjs:312) +assertEnvironmentDatabaseTarget()(cli.mjs:238), sem exigir S3 (as imagens de referência são locais). UsacreateNodeFaceEngine(scripts/lib/faceEngine.mjs:26) eprepareFaceImagedefaceDescriptorIndex.ts(hoje privada em:54— exportar), e exige exatamente 1 rosto por imagem (0 ou >1 → recusa fail-closed registrada no recibo; o operador recorta). Cria a figura se não existir (nesse caso--nameé obrigatório);--replacelimpa as referências existentes;--outdefaultdata/face(gitignored,.gitignore:93); recibo JSON emdata/face/reports/sem vetor/bytes; imprime a instrução de bust. - Seed do catálogo inicial:
scripts/seed-face-figures.mjs+scripts/lib/faceFigureCatalogSeed.mjs+ scriptseed:face-figures. Idempotente por slug (cria sem referências; nunca atualiza linha existente), guard de escrita comoseed:face-consents(--applyexigeFACE_FIGURE_SEED_CONFIRM=1fora do dev local +assertEnvironmentDatabaseTarget(); default plan). Conteúdo: as 6 nomeadas da intenção — Jorge Solla; Lula (fullName "Luiz Inácio Lula da Silva"); Jerônimo (fullName "Jerônimo Rodrigues"); Geraldinho (fullName "Geraldo Júnior"); Wagner (fullName "Jaques Wagner"); Júlio Pinheiro — + os 53 do rostersrc/lib/stateDeputyCatalog.ts, com dedupe por slug (Júlio Pinheiro já está no roster; total 58 slugs únicos). Nome exibido = label público; o slug éslugify(name). - UI: Impeccable B herdada do C233; nenhum shell novo. A faceta
pessoacontinua a mesma UI (menus somem quando sem opções — comportamento atual). Única mudança de copy: emArchivePhotoNoResults(src/components/fotos/ArchivePhotoStates.tsx:32), quando o filtropessoaestá ativo (derivável deactiveFilters), o parágrafo passa a ser: "O filtro Pessoa pública mostra apenas figuras do catálogo curado do mandato, reconhecidas com aval jurídico — nunca terceiros. Tente outra pessoa ou volte a ver todas as fotos aprovadas do álbum." (sem o filtro, o texto atual permanece). É wiring de copy sobre o markup aprovado — não é designer trigger; nenhum elemento estrutural novo. - e2e manifest:
src/utilities/faceIndex(entrada C242,scripts/lib/e2e-affected-manifest.mjs:246-255) passa aspecs: ['frontendFotos', 'frontendFotosSelfie'](o índice agora alimenta os dois specs); nova entradasrc/lib/faceFigureCatalog.ts+src/collections/FaceFigure.ts→['frontendFotos'].src/lib/archivePhotoPublicCatalog.tsjá casa o prefixosrc/lib/archivePhotoda entrada C233 (:227-239) — sem entrada nova. - Docs:
AGENTS-public.md(contrato da faceta: fonte facial, gate por Consent, catálogo curado, sem terceiros); runbookdocs/ops/teqo-1313-deploy.md§C244; changelogdocs/changelog/2026-10-02-c244.md; nota "Implementação: docs/plans/album-pessoa-facial-impl.md" emdocs/plans/album-pessoa-facial.md.
Dados → forma (se aplicável)
N/A — nenhum número/score em nenhum estado; o resultado é a lista de fotos do C233. A mudança é de origem de dado e copy do estado vazio.
Fases verificáveis
- Tracer / schema + contrato puro (quota ~0,5 dia) —
FaceFigure.ts, migrationadd_face_figure+index.ts,generate:types,src/lib/faceFigureCatalog.tsetests/unit/faceFigureCatalog.unit.spec.ts(threshold/modelo/ativo/dedupe/ordenação/sem score/pivô). Verificação:pnpm migratelocal epnpm gate:fastverdes. - Leitura pública e faceta (quota ~1 dia) —
faceFigureReads.ts,getApprovedArchivePhotoAlbumItems+ wiring da página/fotos, mudança de tipo/derivação emarchivePhotoPublicCatalog.ts, copy condicional emArchivePhotoNoResults, atualização detests/unit/archivePhotoPublicCatalog.unit.spec.ts(texto não cria faceta) e novo int spec de leitura (Consent fail-closed, figura inativa, purge, opt-out/bust). Verificação:pnpm test:intnos specs novos +pnpm test:unitverdes; conferência manual em dev com figura semeada. - Curadoria (Consent + seeds + enrollment) (quota ~1 dia) — parágrafos novos no aviso,
seed-face-figures+ manifest/pin,faces:enroll-figure+faceFigurePlan.mjs+ unit do parser, export deprepareFaceImage, scripts nopackage.json. Verificação: dry-runs (seed:face-consents,seed:face-figures,faces:enroll-figure) imprimem o esperado; um enrollment local real (imagem de teste) grava referência e a faceta acende. - e2e (quota ~0,5 dia) — atualizar
tests/e2e/frontendFotos.e2e.spec.ts: semearfaceFigure+ linhasarchivePhotoFaceque casam para o?pessoa=rui-costa, provar que nome só-texto NÃO cria faceta/card/overlay, atualizar asserções deJorge Sollado card/overlay; manifest atualizado. Verificação:pnpm test:e2e:affected(ou os dois specs de fotos) verde. - Docs + entrega (quota ~0,5 dia) — runbook §C244,
AGENTS-public.md, changelog, nota na intenção;pnpm gate:fast; push viapnpm push. O deploy de produção segue o runbook e é hard-stop humano (re-seed → seed → enrollment por figura → bust → conferência).
Rabbit holes / Não escopo (engenharia)
- Materializar o vínculo (opção B), marker de revisão das figuras em
faces.checkedKeye qualquer reprocessamento dos 18k rostos. - pgvector/ANN/índice dedicado ou matching por request/por figura (opção C).
- Qualquer score, percentual, distância, ranking ou ordenação por confiança — nem em recibo de UI, nem em API.
- Tela nova de curadoria (upload/queue) no admin além do array da collection; bulk enrollment pela web.
- Guardar imagens de referência ou vetores no repo/S3 público; recibos com vetor/bytes.
- Usar
catalog.people/resolvePublicFigureNamecomo fallback ou fonte do filtro (decisão do dono); nomear qualquer pessoa fora do catálogo; API pública de reconhecimento; vídeo. - Mexer em
searchText/ficha (catalog.peoplecontinua conteúdo da Central) e no caminho quente do endpoint selfie/rota de mídia. - Re-seed automático do Consent dentro do enrollment (o provisionamento é passo explícito do runbook).
Riscos e mitigação
- Falso positivo a 0.45 nomeando a figura errada: sem score na UI; revisão por exceção no runbook (conferir o recibo e a faceta; desativar a figura ou remover a referência no admin, que busta a tag); referências curadas 1–8 por figura.
- Aviso do Consent desatualizado em produção: re-seed do
busca-selfie-indiceé pré-condição registrada ANTES de qualquer enrollment; passo 1 do runbook e conferência do texto na página/fotos/encontre. - Cache stale após CLI (lote/enrollment fora do Next): bust obrigatório de
archivePhotosno runbook; hooks deArchivePhoto/FaceFigurecobrem o runtime; opt-out busta na função de delete. - Opt-out sem efeito na faceta: o mapa é
unstable_cachesem TTL — orevalidateArchivePhotosListing()emdeleteFaceDescriptorMatchesé o que garante efeito imediato; int test pina orevalidateTagchamado. - URL pública
?pessoa: a chave não muda e o slug segueslugify(name); o seed usa o label público do roster (mesmos slugs de hoje). Teste unit pin do catálogo de seed (58 únicos, sem colisão). - Índice/DB indisponível:
loadApprovedPhotoFigureMapfalha fechado ([]) — a faceta some, o álbum e a rota quente seguem funcionando; Consent ausente idem. - Privacidade das referências: imagens de referência vivem fora do repo (gitignored, homeserver, montadas read-only no maintenance); recibos sem vetor/bytes; acesso admin-only; nada muda no gate do C240.
- Contrato do catálogo público quebra em teste/central:
peoplevira{slug,name}[]; card/lightbox usampeopleLabel, selfie usaFaceSearchPhotoView(sempeople) — os 3 consumidores foram verificados; unit/int cobrem. - e2e frágil por seed REST: criar figuras/linhas no
beforeAll(antes da primeira visita que cacheia o mapa) e limpar emafterAll(figuras criadas + fotos, cujo FK cascateia as linhas de rosto).
Aceite de engenharia
- Aceite de produto da intenção ainda coberto: faceta por rosto, "Quem aparece" só curado, sem terceiros, sem score, texto vazio honesto, kill switch/despublicação/opt-out imediatos.
- Invariantes AGENTS/engineering-standards: identificadores em inglês e copy pt-BR;
src/lib/puro/client-safe esrc/utilities/comserver-only; Consent fail-closed por chave estável; acesso admin-only compayloadAdminOnly; Local API comoverrideAccessjustificado nos reads anônimos; hot path do endpoint selfie/mídia intocado; sem collection de pessoa paralela (FaceFigure é catálogo de figuras, não cadastro; semContact). - Testes de domínio previstos: unit do matcher/pivô e do parser/plano; unit do catálogo público (texto não governa); int do read do álbum (Consent fail-closed, figura inativa, purge, opt-out/bust) e do access lockdown (
faceFigurenoit.eachde PII/legal,tests/int/collectionAccessLockdown.int.spec.ts:197); e2e dofrontendFotoscom a faceta facial e o caso negativo do texto. - Migration aditiva
add_face_figure+index.ts+payload-types.tscommitados;pnpm migratelocal limpo. - Sem mudança no
seed:minimal(FaceFigure não é boot data e nenhuma chave de Consent nova entra no manifest). - Docs:
AGENTS-public.md, runbook §C244, changelog2026-10-01-c244.md, nota na intenção.
Execução (checklist)
- Rebase em
mainantes depnpm migrate:create add_face_figure; rodarpnpm migrateepnpm generate:types; commitar migration (ts+json+index.ts) epayload-types.ts. - Criar
FaceFigure.ts, registrar nopayload.config.tse escrever o matcher/pivô puro com unit. - Exportar
prepareFaceImagedefaceDescriptorIndex.tse adicionar o bust do opt-out emdeleteFaceDescriptorMatches. - Criar
faceFigureReads.ts+getApprovedArchivePhotoAlbumItems+ wiring da página + tipopeople+ copy do estado vazio. - Reescrever os testes unit afetados e criar os int specs; adicionar
faceFigureao lockdown de access. - Atualizar o aviso em
faceConsentTexts.mjse o pin do unit de textos; criarseed-face-figures+ manifest efaces:enroll-figure+ parser; scripts nopackage.json. - Atualizar
frontendFotos.e2e.spec.tsescripts/lib/e2e-affected-manifest.mjs. - Atualizar
AGENTS-public.md, runbook §C244 (ordem: re-seed do aviso →seed:face-figures→faces:enroll-figurepor figura com canário → bust dearchivePhotos→ conferência → revisão de falsos positivos → rollback por desativação), changelog e nota na intenção. pnpm gate:fast; e2e afetado local;pnpm push; PR com a linha de hard-stops (migração de schema, contrato público, Consent/LGPD) e o deploy de produção executado pelo runbook com aprovação humana.
Verificação de fatos (correções do briefing)
- Consent NÃO é versionado pelo Payload.
src/collections/Consent.tsnão temversions(só Petition/Post/VotePledge têm);seed:face-consentsatualiza a linha existente in place (scripts/seed-face-consents.mjs:63-90), e a versão canônica do texto é o git (faceConsentTexts.mjs). O re-seed, portanto, sobrescreve o texto atual — comportamento suficiente e registrado no runbook. src/lib/archivePhotoPublicCatalog.tsjá tem entry no manifest: o prefixosrc/lib/archivePhotoda entrada C233 (e2e-affected-manifest.mjs:227-239) casa o arquivo e mapeia['frontendFotos','frontendFotosSelfie']; sósrc/lib/faceFigureCatalog.tsesrc/collections/FaceFigure.tsprecisam de entry nova, e a entrada desrc/utilities/faceIndexprecisa ganharfrontendFotos.- 6 nomeadas + 53 do roster têm interseção (Júlio Pinheiro está no roster como "Julio Pinheiro"): o seed deduplica por slug e cria 58 figuras únicas, não 59; o teste unit pin isso.
- O e2e depende do texto em 3 pontos, não só no
?pessoa=rui-costa:tests/e2e/frontendFotos.e2e.spec.ts:219(card mostra "Jorge Solla"),:258-261(filtro porrui-costa) e:288(overlay mostra "Jorge Solla") — os três passam a usar figura/rosto, e o texto vira o caso negativo (nome nocatalog.peoplesem linha de rosto não cria faceta nem linha "Quem aparece"). prepareFaceImageé privada emsrc/utilities/faceIndex/faceDescriptorIndex.ts:54— confirmado que precisa ser exportada para o CLI.- Caminho quente confirmado:
getApprovedArchivePhotoItemsalimenta o endpoint selfie (api/fotos/selfie/route.ts:106) e, viagetApprovedArchivePhotoById(archivePhotoReads.ts:68), a rota de mídia (fotos/[id]/midia/route.ts:40);hasPublishedArchivePhotostem 6 call sites (home, cards, conteúdos, jingles,[type], footer). Por isso a função com figuras é nova e exclusiva da página. faces.checkedKeycontinua sendo só o modelo; com a abordagem A não há marker novo nem reprocessamento dos 18k rostos — a hipótese da intenção ("o índice atual precisa ser reprocessado ao introduzir figuras") fica superada.unstable_cachesemrevalidatenão expira sozinho, então o bust no opt-out/CLI é obrigatório (não apenas "além do cache in-process"), como já previsto no briefing.seed:minimalnão muda:scripts/lib/seed-minimal-manifest.mjs:13-19lista só as 4 chaves fail-closed clássicas; nem as chaves do C242 entram, efaceFigurenão é boot data.
Débitos triados (capture-review-debts)
Achados do /simplify: 12 já resolvidos no próprio diff (bust do runbook, ordem
do down() da migration, ordem do seed e2e, dedupe do enrollment, regex de slug,
tipagem de toApprovedItems, maxRows 1–3, fallback do die, references: [],
readOnly redundante, "53" mágico, retorno não usado) e 5 descartados (YAGNI/
acoplamento/desenho). Defer com gatilho: o catch fail-closed de
loadApprovedPhotoFigureMap engole qualquer erro — se houver um incidente de
álbum vazio em produção, adicionar log rate-limited/observabilidade. Nenhum
débito expensive_lock — sem Issues novas.
Self-score (decision-quality)
5/5.
- Decisões caras têm rejeitadas: collection nova, contrato público do slug, origem do vínculo, cache/Consent e bust estão decididos com A/B/C/D e rejeitadas registradas.
- Cabe no appetite: derivação em leitura reusa índice/cache do C240 e dispensa reprocessamento; o custo é ~1 collection + 1 migration + leitura + 2 CLIs.
- Rabbit holes nomeados: materialização, marker, pgvector, score, tela de curadoria, referências no repo.
- Depth check: reusa
faceEuclideanDistance/findFaceDescriptorPhotoIds/loadFaceDescriptorIndex/unstable_cache/getConsentByKey/revalidateArchivePhotosListing/payloadAdminOnly/padrões de CLI e seed; nenhum pass-through novo. - Outcome de produto preservado: a intenção não foi reescrita; muda só a engenharia da origem do dado, com o aceite e os guardrails intactos.