People

O People guarda o que a sua empresa sabe sobre uma pessoa física — e, junto com cada informação, de onde ela veio, quem conferiu e até quando vale. Não é uma lista de clientes: é o registro do que foi provado sobre cada um, com prazo de validade embutido.

Na prática, ele responde uma pergunta que hoje ninguém responde sem abrir cinco telas: "para liberar esta operação, eu sei o suficiente sobre esta pessoa?" O comprovante de residência venceu ontem? O nível cai sozinho, a resposta muda de sim para não e um evento avisa quem precisa saber — sem ninguém rodar nada.

O núcleo está implementado; o bloco não está completo. status: alpha — existe código em src/people/, schema people no Postgres, 15 rotas, fachada de dois métodos e 68 testes. O que ainda NÃO existe, de propósito, está listado em §15: consentimento formal com texto versionado, merge de duplicata, relatório e expurgo do titular, prova de vida pela porta de biometria e a ponte com o customers. O núcleo deixa o gancho pronto para os cinco — tabela, coluna ou porta — sem implementá-los. Nada foi deployado. O desenho continua em openspec/changes/people-block/ e o que existe hoje ao lado dele é o bloco Customers, que segue intacto (§12).

O cenário. Uma operação de crédito recebe um cliente pelo WhatsApp, pede uns documentos, consulta um bureau, aprova. Seis meses depois, o cliente volta. Ninguém sabe dizer o que foi conferido da primeira vez, nem se ainda vale.

O que trava hoje.

• O dado não tem origem. No customers, monthlyIncome é uma coluna. A renda que o cliente digitou e a renda que veio do bureau ocupam o mesmo lugar. Quem lê depois não distingue, e nenhuma política consegue exigir "renda comprovada" sem gambiarra no consumidor.
• Nada vence. Um comprovante de 2023 e um de ontem valem igual. A regra que exigia documento recente vira responsabilidade de alguém lembrar.
• O documento fica em claro. Person.taxIdValue é String sem cifra e sem coluna de hash; a busca por CPF é igualdade em texto claro. O bloco biometrics, que nasceu depois, já guarda o sujeito por HMAC.
• Não há subconta. Um revendedor não consegue separar as pessoas dos clientes dele: o modelo só tem organizationId.
• Ninguém consome. customers não tem fachada e nenhum outro bloco o importa. Cada produto reimplementa "quem é essa pessoa" por dentro.

O custo de não resolver. Toda contestação de operação vira arqueologia: abrir a conversa, achar o print, torcer para o arquivo ainda estar no lugar. Toda auditoria de LGPD vira trabalho manual — o data-extraction já documenta o custo dessa lacuna no §15 dele, chamando o expurgo manual de "a lacuna mais relevante para compliance". E toda regra de negócio que dependia de "documento recente" passou a depender de disciplina humana, que é a garantia mais cara que existe.

Procedência por atributo. Cada informação carrega origem, confiança, quando foi verificada e quando expira — e valores de origens diferentes convivem em vez de se sobrescreverem em silêncio.

Nível que cai sozinho. O nível não é coluna: é calculado na leitura sobre as evidências válidas naquele instante. Entre a expiração e a leitura não existe janela em que a ficha mente.

Uma pergunta, uma resposta. GET /people/:id/assurance?required=evidenced devolve satisfied, o nível por dimensão e o que falta. Quem pergunta traz o requisito; o bloco não precisa conhecer o produto.

LGPD, com o gancho pronto. O consentimento tem tabela, o expurgo tem onde olhar, e o relatório tem de onde ler — mas as três rotas são do próximo PR (§15). O que o núcleo já garante é o que torna as três possíveis depois: procedência em toda informação e documento cifrado com leitura em claro sob permissão própria e com evento.

Panorama. O mercado vende verificação, não registro. Persona, Onfido e Idwall orquestram muito bem o momento do onboarding: consultam, leem documento, batem selfie, devolvem aprovado ou reprovado. O que fazer com aquilo depois — onde guardar, como saber que envelheceu, como provar dali a dois anos o que se sabia no dia — continua sendo problema do cliente. É o espaço em que o People vive: ele não compete com a verificação, ele é o lugar onde o resultado dela mora e envelhece.

Nossos diferenciais.

