# Responsibility Boundaries: FastMCP, LaBSE, Router, Inspection

This document defines the intended responsibility split for the LLM runtime stack in `blender-ai-mcp`.

It exists to prevent architectural drift while the project grows its FastMCP platform, semantic matching, router intelligence, and Blender inspection surface.

---

## Why This Document Exists

This project now contains four different kinds of intelligence:

- MCP platform behavior
- semantic understanding
- deterministic execution correction
- Blender state inspection

If those layers blur together, the system becomes harder to:

- trust
- tune
- debug
- migrate safely to FastMCP 3.x

The goal is to make each layer explicit and keep the stack coherent as the product expands.

---

## Layer 1: FastMCP Platform Layer

### Role

FastMCP is the **platform and presentation layer** for the MCP product surface.

It should be responsible for:

- tool discovery
- tool visibility
- session-aware capability shaping
- API surface transformation
- prompt delivery
- user elicitation
- background task UX
- versioned client surfaces
- structured interaction contracts at the MCP boundary

### It Is Good At

- deciding what the client can see
- making large catalogs manageable
- adapting the public surface for different client types
- carrying interaction patterns such as prompts, structured clarifications, and long-running jobs

### It Is Not The Authority For

- semantic intent understanding
- scene truth
- geometry correctness
- Blender execution safety

### Design Rule

If the question is:

- “what should be exposed?”
- “what should be discoverable?”
- “how should clients interact with this surface?”

the answer belongs primarily to FastMCP.

### Guided Visibility Note

On `llm-guided`, runtime visibility should have one clear authority:

- `build_visibility_rules(...)`
- the current session phase / `guided_handoff`
- the current `guided_flow_state`

Capability tags and the capability manifest are allowed to carry coarse
metadata for:

- discovery and inventory
- provider grouping
- pinned/default entry hints
- phase-shaped catalog hints

They must not become a second hidden runtime phase gate once the guided
visibility rules are built.

Guided state/visibility updates that happen during native MCP requests must be
completed through the active request path. On Streamable HTTP, sync routed tools
that mutate guided session state should defer post-route visibility or spatial
finalizers to an awaited MCP wrapper instead of scheduling detached writes on the
request loop.

---

## Layer 2: LaBSE Semantic Layer

### Role

LaBSE is the **semantic retrieval and generalization layer**.

It should be responsible for:

- multilingual workflow matching
- semantic workflow reranking
- synonym and phrasing generalization
- learned parameter mapping reuse
- semantic modifier interpretation

### It Is Good At

- matching intent across languages
- handling prompt paraphrases
- retrieving likely workflows or mappings when wording varies
- supporting learned semantic memory

### It Is Not The Authority For

- the final public tool catalog
- exact tool safety policy
- scene-state truth
- geometry validation
- whether a correction actually succeeded

### Design Rule

If the question is:

- “what did the user probably mean?”
- “which workflow or modifier is semantically closest?”

LaBSE is appropriate.

If the question is:

- “what is actually true in Blender?”
- “is this operation safe?”
- “did the fix work?”

LaBSE must not be the source of truth.

### Current Enforcement Notes

- general MCP tool discovery is owned by FastMCP search and visibility controls
- semantic parameter memory is allowed only when the prompt is relevant to the target parameter
- semantic workflow results are workflow-retrieval input, not proof of truth or policy approval
- prompt recommendation may use explicit session state such as active goal,
  phase/profile, and typed guided-handoff metadata; it must not scrape free-form history

---

## Layer 3: Router Policy And Safety Layer

### Role

The router is the **deterministic policy layer** between LLM intent and Blender execution.

It should be responsible for:

- mode correction
- selection correction
- safe parameter normalization
- clamping
- guardrails and blocking
- confidence-based workflow adaptation
- explicit override policy
- converting intent into safer tool sequences

### It Is Good At

- applying deterministic precondition fixes
- protecting Blender from obvious misuse
- enforcing operational policy
- handling correction/ask/block decisions

### It Is Not The Authority For

- raw semantic retrieval
- public MCP exposure strategy
- final scene correctness by itself

