@evertonferreira96/agents 0.0.0-stage → 0.1.1

package/.claude/skills/arch-api/references/contract.md

@@ -0,0 +1,289 @@
+# Contrato: props, exec e OpenAPI
+
+Abra ao escrever ou revisar um `props.surface` ou `exec.surface`, ao declarar erros, paginação ou decorators de contexto, ao nomear schemas, ao mudar um contrato existente ou ao mexer na geração do `openapi.json`. As regras curtas estão no `SKILL.md` (regras 1 a 8 e 13); aqui fica a mecânica.
+
+---
+
+## 1. `props.surface`
+
+Um arquivo por caso de uso: `surfaces/<acao>.<domain>.props.surface.ts`. Ele é o contrato e só declara; não importa service nem tem lógica.
+
+```ts
+import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+import { registerOpenApi } from '@/common/docs/openapi/registries.docs';
+import { docs } from '@/common/docs/openapi/response.docs';
+import { http } from '@/common/http/enums';
+import {
+  customerParamsSchema,
+  invoiceDetailResponseSchema,
+  invoiceItemInputSchema,
+} from '../entities/invoices.entities';
+
+const openapi = new OpenAPIRegistry();
+registerOpenApi(openapi);
+
+const Method = 'post';
+const Endpoint = '/customers/:customerId/invoices';
+const OperationId = 'createInvoice';
+const Tags = ['Invoices'];
+
+const requestRouteParamsSchema = customerParamsSchema.openapi('CreateInvoiceRouteParamRequest');
+openapi.register('CreateInvoiceRouteParamRequest', requestRouteParamsSchema);
+
+const requestBodySchema = z
+  .object({
+    items: z.array(invoiceItemInputSchema).min(1).max(100),
+    notes: z.string().trim().max(2000).nullable().optional(),
+    dueAt: z.string().datetime().optional(),
+  })
+  .strict()
+  .openapi('CreateInvoiceBodyRequest');
+openapi.register('CreateInvoiceBodyRequest', requestBodySchema);
+
+const responseBodySchema = invoiceDetailResponseSchema().openapi('CreateInvoiceBodyResponse');
+openapi.register('CreateInvoiceBodyResponse', responseBodySchema);
+
+openapi.registerPath({
+  method: Method,
+  path: Endpoint,
+  operationId: OperationId,
+  tags: Tags,
+  summary: 'Cria uma fatura',
+  description:
+    'Cria a fatura em rascunho. Cliente bloqueado = 422 `invoice.customer_blocked`; item fora do catálogo = 422 `invoice.item_invalid` (`details.items`); código repetido = 409 `invoice.duplicate`. Exige `invoices:create`.',
+  security: [{ bearerAuth: [] }],
+  request: {
+    params: requestRouteParamsSchema,
+    body: { required: true, content: { 'application/json': { schema: requestBodySchema } } },
+  },
+  responses: {
+    ...docs.response,
+    ...docs.conflict,
+    ...docs.unprocessable,
+    [http.status.success.created]: {
+      description: 'Sucesso',
+      content: { 'application/json': { schema: responseBodySchema } },
+    },
+  },
+});
+
+export const instructions = {
+  settings: {
+    endpoint: Endpoint,
+    method: Method,
+    operationId: OperationId,
+    tags: Tags,
+    request: { params: requestRouteParamsSchema, body: requestBodySchema },
+    response: { body: responseBodySchema },
+  },
+  openapi,
+};
+
+export namespace Instruction {
+  export namespace Params {
+    export type Body = z.infer<typeof requestRouteParamsSchema>;
+  }
+  export namespace Request {
+    export type Body = z.infer<typeof requestBodySchema>;
+  }
+  export namespace Response {
+    export type Body = z.infer<typeof responseBodySchema>;
+  }
+}
+```
+
+Regras do props:
+
+- `registerOpenApi(openapi)` logo depois de criar o registry; sem ele o endpoint não entra no documento.
+- `Endpoint` usa a sintaxe do Express (`:customerId`); o build converte para `{customerId}` no documento.
+- `OperationId` em camelCase, único na API e estável: é o nome do método no client gerado. O nome do arquivo e do service é o kebab dele (`createInvoice` -> `create-invoice`).
+- `Tags` usa uma tag já descrita no build; tag nova ganha descrição lá.
+- Nomes de schema por operação (o par `.openapi` + `register` é a regra 5 do `SKILL.md`):
+
+| Peça | Nome |
+|---|---|
+| params de rota | `<Operation>RouteParamRequest` |
+| query | `<Operation>QueryParamRequest` |
+| body de request | `<Operation>BodyRequest` |
+| body de response | `<Operation>BodyResponse` |
+| item ou objeto de domínio reutilizado | nome do domínio em `entities/` (`InvoiceSummary`, `InvoiceListSort`) |
+
+- Envelope de resposta compartilhado entre operações é fábrica em `entities/` (`invoiceDetailResponseSchema = () => z.object({ data: invoiceDetailSchema }).strict()`): cada operação nomeia a sua cópia e o item continua um schema só.
+- `summary` curto; `description` diz o que a operação faz, cada `code` de 409/422 com a condição (e o `details` quando houver) e a permissão exigida. É o que o consumidor lê para tratar erro.
+- Extensões `x-*` que o repo adota no `registerPath` (metadados para outros consumidores do documento) entram em todo endpoint novo, copiadas do vizinho e ajustadas; são contrato.
+- Body com `required: true`; query e params entram direto em `request`.
+- `instructions.settings.request` tem só as chaves que existem (`params`, `query`, `body`); `Instruction` tem um namespace por chave (`Params`, `Query`, `Request`) mais `Response`, todos por `z.infer`.
+- Rota pública: `security: []` no `registerPath` (regra 8 do `SKILL.md`). Siga o vizinho público: se ele só omite `security` (como o scaffold da referência gera), o documento herda o `security` global do build e mostra a rota como protegida; registre como melhoria (`review.md` §3).
+- `204` não declara `content`.
+
+---
+
+## 2. Registry e geração do documento
+
+```txt
+props.surface        new OpenAPIRegistry() + registerOpenApi(openapi)      -> lista global (common/docs/openapi/registries.docs.ts)
+<domain>.surface.module.ts   import './surfaces/<acao>.<domain>.props.surface'   (efeito colateral: executa o registro)
+common/docs/openapi/build.ts securitySchemes (bearerAuth) + getOpenApiRegistries() + info, servers, tags; normaliza :param -> {param}
+common/docs/openapi/generate.ts   grava openapi.json; o script de geração do repo também gera generated/openapi-client.d.ts
+```
+
+- O registro acontece quando o arquivo do props é executado. O surface module importa cada props por efeito colateral, e é esse import que o repo usa para garantir o registro: todo props novo ganha a sua linha ali.
+- O exec importa `instructions` por valor e `Instruction` como tipo; por que um props nunca entra por `import type`: anti-padrões do `SKILL.md`.
+- `securitySchemes` é registrado uma vez, no build. Sem ele, o `bearerAuth` que todo endpoint declara aponta para um scheme inexistente e o client não sabe que precisa de token. Se o build também declara `security` global, ele vale para toda operação que não declara a sua (§1).
+- O `servers` do documento casa com o prefixo global do `main.ts` (ex.: `/api/v1`); o `/docs` da app serve o mesmo `buildOpenApiDocument()`, com exposição fail-closed (`security.md` §1).
+
+---
+
+## 3. `exec.surface`
+
+```ts
+import { Controller, HttpCode, Post, UseGuards } from '@nestjs/common';
+import { AuthUser } from '@/common/decorators/auth.user.decorators';
+import { ZdBody, ZdParam } from '@/common/decorators/requests.http.decorators';
+import { AuthUserGuard } from '@/common/guards/auth.user.guard';
+import { http } from '@/common/http/enums';
+import type { IAuthUser } from '@/modules/auth/entities/auth.user.entities';
+import { CreateInvoiceService } from '../services/create-invoice.service';
+import { type Instruction, instructions } from './create-invoice.invoices.props.surface';
+
+@Controller()
+export class CreateInvoiceSurface {
+  constructor(private readonly service: CreateInvoiceService) {}
+
+  @Post('customers/:customerId/invoices')
+  @UseGuards(AuthUserGuard)
+  @HttpCode(http.status.success.created)
+  async exec(
+    @AuthUser() user: IAuthUser,
+    @ZdParam(instructions.settings.request.params) params: Instruction.Params.Body,
+    @ZdBody(instructions.settings.request.body) body: Instruction.Request.Body,
+  ): Promise<Instruction.Response.Body> {
+    return this.service.execute({ actorId: user.id, ...params, ...body });
+  }
+}
+```
+
+- Path do decorator: regra 1 do `SKILL.md`; o prefixo global (`api/v1`) não entra nele.
+- `@HttpCode(http.status.success.<ok|created|noContent>)` igual ao status de sucesso do props.
+- Um parâmetro por chave de `instructions.settings.request`: `@ZdParam`, `@ZdQuery`, `@ZdBody`, cada um com o schema do contrato e o tipo `Instruction.*`.
+- O retorno é `Promise<Instruction.Response.Body>`; o TypeScript acusa quando o service devolve outra forma.
+- O input do `execute` é `{ actorId: user.id, ...params, ...query, ...body }` mais o contexto extraído por decorator (por que o spread é seguro: regra 4 do `SKILL.md`). Se duas fontes têm a mesma chave, renomeie no schema, não no exec.
+- Rota pública: sem `@UseGuards(AuthUserGuard)` e sem `@AuthUser()`. Pública que personaliza quando há token: `OptionalAuthUserGuard` com o decorator de usuário opcional do repo.
+
+### Runtime x documento
+
+| Runtime | Documento |
+|---|---|
+| `@UseGuards(AuthUserGuard)` | `security: [{ bearerAuth: [] }]` |
+| `@ZdParam(schema)` | `request.params` |
+| `@ZdQuery(schema)` | `request.query` |
+| `@ZdBody(schema)` | `request.body.content['application/json'].schema` |
+| `@HttpCode(http.status.success.created)` | resposta `201` declarada |
+| decorator do verbo com o path | `method` + `path` do `registerPath` |
+
+---
+
+## 4. Decorators de contexto
+
+O service recebe dado extraído, nunca o `Request`. Use os decorators do repo (`common/decorators/`); os da referência:
+
+| Decorator | Entrega | Comportamento |
+|---|---|---|
+| `@AuthUser()` | usuário do token (`IAuthUser`) | exige `AuthUserGuard` antes |
+| usuário opcional (`optional.auth.user.decorators.ts`) | usuário ou ausente | com `OptionalAuthUserGuard` |
+| `@CorrelationId()` | id de correlação do header | ausente = `undefined` |
+| `@ClientIp()` | `request.ip` | depende do `trust proxy` (`security.md` §1) |
+| `@IdempotencyKey()` | header `Idempotency-Key` | ausente ou vazio = 400; declare o header no contrato do endpoint |
+| `@<Tenant>Ref()` | referência do tenant ativo vinda de header (id ou slug) | **nunca lança**: ausente ou fora do formato = `undefined`; quem resolve e recusa é o service |
+
+Decorator novo só quando o dado é HTTP-aware e transversal; é pequeno, sem I/O e com teste.
+
+---
+
+## 5. Erros no contrato
+
+`common/docs/openapi/response.docs.ts` tem três blocos: `...docs.response` (400, 401, 403, 404), `...docs.conflict` (409: versão, duplicidade, estado) e `...docs.unprocessable` (422: regra de negócio recusou). Quando espalhar cada um: regra 7 do `SKILL.md`.
+
+Exemplos de `code` no formato da referência: `invoice.stale`, `invoice.already_paid`, `invoice.required_fields_missing` (com `details.fields`). Shape completo de cada status e o que vai em `details`: `security.md` §7. Os clients reagem por esse `code`: o web mapeia `error.code` no mapper de falha da feature, o app pelo helper de erro dele; por isso ele é contrato.
+
+---
+
+## 6. Paginação, filtros e sort (lado do contrato)
+
+Helpers únicos em `common/schemas/paginations.ts`: `paginationQuery` (`page` >= 1, `pageSize` 1 a 100, `z.coerce`), `paginatedResponse(item)` (`{ data, meta: { page, pageSize, total, totalPages } }`) e `toPaginationMeta(page, pageSize, total)` (usado no adapter, `domain.md` §6).
+
+```ts
+const requestQueryParamsSchema = paginationQuery
+  .extend({
+    ...invoicesFilterSchema.shape,
+    status: z.enum(['open', 'closed', 'all']).default('open'),
+    sort: invoiceListSortSchema.default('updatedAt'),
+    direction: z.enum(['asc', 'desc']).default('desc'),
+  })
+  .strict()
+  .openapi('ListCustomerInvoicesQueryParamRequest');
+openapi.register('ListCustomerInvoicesQueryParamRequest', requestQueryParamsSchema);
+
+const responseBodySchema = paginatedResponse(invoiceSummarySchema).openapi(
+  'ListCustomerInvoicesBodyResponse',
+);
+openapi.register('ListCustomerInvoicesBodyResponse', responseBodySchema);
+```
+
+- `sort` é `z.enum` nomeado em `entities/` (`InvoiceListSort`) com default; `direction` é `asc|desc` (siga o nome que o vizinho usa). O adapter mapeia o enum para coluna por mapa literal (segunda trava, `domain.md` §7).
+- O helper base estendido fica sem `.refine()` (refinamento impede ou complica o `.extend`); o consumidor fecha com `.strict()` e o nome dele.
+- Filtros reutilizados entre lista e outras leituras viram um schema em `entities/` (`invoicesFilterSchema`) espalhado por `.shape`.
+- Query chega como string: `z.coerce` para número; boolean por `z.stringbool()` (Zod 4) ou helper do repo, nunca `z.coerce.boolean()`.
+- Parâmetro que pode vir repetido ou CSV é normalizado em `z.preprocess` e o shape real é declarado com `.openapi({ type: 'array', items: ... })`.
+- Ausente não filtra; array vazio não é "sem filtro": o service normaliza vazio para ausente.
+- Texto livre de busca tem `.min(1).max(n)`; o escape de curinga é do adapter.
+- Lista grande, feed ou linha do tempo: cursor opaco (`nextCursor`) em vez de offset alto.
+
+---
+
+## 7. Governança de schemas
+
+- Schema de domínio (item, detalhe, enums, params comuns, filtros) mora em `entities/<domain>.entities.ts`, nomeado; request e response da operação moram no props.
+- `common/schemas` só para o que dois ou mais domínios usam.
+- Response nunca deriva do model do ORM.
+- Create e update não compartilham schema quando os obrigatórios diferem: separe `CreateXBodyRequest`, `UpdateXBodyRequest`.
+- Input valida o que o cliente envia; o schema de resposta é o que sai. Vocabulário público diferente do físico é traduzido no mapper e não vaza para o SQL.
+- Todo `enum` e `version` que o client manda de volta tem `describe` dizendo o efeito (`'Versão lida: 409 invoice.stale se mudou'`).
+
+---
+
+## 8. Versionamento e breaking changes
+
+Toda mudança de contrato é classificada no PR.
+
+| Tipo | Exemplos | Versão nova? |
+|---|---|---|
+| `patch` | descrição, exemplo, summary, documentar um erro que já existe em runtime | Não |
+| `minor` | endpoint novo, campo opcional no response, valor de enum compatível, filtro ou header opcional | Normalmente não |
+| `major` | remover ou renomear campo, mudar tipo, mudar required/optional, remover valor de enum, mudar `operationId`, status de sucesso, envelope, paginação (inclusive offset para cursor), semântica de filtro, formato de erro, **mudar um `code`**, remover endpoint | Sim |
+
+Um `code` é contrato tanto quanto o schema: o consumidor escolhe comportamento por ele. Major exige versão nova (o prefixo global carrega a versão), migração coordenada ou aprovação explícita.
+
+Depreciação, nesta ordem: marcar `deprecated` no OpenAPI; documentar o substituto (e o prazo, se houver); comunicar consumidores conhecidos; manter compatibilidade pelo período combinado; remover só depois do diff aprovado e dos consumidores migrados.
+
+---
+
+## 9. Lint de OpenAPI (se o repo tiver)
+
+Com Spectral ou equivalente, como `error`: `operationId` presente, camelCase e único; tags presentes; erro no schema padrão; protegido com `security`; `204` sem body; path param declarado; nenhuma data como objeto. Como `warn`: summary presente, schema de sucesso inline, `meta` de paginação fora do padrão. "Protegido documenta 401" vale só nessa direção: endpoint público (ex.: login) também devolve 401. Sem ferramenta, sugira o ruleset sem bloquear a entrega.
+
+---
+
+## 10. Paridade e CI
+
+```txt
+<pm> run openapi:generate          gera openapi.json e generated/openapi-client.d.ts
+git diff --exit-code openapi.json  quando o repo versiona o documento: contrato mudado sem regenerar falha
+<pm> run check-types               o client .d.ts e os Instruction.* compilam
+testes                             unit valida o retorno do service contra instructions.settings.response.body
+```
+
+Uma checagem de paridade rota x documento falha quando há handler sem operação no documento (endpoint que o consumidor não conhece, muitas vezes sem guard), operação sem handler ou com path diferente do decorator (método no client que devolve 404) ou `operationId` duplicado (quebra o client). Se o repo tem essa checagem, ela roda no gate; se não tem, o e2e da rota é a trava e a checagem fica registrada como melhoria (`review.md` §3).
+
+O PR deixa claro: operações adicionadas, schemas alterados, se houve breaking change, se `operationId`, status, envelope ou `code` mudou. Os clients (web e app) regeneram a partir do `openapi.json` do build.