1. O nível decai sozinho. Não é um campo com job por trás — é derivado na leitura. Copiar exige repensar o modelo de dados inteiro, não acrescentar uma coluna.
2. Procedência por atributo. Ter um campo "verificado: sim/não" é fácil; ter cada atributo com origem, confiança e prazo, e a política conseguindo exigir "esta origem, no máximo com tantos dias", muda o que dá para escrever como regra.
3. Subconta no schema. Quem nasceu com um nível de tenancy raramente ganha o segundo sem reescrever a camada de acesso.

Quando escolher o concorrente. Se o seu problema é verificar e não guardar — você precisa de leitura de documento em 40 países amanhã, com certificação eIDAS — Onfido ou Persona entregam isso hoje e nós não. Se você quer um editor visual em que o time de risco monta a esteira sem engenharia, Persona é melhor nisso. E se você precisa de cobertura de fontes brasileiras pronta com esteira embutida, a Idwall resolve mais rápido. O People faz sentido quando o registro é seu ativo — quando você vai precisar, dali a dois anos, provar o que sabia naquele dia.

Precificação em definição. O bloco está especificado e nenhum preço foi fechado. O que já está decidido são os drivers.

Por que a unidade é justa. Cobrar por consulta pune quem organiza o processo; cobrar por pessoa ativa alinha o preço ao valor. E consulta cacheada não é cobrada duas vezes — é a mesma disciplina que o bureaus já aplica, cujo próprio tagline é "cache que impede pagar duas vezes pelo mesmo CPF".

A conta de guardanapo. O custo evitado não é a verificação (essa você paga de qualquer jeito) — é a operação: o analista que reconfere o que já estava conferido, o mutirão de LGPD, a contestação que vira arqueologia. Quando houver preço, esta seção ganha a comparação em cenário nomeado, com a data da consulta ao preço público de cada análogo.

flowchart TD
  Cliente["Painel / workflow / outro bloco"] -->|HTTP com JWT ou chave| Rotas
  OutroBB["Outro building block"] -->|IPeopleFacade| Servicos

  subgraph People
    Rotas["Rotas (Hono)"] --> Servicos["Serviços"]
    Servicos --> Assurance["AssuranceService (calcula na leitura)"]
    Servicos --> Repos["Repositórios (Prisma, schema people)"]
    Servicos --> Portas["Portas de saída"]
  end

  Portas -->|IBureausFacade| Bureaus
  Portas -->|IBiometricsFacade| Biometrics
  Portas -->|IFileStorageFacade| FileStorage
  Portas -->|fachada a criar| DataExtraction
  Servicos -->|EventPublisher| Stream["Stream iam-events"]
  Stream --> AuditTrail["audit-trail"]
  Stream --> Webhooks["webhooks-engine"]

Três decisões que não são óbvias.

O nível não é coluna. Se fosse, alguém escreveria nela, e a partir daí o nível vira opinião. Ele é derivado a cada leitura das evidências válidas naquele instante. A varredura diária existe só para avisar que caiu, nunca para mudar o estado — entre a expiração e o job não há janela em que a ficha mente.

Toda saída passa por fachada. O bloco nunca fala HTTP com provedor externo e nunca monta o caminho de outro bloco à mão. O motivo é concreto: o caminho real do data-extraction é /data-extraction/api/v1/data-extraction/extractions — o nome do módulo aparece duas vezes, e quem escreve de cabeça erra. Hoje o núcleo usa uma só: IFileStorageFacade, para conferir que o fileId do documento é desta organização. As portas de bureau, biometria e leitura de documento ainda não são disparadas por aqui (§15) — e quando forem, entram pelas fachadas, não por fetch solto. Fachada ausente no processo vira aviso, não queda: o documento é gravado sem a conferência do arquivo, que é honesto e não perde o dado.

Auditoria não tem fachada, e não precisa. Todo bloco publica no stream Redis iam-events via EventPublisher.safePublish, e o audit-trail lê esse mesmo stream por consumer group. O que o People precisa é publicar com organizationId e subaccountId na metadata — e ganhar entrada própria em RESOURCE_TYPE_MAPPING, senão o mapeador cai no genérico e grava o organizationId como id do recurso (bug já corrigido para baas.* e biometrics.*).

No modo monolito as fachadas resolvem para os serviços locais; em standalone, para chamadas HTTP por ModuleClient. O bloco não sabe em qual modo está.

Glossário.

Modelo de dados. Sete modelos no schema people. Toda tabela tem organizationId e subaccountId String?.

O prefixo dos modelos é People, e não Person: o nome Person já é do customers, e nome de modelo Prisma é global — o schema nem compila com os dois. Os nomes de TABELA são os da spec.

