# [DEF:Std:API_FastAPI:Standard]
# @TIER: CRITICAL
# @PURPOSE: Unification of all FastAPI endpoints following GRACE-Poly.
# @LAYER: UI (API)
# @INVARIANT: All non-trivial route logic must be wrapped in `belief_scope`.
# @INVARIANT: Every module and function MUST have `[DEF:]` anchors and metadata.

## 1. ROUTE MODULE DEFINITION
Every API route file must start with a module definition header:
```python
# [DEF:ModuleName:Module]
# @TIER: [CRITICAL | STANDARD | TRIVIAL]
# @SEMANTICS: list, of, keywords
# @PURPOSE: High-level purpose of the module.
# @LAYER: UI (API)
# @RELATION: DEPENDS_ON -> [OtherModule]
```

## 2. FUNCTION DEFINITION & CONTRACT
Every endpoint handler must be decorated with `[DEF:]` and explicit metadata before the implementation:
```python
@router.post("/endpoint", response_model=ModelOut)
# [DEF:function_name:Function]
# @PURPOSE: What it does (brief, high-entropy).
# @PARAM: param_name (Type) - Description.
# @PRE: Conditions before execution (e.g., auth, existence).
# @POST: Expected state after execution.
# @RETURN: What it returns.
async def function_name(...):
    with belief_scope("function_name"):
        # Implementation
        pass
# [/DEF:function_name:Function]
```

## 3. DEPENDENCY INJECTION & CORE SERVICES
*   **Auth:** `Depends(get_current_user)` for authentication.
*   **Perms:** `Depends(has_permission("resource", "ACTION"))` for RBAC.
*   **Config:** Use `Depends(get_config_manager)` for settings. Hardcoding is FORBIDDEN.
*   **Tasks:** Long-running operations must be executed via `TaskManager`. API routes should return Task ID and be non-blocking.

## 4. ERROR HANDLING
*   Raise `HTTPException` from the router layer.
*   Use `try-except` blocks within `belief_scope` to ensure proper error logging and classification.
*   Do not leak internal implementation details in error responses.

# [/DEF:Std:API_FastAPI]