The router may use semantic inputs, but it should not become a fuzzy all-purpose brain.

### Design Rule

If the question is:

- “how do we execute this safely?”
- “what deterministic correction can we apply?”
- “should we auto-fix, ask, or block?”

the router owns that decision.

Speculative reinterpretation must be tightly governed by confidence and risk policy.

---

## Layer 4: Inspection And Assertion Layer

### Role

The inspection/assertion layer is the **truth and verification layer**.

It should be responsible for:

- current scene state
- object dimensions and origin
- topology and attribute state
- hierarchy and material/node inspection
- render-based visual QA
- future assertions about alignment, contact, symmetry, containment, and correctness

### It Is Good At

- reporting what actually exists in Blender
- validating whether expected conditions are true
- feeding reliable state back into the router or client LLM

### It Is Not The Authority For

- semantic intent matching
- API discovery
- public-surface shaping

### Design Rule

If the question is:

- “what is the actual state right now?”
- “did the operation produce the intended result?”
- “are these objects aligned / intersecting / inside / symmetric?”

the answer belongs to inspection/assertion tools, not to LaBSE and not to speculative router logic.

Silhouette metrics and future part-segmentation outputs are perception inputs:

- they may inform operator-facing `action_hints`
- they do not replace truth assertions
- they do not become router safety policy on their own
- `vision_contract_profile` remains routing metadata for external prompting/parsing, not evidence

Goal-derived quality gates follow the same split:

- LLMs, `reference_understanding`, silhouette analysis, segmentation,
  classification scores, and VLM checkpoint findings may propose gates or
  bounded evidence refs
- the MCP/session layer normalizes those proposals into `active_gate_plan` and
  starts every gate as `pending`
- scene, spatial, mesh, and assertion verifiers own later `passed`, `failed`,
  `blocked`, `stale`, or `waived` status transitions
- the first shipped verifier transition is relation-graph based:
  `scene_relation_graph(...)` may mark `required_part`, `attachment_seam`, and
  `support_contact` gates with authoritative `scene_truth` or
  `spatial_relation` evidence refs, while guided mutations mark prior evidence
  stale through the existing spatial dirtying path
- gate blockers shape visibility/search through the existing FastMCP guided
  surface only; they do not create a second catalog authority and they do not
  make semantic search responsible for pass/fail truth
- reference stage checkpoint responses may project active gate state into
  top-level blocker/action/tool-hint fields, but those fields remain read-only
  summaries of server-owned verifier state rather than a new policy authority
- client-supplied completion claims and hidden tool names are policy warnings,
  not trusted truth

The same boundary applies to the shipped read-only spatial graph artifacts:

- `scene_scope_graph(...)` and `scene_relation_graph(...)` are inspection/truth
  products derived from measured/asserted state
- FastMCP visibility/search decides when those artifacts are exposed on
  `llm-guided`
- the router may consume their typed findings for bounded policy decisions, but
  it must not become the authority that invents scope or relation truth on its
  own

---

## Target System Contract

The intended system contract is:

- **FastMCP** decides what is visible and how interaction is structured.
- **LaBSE** decides what is semantically similar.
- **Router** decides what is safe and how execution should be corrected.
- **Inspection / Assertion** decides what is true and whether the result is acceptable.

For hybrid correction-loop payloads such as ranked `correction_candidates`,
preserve those boundaries inside the contract itself:

- vision evidence may justify *what looks wrong*
- truth evidence may justify *what is spatially wrong*
- macro candidates may justify *what bounded repair is available*

Do not collapse those sources into one fuzzy score that hides provenance.
Ranking is allowed; source erasure is not.

When loop-facing summaries such as `correction_focus` are derived from those
ranked candidates, preserve the ranked order but keep the richer source payload
available alongside the summary list. The summary is for loop ergonomics; the
candidate payload remains the authoritative provenance record.

When `loop_disposition` is influenced by deterministic truth signals, prefer
explicit bounded rules such as high-priority contact/overlap/assertion failure
over fuzzy confidence blending. Truth-driven escalation is allowed; source
blurring is not.

For correction policy specifically:

