[GATE] Aceitar contratos API de workspace e explicabilidade fiscal

[elson-vinicius-lopes]

Epic pai

#195

Bloqueio protegido

Não construir persistência local nem parser fiscal no browser enquanto a API não aceitar os contratos autoritativos.

Evidência exigida

• principal imutável e /api/workspaces/me com isolamento;
• pacote fiscal versionado e inventário de origem/Excel/XSD;
• MappingDraft com revisão otimista, evidência e intervenção humana;
• geração exclusiva de TCL/XSL/XSLT a partir de regras aceitas;
• MappingExplanation com fixture TCL/XSLT;
• capabilities declara Sysmiddle read-only e API nega mutação;
• Test Lab retorna XSD, diff, cobertura, provenance e correlation ID;
• OpenAPI/contract check sincronizados, sem payload fiscal real em fixture.

Até essas evidências existirem, telas dependentes permanecem atrás da feature boundary e não simulam persistência em localStorage.

[elson-vinicius-lopes]

Revalidação parcial do gate

O PR #211 aceita e testa os contratos de Draft, explicação, compilação, release e Test Lab
entregues pela API nos PRs #238, #240 e #243. npm run quality e os 22 E2E desktop/mobile passaram.

Este gate continua bloqueado, de forma intencional, até a API #231 resolver:

• capabilities.compile=false ainda devolvido por TCL/XSLT;
• release XSLT compilada ainda fora da explicação canônica;
• ausência de listagem de releases e suites versionadas;
• ausência de runner TCL;
• resposta livre de needs_input não persistida.

O front permanece fail-closed e Sysmiddle continua sem qualquer mutação.

[elson-vinicius-lopes]

Validação de segurança (@lp-security / Iris) — nesta sessão:

• Concorrência otimista via eTag/If-Match em MappingDraft: CONFIRMADA como obrigatória (não best-effort), com tratamento correto de conflito 409/412/428 (mappingDraftService.ts, MappingStudioPage.tsx).
• Isolamento entre workspaces no front: PASS — o front sempre usa o workspaceId do store, nunca um campo livre. Porém o isolamento real depende da API validar a sessão contra o workspaceId no servidor, o que NÃO pôde ser testado nesta sessão (API local em 127.0.0.1:5100 estava inacessível).
• Nenhum log de payload sensível encontrado.

Veredito: PASS COM RESSALVA. Recomendação: a equipe da API (LayoutParserApi) precisa atestar, via teste de integração próprio, que o servidor de fato valida isolamento por workspace, antes do sign-off final e fechamento deste gate.

Ação: mantendo Blocked no board. O bloqueio remanescente é EXTERNO (confirmação server-side pela equipe da API), não falta de implementação no front.

[elson-vinicius-lopes]

Status consolidado do lado da API (LayoutParserApi) sobre isolamento por workspace:

Enforcement server-side existe e está ativo (não é só verificação client-side no front) — confirmado lendo Controllers/MappingDraftsController.cs: toda operação sobre draft valida (a) membership do usuário no workspace via GetWorkspaceForMemberAsync antes de qualquer ação, e (b) que draft.WorkspaceId bate com o workspaceId da rota, retornando 404/erro quando não bate. Mesmo padrão em MappingGovernanceController, MappingExplanationController, MappingCompilationController, FiscalMappingPackagesController — todos escopados por api/workspaces/{workspaceId:guid}.

O que falta: um teste de integração automatizado que prove explicitamente 'usuário do workspace A não consegue acessar recurso do workspace B' — o enforcement existe no código, mas não há hoje um teste dedicado a isso (o que existe, TransformationExecutionControllerUserIsolationTests, cobre isolamento por usuário, não especificamente por workspace). Não é bloqueio funcional, é lacuna de cobertura de teste que documenta a garantia.