package/.claude/skills/arch-api/references/domain.md

@@ -0,0 +1,301 @@
+# Domínio: services, regras, access, ports, adapters e módulos
+
+Abra ao escrever ou revisar um service, um `*.rules.ts`, o `<domain>-access.ts`, o mapper, os erros, o port, o adapter (com `.sql.ts` e `-db-errors.ts`), os módulos `sgbds`/`surface`, um worker, outbox, idempotência ou cache. As regras curtas estão no `SKILL.md` (regras 3, 4, 9 a 14); o nível do banco está em `arch-db`.
+
+---
+
+## 1. Service: um caso de uso por arquivo
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { UnprocessableDomainException } from '@/common/http/errors';
+import type { AuditWriteInput } from '@/modules/audit/entities/audit.entities';
+import { PermissionsPolicyService } from '@/modules/rbac/services/permissions-policy.service';
+import type { InvoiceItemInput } from '../entities/invoices.entities';
+import { InvoicesRepositoryPort, type NewInvoice } from '../ports/invoices.repository.port';
+import { assertCanActOnCustomer } from './invoices-access';
+import { InvoiceCustomerResolverService } from './invoice-customer.resolver';
+import { loadInvoiceDetail } from './invoice-context';
+import { priceItems } from './pricing.rules';
+
+type Input = { actorId: string; customerId: string; items: InvoiceItemInput[]; notes?: string | null; dueAt?: string };
+
+@Injectable()
+export class CreateInvoiceService {
+  constructor(
+    private readonly repository: InvoicesRepositoryPort,
+    private readonly customers: InvoiceCustomerResolverService,
+    private readonly policy: PermissionsPolicyService,
+  ) {}
+
+  async execute(input: Input) {
+    const customer = await this.customers.require(input.customerId); // 404 se não existe
+    const access = await assertCanActOnCustomer(this.policy, input.actorId, customer, 'create');
+    if (customer.status === 'BLOCKED') {
+      throw new UnprocessableDomainException('invoice.customer_blocked', 'Cliente bloqueado');
+    }
+    const catalog = await this.repository.findLiveProducts(input.items.map((item) => item.product));
+    const priced = priceItems(catalog, input.items); // regra pura; lança 422 invoice.item_invalid
+
+    const data: NewInvoice = {
+      customer: customer.id,
+      tenant: customer.tenant,
+      notes: input.notes ?? null,
+      dueAt: input.dueAt ? new Date(input.dueAt) : null,
+      totalAmount: priced.total,
+      createdBy: input.actorId,
+    };
+    const created = await this.repository.createInvoice(data, priced.items, (invoice) => [
+      { actorId: input.actorId, entityType: 'invoice', entityId: invoice.id, action: 'invoice-created' },
+    ] satisfies AuditWriteInput[]);
+
+    return loadInvoiceDetail(this.repository, customer, created.id, access);
+  }
+}
+```
+
+- O default de negócio de um campo opcional do `Input` (regra 3) é decidido aqui.
+- Ordem: resolver o recurso pai (404) -> `assert*` do access -> estado do recurso (422/409) -> leituras para validar referências -> regras puras -> montar `New*`/`*Write` campo a campo -> um método de escrita do port -> devolver o contrato (`{ data }` ou `{ data, meta }`) pelo mapper.
+- Audit é montado no service e gravado pelo adapter na mesma transação do write (o callback recebe o id criado). Borda: string ISO -> `Date` no `New*`; array vazio -> ausente; `?? null` para opcional que vira coluna.
+
+---
+
+## 2. `*.rules.ts`: regra pura
+
+Função sem I/O e sem DI: posição, preço, transição de estado, campos obrigatórios, formato de código. Recebe dados já carregados e devolve valor ou lança exceção de domínio com `code` (fábrica local no topo do arquivo). Constantes da regra são exportadas (o spec e o adapter as reutilizam). Todo `*.rules.ts` tem `*.rules.spec.ts` ao lado; é o teste mais barato da suíte.
+
+---
+
+## 3. `<domain>-access.ts`: autorização por recurso
+
+```ts
+import { PERMISSIONS } from '@/common/auth/permissions';
+import { ForbiddenCustomHttpException, NotFoundDomainException } from '@/common/http/errors';
+import type { CustomerAccess, PermissionsPolicyService } from '@/modules/rbac/services/permissions-policy.service';
+import type { InvoiceCustomerRecord, InvoiceViewer } from '../ports/invoices.repository.port';
+
+const MANAGERS = [PERMISSIONS.invoices.manage] as const;
+
+export const INVOICE_ACTIONS = {
+  create: [PERMISSIONS.invoices.create, ...MANAGERS],
+  cancel: [PERMISSIONS.invoices.cancel, ...MANAGERS],
+} as const;
+export type InvoiceAction = keyof typeof INVOICE_ACTIONS;
+
+/** Executa a ação no cliente; tenant encerrado não aceita escrita (403). */
+export async function assertCanActOnCustomer(
+  policy: PermissionsPolicyService, actorId: string, customer: InvoiceCustomerRecord, action: InvoiceAction,
+): Promise<CustomerAccess> {
+  // método do policy service para o escopo do recurso; use o que o repo expõe
+  const access = await policy.assert.access.customer({ customer: customer.id, user: actorId, allow: INVOICE_ACTIONS[action] });
+  if (customer.tenantStatus === 'CLOSED') throw new ForbiddenCustomHttpException('Operação indisponível');
+  return access;
+}
+
+export const can = (access: CustomerAccess, action: InvoiceAction) =>
+  access.canRead && INVOICE_ACTIONS[action].some((key) => access.permissions.includes(key));
+
+export const viewerOf = (actorId: string, access: CustomerAccess): InvoiceViewer => ({
+  userId: actorId, privileged: can(access, 'cancel'),
+});
+
+/** Fatura restrita: para quem não pode vê-la, ela não existe. */
+export function assertInvoiceVisible(invoice: { restricted: boolean }, viewer: InvoiceViewer): void {
+  if (invoice.restricted && !viewer.privileged) throw new NotFoundDomainException('Fatura não encontrada');
+}
+```
+
+- Funções exportadas, não classe: recebem o policy service injetado no service, o ator e o recurso já carregado.
+- `<DOMAIN>_ACTIONS` lista, por ação, as permissões que passam (OR); conjunção é regra no próprio `assert*`.
+- `can(access, action)` alimenta campos de capacidade na resposta (`access: { canCancel }`), para a tela esconder o botão sem adivinhar.
+- `viewerOf` traduz o acesso no que o adapter precisa para filtrar a leitura (visibilidade no SQL).
+- Além do 404 da regra 9: 403 quando o recurso é visível mas a ação não; tenant em estado que bloqueia escrita (cancelado, removido) também é 403.
+- Chaves de permissão vêm de `common/auth/permissions.ts`; permissão nova entra lá e na seed/migration do catálogo.
+
+---
+
+## 4. Mapper e erros
+
+- `services/<domain>.mapper.ts`: funções `serialize<Coisa>(row, ...)` de `*Row` (como o banco devolve: `Date | string`, `numeric` como string, JSON agregado) para o tipo do schema de resposta, sem I/O. Datas por `iso(value)` / `isoOrNull(value)` (`new Date(value).toISOString()`), números por `Number(...)`, listas por `?? []`.
+- `services/<domain>-errors.ts`: fábricas reutilizadas por service e adapter (`staleInvoice = () => new ConflictDomainException(STALE_INVOICE, 'invoice.stale')`). Mensagem para humano no idioma do produto; `code` estável.
+
+---
+
+## 5. Port
+
+```ts
+import type { InvoiceStatus } from '@/common/sgbds/generated/client';
+import type { IPaginatedResult } from '@/common/sgbds/ports/core.operations.repository.port';
+import type { AuditWriteInput } from '@/modules/audit/entities/audit.entities';
+import type { InvoiceListSort, InvoicesFilter } from '../entities/invoices.entities';
+
+type DateLike = Date | string;
+// InvoiceCustomerRecord, InvoiceViewer, ProductRecord e PricedItem: escritos à mão no mesmo arquivo, como os abaixo.
+
+export type InvoiceSummaryRow = { id: string; code: string; status: InvoiceStatus; totalAmount: number | string;
+  dueAt: DateLike | null; version: number; createdAt: DateLike };
+export type InvoiceListFilter = InvoicesFilter & { page: number; pageSize: number; sort: InvoiceListSort; direction: 'asc' | 'desc' };
+export type NewInvoice = { customer: string; tenant: string; notes: string | null; dueAt: Date | null;
+  totalAmount: number; createdBy: string };
+export type InvoiceWrite = { invoice: string; version: number; actorId: string;
+  set: Partial<{ notes: string | null; dueAt: Date | null; status: InvoiceStatus }>; audits: AuditWriteInput[] };
+
+export abstract class InvoicesRepositoryPort {
+  abstract findCustomer(customerId: string): Promise<InvoiceCustomerRecord | null>;
+  abstract findLiveProducts(ids: string[]): Promise<ProductRecord[]>;
+  abstract listInvoices(customerId: string, filter: InvoiceListFilter, viewer: InvoiceViewer): Promise<IPaginatedResult<InvoiceSummaryRow[]>>;
+  /** Cria numa transação: fatura, itens e audits. */
+  abstract createInvoice(data: NewInvoice, items: PricedItem[], audits: (invoice: { id: string }) => AuditWriteInput[]): Promise<{ id: string; code: string }>;
+  /** UPDATE com `WHERE version = <lida>`; 0 linhas = 409 invoice.stale. Devolve a versão nova. */
+  abstract writeInvoice(change: InvoiceWrite): Promise<number>;
+}
+```
+
+- `abstract class <Domain>RepositoryPort` é o token de DI; o service injeta o port, nunca o adapter.
+- Tipos por papel: `*Row` (leitura como o SQL devolve), `*Record` (estado que os writes precisam), `New*` (insert), `*Write` (update com `set` parcial, `version` e audits).
+- Além do que a regra 10 do `SKILL.md` permite do ORM, o port pode fazer `import type` de `entities/` do próprio domínio e de tipos de entrada de outro domínio (audit).
+- Ausência é `null`. Comentário curto no método quando a semântica não é óbvia (transação, filtro aplicado ou não, o que o retorno significa).
+- O scaffold da referência gera o port estendendo o repositório base genérico do módulo de banco (CRUD sobre `unknown`); domínio com regra troca isso por métodos próprios tipados, como os vizinhos maduros.
+- Integração externa do domínio (provider de terceiro usado só por ele) é `ports/<x>.provider.port.ts` com `abstract class I<X>Provider`; capacidade usada por vários domínios vai para `common/` (`common.md`).
+
+---
+
+## 6. Adapter
+
+```ts
+const INVOICE_ERRORS = {
+  uq_invoices_code: () => new ConflictDomainException('Código de fatura repetido', 'invoice.duplicate'),
+  ck_invoices_total_positive: () => new UnprocessableDomainException('invoice.total_invalid', 'Total precisa ser positivo'),
+};
+
+@Injectable()
+export class PrismaInvoicesRepositoryAdapter extends InvoicesRepositoryPort {
+  constructor(private readonly prisma: PrismaDatabaseService, private readonly pg: NodePostgresDatabaseService) {
+    super();
+  }
+
+  async listInvoices(customerId: string, filter: InvoiceListFilter, viewer: InvoiceViewer) {
+    const { page, count } = buildListQueries(customerId, filter, viewer);
+    const [rows, total] = await Promise.all([
+      this.pg.query<InvoiceSummaryRow>(page.text, page.values),
+      this.pg.query<{ total: number }>(count.text, count.values),
+    ]);
+    return { data: rows.rows, meta: toPaginationMeta(filter.page, filter.pageSize, total.rows[0]?.total ?? 0) };
+  }
+
+  async writeInvoice(change: InvoiceWrite) {
+    try {
+      return await this.prisma.$transaction(async (tx) => {
+        const { count } = await tx.invoice.updateMany({
+          where: { id: change.invoice, version: change.version, deletedAt: null },
+          data: { ...change.set, updatedAt: new Date() },
+        });
+        if (count === 0) throw staleInvoice();
+        await tx.audit.createMany({ data: change.audits.map(toAuditCreateInput) });
+        const updated = await tx.invoice.findUnique({ where: { id: change.invoice }, select: { version: true } });
+        return updated?.version ?? change.version + 1;
+      });
+    } catch (error) {
+      rethrowInvoicesDbError(error, INVOICE_ERRORS, { foreignKey: 'Cliente ou produto inexistente', check: 'Dados da fatura fora do formato' });
+    }
+  }
+}
+```
+
+- `extends <Domain>RepositoryPort` com `super()`; o nome começa pela tecnologia (`Prisma`, `Pg`, `Http`). Injeta os serviços do módulo global de banco: na referência, ORM para escrita, `$transaction` e leitura simples por `select` explícito; driver para leitura quente com SQL de `<domain>.sql.ts`. Siga a divisão do repo.
+- Leitura: `rows[0] ?? null`; conversão leve (`Number(...)`, default de JSON) no adapter, formato de resposta no mapper.
+- Escrita: um método do port = uma transação com tudo que a invariante precisa (linhas, filhos, audits, renumeração); o service nunca vê `tx` (regra 14 do `SKILL.md`).
+- Lock otimista (regra 14): `updateMany` com `version` no `where` e `count === 0` -> `stale<Coisa>()`. O incremento de `version` é do banco (trigger) ou do adapter, conforme o repo.
+- Sequência por pai (código `INV-0042`): `UPDATE ... SET next_number = next_number + 1 ... RETURNING` dentro da transação, que trava a linha do pai até o commit.
+- `try/catch` em todo método de escrita, terminando em `rethrow<Domain>DbError`.
+
+### `<domain>-db-errors.ts`
+
+```ts
+export function rethrowInvoicesDbError(error: unknown, known: Record<string, () => HttpException>, messages?: Messages): never {
+  if (error instanceof HttpException) throw error;            // exceção de domínio lançada dentro da transação
+  const hit = constraintOf(error, Object.keys(known));         // nome em error.constraint, em meta do ORM ou no texto
+  if (hit) throw known[hit]();
+  rethrowDbError(error, messages);                             // common/sgbds/settings/db-errors.ts: genérico + log
+}
+```
+
+- O mapa constraint/trigger -> fábrica fica no adapter (`<DOMAIN>_ERRORS`); toda constraint que um write pode violar tem entrada, com o `code` declarado no contrato.
+- O genérico (`rethrowDbError`) cobre unique (409), FK (409), CHECK (400), registro inexistente (404; `P2025` no Prisma) e o resto (500), com mensagem de negócio por parâmetro, e loga a causa real. Ramos com `code` específicos do repo (exclusão, códigos lançados por trigger) rodam dentro dele antes dos genéricos: constraint nova com `code` próprio entra no mapa do adapter ou nesses ramos, nunca depois. O client nunca recebe nome de constraint, SQL ou valor.
+- Nunca importe o `-db-errors` de outro domínio; `constraintOf` repetido em vários domínios é candidato a subir para `common/sgbds/settings/`.
+
+---
+
+## 7. `<domain>.sql.ts`: SQL montado por funções puras
+
+```ts
+export type SqlQuery = { text: string; values: unknown[] };
+
+class Params {
+  readonly values: unknown[] = [];
+  add(value: unknown): string { this.values.push(value); return `$${this.values.length}`; }
+}
+
+export const INVOICE_LIST_SORT: Record<InvoiceListFilter['sort'], string> = {
+  updatedAt: 'i.updated_at', createdAt: 'i.created_at', dueAt: 'i.due_at', total: 'i.total_amount',
+};
+
+export function buildListQueries(customerId: string, filter: InvoiceListFilter, viewer: InvoiceViewer) {
+  const build = (withPage: boolean): SqlQuery => {
+    const p = new Params();
+    const where = [`i.customer = ${p.add(customerId)}::uuid`, 'i.deleted_at IS NULL'];
+    if (!viewer.privileged) where.push('i.restricted = false');
+    if (filter.search) where.push(`i.code ILIKE ${p.add(likePattern(filter.search))}`);
+    if (!withPage) return { text: `SELECT count(*)::int AS total FROM invoices i WHERE ${where.join(' AND ')}`, values: p.values };
+    const direction = filter.direction === 'asc' ? 'ASC' : 'DESC';
+    return {
+      text: `SELECT ${SUMMARY_COLUMNS} FROM invoices i WHERE ${where.join(' AND ')}
+              ORDER BY ${INVOICE_LIST_SORT[filter.sort]} ${direction} NULLS LAST, i.id ${direction}
+              LIMIT ${p.add(filter.pageSize)}::int OFFSET ${p.add((filter.page - 1) * filter.pageSize)}::int`,
+      values: p.values,
+    };
+  };
+  return { page: build(true), count: build(false) };
+}
+```
+
+- Funções puras que devolvem `{ text, values }`, mais constantes `*_SQL` para query fixa: testáveis sem banco e executáveis no `psql` com o mesmo texto.
+- Além da regra 12 do `SKILL.md`: cast explícito em cada `$n`, tiebreaker na mesma direção do sort, `LIKE` escapado pelo util do repo (`common/utils/sql/`).
+- Todo `$n` adicionado aparece no texto: parâmetro sem uso quebra o `PREPARE` (`could not determine data type`). Por isso a contagem é montada sem os parâmetros só da página.
+- Projeção explícita com alias camelCase; relacionados agregados em JSON na mesma query. A visibilidade do `viewer` entra no `WHERE`, para lista e total baterem.
+- SQL completo de listagem, keyset, índices e `EXPLAIN`: `arch-db` (reference `indexes-queries.md` de lá).
+
+---
+
+## 8. Módulos e acesso entre domínios
+
+- `<domain>.sgbds.module.ts` só liga port -> adapter e exporta o port: `@Module({ providers: [{ provide: InvoicesRepositoryPort, useClass: PrismaInvoicesRepositoryAdapter }], exports: [InvoicesRepositoryPort] })`. Se o domínio oferece um service a outros, o módulo que o declara também o exporta.
+- `<domain>.surface.module.ts`: `imports` com o próprio `SgbdsModule` e os módulos dos domínios de que depende; `controllers` com todos os exec; `providers` com todos os services, resolvers e helpers injetáveis; uma linha `import './surfaces/<acao>.<domain>.props.surface'` por endpoint.
+- `common/surfaces/surface.module.ts` importa e exporta todos os `<Domain>SurfaceModule`. Rotas conflitantes entre módulos (`customers/me/invoices` x `customers/:id`) dependem da ordem: o módulo da rota estática vem antes, com comentário dizendo por quê.
+- Entre domínios, a regra está no `SKILL.md` (Colocação). Complemento: tipos e funções puras do outro domínio (`entities`, mapper de audit) podem ser importados pelo caminho; o que tem estado ou DI chega pelo `exports` do módulo dele.
+
+---
+
+## 9. Workers, outbox, idempotência e cache
+
+- **Worker**: `<assunto>.worker.ts` no módulo do domínio consome a fila pela capacidade de fila ou mensageria do repo (copie a fiação de um worker vizinho); é idempotente (a mesma mensagem duas vezes não duplica efeito) e chama services, não adapters de outro domínio.
+- **Outbox**: efeito externo que não pode se perder depois do commit (evento, e-mail transacional, integração). O registro de outbox entra na mesma transação do write; o worker de outbox publica depois do commit, at-least-once; o consumidor é idempotente. Na referência, serviço e worker de outbox moram em `common/messaging`; siga como o vizinho que já publica evento grava o registro.
+- **Idempotência**: exija `Idempotency-Key` quando a operação cria cobrança, pagamento, pedido ou solicitação, dispara integração externa, pode ser repetida por retry, ou não pode duplicar registro. Mecânica pelo `IIdempotencyProvider` de `common/resilience` (confira o vizinho que já o usa):
+
+```txt
+acquire({ key, actorId, method, route, payloadHash, ttlSeconds }) -> 'NEW' | 'REPLAY' | 'CONFLICT'
+  NEW       processa; sucesso -> complete(key, actorId, method, route, responseBody); falha -> release(...)
+  REPLAY    get(...) e devolve a mesma resposta lógica (em andamento: 409 ou 202, conforme o padrão do repo)
+  CONFLICT  mesma key com payload diferente -> 409
+```
+
+O header entra no contrato (`@IdempotencyKey()`, `contract.md` §4); o hash do payload usa o helper de `common/resilience`; payload sensível não é guardado inteiro.
+
+- **Trabalho pesado**: payload limitado no schema (`.max()` em texto e array); o que passa do tempo de request (relatório, lote) vira 202 + fila. Descubra o SLO do projeto; não invente número universal.
+- **Cache** só com chave, escopo (público, usuário, tenant), TTL e invalidação definidos; cache por usuário ou tenant sem chave composta é vazamento; cache de autorização exige invalidação provada por teste.
+
+---
+
+## 10. Fronteira com `arch-db`
+
+Aqui (`arch-api`): onde o banco vive na aplicação (`common/sgbds/*`), como o adapter injeta os clientes, a transação dentro do método do adapter, a tradução de constraint para `code`, o contrato de listagem e o comando de paridade migration x schema do repo. Lá (`arch-db`), e não aqui: modelagem e tipos, constraints e nomes, soft delete, FKs, índices e `EXPLAIN`, SQL de listagem completo, keyset, upsert, bulk, locks, isolamento, timeouts e retry, migrations (expand/contract, lock-safety), seeds e backfill, pool (tamanho, quantos por processo) e multi-tenant no banco. Se as duas divergirem no nível do banco, `arch-db` vence.