ownerId não estava na spec, e precisa estar. A spec pediu @@unique([organizationId, subaccountId, documentHash]). Esse índice não impede a duplicata do caso mais comum — o da própria organização —, porque no Postgres NULL não é igual a NULL: duas linhas com subaccount_id nulo e o mesmo hash convivem sem violar nada. A coluna derivada owner_id (subaccountId ?? organizationId) resolve, é expressável em Prisma (índice parcial não é) e mantém o subaccount_id nulável de que o filtro de leitura precisa. Há prova em SQL disso no corpo do PR.

Máquina de estados do nível.

stateDiagram-v2
  [*] --> declared
  declared --> verified: fonte externa confere o dado
  verified --> evidenced: documento válido sustenta
  evidenced --> certified: prova de vida ou assinatura qualificada
  certified --> evidenced: a prova mais forte vence
  evidenced --> verified: o documento vence
  verified --> declared: a verificação vence

As setas para baixo não precisam de comando: acontecem porque a evidência deixou de estar válida no momento da leitura.

Máquina de estados do documento.

stateDiagram-v2
  [*] --> pending
  pending --> uploaded: arquivo confirmado no File Storage
  uploaded --> reading: leitura pedida ao Data Extraction
  reading --> read: leitura concluída
  reading --> pending: prazo estourado, com motivo operacional
  read --> valid: conferida e dentro da validade
  valid --> expired: passou de validUntil
  read --> rejected: conferência recusou

