SGF/docs/MODULE_ASSOCIATION_HTTP_LOCK_DELIVERY.md

# Fila de associações — resposta HTTP ao limite de espera

02/11/2026. Continuação local da [consolidação de carga e concorrência](MODULE_ASSOCIATION_LOAD_CONSOLIDATION.md). A pendência escolhida foi a resposta da API quando uma prévia ou confirmação atinge o limite de espera por bloqueio. Não houve nova execução das matrizes de carga, índices ou 440 leituras concorrentes.

## Comportamento implementado

O [controlador administrativo existente](../app/Modules/Identity/Http/ModuleRecordsController.php) trata exclusivamente `QueryException` com SQLSTATE **55P03**, após o serviço devolver a excepção e desfazer a transacção. Prévia e confirmação devolvem **HTTP 423**, `code: association_busy`, `Cache-Control: no-store` e a mensagem:

> A conferência está ocupada por outra operação. Aguarde e volte a confirmar; o estado será novamente validado.

A resposta contém apenas `code` e `message`: não expõe SQL, bindings, tokens, stack trace ou identificadores internos. Outros erros de base de dados continuam a ser propagados ao tratamento existente. Os conflitos 409, recusas de acesso e validações mantêm o percurso anterior. A interface já apresenta a mensagem devolvida pela API e mantém a repetição manual; não precisou de alteração visual.

Não foi introduzida repetição automática da decisão nem alterado o prazo de espera da aplicação/base. Se a ligação já tiver um limite configurado e este for atingido, existe agora uma resposta administrativa compreensível. Sem limite configurado, esta alteração não limita por si só a espera. A política de espera no destino continua por definir/verificar na implantação.

O serviço de leitura conjunta, prévia, confirmação e idempotência não foi alterado: SHA-256 **b901bccc73a59e80d98d32a56532e9300a55ba9a216e5ac5a0ce84d78f976397**. As medições anteriores continuam referidas às respectivas fontes e condições; não medem o desempenho deste novo ramo de resposta HTTP.

## Prova nova e recuperação

Execução exclusivamente em **sgf_tempo_test**, role **sgf_test_runner**, porta **55439**, cluster **sgf_modular_regression_2576427d1939**, com verificação física antes de preparar dados. Três clientes novos num âmbito sintético novo, retido apenas na regressão para visibilidade entre processos, com manifesto privado. Não se limpou/reinicializou a base.

Um processo manteve uma confirmação não gravada. Um segundo processo chamou a API pelo kernel HTTP com `lock_timeout=1000ms` exclusivamente nessa ligação de prova. Observou-se a espera `transactionid` e verificou-se o primeiro processo entre os bloqueadores. O prazo terminou antes de libertar a primeira transacção.

| Operação que esperou | Resposta ao limite | Tempo total ms | Libertação posterior | Recuperação manual |
| --- | --- | ---: | --- | --- |
| Confirmação | 423 / association_busy | 1086,658 | rollback | 200; repetição devolve o mesmo evento |
| Confirmação | 423 / association_busy | 1093,136 | commit | 409 com token antigo; nova prévia disponível |
| Prévia | 423 / association_busy | 1083,944 | rollback | nova prévia 200; confirmação e repetição sem duplicação |

Cada cenário verificou a contagem de decisões imediatamente após libertar a primeira transacção: **zero** nos casos de rollback e **uma** no caso de commit. O pedido que recebeu 423 não deixou uma decisão parcial. Após os passos de recuperação/repetição ficou exactamente **um evento por cliente**. Não se propagaram associações a dependentes.

O teste dos trabalhadores exige a resposta JSON exacta e o cabeçalho sem cache. A recuperação usa as rotas reais da API em processo, mantendo contexto, autenticação e direitos sintéticos. A conferência antiga continua a ser recusada se outra decisão alterou a revisão.

- **1 teste / 54 asserções** no coordenador, mais três trabalhadores aprovados, para os novos cenários HTTP.
- **13 testes / 232 asserções** afectados da fila aprovados. Repetidos porque o controlador de prévia/confirmação mudou; incluem permissões, isolamento, revisão, dependências, concorrência e recuperação existentes. Não se repetiu a suite de navegação nem suites alheias.
- Impressões digitais dos registos QA anteriores e catálogo de índices iguais no ensaio de bloqueio. Hashes das provas válidas anteriores conferidos e preservados.

[Prova sanitizada](proofs/module-association-http-lock-20261102.json) · [Resumo, fontes, testes e hashes](proofs/module-association-http-lock-summary-20261102.json). Launcher específico: `scripts/module-association-compare.mjs http-lock`, após actualizar apenas a cópia de regressão existente com `sync`. Não usar `prepare` ou reset. Entradas dos trabalhadores, tokens e manifestos permanecem privados.

## Preservação e limites

Os seis registos protegidos, a cache bloqueada, a demonstração 8039 e alterações alheias foram preservados. Sem ligação ao destino, índice/migração, direito público, activação de Compras, publicação, aceitação ou checkpoint presumidos. A preparação sintética e os seus resultados ficaram na base de regressão; não se declara rollback de toda a fixture.

Esta prova cobre a resposta pelo kernel HTTP em processo; não mede rede, servidor HTTP implantado, login/MFA, TLS ou navegador. Os tempos incluem a espera deliberada de aproximadamente um segundo. Não representam latência normal, SLA ou capacidade de implantação. A criação de índices e a política operacional de espera/repetição no destino continuam separadas. **Revisão visual e validação da capacidade de implantação permanecem pendentes**, sem tentativa pela via de navegador bloqueada.