- normalized confidence and explicit risk classes should feed one router policy decision
- that decision should resolve to `auto-fix`, `ask`, or `block`
- operator-visible policy context should surface the chosen path and rationale

This separation should hold even when the same request touches all four layers.

## Sampling Assistant Guardrails

Sampling assistants do not introduce a fifth authority layer.
They are a bounded FastMCP-mediated helper mechanism that must remain subordinate to the existing split above.

Allowed first responsibilities:

- summarize structured inspection payloads
- compress large diagnostics into compact next-step guidance
- draft repair suggestions from router/runtime diagnostics

Forbidden first responsibilities:

- autonomous geometry-destructive planning
- hidden substitution for router safety policy
- scene-truth decisions without inspection contracts
- detached background reasoning outside an active MCP request

Design rule:

- assistants may help interpret inspection truth
- assistants may help draft recovery guidance from diagnostics
- assistants must not become the authority for safety approval, discovery ownership, or Blender truth

---

## Current State In This Repository

### FastMCP Layer

Current state: **partially aligned, needs major improvement**

- The server already has a strong MCP surface.
- However, the current runtime is still mostly a flat registered tool catalog.
- Discovery, visibility shaping, versioned surfaces, and other 3.x platform features are not yet the main organizing principle.

Interpretation:

- This layer is the main area that still needs structural improvement.

### LaBSE Layer

Current state: **mostly aligned**

- LaBSE is already used mainly for workflow matching, multilingual semantics, and parameter memory.
- Shared model loading via DI is already in place.
- This is directionally correct.

Interpretation:

- Keep LaBSE.
- Do not let it expand into discovery, truth, or safety roles.

### Router Layer

Current state: **good foundation, needs policy hardening**

- Mode switching, selection injection, alias normalization, and parameter clamping already exist.
- Workflow adaptation and confidence concepts already exist.
- Pattern overrides also exist.

Interpretation:

- The deterministic safety role is present.
- What still needs work is policy clarity:
  - when auto-fix is allowed
  - when the system should ask
  - when override behavior is too speculative
  - how corrections are audited and validated

### Inspection / Assertion Layer

Current state: **strong inspection, incomplete assertion**

- Inspection is already one of the strongest parts of the repo.
- The system has rich tools for context, topology, modifiers, constraints, bounds, origins, and view-based inspection.
- However, assertions are still weaker than inspections.

Interpretation:

- The project already has a strong truth layer foundation.
- It now needs explicit assertion tools and postcondition-based validation.

---

## Practical Rules For Contributors

- Do not use LaBSE to solve a problem that FastMCP discovery/visibility should solve.
- Do not use semantic similarity as proof of scene correctness.
- Do not silently convert speculative semantic guesses into automatic Blender writes unless the correction policy clearly allows it.
- Prefer structured inspection outputs over prose when correctness matters.
- Prefer elicitation over silent reinterpretation in medium-confidence cases.
- Treat inspection and future assertion tools as the final authority on Blender state.

---

## Related Docs

- [README](./README.md)
- [ROUTER_ARCHITECTURE.md](./ROUTER_ARCHITECTURE.md)
- [WORKFLOWS/workflow-execution-pipeline.md](./WORKFLOWS/workflow-execution-pipeline.md)
- [LLM Guide v2](../LLM_GUIDE_V2.md)
- [Spatial Intelligence Upgrade Proposal](../Spacial-intelligence-upgrades-for-blender-ai-mcp.md)
- [TASK-083](../_TASKS/TASK-083_FastMCP_3x_Platform_Migration.md)
- [TASK-084](../_TASKS/TASK-084_Dynamic_Tool_Discovery.md)
- [TASK-089](../_TASKS/TASK-089_Typed_Contracts_and_Structured_Responses.md)
- [TASK-095](../_TASKS/TASK-095_LaBSE_Semantic_Layer_Boundaries.md)
- [TASK-096](../_TASKS/TASK-096_Confidence_Policy_for_Auto_Correction.md)
- [TASK-097](../_TASKS/TASK-097_Transparent_Correction_Audit_and_Postconditions.md)
