Mastrao
Guide/Mastra Integration Boundary

Mastra Integration Boundary

Define what Mastra can own in Mastrao and what remains governed by Mastrao.

Mastra can provide the generic agentic runtime behind Hermès, but it must not become the authority for cabinet knowledge, permissions, evidence, retention or external effects.

This page summarizes the integration boundary. The detailed architecture plan lives in .agents/plan/context-c03-mastra-integration-boundary.md.

Core Rule

Use Mastra for execution. Use Mastrao for authority.

Hermès UI
  -> Mastra agent or workflow
  -> Mastrao tool gateway
  -> governed MatterContextPack
  -> cited answer, structured proposal or refusal

Mastra can reason over a supplied context pack. It cannot decide the matter scope, bypass authorization, write accepted assertions directly or persist a pack as durable cabinet memory.

What Mastra Can Own

Mastra is a good candidate for reusable agent infrastructure:

  • agent execution and model/tool-call mechanics;
  • typed tools;
  • workflows with steps, parallelism, suspension and resume;
  • conversation memory and working memory within a scoped lifecycle;
  • retrieval utilities, including RAG and GraphRAG;
  • generic input/output guardrails;
  • traces, metrics, evals and local Studio inspection;
  • MCP client/server plumbing.

What Mastrao Must Own

Mastrao keeps the legal-grade control plane:

  • actor, cabinet, matter and effective-wall authorization;
  • governed matter memory and accepted assertions;
  • source identity, provenance, versions and locators;
  • retention, deletion, legal hold, supersession and revocation;
  • Action Gateway approvals and external effect receipts;
  • evidence-grade audit;
  • domain rubrics and release gates.

Memory Boundary

Mastra memory and Mastrao governed memory are different systems.

Mastra memory can help Hermès continue a conversation. It cannot make a matter assertion true, accepted, current, revoked or superseded.

For matter-scoped answers, Hermès should request a short-lived context pack from Mastrao:

resolveMatterContext(request)
  -> authorization before retrieval
  -> current source and assertion checks
  -> bounded MatterContextPack
  -> cited answer or refusal

Tool Boundary

Every Mastra tool that touches cabinet data must be mediated by Mastrao.

The tool gateway is responsible for:

  • validating input schemas;
  • resolving the current actor and scope;
  • enforcing permissions outside the LLM;
  • issuing short-lived scoped grants;
  • binding idempotency and postconditions;
  • recording safe audit receipts.

MCP Boundary

MCP should be treated as an external integration surface, not as trusted internal code.

Before using an MCP server, Mastrao must define allowed hosts, allowed tools, minimal scopes, timeouts, approval policy and logging. Tool descriptions, annotations and results are untrusted unless the server has been explicitly trusted.

Guardrail Boundary

Mastra guardrails are useful defense-in-depth.

They do not replace:

  • server-side authorization;
  • scoped grants;
  • sandboxing;
  • source lifecycle checks;
  • human approval;
  • Action Gateway policy;
  • evidence validation.
  1. Document and review the C03 boundary.
  2. Build a provider-free local spike where a Mastra-style workflow consumes a fixture MatterContextPack.
  3. Define the Mastrao tool gateway surface for resolveMatterContext.
  4. Choose one Hermès workflow that benefits from Mastra orchestration.
  5. Map Mastra observability and evals to Mastrao release gates.
  6. Define which conversation memories can live in Mastra storage and how users explicitly promote content into governed matter memory.

References

Mastrao Governed Context and Hermès