mcloh/Enterprise-MCP-Service-Bus
1
0
Fork 0
mirror of https://github.com/mcloh/Enterprise-MCP-Service-Bus.git synced 2026-11-06 06:24:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

revisão e complementação da documentação do projeto

Browse Source
This commit is contained in:
Marcos Lohmann
2026-09-14 14:30:48 -03:00
parent 9a99ec6cc8
commit 868d885cb6
31 changed files with 46 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
RI/docs/AS-BUILT.en-us.md
View File

@@ -11,10 +11,9 @@ the RI, see [`How-To.md`](How-To.md). For those who will **evaluate/adapt** the
scenario, see [`Assumptions.md`](Assumptions.md) and
[`Production-Recommendations.md`](Production-Recommendations.md).
This document succeeds the planning backlog `docs/RI-PLANNING.md` (removed from the repository
after the completion of milestone M4, with history preserved in git) — the factual information
from that backlog that is still relevant to whoever uses the finished product was migrated here,
to `Assumptions.md`, and to `Production-Recommendations.md`.
Individual architectural decisions are recorded in [`../../docs/adr/`](../../docs/adr/)
(ADR-001 through ADR-025); the assumptions and reasoning behind them are synthesized in
[`Assumptions.md`](Assumptions.md).
## Status
@@ -31,8 +30,8 @@ Registry.
## Epic index
Every `EP-XX-TXX` that appears in comments/docstrings in the source code references one of these
epics. This table is what replaces `docs/RI-PLANNING.md` §8.6 as the context source for those
references.
epics. This table is the authoritative reference for these labels — consult it whenever a
comment/docstring cites an `EP-XX-TXX` without further context.
| Epic | Title | Main module/test |
|---|---|---|
@@ -167,7 +166,7 @@ exchange).
### Auditing, correlation and observability (EP-08)
**Responsibility:** `audit/models.py` defines `EventEnvelope` with a 3-category taxonomy adopted
from the Agent Platform OCI reference (ADR-022): **IC** (Client Interaction/business journey,
from the Agent Platform OCI reference (ADR-022): **IC** (Control Indicator/business journey,
e.g. `client_authenticated`, `tool_call_allowed`), **NOC** (operational/availability error, e.g.
`pdp_unavailable`), **GRL** (guardrail/governance, e.g. `tool_call_denied`,
`tools_list_filtered`, `bypass_attempt_detected`). Every event recursively sanitizes any key

13
RI/docs/AS-BUILT.md
View File

@@ -9,10 +9,9 @@ Público-alvo: quem vai **integrar com ou estender** a RI. Para quem vai **rodar
[`How-To.md`](How-To.md). Para quem vai **avaliar/adaptar** a RI para um cenário real, ver
[`Assumptions.md`](Assumptions.md) e [`Production-Recommendations.md`](Production-Recommendations.md).
Este documento sucede o backlog de planejamento `docs/RI-PLANNING.md` (removido do
repositório após a conclusão do marco M4, com histórico preservado no git) — a informação
factual desse backlog que ainda é relevante para quem usa o produto acabado foi migrada para
cá, para `Assumptions.md` e para `Production-Recommendations.md`.
Decisões arquiteturais individuais estão registradas em [`../../docs/adr/`](../../docs/adr/)
(ADR-001 a ADR-025); as premissas e razões por trás delas estão sintetizadas em
[`Assumptions.md`](Assumptions.md).
## Status
@@ -29,8 +28,8 @@ real para o Registry.
## Índice de épicos
Cada `EP-XX-TXX` que aparece em comentários/docstrings do código-fonte referencia um destes
épicos. Esta tabela é o que substitui `docs/RI-PLANNING.md` §8.6 como fonte de contexto para
essas referências.
épicos. Esta tabela é a referência autoritativa para essas siglas — consulte-a sempre que um
comentário/docstring citar um `EP-XX-TXX` sem contexto adicional.
| Épico | Título | Módulo/teste principal |
|---|---|---|
@@ -164,7 +163,7 @@ backend. 7 testes (4 unit com `httpx.MockTransport`, 3 e2e contra Keycloak real,
### Auditoria, correlação e observabilidade (EP-08)
**Responsabilidade:** `audit/models.py` define `EventEnvelope` com uma taxonomia de 3 categorias
adotada da referência Agent Platform OCI (ADR-022): **IC** (Interação de Cliente/negócio-jornada,
adotada da referência Agent Platform OCI (ADR-022): **IC** (Indicador de Controle/negócio-jornada,
ex. `client_authenticated`, `tool_call_allowed`), **NOC** (operacional/erro de disponibilidade,
ex. `pdp_unavailable`), **GRL** (guardrail/governança, ex. `tool_call_denied`,
`tools_list_filtered`, `bypass_attempt_detected`). Todo evento sanitiza recursivamente qualquer

2
RI/docs/interfaces/audit-events.en-us.md
View File

@@ -48,7 +48,7 @@ rather than a taxonomy of its own:
| Category | Meaning | `event_type` examples |
|---|---|---|
| `ic` | Customer Interaction / business journey — the call progressed normally | `client_authenticated`, `tool_call_allowed`, `agent_turn_completed`, `nba_recalculated` |
| `ic` | Control Indicator / business journey — the call progressed normally | `client_authenticated`, `tool_call_allowed`, `agent_turn_completed`, `nba_recalculated` |
| `noc` | Operational/error — an availability failure, not a policy decision | `pdp_unavailable`, `backend_credential_unavailable` |
| `grl` | Guardrail/governance — an entitlement/policy boundary was applied or tested | `tool_call_denied`, `tools_list_filtered`, `tool_call_require_approval`, `approval_granted`, `bypass_attempt_detected`, `journey_ended_after_denial` |

2
RI/docs/interfaces/audit-events.md
View File

@@ -48,7 +48,7 @@ em vez de uma taxonomia própria:
| Categoria | Significado | Exemplos de `event_type` |
|---|---|---|
| `ic` | Interação de Cliente / negócio-jornada — a chamada progrediu normalmente | `client_authenticated`, `tool_call_allowed`, `agent_turn_completed`, `nba_recalculated` |
| `ic` | Indicador de Controle / negócio-jornada — a chamada progrediu normalmente | `client_authenticated`, `tool_call_allowed`, `agent_turn_completed`, `nba_recalculated` |
| `noc` | Operacional/erro — falha de disponibilidade, não uma decisão de política | `pdp_unavailable`, `backend_credential_unavailable` |
| `grl` | Guardrail/governança — uma fronteira de entitlement/política foi aplicada ou testada | `tool_call_denied`, `tools_list_filtered`, `tool_call_require_approval`, `approval_granted`, `bypass_attempt_detected`, `journey_ended_after_denial` |

6
RI/services/example_mcp_servers/sales_domain/server.py
View File

@@ -3,9 +3,9 @@
Read-only tools (risk tier R1, see README.md §17): customer.search,
customer.get, order.get, inventory.check. Write tools (R2): quote.create,
quote.update. Backed by static mock data -- this server is deliberately
"dumb": it never authorizes anything (see `docs/adr/ADR-023-autorizacao-nunca-vem-do-payload.md`).
Authorization happens exclusively upstream, in the Gateway/PEP (EP-05)
before a call ever reaches this process.
"dumb": it never authorizes anything (see
`docs/adr/ADR-023-autorizacao-nunca-vem-do-payload.md`). Authorization happens
exclusively upstream, in the Gateway/PEP (EP-05) before a call ever reaches this process.
Run directly for local development:

4
RI/src/emcp_bus/audit/models.py
View File

@@ -3,7 +3,7 @@
Adopts the IC/NOC/GRL taxonomy from the Agent Platform OCI reference
(ADR-022, docs/research/hoshikawa-agent-platform-oci.md) as the
`EventEnvelope.category` classification, rather than inventing a parallel
one: IC (Interação de Cliente/negócio-jornada), NOC (operacional/erro), GRL
one: IC (Indicador de Controle/negócio-jornada), NOC (operacional/erro), GRL
(guardrail/governança). `decision_id`/`policy_decision_id`/`entitlement_version`
(ADR-017, EP-08-T03) travel as first-class correlation fields on every event,
not as opaque payload keys, so a consumer can join events across the chain
@@ -27,7 +27,7 @@ class EventCategory(StrEnum):
"""README.md §27 event classes, mapped onto the Hoshikawa IC/NOC/GRL vocabulary."""
IC = "ic"
"""Interação de Cliente / negócio-jornada: the call progressed normally
"""Indicador de Controle / negócio-jornada: the call progressed normally
(e.g. `client_authenticated`, `tool_call_allowed`)."""
NOC = "noc"