Escrita a partir de src/people/routes/people.router.ts. São 15 rotas (mais /people/health e /people/health/ready, montadas pelo helper compartilhado). O que a spec desenhou e este PR não implementou — merge, consentimento, relatório, expurgo, config/* e rekey — saiu desta seção e está em §15, para a tabela não prometer rota que não responde.

Prefixo: /people/api/v1. Toda rota exige authMiddleware, requirePermission(...) e contexto de organização. Todas aceitam chave de subconta e o header X-Subaccount-Id (people está em SUBACCOUNT_AWARE).

Pessoas

Nível de conhecimento

Evidência

Política do tenant

Toda verificação que entra pela rota é EXTERNAL. origin só aceita esse valor; mandar INTERNAL é recusado com 400, não ignorado. Evidência interna nasce de PeopleVerificationService.recordInternal, que não tem rota — só uma porta do bloco chama.

Referência ambígua é 409. Com chave de organização (sem X-Subaccount-Id), o mesmo externalRef ou documento pode existir em duas subcontas. O bloco não escolhe uma: resolve, assurance/batch e verifications/ingest devolvem PEOPLE_AMBIGUOUS_SUBJECT no item, e nada é gravado. Repita com a subconta.

A rota principal, em detalhe.

GET /people/api/v1/people/{id}/assurance?required=evidenced&dimensions=identity,income

GET /people/api/v1/people/{id}/assurance?required=evidenced&dimensions=identity,income

{
  "data": {
    "personId": "3f0a…",
    "level": "verified",
    "satisfied": false,
    "required": "evidenced",
    "dimensions": {
      "identity": { "level": "evidenced", "until": "2027-03-12T00:00:00.000Z",
                    "sustainedBy": [{ "kind": "document", "id": "d1…", "source": "document" }] },
      "income":   { "level": "verified",  "until": "2026-10-01T00:00:00.000Z",
                    "sustainedBy": [{ "kind": "verification", "id": "v2…", "source": "external" }] },
      "address":  { "level": "declared",  "until": null, "sustainedBy": [] },
      "liveness": { "level": "declared",  "until": null, "sustainedBy": [] }
    },
    "missing": [
      { "dimension": "income", "current": "verified", "need": "evidenced",
        "suggest": "anexe um documento de renda válido" }
    ],
    "cached": true,
    "computedAt": "2026-09-22T13:04:11.000Z"
  }
}

{
  "data": {
    "personId": "3f0a…",
    "level": "verified",
    "satisfied": false,
    "required": "evidenced",
    "dimensions": {
      "identity": { "level": "evidenced", "until": "2027-03-12T00:00:00.000Z",
                    "sustainedBy": [{ "kind": "document", "id": "d1…", "source": "document" }] },
      "income":   { "level": "verified",  "until": "2026-10-01T00:00:00.000Z",
                    "sustainedBy": [{ "kind": "verification", "id": "v2…", "source": "external" }] },
      "address":  { "level": "declared",  "until": null, "sustainedBy": [] },
      "liveness": { "level": "declared",  "until": null, "sustainedBy": [] }
    },
    "missing": [
      { "dimension": "income", "current": "verified", "need": "evidenced",
        "suggest": "anexe um documento de renda válido" }
    ],
    "cached": true,
    "computedAt": "2026-09-22T13:04:11.000Z"
  }
}

Quais dimensões entram na conta. Com ?dimensions=, as que você pediu. Sem ele, as que têm algum sinal — e identity sempre tem, porque a pessoa só existe com um documento informado. A spec não decidiu isto, e o padrão óbvio (as quatro, sempre) transformaria liveness num veto universal: toda pessoa sem biometria responderia declared e a pergunta perderia a serventia. Uma dimensão sem sinal continua visível na resposta — ela só não puxa o resultado para baixo sem ninguém ter pedido. Para exigi-la, peça-a: ?dimensions=identity,liveness.

Do zero ao primeiro nível calculado. Em ambiente local (bun run dev:people, porta 3038).

O que foi executado, e o que não foi. O fluxo abaixo — criar, perguntar, registrar evidência, perguntar de novo — está coberto por teste de integração com testcontainers (tests/integration/people/people-core-flow.test.ts, 15 casos, verdes). Os curl desta seção não foram rodados contra um serviço no ar: este PR não deploya nada. Eles são a tradução literal do que o teste exercita.

1. Autenticar.

TOKEN=$(curl -s -X POST "$IAM/iam/api/v1/users/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"…","password":"…"}' | jq -r '.accessToken')

TOKEN=$(curl -s -X POST "$IAM/iam/api/v1/users/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"…","password":"…"}' | jq -r '.accessToken')

A rota é /users/login e o token vem na raiz (.accessToken), como documentam baas, biometrics e audit-trail. Até 23/09/2026 esta seção dizia /auth/login e .data.accessToken: quem seguia o início rápido parava num 404.

Se você acabou de criar o usuário pela API, ele não loga ainda. POST /iam/api/v1/users devolve status: "pendente", e o login responde 401 Invalid credentials — a mesma mensagem de senha errada, então não há como distinguir olhando a resposta. Ative antes: PATCH /iam/api/v1/users/:id com {"status":"ativo"}.

2. Criar a pessoa. Idempotente por externalRef; o mesmo documento no mesmo dono reconhece em vez de duplicar.

curl -s -X POST "$BASE/people/api/v1/people" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Maria Souza","document":{"type":"BR_CPF","value":"12345678909"},
       "externalRef":"lead-8821",
       "attributes":[{"key":"income","value":"5000","source":"declared","confidence":"LOW"}]}'

curl -s -X POST "$BASE/people/api/v1/people" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Maria Souza","document":{"type":"BR_CPF","value":"12345678909"},
       "externalRef":"lead-8821",
       "attributes":[{"key":"income","value":"5000","source":"declared","confidence":"LOW"}]}'

201 na primeira vez, 200 nas seguintes. O documento volta mascarado:

{ "data": { "id": "3f0a…", "externalRef": "lead-8821",
            "document": { "type": "BR_CPF", "masked": "***.***.789-09" } } }

{ "data": { "id": "3f0a…", "externalRef": "lead-8821",
            "document": { "type": "BR_CPF", "masked": "***.***.789-09" } } }

3. Perguntar o nível com um requisito.

curl -s "$BASE/people/api/v1/people/3f0a…/assurance?required=verified" \
  -H "Authorization: Bearer $TOKEN"

curl -s "$BASE/people/api/v1/people/3f0a…/assurance?required=verified" \
  -H "Authorization: Bearer $TOKEN"

satisfied: false, com missing dizendo o que falta.

4. Registrar a evidência — aqui, uma verificação que o cliente trouxe pronta.

curl -s -X POST "$BASE/people/api/v1/people/3f0a…/verifications" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"dimension":"identity","type":"document.match","origin":"EXTERNAL",
       "provider":"idwall","outcome":"APPROVED","grade":"VERIFIED",
       "occurredAt":"2026-09-20T10:00:00.000Z","expiresAt":"2027-03-20T10:00:00.000Z",
       "evidenceRef":"protocolo-8821"}'

curl -s -X POST "$BASE/people/api/v1/people/3f0a…/verifications" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"dimension":"identity","type":"document.match","origin":"EXTERNAL",
       "provider":"idwall","outcome":"APPROVED","grade":"VERIFIED",
       "occurredAt":"2026-09-20T10:00:00.000Z","expiresAt":"2027-03-20T10:00:00.000Z",
       "evidenceRef":"protocolo-8821"}'

5. Perguntar de novo. identity sai em verified, com until — mas a resposta global ainda vem level: declared, satisfied: false:

curl -s "$BASE/people/api/v1/people/3f0a…/assurance?required=verified" \
  -H "Authorization: Bearer $TOKEN"        # → level: declared, satisfied: false

curl -s "$BASE/people/api/v1/people/3f0a…/assurance?required=verified&dimensions=identity" \
  -H "Authorization: Bearer $TOKEN"        # → level: verified, satisfied: true

curl -s "$BASE/people/api/v1/people/3f0a…/assurance?required=verified" \
  -H "Authorization: Bearer $TOKEN"        # → level: declared, satisfied: false

curl -s "$BASE/people/api/v1/people/3f0a…/assurance?required=verified&dimensions=identity" \
  -H "Authorization: Bearer $TOKEN"        # → level: verified, satisfied: true

Não é defeito, é a regra de §9 "quais dimensões entram na conta": sem ?dimensions=, entram todas as que têm algum sinal — e o atributo income do passo 2, ainda que declared, é um sinal. A dimensão income entra na conta em declared e puxa o nível global para baixo. Pergunte pela dimensão que o seu ato exige (?dimensions=identity), ou registre evidência de renda também. Até 23/09/2026 este passo prometia satisfied: true sem o recorte — o smoke bateu nisto.

6. Uma tela inteira, numa chamada.

curl -s -X POST "$BASE/people/api/v1/assurance/batch" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"required":"verified","refs":[{"id":"3f0a…"},{"externalRef":"lead-8821"}]}'

curl -s -X POST "$BASE/people/api/v1/assurance/batch" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"required":"verified","refs":[{"id":"3f0a…"},{"externalRef":"lead-8821"}]}'

Resposta 207: cada item resolvido por si, um ruim não derruba os outros.

Receita 1 — Liberar uma operação só se o nível bastar

Objetivo. Não deixar a operação seguir com conhecimento insuficiente.

RESP=$(curl -s "$BASE/people/api/v1/people/$ID/assurance?required=evidenced" -H "Authorization: Bearer $TOKEN")
echo "$RESP" | jq -e '.data.satisfied == true' >/dev/null || { echo "$RESP" | jq '.data.missing'; exit 1; }

RESP=$(curl -s "$BASE/people/api/v1/people/$ID/assurance?required=evidenced" -H "Authorization: Bearer $TOKEN")
echo "$RESP" | jq -e '.data.satisfied == true' >/dev/null || { echo "$RESP" | jq '.data.missing'; exit 1; }

Armadilha. O required vem de quem pergunta, nunca do bloco. Qual nível cada ato exige é regra do produto e vive na política da vertical — o People não conhece o ato.

Receita 2 — Uma tela com 80 pessoas, sem 80 chamadas

Objetivo. Listar a fila da mesa sem derrubar a tela.

curl -s -X POST "$BASE/people/api/v1/assurance/batch" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"required":"verified","refs":[{"id":"…"},{"externalRef":"lead-8821"}]}'

curl -s -X POST "$BASE/people/api/v1/assurance/batch" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"required":"verified","refs":[{"id":"…"},{"externalRef":"lead-8821"}]}'

Resposta 207: cada item resolvido por si, um ruim não derruba os outros.

Armadilha. Não substitua isto por um laço no cliente. Uma chamada por linha de tela já nos custou uma tela de 38 s, uma resposta de 16 MB e recusa por rajada — e nenhuma das três apareceu em teste, só no cliente. Teto de 100 por lote, e paginação por cursor, nunca por offset.

Receita 3 — Renovar antes de a evidência vencer

Objetivo. Pedir o documento novo antes de a operação travar.

Assine people.assurance.expired no webhooks-engine e dispare o fluxo de renovação. O evento traz pessoa, dimensão, nível anterior e nível atual.

Armadilha. O evento é aviso, não causa. O nível já tinha caído na leitura anterior; quem depende de estado lê o assurance, não o evento.

Receita 4 — Ingerir evidência que o cliente já tem

Objetivo. Aproveitar o que já foi verificado fora, sem fingir que fomos nós.

curl -s -X POST "$BASE/people/api/v1/verifications/ingest" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"items":[{"person":{"externalRef":"lead-8821"},"dimension":"income",
        "type":"income.statement","origin":"EXTERNAL","provider":"parceiro",
        "outcome":"APPROVED","grade":"VERIFIED","occurredAt":"2026-09-20T10:00:00.000Z",
        "idempotencyKey":"lote-7/linha-1"}]}'

curl -s -X POST "$BASE/people/api/v1/verifications/ingest" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"items":[{"person":{"externalRef":"lead-8821"},"dimension":"income",
        "type":"income.statement","origin":"EXTERNAL","provider":"parceiro",
        "outcome":"APPROVED","grade":"VERIFIED","occurredAt":"2026-09-20T10:00:00.000Z",
        "idempotencyKey":"lote-7/linha-1"}]}'

Armadilhas. A chave de idempotência é por registro e é do dono: rodar o lote de novo devolve 200 duplicate em vez de criar a segunda linha — é isso que faz a retomada de uma carga interrompida ser segura. Gere a chave com o id da pessoa dentro; a mesma chave apontando para outra pessoa é recusada (PEOPLE_IDEMPOTENCY_CONFLICT). E origin: EXTERNAL exige provider e occurredAt: sem quem verificou e quando, não é evidência, é afirmação — e ela fica marcada como externa para sempre, porque não somos nós que podemos auditá-la.

Receita 5 — Saber de onde veio cada informação

Objetivo. Responder "esse endereço foi conferido por quem, e ainda vale?".

curl -s "$BASE/people/api/v1/people/$ID/attributes" -H "Authorization: Bearer $TOKEN" | jq '.data[]'

curl -s "$BASE/people/api/v1/people/$ID/attributes" -H "Authorization: Bearer $TOKEN" | jq '.data[]'

Cada atributo volta com o vigente (o de maior confiança entre os não vencidos), as others origens e divergent: true quando duas origens válidas afirmam valores diferentes.

Armadilha. divergent é derivado na leitura, como o nível — não há coluna para marcá-lo, e não há escrita que "resolva" a divergência. Resolver é acrescentar uma origem mais forte.

Merge de duplicata, relatório e expurgo do titular (/merge, /report, /erase) são do próximo PR — ver §15. Até lá, não existe rota para eles, e esta seção não finge que existe.

flowchart LR
  Captura["Captura (WhatsApp, portal)"] --> People
  People -->|consulta| Bureaus
  People -->|prova de vida| Biometrics
  People -->|lê documento| DataExtraction["Data Extraction"]
  People -->|guarda arquivo| FileStorage["File Storage"]
  People -->|nível basta?| Esteira["Esteira de crédito"]
  Companies -->|ponteiro de sócio| People
  People -->|eventos| Auditoria["audit-trail + webhooks-engine"]

Convivência com o Customers, em cinco passos: fachada de compatibilidade → espelho de escrita → migração por organização com relatório de duplicata → virada de leitura → customers marcado legado. Nada é apagado no mesmo passo em que é migrado. Detalhe em openspec/changes/people-block/design.md.

Variáveis de ambiente.

Infraestrutura. PostgreSQL (schema people), Redis (cache do nível e stream iam-events), S3/MinIO pelo File Storage.

Limites. Lote de 100 (/assurance/batch e /verifications/ingest); /people/resolve também em 100; concorrência interna de 8; listagem só por cursor, no máximo 100 por página.

O cache do nível tem DOIS tetos, não um. O TTL configurado e o instante da próxima expiração, o que vier antes. Só o TTL não bastaria: uma evidência que vence em 5 segundos com TTL de 60 serviria 55 segundos de resposta errada — exatamente a janela que o bloco existe para não ter. A chave guarda a ENTRADA do cálculo, não a resposta, então ela serve a qualquer required; e toda escrita de evidência a invalida. A chave é (organização, pessoa) — não leva o dono de quem lê: a primeira versão levava, e a organização gravando evidência deixava a chave da subconta mentindo por até 60 s. Quem pode ler é decidido antes de o cache entrar.

Catálogo de erros.

Eventos publicados (stream iam-events, com organizationId e subaccountId na metadata; people.* tem entrada própria em RESOURCE_TYPE_MAPPING do audit-trail): people.person.created, people.person.updated, people.person.revealed, people.document.attached, people.verification.completed, people.assurance.raised, people.assurance.expired. Nenhum carrega dado pessoal — nem documento, nem documento mascarado, nem nome, nem contato: só id, dimensão, nível, origem e referência da prova. Há teste que varre os eventos publicados procurando os CPFs usados no fluxo.

Observabilidade. O que existe hoje é o log estruturado de cada varredura e de cada falha de cache. Métrica de distribuição de nível por dimensão e histograma das portas de saída ainda não existem — estão em §15, não aqui.

Instalação por vertical. Tudo que é configurável por tenant — tipos de documento e validade, finalidades de consentimento, portas ligadas, retenção, mapa de dimensões — é declarado pelo pacote da vertical e semeado pelo instalador com a chave do tenant, pelo mesmo caminho que creditBlocks já usa. Um tenant novo não nasce com o bloco vazio. O que fica de fora, de propósito: credencial de provedor, chave de cifra e texto legal próprio do cliente — segredo e jurídico não entram em template versionado. Três regras herdadas de instalações que quebraram: o pacote declara tudo o que usa (pacote que usa o não declarado instala com 201 e o tenant nasce quebrado sem aviso); a instalação é retomável e idempotente por item, com relatório do que faltou; e o conteúdo vem do banco, então a ordem é publicar, semear e só então instalar. Detalhe em openspec/changes/people-block/design.md.

Isolamento. Duas camadas. O middleware compartilhado resolve organização e subconta e falha fechado: um bloco fora do mapa SUBACCOUNT_AWARE recusa chave de subconta e recusa o header, em vez de ignorá-los — por isso people entra no mapa no mesmo commit que cria o bloco. Dentro do bloco, leitura e posse usam predicados distintos: a organização enxerga tudo que é dela; a subconta enxerga só o dela; e a checagem de unicidade usa o dono exato. Recurso fora do escopo responde 404, nunca 403 — um 403 confirmaria a existência do recurso alheio.

Dado sensível. O documento é cifrado em repouso com aes-256-gcm pelo núcleo compartilhado de cifra, e a busca usa HMAC-SHA-256 — o hash resolve unicidade e busca sem ser reversível, e leva a organização dentro da entrada, então o mesmo documento em tenants diferentes não produz o mesmo hash. O número do documento anexado (person_documents.number) é cifrado pela mesma chave: RG e CNH são dado pessoal igual.

Ver o documento inteiro é um ato, não uma consulta. PEOPLE_READ devolve a máscara (***.***.789-09). O valor em claro exige ?reveal=true e a permissão separada PEOPLE_READ_DOCUMENT, e a leitura publica people.person.revealed. Isto é uma correção ao desenho: a spec dizia que o documento em claro aparecia "a quem tem PEOPLE_READ", o que tornaria a máscara decorativa — quem lê a ficha leria o CPF de qualquer jeito.

Chave de API nunca revela. A chave autoriza por padrão de recurso (allowedResources), não por RBAC; o middleware a normaliza num user com permissions: []. Portanto ?reveal=true com chave de API é sempre 403, e é deliberado: automação não precisa do CPF em claro, e uma chave vazada não consegue exportar a base. Só JWT de usuário com PEOPLE_READ_DOCUMENT vê o valor.

O que é IMPOSTO sobre a evidência, e onde.

Nada de dado pessoal em log, evento ou mensagem de erro. Os eventos carregam id, dimensão, nível e referência da prova; o erro de item de lote é genérico de propósito, porque erro de banco carrega valor de coluna e coluna aqui é dado pessoal. Retenção configurável de evidência por tenant ainda não existe (§15).

LGPD. Base legal e finalidade ficam no consentimento, com o hash do texto exibido e a versão do modelo — é o que permite provar depois qual texto a pessoa aceitou; a tabela existe e a rota é o próximo PR (§15). Relatório do titular (art. 18) e expurgo ainda não existem como rota — e o README diz isso em vez de repetir o plano. O que o núcleo já entrega para eles é o que os torna possíveis: cada informação com origem e prazo, e o documento cifrado.

Autenticação e permissões. JWT do IAM ou chave de API. Cinco permissões, cada uma com rota: PEOPLE_READ (ficha, nível, listas), PEOPLE_WRITE (pessoa, documento), PEOPLE_VERIFY (verificação e ingestão), PEOPLE_ADMIN (PUT /config/policy) e PEOPLE_READ_DOCUMENT (?reveal=true) — esta última porque ver o documento inteiro não pode vir junto com ler a ficha.

E elas estão atribuídas a papéis no catálogo padrão (src/iam/constants/permissions.ts), não só declaradas: VIEWER ganha PEOPLE_READ (e não PEOPLE_READ_DOCUMENT — quem só observa não precisa do CPF); CUSTOMER_MANAGER ganha as outras quatro, inclusive PEOPLE_ADMIN; VERIFICATION_OPERATOR ganha PEOPLE_READ e PEOPLE_VERIFY; ADMIN já recebe tudo. O data-extraction é o contra-exemplo que motivou isso: as permissões dele "não estão atribuídas a nenhum papel intermediário no catálogo padrão do IAM".

Pessoa é do tenant, e isso é decisão de produto — não limitação técnica. O mesmo CPF em duas organizações são dois registros distintos, com histórico, consentimento e nível de conhecimento próprios. Não existe pessoa global, nem tabela comum, nem deduplicação entre organizações, nem reaproveitamento de verificação de um tenant por outro — nem quando isso economizaria uma consulta paga a bureau. O motivo é que a base legal do tratamento é de cada tenant: o consentimento que a organização A colheu não autoriza a organização B a saber nada, e a vantagem comercial de uma base compartilhada não paga o risco jurídico de tratá-la como se autorizasse. A decisão está no mecanismo, não só na regra de consulta: o document_hash é HMAC com a organização dentro da entrada, então o mesmo CPF produz hashes diferentes em tenants diferentes, não há índice sobre document_hash sozinho, e toda consulta entra pelo dono. Correlacionar as duas fichas é impossível mesmo para quem lê o banco direto. Dois testes de integração guardam isso: um provando que as duas organizações cadastram o mesmo CPF independentemente, outro provando que nenhuma rota de uma alcança a pessoa da outra — por id, por documento ou pela resolução em lote da fachada.

Por que um bloco novo em vez de melhorar o Customers? Porque a mudança é estrutural: cifrar o documento, criar coluna de hash, mudar a unicidade e partir cinco colunas largas numa tabela de atributos com procedência é reescrever o bloco por dentro, com dado em produção e sem lugar para pousar o intermediário. Como customers não tem nenhum consumidor em processo hoje, o bloco novo sai barato e a convivência é curta.

O Customers vai ser apagado? Não no mesmo passo. A sequência é fachada de compatibilidade, espelho de escrita, migração por organização com relatório de duplicata, virada de leitura e, por último, customers marcado legado e congelado. A remoção, se acontecer, é um PR separado.

O nível pode ser forçado no braço? Não. Ele é calculado na leitura. O que dá para fazer é acrescentar evidência — e aí ele sobe sozinho. Essa recusa é o ponto do bloco: nível editável é nível que vira opinião.

Como o nível cai sem ninguém rodar nada? Porque nada foi gravado. A evidência tem expiresAt; no instante em que você lê, o cálculo ignora o que já venceu. A varredura só avisa com o evento people.assurance.expired. Há teste que prova isso do jeito mais direto possível: a mesma entrada, calculada em dois instantes, dá evidenced antes da expiração e declared depois — sem nenhuma escrita entre as duas leituras.

O que já responde e o que ainda não? Respondem: criar/reconhecer, ficha com procedência, documento, verificação (nossa ou trazida de fora), ingestão em lote, nível por dimensão, lote de nível e a fachada de dois métodos. Não respondem ainda: consentimento, merge, relatório e expurgo do titular, config/* por tenant, rekey e o disparo das portas de bureau/biometria/extração. A lista completa está em §15.

O mesmo CPF pode estar em dois clientes meus? Pode, e deve. A unicidade é do dono exato — organização mais subconta. Duas financeiras do mesmo revendedor atendem a mesma pessoa sem enxergar uma à outra. E quem pede o registro do vizinho recebe 404, não 403.

Quem decide qual nível cada operação exige? Você, na política da sua vertical. O bloco recebe ?required= e responde se atende e o que falta. Ele não conhece o seu produto, de propósito.

Isso substitui a Idwall ou a Unico? Não. Elas verificam; o People guarda o resultado com procedência e prazo. Você continua contratando quem verifica — e passa a ter onde o resultado mora e envelhece.

O que acontece se o provedor de leitura de documento estiver fora? O documento fica em reading até o prazo e depois volta para pending com o motivo operacional. O que o bloco não faz é tratar o 202 como sucesso — foi exatamente assim que extrações ficaram PENDING para sempre em outro bloco.

Um tenant novo precisa de configuração manual? Não. Tipos de documento, finalidades de consentimento, portas ligadas, retenção e mapa de dimensões vêm declarados no pacote da vertical e são semeados pelo instalador com a chave do tenant. O que continua manual, de propósito, é credencial de provedor, chave de cifra e texto jurídico próprio.