Enterprise-MCP-Service-Bus/RI/docs/Assumptions.en-us.md

Assumptions — assumptions and decisions of this RI

This document explains what was assumed when building the Reference Implementation (RI) and why, distinguishing that from what is an architectural guarantee of the reference architecture. It is a synthesis — not a copy — of the decision history recorded in docs/adr/; each ADR remains the canonical record of an individual decision, this document groups the "why" by theme for whoever is evaluating the RI.

Target audience: whoever is going to evaluate or adapt this RI for a real scenario and needs to know what was assumed versus what is a guarantee of the architecture.

General scope

We assume that an RI proves security properties, it is not a production-ready product. Every decision below prioritizes verifiably demonstrating the architecture's invariants (MaximumEntitlement as a ceiling, fail-closed, never elevate privilege by context) over operational completeness (HA, scale, UI). Where the two collided, we chose the simplest RI that still proves the real property against a real dependency — never a mock of the very point being tested.

Identity and PDP: closed technologies, not hypotheses to revisit

We assume Keycloak as Identity Provider and OPA/Rego as PDP because they are OSS (Apache-2.0) and adherent to open standards (OAuth 2.1/OIDC, Rego), not out of arbitrary preference. This resolves two gaps that the reference architecture left open (README.md §48, questions 1 and 3) with a definitive technical decision, not an assumption — they were never revisited throughout the implementation. See docs/adr/ADR-019-identity-extension.md, docs/adr/ADR-025-engine-do-pdp.md.

We rejected a custom PDP engine in Python (more control, but reinvents policy evaluation with no real gain) and Cedar (also would be adequate, but OPA has greater adherence to "open standards" and a more mature Rego community for the scope of this RI).

Operational reference Python/LangGraph/Langfuse (Agent Platform OCI)

We assume as the concrete operational reference the Agent Platform OCI project by Christiano Hoshikawa (docs/research/hoshikawa-agent-platform-oci.md) for the LangGraph/Langfuse/FastMCP layer, instead of inventing a generic pattern from scratch — faster, fewer ad hoc decisions, and a real point of comparison for what "multiagent orchestration" means in practice. We reuse from that reference: StateGraph with a router/supervisor per backend, pluggable checkpointing, the IC/NOC/GRL observability taxonomy with hybrid instrumentation (automatic spans + fail-open manual events), identity.yaml/BusinessContext to normalize identity across channels, FastMCP as the MCP server standard.

We explicitly rejected a single element of that reference: its tool authorization model via a static allowlist evaluated over an agent_id that arrives as data from the conversation's input payload, not as a claim from an independently verified authenticated identity — the reference project itself admits that this does not replace real authentication/authorization. That is exactly the anti-pattern form that the architecture forbids (ADR-001/ADR-002/ADR-003). The RI reuses the proxy shape of that Gateway (invocation/result contracts, per-tool cache, catalog) only at the Fabric/conversational UX layer — the ALLOW/DENY decision remains 100% in our PEP/PDP, never in a self-declared agent_id. See docs/adr/ADR-022-referencia-hoshikawa-agent-platform-oci.md, docs/adr/ADR-023-autorizacao-nunca-vem-do-payload.md. This finding also motivated a dedicated adversarial scenario (tests/adversarial/test_payload_identity_spoofing.py).

Downstream identity

We assume token exchange (RFC 8693) when the backend supports OIDC, with a fallback to a service account isolated per adapter when it does not — because always reusing the client's token (the simpler alternative) is exactly the "blind token passthrough" that the architecture forbids (inbound ≠ outbound identity). See docs/adr/ADR-020-downstream-identity.md.

Client profile granularity

We assume domain + risk tier (e.g.: Sales.Read=R1, Sales.Write=R2, Finance.Payments=R3) as the client profile granularity, instead of a single "enterprise admin" client or domain-only without tier — because only this granularity allows proving blast-radius segmentation between risk tiers within the same domain (README.md §7, §17, §31). See docs/adr/ADR-008-segmentacao-por-dominio-e-risco.md.

Profile Intelligence: deterministic stub, not "real AI"

We assume that "generic and replaceable" Profile Intelligence (README.md §6.10) does not prescribe an algorithm, taxonomy, or real data source — because the reference architecture does not define any of these, deliberately. The RI implements a stub based on deterministic rules over synthetic attributes, behind a replaceable interface (ProfileIntelligenceProvider), which fulfills the contract, not the "intelligence" itself. A production fork replaces only the implementation, never the contract (ProfileView) nor the point where it connects (never to the PDP).

Domain scope: two, not full federation

We assume two example domains (Sales, Finance) as sufficient to prove segmentation/blast-radius between distinct domains, without needing full multi-domain federation. Federation is deliberately out of scope for this RI — it is addressed in the reference architecture's roadmap as a later phase (§47, Phase 5), not an implementation gap.

Environment: 100% local via Docker Compose

We assume that an RI runs entirely locally via docker compose, with environment separation demonstrated by a configuration overlay (config/env/{dev,ci}.yaml) instead of real cloud/hybrid infrastructure — proving the architecture does not require multi-cloud, and simulating multi-cloud without real multi-cloud would prove nothing beyond the simulation itself.

Substitutions to enable testing without heavy infrastructure

• Local JWKS server as a stand-in for Keycloak in most of the e2e suite — valid because what is being tested there is the token validation logic (signature, exp, iss, aud, extraction of azp), which is identical against any valid RS256 JWKS. Real protocol integration with Keycloak (client_credentials grant, real claims issued by a real IdP, RFC 8693) is covered separately, against a real Keycloak 26.7.3 via Docker (tests/e2e/test_real_keycloak.py) — it is not the same test, it is a complementary test that covers exactly what the stand-in cannot.
• SQLite instead of Postgres for the Registry and for the LangGraph checkpointer — valid to prove the contract/behavior (schema, lifecycle, graph pause/resume); it is not a claim about performance or concurrency under production load (see Production-Recommendations.md).
• policy_version as a file hash, not a real OPA bundle revision — a SHA-256 of the content of the .rego files on disk is enough to prove that policy_version flows end to end through every decision and audit event; it is not a claim about policy distribution in a production cluster.

Items deliberately out of scope

• REST adapter without a live path through the Gateway (EP-06-T04): implemented and tested standalone; none of this RI's example backends is REST, so there is no live path through the Gateway exercising it. It would only become relevant if a future domain needed a non-MCP-native backend.
• LangGraph deliberately absent from the Gateway/Fabric — used only where there is real state, cycles, or checkpointing (Service Orchestrator, EP-11; Agent Runtime handoff, EP-12-T03). No simple routing (Gateway EP-05, Fabric EP-06, Offering Filter EP-10) uses LangGraph — using a stateful graph for stateless routing would be over-engineering, not a neutral choice. See docs/adr/ADR-021-escopo-langgraph-langfuse.md.
• Rate limiting and anti-replay: real, conscious gaps, not oversights — documented and covered by a dedicated adversarial test (tests/adversarial/test_protocol_identity.py), never silently ignored. See Production-Recommendations.md for what a real deployment needs to add.