teqo-backup/docs/plans/album-catalogacao-producao-impl.md
Francisco Solla 930db3eb02 feat(C245): catalogar o acervo em produção por camadas — metadados primeiro
A catalogação do C232 nunca rodou em produção: catalog.* zerado nas 6.492
fotos publicadas e o engine de visão fora do ar. O pnpm archive:catalog
ganha --metadata-only: deriva município (gazetteer) e temas do texto já
ingerido, sem engine e sem mídia, grava catalog.metadataCheckedAt
(migration aditiva) e não marca catalogedAt — a fila da IA segue aberta.
Nunca escreve catalog.people (C244 assume a faceta por facial).

A passada de IA passa a carimbar os dois markers; a fila de metadados exclui
linha já catalogada pela IA (não rebaixa o source); o --verify relata as duas
camadas com exit pela selecionada; o --apply de metadados dispensa S3_* e
engine. Runbook §C245: metadados → revalidate archivePhotos → IA.

Closes #1417
2026-10-02 10:17:49 -03:00

180 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Impl: C245 — Catalogação do acervo em produção (município, atividade, legenda)
Status: aprovado
Atualizado em: 2026-10-01
Issue: #1417
Intenção: docs/plans/album-catalogacao-producao.md
Appetite restante: herdado — ~1 dia eng + tempo de máquina
## Leitura da intenção
- **Outcome:** o acervo publicado (6.492 fotos) deixa de ter só a faceta **Data**: (1) a camada **metadata** grava `catalog.municipality` e `catalog.themes` a partir do texto já ingerido, e `/fotos` passa a renderizar a faceta **Município** e o card com `data · município`; (2) a camada **IA**, quando o engine local subir, grava legenda/descrição/atividade/texto visível, e o card ganha legenda real e a faceta **Atividade**. Tudo com recibo, reexecução idempotente, curadoria vencendo e nada publicado automaticamente.
- **O que NÃO negociar:** metadata-only **nunca** escreve `catalog.people` (o C244 assume a faceta por facial); nenhuma proposta sobrescreve `curatedFields`; nada muda `publicationStatus`; a IA segue chamada só por endereço privado (guardrail PII); o marker da camada metadata não pode bloquear a fila da IA; reexecutar não duplica nem repaga; sem segunda curadoria e sem superfície nova.
- **O que reavaliar:** a hipótese da intenção sugeria reaproveitar `buildArchivePhotoCatalogWrite` para a camada metadata (`docs/plans/album-catalogacao-producao.md:45`). A engenharia reavalia: o builder da IA carrega semântica de `people`/`alt`/`catalogedAt` que o puro não pode ter — nasce um builder dedicado **no mesmo dono**, com o texto base e o mini-merge extraídos em helpers compartilhados para as duas camadas não divergirem. O marker `catalog.metadataCheckedAt` da hipótese é adotado como proposto.
## Abordagem recomendada
```mermaid
flowchart LR
A[archivePhoto<br/>catalog vazio] --> C{fila metadata:<br/>metadataCheckedAt e catalogedAt ausentes}
C --> D[texto base puro<br/>alt · título · descrição · álbuns · tags]
D --> E[resolveMentionedMunicipalityId<br/>+ classifySpeechByGazetteer]
E --> F[buildArchivePhotoMetadataCatalogWrite<br/>município + temas · source · metadataCheckedAt]
F --> G[(transação: fresh-read curatedFields<br/>update context archivePhotoCatalog)]
G --> H[hook deriva municipalitySlug<br/>e searchText]
H --> I[POST /api/revalidate?tag=archivePhotos]
A -.-> J[fila IA intacta:<br/>catalogedAt ausente]
J --> K[archive:catalog --apply<br/>S3_* + ARCHIVE_VISION_*]
K --> L[legenda · descrição · atividade<br/>texto visível · pessoas do texto]
L --> G
I --> M[/fotos: facetas Município e Atividade<br/>card data · município · atividade + legenda]
```
**Opções consideradas:** A) duas camadas no mesmo dono, marker próprio e builder puro dedicado (recomendada) | B) só IA quando o engine subir, reusando `catalogedAt`/`source` para adiantar o texto | C) script/SQL ad-hoc paralelo.
**Recomendação:** A — o produtor de `/fotos` já existe (C233) e o que falta é dado; a camada pura é derivável do texto já ingerido (sem modelo, sem mídia) e a IA entra depois pela mesma transação/guardas do C232, sem reabrir o que o puro marcou.
**Rejeitadas:** B porque reusar `catalogedAt` para metadata torna a fila da IA ambígua — ou a IA nunca pega uma linha `metadata` (o marker bloqueia o processamento futuro), ou passa a reabri-las e o `source` deixa de ser testemunho da passada que gravou (podendo virar `none` sem nenhuma mudança de conteúdo), além de um "nada a propor" do puro bloquear a IA para sempre; C porque duplicaria transação, curadoria, guardas e recibo — exatamente o "twin" que a doutrina proíbe.
### Componentes / mudanças
**Contrato puro (no dono atual, sem I/O e sem `server-only`)**
- **`archivePhotoCatalogText(source, extras?)`** (`src/lib/archivePhotoCatalog.ts`): junta/filtra o texto base da ficha (alt, título, descrição, álbuns, tags) com extras opcionais; a IA passa `suggestion.caption`/`visibleText` (hoje inline em `src/utilities/flickr/archivePhotoCatalog.ts:199-209`) e a metadata passa vazio. Um dono do join impede as duas camadas de divergirem.
- **`buildArchivePhotoMetadataCatalogWrite({ municipalityId, gazetteerThemes, curatedFields, currentCatalog, metadataCheckedAt })`** (`src/lib/archivePhotoCatalog.ts`): merge puro que só propõe `municipality` e `themes` — **nunca `people`**; respeita `curatedFields`; devolve `{ data: { catalog: { municipality?, themes?, source: 'metadata' | 'none', metadataCheckedAt } }, source }`; nunca toca `catalogedAt`. Reusa `archivePhotoThemesFrom` (`:176-183`) e o vocabulário `ArchivePhotoCuratedField` (`:62-74`).
- **`buildArchivePhotoCatalogWrite` (edit)** (`src/lib/archivePhotoCatalog.ts:406-520`): ganha `metadataCheckedAt` na entrada e o grava no `catalog` ao lado de `source`/`catalogedAt` — a passada de IA também marca a camada metadata, pois é nela que a derivação determinística de texto roda. Os helpers privados de "o que pode ser escrito" e `pick` (`:438-469`) passam a ser compartilhados pelos dois builders, sem mudar comportamento.
- **Testes do puro** (`tests/unit/archivePhotoCatalog.unit.spec.ts:26-50,195+`): factories `suggestion()`/`writeInput()` ganham `metadataCheckedAt`; novo describe do builder metadata (campos propostos, curated vence, `source`, markers, nunca `people`).
**Server-side Payload (mesmo arquivo dono do C232)**
- **`listArchivePhotoMetadataCatalogQueue` / `catalogArchivePhotoMetadata`** (`src/utilities/flickr/archivePhotoCatalog.ts`, `import 'server-only'` já no topo): fila `where { 'catalog.metadataCheckedAt': { exists: false }, 'catalog.catalogedAt': { exists: false } }` (o segundo termo protege legado/linha já catalogada), sem download/sharp/engine — só DB. Reusa `toItem`/`catalogSelect` (`:68-105`), `resolveMentionedMunicipalityId` (`src/utilities/municipality/municipalityMentionResolver.ts:15-38`), `classifySpeechByGazetteer` (`src/lib/speechGazetteer.ts:447`) e `archivePhotoCatalogText`; devolve o mesmo `ArchivePhotoCatalogResult`. Estágios de falha: `resolve` e `write`.
- **Núcleo transacional extraído (privado)** no mesmo arquivo: fresh-read `{ alt, curatedFields, catalog }` + `skip(doc)` + `payload.update` com `context: { archivePhotoCatalog: true }` + `withPayloadTransaction` (`src/utilities/payloadTransaction.ts`), parametrizado por um `buildWrite(doc)`; a derivação de texto (município/temas) compartilhada fica em `deriveArchivePhotoCatalogText`. `catalogArchivePhoto` (IA) e `catalogArchivePhotoMetadata` passam a chamá-lo; o comportamento externo da IA é inalterado (download → image → analyze → resolve continuam com os mesmos estágios nomeados).
- **Fila da IA** (`listArchivePhotoCatalogQueue`, `:113-143`): inalterada — continua sendo o único dono do `catalogedAt`; a IA passa a gravar `metadataCheckedAt` no write (via builder).
**Schema**
- **Campo `metadataCheckedAt`** no `catalogGroup` (`src/collections/ArchivePhoto.ts:53-153`), depois de `catalogedAt`: `date`, `index: true`, `admin.readOnly: true`, descrição de idempotência da camada sem IA ("preenchida não reprocessa o puro"). Precedente de marker só-de-batch: `faces.checkedAt/checkedKey` do C234 (`src/collections/ArchivePhoto.ts:311-337`; gravação em `src/utilities/faceIndex/faceDescriptorIndex.ts:243-252`).
- **Migration `add_archive_photo_metadata_checked`**: `pnpm migrate:create add_archive_photo_metadata_checked` gera `.ts`/`.json` + registro em `src/migrations/index.ts` (não editar à mão; última entrada hoje `20261001_040904_add_archive_photo_face`, `:563-565`). Aditiva: coluna `catalog_metadata_checked_at timestamp(3) with time zone` + índice `archive_photo_catalog_catalog_metadata_checked_at_idx`; `down` derruba índice e coluna — mesmo padrão de `src/migrations/20260926_132106_add_archive_photo_catalog.ts:39,54,72,81`. `push:false` (`src/payload.config.ts:173`); `pnpm generate:types` em seguida.
**CLI/ops**
- **`--metadata-only`** (`scripts/catalog-archive-photos.mjs` + `scripts/lib/archiveCatalogPlan.mjs:23-60`): seletor de camada em plan/`--apply`/`--verify`. No `--apply` metadata-only as guardas caem para `assertWriteConfirm` (`ARCHIVE_CATALOG_CONFIRM`) + `assertEnvironmentDatabaseTarget` (`scripts/lib/cli.mjs:312-320,238-301`), **sem** `mirroredMediaRequired` (`:197-202`) e **sem** `assertLocalVisionEndpoint`/`ARCHIVE_VISION_MODEL` (`:373-403`) — não há mídia nem engine no caminho. No modo IA, tudo como hoje.
- **Recibo/inventário layer-aware** (`scripts/lib/archiveCatalogPlan.mjs:72-195`): parser com `metadataOnly`; resumo ganha `layer: 'metadata' | 'ai'`; `summarizeArchiveCatalogInventory` passa a expor `metadata: { checked, pending }`, `ai: { cataloged, pending }`, `bySource`, cobertura (`withoutScene` sobre as linhas da IA, `withoutMunicipality` sobre as linhas verificadas pelo metadata) e `missingFilename`; as linhas humanas mostram **as duas camadas** e o exit do `--verify` é pela camada selecionada (`--metadata-only` → pendência metadata; sem flag → pendência IA).
- **Runbook §C245** em `docs/ops/teqo-1313-deploy.md`, antes de `## C242` (`:1455`): passo 1 metadata-only em produção (sem engine/S3); passo 2 `POST /api/revalidate?tag=archivePhotos` (o write no container de manutenção não busta o ISR do app — `revalidateTagSafely` no-op fora de request, `src/utilities/documents.ts:27-34`; tag allowlistada em `src/utilities/revalidateRequest.ts:15,38`; rota `src/app/(frontend)/api/revalidate/route.ts:84`); passo 3 IA quando o engine subir (subida já documentada em §C232, `:1411-1433`); verificação e rollback funcional (grupo aditivo; limpar no admin como em `:1451-1453`).
- **Changelog** `docs/changelog/<data>-c245.md` (parágrafo único iniciando `**C245 — ... (data):**`, molde `docs/changelog/2026-09-26-c232.md:1`; guard additions-only `scripts/check-changelog-append-only.mjs:105-115`).
- **Migration:** a acima (aditiva, 1 coluna + 1 índice; stop humano antes de executar no fluxo `--auto`).
- **Access / Consent:** intocados — `canReadArchivePhoto`/`payloadAdminOnly` e `publicationStatus` não mudam; o CLI continua o ator confiável com `overrideAccess: true` documentado (`src/utilities/flickr/archivePhotoCatalog.ts:132-133,232-233,265-266`). Sem Consent novo: não há coleta nova, biometria ou publicação.
- **UI:** nenhuma (Impeccable A) — a ficha usa o grupo `catalog` existente (campo novo readOnly) e as facetas/card do C233 (`src/lib/archivePhotoPublicCatalog.ts:264-300,308-317,337-369`) passam a renderizar quando houver dado; a superfície pública só reflete depois da revalidação da tag. Sem dispatch de designer.
### Dados → forma (se aplicável)
Não aplicável — a intenção declara que a catalogação não apresenta números; cobertura por camada é recibo operacional do `--verify`, não leitura pública.
## Decisões de engenharia
### D1 — Marker próprio da camada metadata
- **Opções:** A) coluna nova `catalog.metadataCheckedAt` (date, index, readOnly), com migration aditiva | B) reusar `catalog.catalogedAt` com `source=metadata`.
- **Recomendação:** A — a fila da IA é "`catalogedAt` ausente" (`src/utilities/flickr/archivePhotoCatalog.ts:126`) e precisa continuar sendo; o marker separado espelha o precedente C234 (`faces.checkedAt/checkedKey`, `src/collections/ArchivePhoto.ts:311-337`; int `tests/int/faceDescriptorIndex.int.spec.ts:138-143`).
- **Rejeitadas:** B porque faria a IA nunca pegar a linha `metadata` (ou exigiria reabri-la), tornando o `source` um recálculo — podendo virar `none` numa linha já gravada sem mudança de conteúdo (procedência desonesta) — e porque um "nada a propor" do puro bloquearia a IA permanentemente; `catalogedAt` segue chave exclusiva da IA e o `source` segue contando o que de fato entrou.
### D2 — Duas filas, duas semânticas
- **Opções:** A) fila metadata = `metadataCheckedAt` ausente **e** `catalogedAt` ausente; fila IA = `catalogedAt` ausente (inalterada); a passada de IA grava `metadataCheckedAt` junto | B) fila metadata = só `metadataCheckedAt` ausente | C) um único `--refresh`.
- **Recomendação:** A — a condição dupla evita reprocessar linha já catalogada pela IA (incluindo legado com `catalogedAt`, hoje zero em produção) e evita rebaixar `source`; a IA marca a camada metadata porque a derivação de texto roda dentro dela (linha que passou pela IA já passou pelo puro). `--verify` relata as duas camadas; `--metadata-only --verify` falha por pendência de metadata, sem a flag por pendência de IA, sempre listando as duas.
- **Rejeitadas:** B porque uma linha legada com `catalogedAt` entraria na fila de metadata e poderia recomputar `source` (`ai` → `metadata`/`none`); C porque não há necessidade de reprocessar e o refresh reabriria a porta para repagar tudo.
### D3 — Builder puro dedicado + texto base compartilhado
- **Opções:** A) `buildArchivePhotoMetadataCatalogWrite` novo no mesmo lib, com helpers de merge/texto compartilhados com o builder da IA | B) reusar `buildArchivePhotoCatalogWrite` com `suggestion` vazio | C) SQL direto.
- **Recomendação:** A — o builder novo só propõe `municipality`/`themes`, nunca `people`, devolve `source` honesto (`metadata|none`), grava `metadataCheckedAt` e nunca `catalogedAt`; `archivePhotoCatalogText` elimina a divergência do texto base (hoje inline em `src/utilities/flickr/archivePhotoCatalog.ts:199-209`). Os helpers privados de `pick`/`writes` são compartilhados (depth check: nenhum módulo novo nasce para copiar o que já existe).
- **Rejeitadas:** B porque reusar o builder da IA com sugestão vazia gravaria `catalogedAt` (bloqueando a fila da IA para sempre) e misturaria a semântica de `people`/`alt` da IA na camada que não pode tê-las; C porque joga fora transação, curadoria e os hooks que derivam `municipalitySlug`/`searchText`.
### D4 — Pipeline metadata no dono server-side, núcleo transacional único
- **Opções:** A) `listArchivePhotoMetadataCatalogQueue` + `catalogArchivePhotoMetadata` em `src/utilities/flickr/archivePhotoCatalog.ts`, com o núcleo fresh-read/skip/update/context extraído e compartilhado com a IA | B) pipeline em arquivo novo | C) duplicar o bloco transacional dentro do CLI.
- **Recomendação:** A — o dono server-side já é esse arquivo (C232) e o padrão "fresh-read dentro da transação + `context.archivePhotoCatalog` + bypass documentado" não pode existir em duas versões; a extração é privada (API pública inalterada) e os pipelines diferem só no que antecede a transação (download/sharp/analyze vs. nada) e no `shouldSkip` (`catalogedAt` para IA; `metadataCheckedAt || catalogedAt` para metadata). O item reusa o mesmo `ArchivePhotoCatalogItem`/`toItem`/`catalogSelect`.
- **Rejeitadas:** B cria o twin do pipeline no mesmo domínio; C tira transação/curadoria do dono e faz o CLI conhecer o shape da ficha.
### D5 — CLI `--metadata-only` com guardas por camada e recibo honesto
- **Opções:** A) `--metadata-only` como seletor de camada; apply metadata-only não exige `S3_*` nem engine; verify biplex com exit pela camada | B) comando novo (`archive:catalog:metadata`) | C) exigir as guardas completas mesmo no metadata-only.
- **Recomendação:** A — a camada pura não baixa mídia nem chama engine, então exigir S3/`ARCHIVE_VISION_*` só criaria bloqueio artificial em produção (o engine está fora do ar, que é o motivo do item); as guardas que importam (`ARCHIVE_CATALOG_CONFIRM`, `TEQO_ENV` com o nome exato do banco) continuam. O recibo carrega `layer` e o `--verify` mantém a leitura das duas camadas — metadata pendente não esconde IA pendente.
- **Rejeitadas:** B multiplica scripts e recibo; C atrasa a entrega de valor (município) atrás de um engine indisponível.
### D6 — Entrega e execução em produção
- **Opções:** A) ferramenta + runbook §C245 na mesma entrega; execução em produção como passo operacional pós-merge com revalidação da tag | B) executar o lote de produção nesta sessão | C) publicar direto pela UI.
- **Recomendação:** A — a sessão de implementação não escreve em produção (proibição da skill; DB de prod é stop): o runbook documenta metadata-only primeiro (sem engine), `revalidate` da tag `archivePhotos`, verify, e a IA quando o engine subir. Nenhuma UI nova (Impeccable A; sem dispatch de designer).
- **Rejeitadas:** B viola o guardrail de escrita em produção e o stop de banco; C não existe — a publicação é a C233 e continua ato humano.
### D7 — Testes
- **Opções:** A) unit do builder/texto; unit do parser/inventário/linhas layer-aware; guarda por subprocesso; int metadata→IA sobre `teqo_wt245_test`; sem e2e novo (OPS72) | B) e2e novo | C) só manual.
- **Recomendação:** A — cobre o que não pode falhar em silêncio: (i) unit `tests/unit/archivePhotoCatalog.unit.spec.ts` (builder metadata: município/temas, curated vence, `source`, `metadataCheckedAt`, nunca `people`; builder IA grava o marker); (ii) unit `tests/unit/archiveCatalogPlan.unit.spec.ts:16-141` (parser com `metadataOnly`, resumo com `layer`, inventário de duas camadas, linhas); (iii) `tests/unit/archiveCatalogCli.unit.spec.ts` (harness spawnSync `:12-36`): com `--metadata-only --apply`, `ARCHIVE_VISION_BASE_URL` pública setada e sem S3, o processo **não** morre nas guardas de engine/S3 — sem tocar banco real (porta local fechada; asserção nas mensagens ausentes `host público`/`S3_BUCKET`/`ARCHIVE_VISION_BASE_URL ausente`); (iv) int `tests/int/archivePhotoCatalog.int.spec.ts` (fixtures `:67-121`): metadata grava município/temas/marker e não grava `people`/`catalogedAt`; a linha sai da fila metadata e **continua** na fila IA; a IA depois grava caption/scene, preserva o município e reescreve o marker; linha legada (com `catalogedAt` e sem marker, escrita com `context.archivePhotoCatalog`) é excluída das duas filas; curadoria vence; falha da resolução (payload de teste que delega ao real mas lança no `find` da collection `municipality`) não escreve e a linha permanece na fila. Sem e2e novo: a superfície admin é stock e o álbum já é coberto (`frontendFotos`, OPS72).
- **Rejeitadas:** B porque o admin é stock e o álbum não muda (OPS72); C porque idempotência/curadoria/guardas são exatamente o risco do lote.
## Fases verificáveis
1. **Fase 1 — Contrato puro + schema** (quota ~0,25 dia): `archivePhotoCatalogText`, `buildArchivePhotoMetadataCatalogWrite`, `metadataCheckedAt` no builder da IA (e factories do unit), campo no `catalogGroup`; `pnpm migrate:create add_archive_photo_metadata_checked` (revisar diff à mão), `pnpm migrate` local, `pnpm generate:types`; unit do puro. Gate: `pnpm gate:fast`.
2. **Fase 2 — Pipeline metadata** (quota ~0,25 dia): fila/pipeline + núcleo transacional extraído em `src/utilities/flickr/archivePhotoCatalog.ts`; int metadata→IA no `teqo_wt245_test`. Gate: `pnpm gate:fast` + int local.
3. **Fase 3 — CLI layer-aware** (quota ~0,25 dia): parser/resumo/inventário/linhas, `--metadata-only`, guardas por camada; unit de `archiveCatalogPlan` e do subprocesso; plan/`--verify` contra o banco do worktree (read-only). Gate: `pnpm gate:fast`.
4. **Fase 4 — Ops e entrega** (quota ~0,25 dia): runbook §C245 antes de `## C242`, changelog `docs/changelog/<data>-c245.md`, plano no commit/PR. A execução em produção (metadata-only → revalidate → verify; IA quando o engine subir) fica documentada no runbook e **fora do run desta sessão**.
## Rabbit holes / Não escopo (engenharia)
- Engine de visão de terceiro, OCR dedicado, recorte/edição de imagem — produto já cortou (PII) e a intenção manda fora.
- `catalog.people` derivado de texto na camada metadata — o C244 assume a faceta por facial; escrever aqui seria inventar a segunda curadoria de pessoa.
- Reabrir linhas com `catalogedAt` (legado) ou criar `--refresh` — nenhuma linha legada existe hoje e a fila dupla de D2 já resolve o futuro.
- Backfill de `metadataCheckedAt` em linhas já catalogadas — sem demanda; a IA grava o marker quando roda.
- Superfície nova de revisão/fila de curadoria — Impeccable A; só nasce no gate.
- Env nova (`ARCHIVE_METADATA_*`) — a camada pura não precisa de engine/mídia.
- Segundo script/comando ou segunda fila para a metadata — o seletor `--metadata-only` é a camada.
- Otimizar o lote (paralelismo, bulk update) — 6,5k linhas DB-only cabem no tempo de máquina; medir antes.
## Adiado com gatilho (pós-simplify)
- **Predicado único de "metadata pendente"** (fila no `where`, `skip` transacional e inventário):
hoje a mesma semântica mora em 3 mecânicas diferentes. **Gatilho:** um quarto
consumidor em JS ou uma mudança da regra (novo marker/refresh) — aí extrair o
predicado no dono. (cheap_polish, score 2)
- **Corrida metadata×IA no write** (o skip lê `catalogedAt`, mas um commit de IA entre o
read e o update da metadata poderia rebaixar o `source`): as camadas rodam
serializadas por ops (runbook) e o `source` da IA não é sobrescrito por mutação de
campos; **gatilho:** se as camadas passarem a rodar concorrentes, trocar por update
condicional por marcador. (cheap_polish, score 2)
- **Teste de falha de resolução** espião no primeiro `payload.find`: **gatilho:** próxima
edição do pré-transação de `catalogArchivePhotoMetadata` — estreitar o stub por
collection. (cheap_polish, score 2)
## Riscos e mitigação
1. **Migration no fluxo `--auto`** — é aditiva e pequena (1 coluna + 1 índice), mas o fluxo para para confirmação humana antes de executá-la; o diff gerado é revisado à mão contra o snapshot e aplicado primeiro no banco do worktree; nenhuma migration entregue é reescrita.
2. **Escrita em produção fora de hora** — o run desta sessão não escreve em produção; os guardas `ARCHIVE_CATALOG_CONFIRM` + `TEQO_ENV=production`/`teqo_1313` continuam, e o passo 1 do runbook roda no serviço de manutenção com o env file do stack.
3. **Cache ISR não bustado pelo CLI** — o write no container não tem request scope (`src/utilities/documents.ts:27-34`); sem o passo 2 (`POST /api/revalidate?tag=archivePhotos`) as facetas não aparecem. O runbook fixa a ordem: apply → revalidate → verify.
4. **`undefined` vs `null` e curadoria** — Payload ignora `undefined` e nunca limpa; os builders nunca devolvem `null` para "não escrever" (só `undefined`/omitido), e o fresh-read dentro da transação garante que uma edição humana concorrente vence (precedente C234 `faces`, `tests/int/faceDescriptorIndex.int.spec.ts:138-143`).
5. **Marker bloqueando a IA** — a fila da IA continua sendo só `catalogedAt`; o int metadata→IA prova que a linha marcada pelo metadata volta à fila da IA e que a IA mantém município/temas.
6. **CI high-risk** — a migration e a edição de `src/collections/ArchivePhoto.ts` puxam unit/int full + e2e curado, e `src/utilities/flickr` mapeia para `frontendFotos`/`frontendFotosSelfie` (`scripts/lib/e2e-affected-manifest.mjs:57,224-239`); manter o PR focado. `scripts/lib/archiveCatalogPlan.mjs` é pinado (`scripts/lib/test-affected-core.mjs:46`) e o invariante de closure segue fechado (`tests/unit/ciSkipInvariants.unit.spec.ts:192-216`).
7. **Cobertura parcial do texto** — município/atividade só entram quando o texto (ou a visão) sustenta; o `--verify` reporta `withoutMunicipality`/`withoutScene` por camada e nada é inventado.
8. **Spec de subprocesso tocando banco** — o caso metadata-only usa porta local fechada e asserção nas mensagens ausentes; nunca aponta para um banco real.
9. **Contrato do `--verify` antigo** — a saída muda (duas camadas) e o exit passa a depender da flag; o runbook e o changelog citam a mudança para o operador.
## Aceite de engenharia
- [ ] Builder metadata puro cobre o aceite: só `municipality`/`themes`, nunca `people`; `curatedFields` vence; `source` ∈ `metadata|none`; grava `metadataCheckedAt`, nunca `catalogedAt`; o builder da IA grava `metadataCheckedAt` junto do `catalogedAt`.
- [ ] Fila metadata = `metadataCheckedAt` ausente e `catalogedAt` ausente; fila IA inalterada; int prova o ciclo metadata→IA (município/temas preservados, caption/scene depois, legado excluído, curadoria vence, falha não escreve).
- [ ] `/fotos` exibe **Município** após a camada metadata (via `municipalitySlug` derivado no hook + revalidação da tag) e **Atividade**/legenda após a camada IA; `curatedFields` sempre vence; nada é publicado.
- [ ] Migration `add_archive_photo_metadata_checked` gerada, revisada, aplicada local, index registrado, tipos regenerados; `push:false` mantido.
- [ ] `--metadata-only` em plan/apply/verify; apply metadata-only exige só `ARCHIVE_CATALOG_CONFIRM` + `TEQO_ENV`; verify sempre lista as duas camadas e o exit é pela selecionada.
- [ ] Runbook §C245 antes de `## C242` (metadata-only → revalidate `archivePhotos` → verify → IA quando o engine subir; rollback) e changelog `docs/changelog/<data>-c245.md` entregues; nenhuma UI nova.
- [ ] Access/Consent intocados; bypass `overrideAccess` documentado; sem env nova; sem segundo pipeline/script.
- [ ] Gates: `pnpm gate:fast`, int local, e2e curado do CI verdes; deploy staging-primeiro; execução em produção documentada e fora da sessão.
## Self-score (decision-quality)
1. Decisões caras com rejeitadas? **Sim** — D1–D7 têm opções, recomendação e rejeitadas explícitas (marker vs `catalogedAt`, builder dedicado vs reuso, guardas por camada, etc.).
2. Abordagem cabe no appetite? **Sim** — ~1 dia de engenharia em 4 fases de ~0,25 dia; o tempo de máquina (6,5k linhas DB-only, depois IA quando o engine subir) fica fora do código.
3. Rabbit holes nomeados? **Sim** — terceiro/OCR, pessoas por texto, refresh/legado, backfill, superfície nova, env nova, segundo script, otimização prematura do lote.
4. Depth check: reusa shells/helpers? **Sim** — fila/item/select, `resolveMentionedMunicipalityId`, `classifySpeechByGazetteer`, `withPayloadTransaction`, contexto/hook do `archivePhotoCatalog`, guardas de `cli.mjs`, precedente C234 de marker, CLI/recibo C232, revalidação da tag existente.
5. Intenção permanece satisfeita? **Sim** — o outcome (facetas e card com dados reais, duas camadas, idempotente, curadoria vence, nada publicado) não muda; a engenharia só escolhe como.
**Score: 5/5.**