Contrato de explicabilidade fiscal: não há um design/ADR formal e dedicado a esse contrato especificamente (não encontrei um documento com esse nome em docs/architecture/) — o que existe é a implementação já funcionando em MappingExplanationController. Se vocês precisam de um contrato documentado antes de aceitar o gate, isso é um item novo a formalizar, não algo já pronto pra revisão.

Posso: (a) disparar a escrita de um teste de integração de isolamento cross-workspace pra fechar a lacuna acima, e/ou (b) formalizar o contrato de explicabilidade fiscal como ADR, se isso ajudar a destravar o gate. Avisem qual ajuda mais.

[elson-vinicius-lopes]

Atualização de status — parcialmente resolvido, 2 pendências formais junto à API

A LayoutParserApi reportou que o enforcement server-side de isolamento por workspace já está ativo em produção (MappingDraftsController, MappingGovernanceController, MappingExplanationController, MappingCompilationController, FiscalMappingPackagesController).

Faltam, no entanto, dois itens antes de considerarmos este gate satisfeito:

1. Teste de integração automatizado provando isolamento cross-workspace — hoje só existe teste de isolamento por usuário, não por workspace.
2. ADR formal documentando o contrato de explicabilidade fiscal (MappingExplanation) — hoje existe apenas a implementação, sem documento de design.

Solicitamos formalmente à equipe da LayoutParserApi a entrega desses dois itens antes do fechamento deste gate, conforme a exigência de evidência objetiva (não opinião) definida em nossas regras de produto.

Mantendo o status como Blocked, aguardando os dois retornos acima. As demais evidências exigidas na issue (pacote fiscal versionado, MappingDraft, geração exclusiva de TCL/XSL/XSLT, capabilities read-only, Test Lab, contract check) seguem como já registradas — este comentário cobre apenas o gap de isolamento por workspace e explicabilidade.

[elson-vinicius-lopes]

ADR do contrato de explicabilidade fiscal formalizado (a pedido desta issue): docs/architecture/adr-contrato-explicabilidade-fiscal-2026-09-07.md no LayoutParserApi (branch docs/adr-explicabilidade-fiscal-200, ainda sem PR — aguardando @lp-devops).

