# Impl: C120 — race de append de telefone em findOrCreateContactByPhone (lock de ficha) Status: aprovado Atualizado em: 2026-08-24 Issue: #663 Intenção: body da Issue (fonte única — não há `docs/plans/c120-*.md` de intenção; o body é a spec) Appetite restante: herdar sem appetite declarado (P2) ## Leitura da intenção - **Outcome (aceite):** dois fluxos concorrentes contra a MESMA ficha nunca perdem um telefone digitado — ou, na alternativa, uma decisão documentada de aceitar a perda com rationale. O alvo nomeado é `findOrCreateContactByPhone` (`src/utilities/contactIdentity.ts`). - **O que NÃO negociar:** granularidade de lock por ficha (não trocar o modelo de identidade); sem mudança de schema (nenhuma migration; `contact_phones` relacional intocado); sem mudança de Access/Consent; editar o dono que já possui o concern (locks de contato), não criar caminho paralelo. - **Por que não foi no C112:** a granularidade por-telefone é herdada do C111; o C112 alargou a janela ao introduzir o append-on-reuse (re-registro/import da MESMA pessoa com 1 ficha e primário inambíguo). Dois fluxos que resolvam a mesma ficha por primários DIFERENTES (ficha com 2+ números) não disputam nenhum `contact-phone:*` em comum — os locks por-telefone disjuntos não os serializam, os dois leem o array pré-mudança e o last-writer-wins perde um append. O lock por ficha é o ponto de serialização correto. - **O que reavaliar:** (a) o MECANISMO — lock de ficha+re-read (A) vs escrita determinística SQL (B) vs aceitar/documentar (C); (b) se o RMW do sync conta→ficha (`CampaignUser.ts`) entra no escopo mesmo com o custo CI de `src/collections/` (HIGH_RISK); (c) os editors full-replace de staff — entrarem ou serem documentados como fora do aceite; (d) se a chave do invite redemption (`invite-redemption-contact:`) é unificada agora ou vira débito; (e) a forma do spec int (chamada direta da unidade vs através dos flows de action, que exigem consent/municipality etc.). ## Abordagem recomendada O núcleo é lock de ficha `contact-ficha:` AO REDOR do read-modify-write **com re-leitura da ficha DENTRO do lock**. Sem a re-leitura o lock não resolve nada: o array lido no `find` pré-lock pode estar stale e o append ainda se perde. Os locks de telefone de hoje são mantidos (são a serialização cruzada entre fichas distintas no create-path e a proteção de dedupe de criações concorrentes); o ficha-lock é sempre adquirido POR ÚLTIMO e sozinho (uma chave de entidade por RMW), então não existe ciclo de lock-order. ```mermaid sequenceDiagram participant A as Fluxo A (tx₁) participant P as Postgres participant B as Fluxo B (tx₂) Note over A,P: locks de telefone disjuntos: P1,P3 (A) vs P2,P4 (B) A->>P: acquire(contact-phone:P1, contact-phone:P3) B->>P: acquire(contact-phone:P2, contact-phone:P4) A->>P: find contact where phones.value=P1 → ficha F B->>P: find contact where phones.value=P2 → ficha F Note over A,B: gate segura os DOIS finds → ambos leem [P1,P2] pré-mudança A->>P: acquire(contact-ficha:F) %% NOVO — lock de ficha, por último A->>P: findByID F (re-read, select phones) → [P1,P2] A->>P: update F phones=[P1,P2,P3] B->>P: acquire(contact-ficha:F) %% bloqueia até o commit de A (xact lock) A->>P: commit → libera o lock B->>P: findByID F (re-read fresco) → [P1,P2,P3] B->>P: update F phones=[P1,P2,P3,P4] B->>P: commit Note over P: F = {P1,P2,P3,P4} — nenhum telefone digitado perdido ``` Sem o fix, A e B escrevem `[P1,P2,P3]` e `[P1,P2,P4]` a partir do MESMO array lido `[P1,P2]` e o último commit vence — final com 3 números, P3 ou P4 perdido (last-writer-wins). O lock de xact garante commit-then-release: o segundo fluxo a entrar sempre re-lê o append do primeiro (que já está commitado) e só acrescenta os seus faltantes. **Opções consideradas:** - **A — lock de ficha `contact-ficha:` + re-read dentro do lock (recomendada):** após o `find` retornar exatamente 1 ficha (`totalDocs === 1`), adquirir o lock, re-ler a ficha via `findByID` (depth 0, `select: { phones: { value: true } }`) dentro do lock e montar o append de faltantes sobre essa leitura fresca; `update` só se `missing > 0`. Mantém os phone locks e o `find` de dedupe intactos. Custo: 1 round-trip de lock + 1 `findByID` seletivo, só no branch de reuso (caminho raro). - **B — escrita determinística via SQL (rejeitada):** append direto na tabela relacional `contact_phones` (`_parent_id`/`_order`/`value`) sem read prévio. Rejeitada porque: `contact_phones` não tem índice UNIQUE nem validação própria — a dedupe intraficha vive só em memória (`normalizeContactPhones`, `Contact.ts:22-59`); um insert SQL burlaria o adapter/hook do Payload (validation, `overrideAccess`, transação única) e o commit atômico com o resto do flow; a mesma garantia custaria algo razoável, mas com blast radius de camada inteira (SQL + ordenação `_order` + validação), para um problema que um advisory lock resolve com 3 linhas no padrão já existente do repo. - **C — aceitar e documentar (rejeitada):** a perda não é benigna em escopo: é um número digitado que SOME silenciosamente num cadastro de rotina (dois registros da mesma pessoa via canais/arquivos diferentes é uso real do apoiador/liderança flow, não janela desprezível), o dado é PII recém-coletado e o custo do fix (A) é baixo e in-pattern. Aceitar exigiria além disso um rationale de produto que não existe. **Recomendação:** A. **Rejeitadas:** B (camada errada — contorna o dono), C (dado coletado some), e também o lock de ficha SEM re-read (insuficiente por construção: serializa a escrita mas não o conteúdo — a re-leitura dentro do lock é a parte que torna o append correto). ### Componentes / mudanças - **~ `src/utilities/contactPhoneLocks.ts`** — adicionar `contactFichaLockKey(id)` → `contact-ficha:${id}` e `acquireContactFichaLock(payload, req, id)` (um wrapper de `acquireTextAdvisoryLocks`). Fica no dono dos locks de contato; a chave segue o padrão das locks por entidade existentes (`campaign-demand:`, `activity:`, `contact-name:`, `person-delete:`). - **~ `src/utilities/contactIdentity.ts:68-87`** — no branch `totalDocs === 1`, após resolver a ficha: `await acquireContactFichaLock(payload, req, existing.id)`; re-ler a ficha com `payload.findByID` (depth 0, `select: { phones: { value: true } }`, `overrideAccess: true`, `req`) DENTRO do lock; montar `missing` e o array final sobre a RE-LEITURA (não sobre `docs[0]` do find); `update` só com `missing > 0`. Atualizar o doc-comment do módulo (mencionar a serialização por ficha no reuso). - **~ `src/collections/CampaignUser.ts:270-291`** — no RMW do sync conta→ficha (account phone mudou e a ficha existe), adquirir `contact-ficha:` antes do `findByID` existente (que já é a leitura do RMW: lock antes do read serializa read+write com um lock só). **DECISÃO: ENTRA no escopo.** Mesma classe de perda (append perdido → número digitado some no sync), mesmo padrão/dono, e o hook já roda em transação no postgres (C99/int exercita phone locks dentro desses hooks — `req.transactionID` existe). Custo: 2 linhas vs 1 camada de risco real no mesmo defeito silencioso. O custo CI (collections = HIGH_RISK) está registrado em Riscos e em Fases. - **+ `tests/int/contactPhoneAppendRace.int.spec.ts`** — spec de concorrência (ver Fase 2). - **Full-replace editors (`updateSupporterContactRecord` em `actions/supporter.ts:216-223`, `contact.ts`, `leadership.ts` field `phones`/wizard, `advisor.ts`, tombstones e o branch `phone` do `leadership.ts` inline) — FORA do aceite (documentado, não alterado):** a semântica de um editor é "o array é agora exatamente isto" — a ficha lock não muda o last-writer-wins de um replace; e o branch `phone` inline (reorderWithPrimaryPhone) é edição explícita de staff que define o primário, não append implícito. O lock só faz sentido onde dois fluxos appendam sem intenção de sobrescrever. Documentar no header do `contactPhoneLocks.ts` (quem serializa o quê) e no commit. - **Invite redemption (`invite-redemption-contact:`, `campaignInviteRepository.ts:127-132`)** — RMW do profile JÁ serializado, mas por chave DIFERENTE → ficha não fica globalmente serializada entre create-flow e redemption-flow. **DECISÃO: capturar como débito**, não unificar agora (unificar é renomear a chave e revalidar os specs de redemption — escopo e risco extras sem relação com o aceite de C120). Nova Issue de débito. - **Migration:** sem migration (nenhuma mudança de schema; `contact_phones` continua `_parent_id`/`_order`/`value`, sem índice UNIQUE, dedupe intraficha segue em memória). - **Access/Consent:** n/a (sem mudança de acesso; `overrideAccess: true` inalterado nos pontos tocados, coberto pelos gates de fluxo existentes). - **UI:** n/a. ## Fases verificáveis 1. **Schema+server** — editar `contactPhoneLocks.ts`, `contactIdentity.ts` e `CampaignUser.ts`, conforme Componentes. Nenhuma migration; nenhum tipo novo (`generate:types` desnecessário — não há campo novo). Verificação local: `tsc --noEmit`. 2. **Teste int** — criar `tests/int/contactPhoneAppendRace.int.spec.ts` (formato abaixo) e rodar com o db de teste do worktree (`pnpm test:int contactPhoneAppendRace`). **Prova em duas direções:** rodar o spec contra o código ATUAL (sem o fix) e ver a asserção `{P1,P2,P3,P4}` falhar com 3 números (prova a perda — o teste não é tautológico); com o fix, a mesma spec passa (prova a sobrevivência). O teste fixa a regressão. 3. **Gates de CI** — com `src/collections/` no diff (CampaignUser), o CI `checks` roda int FULL + e2e CURATED + build + unidades changed (OPS86: diff high-risk nunca zero); `contactIdentity.ts`/`contactPhoneLocks.ts` não têm entrada no manifest nem em `E2E_RISK_PREFIXES` — mas o HIGH_RISK de collections sobrepõe o fallback `campaignHomeActions`. Rodar full cascade local: guards → lint → format → typecheck → knip → cycles → unit → int → build. **Formato do spec int de concorrência (Fase 2):** - Plantar a ficha alvo `F = {P1, P2}` via `campaignFixtures().createContact({ phones: [{ value: P1 }, { value: P2 }] })` (P1/P2 de `campaignFixtures().phone()`). - Dos fluxos CONCORRENTES com primários DIFERENTES e conjuntos de telefone DISJUNTOS (requisito — se os phone locks se sobrepõem, a serialização por-telefone mascara a race): fluxo A `[P1, P3]`, fluxo B `[P2, P4]`, cada um chamando `findOrCreateContactByPhone` direto dentro de `withPayloadTransaction` (que abre transação real e fornece o `req` com `transactionID` — exigência do advisory lock). Forma DECIDIDA: chamada direta da unidade, não via `createSupporterRecord`/`createLeadershipRecord` — os flows de action adicionam consent + municipality + dedupe de liderança/supporter (outras unidades sob teste e mais fixtures), enquanto a unidade sob teste é exatamente `findOrCreateContactByPhone` e ambos os flows reais a chamam de forma idêntica dentro das suas transações. - Gate com `findSpy` sobre `payload.find` segurando o 1º find de AMBOS os fluxos (`firstReadGate`/`firstReadReached`, padrão de `campaignLeadership.int.spec.ts:181-285`, porém com gate nos DOIS reads) — garante que ambos leem o estado `[P1,P2]` antes de qualquer escrita, tornando a perda determinística sem o fix e a sobrevivência determinística com o fix (o xact lock garante: quem entrou por último re-lê o append já commitado do primeiro). Disparar via `Promise.allSettled`. - Asserções: ambos resolvem com `reused: true` e `contactID === F.id`; a ficha F final tem EXATAMENTE {P1,P2,P3,P4} (comparação por conjunto). O assert do waiter de pg_locks (`waitForAdvisoryLockWaiter` + PID via `beginSpy`, que funciona no existing spec porque o waiter vira determinístico quando os dois reads estão gated) pode reforçar o mecanismo, mas não é exigido pelo aceite — o state final basta. - Cleanup: `installCampaignFixtures` (markers + owned) cuida do teardown. ## Rabbit holes / Não escopo - **Lock ordering:** em `findOrCreateContactByPhone`, phone locks são adquiridos em batch ordenado ANTES de qualquer lock de entidade; o ficha-lock é adquirido por ÚLTIMO e sempre SOZINHO (uma chave de ficha por RMW; o branch `totalDocs !== 1` não faz RMW e não ganha lock). Nenhum fluxo segura 2 chaves de entidade de contato simultaneamente (`person-delete:` e `contact-name:`, `invite-redemption-contact:` seguem com chaves próprias e nunca são combinadas com `contact-ficha:*`) — sem ciclo. - **Escrita determinística SQL:** rejeitada (opção B) — exigiria validar/ordenar/ deduplicar fora do hook e do adapter. - **Full-replace/reorder editors:** fora do aceite, documentados (ver Componentes). - **Unificar a chave do invite redemption:** débito capturado, não no escopo. - **Branch de criação (`totalDocs === 0` / `2+`):** sem mudança — a identidade na criação é a ficha recém-escrita e os phone locks já serializam as criações concorrentes. - **Não mexer em `supporterImport.ts`** (modelo de "todos os phones locked up front" intacto). - **Não adicionar lock em `updateSupporterContactRecord`** nem nos demais editors. ## Riscos e mitigação - **Lock de ficha sem re-read ser insuficiente contra a intenção:** não — a re-leitura é parte integrante do componente (fora do lock o fix seria inócuo). O spec int cobre os dois fluxos re-lendo dentro do lock. - **`CampaignUser.ts` sem transação ativa em algum chamador do hook:** no postgres o adapter envolve cada mutation numa transação e expõe `transactionID` aos hooks (evidência C99/int: os phone locks já rodam dentro desses hooks). Se um chamador futuro invocar o update sem transação, `acquireTextAdvisoryLocks` lança com a mensagem fail-closed padrão — nunca perde dado silenciosamente. Residual baixo. - **Deadlock entre fluxos:** chaves de ficha e telefone disjuntas entre os fluxos do aceite (A usa P1,P3 e F; B usa P2,P4 e F — só F em comum, e a ficha é sempre a última); nenhum fluxo adquire uma chave de outro fluxo depois de segurar a própria. A invariante de ordenação é única no código (documentada no comment do módulo). - **Custo CI (collections = HIGH_RISK):** int full + e2e curated + build no PR. Patch pequeno e de padrão já coberto; o custo é o preço da camada de serialização no sync conta→ficha (C99 já paga esse preço hoje por incluir o hook em collections). - **Re-read extra (perf):** 1 `findByID` seletivo a mais, só no branch de reuso; desprezível vs. o round-trip de lock já existente no mesmo caminho. - **Ficha deletada entre o `find` e o lock (`person-delete` concorrente):** a re-leitura falha com erro claro → rollback da transação (fail-closed), sem corrupção. Fora do aceite. - **Flakiness do spec:** telefones únicos por fixture (`phone()`), gate determinístico nos dois reads, transações via `withPayloadTransaction` (commit/rollback corretos); `waitForAdvisoryLockWaiter` só reforça o mecanismo e usa espera ativa com timeout (padrão já usado no repo). ## Aceite de engenharia - [ ] Aceite da intenção: dois fluxos concorrentes contra a mesma ficha nunca perdem um telefone digitado (spec int prova a perda sem o fix e a sobrevivência com o fix) - [ ] Decisão de concorrência registrada (A recomendada) com B e C rejeitadas e rationale - [ ] Invariantes AGENTS/engineering-standards: sem migration, sem schema, sem Access/Consent; edita o dono (`contactPhoneLocks.ts`); sem paralelismo de caminho - [ ] Testes de domínio previstos: `tests/int/contactPhoneAppendRace.int.spec.ts` (concorrência por ficha, primários distintos, gate nos dois reads) - [ ] CI previsto: int full + e2e curated + build + unidades changed (blast de `src/collections/CampaignUser.ts`) — gates verdes antes do merge - [ ] Débitos registrados em Issue: unificação da chave `invite-redemption-contact:*` vs `contact-ficha:*`; full-replace/reorder editors documentados como fora do aceite