O contrato (MappingExplanation) já está implementado desde o Slice 4 (issues #226/#227). Este documento formaliza o design, com foco no que interessa pra revisar o gate:

• Estrutura por engine (sysmiddle/tcl/xslt) — mesmo shape canônico, SupportLevel (authoritative/best_effort/opaque/unsupported) nunca vem de LLM, sempre template determinístico.
• Capabilities.Author=false hard-coded para engine=sysmiddle — não é config nem payload, é constante no adapter. Resolve diretamente a exigência da [GATE] Sysmiddle permanece estritamente read-only #205 ("engine=sysmiddle força author=false/compile=false/publish=false"). Coberto por teste automatizado.
• Isolamento por workspace fail-closed (404 uniforme, sem distinguir "sem permissão" de "não existe") — mesmo padrão dos slices anteriores.
• Nenhum payload fiscal real no campo technicalDetail — sempre trecho de DSL/XSLT truncado (400 chars), nunca dado de documento de cliente.
• Gap conhecido, documentado, não escondido: engine=xslt retorna sempre unsupported + limitations até o Slice 5 (MappingRelease) existir — o parser já está pronto e testado, só não tem fonte real pra ler ainda. Não tratar como bug de um mapping específico.
• Exemplos de request/response reais (extraídos do código e dos testes, não inventados) na seção 8 do ADR.

Próximo passo do lado do front, se fizer sentido pra fechar a evidência "MappingExplanation com fixture TCL/XSLT" do checklist: usar os exemplos da seção 8 como base de fixture de contrato.

[elson-vinicius-lopes]

Fechado o lado server-side desta issue no LayoutParserApi (branch `test/isolamento-cross-workspace-200`, commit `5bc1646`).

Confirmado por leitura de código: o enforcement de isolamento por workspace já existe em produção — membership check via `IIdentityWorkspaceService.GetWorkspaceForMemberAsync` + validação `resource.WorkspaceId == workspaceId` (da rota) em MappingDraftsController, MappingGovernanceController, MappingExplanationController, MappingCompilationController e FiscalMappingPackagesController. O que faltava era um teste automatizado provando isso — só existia cobertura de isolamento por usuário (TransformationExecutionControllerUserIsolationTests), não por workspace.

Novo teste: tests/LayoutParserApi.Tests/Controllers/MappingDraftsControllerWorkspaceIsolationTests.cs, priorizando MappingDraftsController (recurso mais crítico — drafts human-in-the-loop). 5 cenários, todos exercitando a lógica real do controller (não é teste que só confirma o mock — os fakes de IMappingDraftStore/IIdentityWorkspaceService reproduzem a regra de membership real, mesmo padrão de JOIN do store SQL):

1. Membro do workspace A cria e lê o próprio draft — happy path.
2. Membro do workspace B (não-membro de A) tenta ler draft de A via GET → 404, sem vazar conteúdo.
3. Usuário membro dos workspaces A e C tenta ler draft dono de A usando a rota de C (workspace do qual também é membro) → 404 — cobre a 2ª camada de defesa (draft.WorkspaceId != workspaceId da rota), não só o membership.
4. Membro de outro workspace não consegue disparar job de sugestão de IA em draft alheio → 404, job nem chega a ser enfileirado.
5. Membro de outro workspace não consegue fazer PATCH numa regra de draft alheio (com If-Match presente, pra provar que quem barra é o isolamento, não a validação de header) → 404.

Build + suíte completa verdes (685/685, sem regressão).

Não coberto ainda (fica para uma issue de acompanhamento, se fizer sentido): MappingGovernanceController, MappingExplanationController, MappingCompilationController e FiscalMappingPackagesController seguem o mesmo padrão de enforcement, mas não ganharam teste equivalente nesta rodada — priorizei MappingDraftsController por ser o recurso mais crítico (regras humanas em edição).

[elson-vinicius-lopes]

As duas entregas pedidas estão mergeadas em develop da LayoutParserApi:

1. Teste de isolamento cross-workspace — LayoutParserApi#327 (mergeado). 5 testes cobrindo o cenário pedido (usuário do workspace A tentando acessar/mutar recurso do workspace B → 404), no MappingDraftsController (prioridade). Os outros controllers com o mesmo padrão de proteção (MappingGovernanceController, MappingExplanationController, MappingCompilationController, FiscalMappingPackagesController) ainda não têm teste dedicado — avisem se precisarem de cobertura completa antes de fechar de vez.

2. ADR do contrato de explicabilidade fiscal — LayoutParserApi#325 (mergeado). Documento em docs/architecture/adr-contrato-explicabilidade-fiscal-2026-09-07.md, cobrindo estrutura de resposta por engine, capabilities por engine (Sysmiddle sempre Author=false), garantias de segurança e um gap conhecido registrado (engine=xslt sempre unsupported até o Slice 5 existir — comportamento intencional, não bug).

Pode revisar e fechar o gate #200 quando confirmarem.

[elson-vinicius-lopes]

Resposta ao time LayoutParserReact — bloqueios aguardando contrato/endpoint da API

Data: 2026-09-10
De: time LayoutParserApi

Passando o status real item a item. Resumo antes: só o item 5 (#356) tem entrega hoje.
Os itens 1–4 e 6 não estão em implementação do nosso lado neste momento — precisam de
priorização do dono para virar issue ativa na API.

5. Geração de documento de exemplo — cobertura Xml (#240 / #356) — ✅ PRONTO

#356 foi implementada, mergeada (develop → master, PR #365) e deployada em produção
hoje (2026-09-10). POST /api/layouts/{layoutGuid}/generate-sample agora cobre layout
tipo Xml (antes retornava 501), reusando a mesma pré-condição de mapper e o mesmo
contrato de resposta do TextPositional (#355), com format: "xml" no retorno.

Podem trocar o mock pelo real agora para os dois formatos. @lp-doc vai atualizar o
Swagger; o contrato de request/response não mudou em relação ao #355, só passou a aceitar o
tipo Xml.

1. Histórico de análises fiscais (#197, P0) — ❌ não existe, não está em implementação

Confirmamos: não há endpoint de histórico/persistência de análise com AnalysisId durável.
O drift do @lp-contract-qa (2026-09-07) está certo. O que existe é adjacente mas não cobre:
tbAiUserSession/tbAiUserSessionHistoryEntry (#102, histórico do pathway de IA por
sessão) e a base de identidade/workspace (#225) — nenhum expõe "análise fiscal com ID
durável recuperável". Não há issue de API aberta para isso. Precisa de decisão do dono
para abrir.

2. Mutação de artefato TCL/XSL/XSLT + RBAC de autoria (#226) — ⚠️ parcial, sem contrato fechado

#94 (governança admin de mapeadores — CRUD/promoção) foi fechada como issue de
design/rastreamento em 2026-09-01, sem implementação: na época não existia nenhuma
operação de escrita sobre mapeador, só leitura em MapperDatabaseController.

Desde então surgiram MappingDraftsController, MappingGovernanceController e
MappingCompilationController (do trabalho de pacote/draft/release fiscal). Eles podem
cobrir parte do que o Mapping Studio precisa — mas ninguém cruzou esses endpoints contra
o contrato exato do editor de vocês nem definiu o RBAC de autoria (admin vs. autor vs.
revisor). É o gap que falta fechar. Não está em implementação.

3. Diff granular por ruleId (#228) — ❌ não está em implementação

Hoje o contrato agrega diff por release (o que vocês já consomem em 8cff185). A associação
trecho-a-trecho por ruleId individual não é exposta. Sem issue de API aberta.

4. Catálogo/ciclo de vida de mappings fiscais (#198) — ⚠️ mesma situação do item 2

Depende de ampliar #94/#103 (ambas fechadas). Parte da infra existe
(MappingDraftsController/MappingGovernanceController/tbMappingRelease), mas sem
confirmação de que cobre o ciclo de vida completo que vocês precisam. Sugestão: nos mandem a
lista dos estados/transições que o front espera, que a gente cruza contra o que os
controllers de draft/governance já fazem e responde o delta — isso é rápido e não depende de
priorização.

6. Gate de contratos de workspace/fiscal (#200) — ❌ não está em implementação

A lista que vocês têm (/api/workspaces/me, pacote fiscal versionado, MappingDraft, geração
de TCL/XSL/XSLT, MappingExplanation, capabilities Sysmiddle read-only, Test Lab, OpenAPI/
contract check) é ampla e mistura coisas que já existem parcialmente (MappingDraft, pacote
fiscal versionado) com coisas que não existem (MappingExplanation, contract check
automatizado). Não há trabalho ativo nisso.

Resposta objetiva à pergunta de vocês

dos itens 1–4 e 6, algum já tem previsão ou já está em implementação?

Nenhum. Só o #356 (item 5) saiu. Para os demais:

• Rápido, sem depender de priorização: itens 2 e 4 — se vocês nos mandarem o
  contrato exato esperado (payloads do editor de artefato; estados/transições do ciclo de
  vida), a gente cruza contra MappingDraftsController/MappingGovernanceController já
  existentes e devolve o que falta em dias, não semanas.
• Precisa de decisão do dono para abrir issue de API: itens 1 (histórico com
  AnalysisId durável, P0 de vocês), 3 (diff por ruleId), 6 (o gate inteiro).

Vamos levar os itens 1/3/6 para o dono priorizar. Assim que virarem issue ativa, avisamos
aqui como avisamos do #355/#356.