feat(extensions): add OperationValidator.precheck pre-body-parse hook (#1548)

Add an optional ``precheck`` method to ``OperationValidatorExtension`` that
extensions can override to gate a request *before* its body is read off the
wire. Wire it as a FastAPI ``Depends`` ahead of the body parameter on the
billable POST routes (retain, recall, reflect, file retain, mental-model
create, mental-model refresh) so a rejecting precheck short-circuits the
request without ever materialising the JSON payload in memory.

The post-body-parse ``validate_retain`` / ``validate_recall`` /
``validate_reflect`` hooks are unchanged and remain the source of truth for
precise per-call cost and quota arithmetic. ``precheck`` is intentionally a
cheap, side-effect-free check — its sole purpose is to let an extension
short-circuit work that would otherwise allocate the request body
unnecessarily (e.g. a quota-exhausted caller submitting many large bodies).

Why before body parse:

FastAPI resolves dependencies before deserialising the route's body
parameter. A validator that runs only after parse — i.e. inside the route
handler's body — sees the already-materialised request, which is the wrong
layer for "this caller should not be allowed to spend resources on this
request at all" decisions. Wiring as ``Depends`` puts the gate at the right
layer with a one-line change per route.

Verified:

- FastAPI 0.125.0 resolves ``Depends`` raising ``HTTPException`` before
  Pydantic deserialises the body, regardless of declaration order. A
  reproducer using a ``model_validator(mode='before')`` recorder confirms
  zero body-parse calls on the rejection path.
- The new ``PrecheckContext`` carries only operation name + bank_id +
  request_context (already-resolved tenant). No body access — by design.
- Default ``precheck`` returns ``ValidationResult.accept()``; existing
  validators are unaffected.

Tests: +7 unit tests covering the default no-op, the FastAPI Depends
wiring, accept/reject paths, status-code/reason propagation, and explicit
"body never parsed on rejection" assertions for retain / recall / reflect
plus a "GET routes are unaffected" guard. All passing.

Author: cdbartholomew

hindsight-api-slim/hindsight_api/api/http.py

@@ -2892,6 +2892,57 @@ def get_request_context(authorization: str | None = Header(default=None)) -> Req
                 api_key = authorization.strip()
         return RequestContext(api_key=api_key)
 
+    def precheck_for(operation: str):
+        """
+        Build a FastAPI dependency that runs ``OperationValidator.precheck``.
+
+        FastAPI resolves dependencies before deserialising the route's body
+        parameter. Wiring this dependency on the billable POST routes lets
+        an extension reject a request — e.g. with HTTP 402 when a tenant's
+        balance is exhausted — without the request body ever being read or
+        materialised in memory.
+
+        The dependency intentionally:
+        - authenticates the tenant (so ``request_context.tenant_id`` is
+          resolved before the precheck runs);
+        - falls through silently when no validator is configured or the
+          validator's default no-op precheck is in effect;
+        - converts a rejection ``ValidationResult`` into the corresponding
+          ``HTTPException`` directly (the per-route ``OperationValidationError``
+          catch blocks don't see exceptions raised in dependencies, so we
+          translate here instead of relying on each handler's try/except).
+
+        Args:
+            operation: Short identifier for the route, e.g. ``"retain"``.
+
+        Returns:
+            A FastAPI dependency callable suitable for ``Depends(...)``.
+        """
+
+        async def _precheck_dep(
+            bank_id: str,
+            request_context: RequestContext = Depends(get_request_context),
+        ) -> None:
+            validator = getattr(app.state.memory, "_operation_validator", None)
+            if validator is None:
+                return
+            from hindsight_api.extensions import PrecheckContext
+
+            await app.state.memory._authenticate_tenant(request_context)
+            ctx = PrecheckContext(
+                operation=operation,
+                bank_id=bank_id,
+                request_context=request_context,
+            )
+            result = await validator.precheck(ctx)
+            if not result.allowed:
+                raise HTTPException(
+                    status_code=result.status_code,
+                    detail=result.reason or "Operation not allowed",
+                )
+
+        return _precheck_dep
+
     # Global exception handler for authentication errors
     @app.exception_handler(AuthenticationError)
     async def authentication_error_handler(request, exc: AuthenticationError):
@@ -3149,7 +3200,10 @@ async def api_get_observation_history(
     )
     @audited("recall")
     async def api_recall(
-        bank_id: str, request: RecallRequest, request_context: RequestContext = Depends(get_request_context)
+        bank_id: str,
+        request: RecallRequest,
+        request_context: RequestContext = Depends(get_request_context),
+        _precheck: None = Depends(precheck_for("recall")),
     ):
         """Run a recall and return results with trace."""
         import time
@@ -3337,7 +3391,10 @@ def _fact_to_result(fact: "MemoryFact") -> RecallResult:
     )
     @audited("reflect")
     async def api_reflect(
-        bank_id: str, request: ReflectRequest, request_context: RequestContext = Depends(get_request_context)
+        bank_id: str,
+        request: ReflectRequest,
+        request_context: RequestContext = Depends(get_request_context),
+        _precheck: None = Depends(precheck_for("reflect")),
     ):
         metrics = get_metrics_collector()
 
@@ -3835,6 +3892,7 @@ async def api_create_mental_model(
         bank_id: str,
         body: CreateMentalModelRequest,
         request_context: RequestContext = Depends(get_request_context),
+        _precheck: None = Depends(precheck_for("mental_model_create")),
     ):
         """Create a mental model (async - returns operation_id)."""
         try:
@@ -3883,6 +3941,7 @@ async def api_refresh_mental_model(
         bank_id: str,
         mental_model_id: str,
         request_context: RequestContext = Depends(get_request_context),
+        _precheck: None = Depends(precheck_for("mental_model_refresh")),
     ):
         """Refresh a mental model by re-running its source query (async)."""
         try:
@@ -5729,7 +5788,10 @@ async def api_list_webhook_deliveries(
     )
     @audited("retain")
     async def api_retain(
-        bank_id: str, request: RetainRequest, request_context: RequestContext = Depends(get_request_context)
+        bank_id: str,
+        request: RetainRequest,
+        request_context: RequestContext = Depends(get_request_context),
+        _precheck: None = Depends(precheck_for("retain")),
     ):
         """Retain memories with optional async processing."""
         metrics = get_metrics_collector()
@@ -5899,6 +5961,7 @@ async def api_file_retain(
         files: list[UploadFile] = File(..., description="Files to upload and convert"),
         request: str = Form(..., description="JSON string with FileRetainRequest model"),
         request_context: RequestContext = Depends(get_request_context),
+        _precheck: None = Depends(precheck_for("files_retain")),
     ):
         """Upload and convert files to memories."""
         from hindsight_api.config import get_config

hindsight-api-slim/hindsight_api/extensions/__init__.py

@@ -40,6 +40,7 @@
     # Core operations
     OperationValidationError,
     OperationValidatorExtension,
+    PrecheckContext,
     RecallContext,
     RecallResult,
     ReflectContext,
@@ -72,6 +73,7 @@
     "DeferOperation",
     "OperationValidationError",
     "OperationValidatorExtension",
+    "PrecheckContext",
     "RecallContext",
     "RecallResult",
     "ReflectContext",

hindsight-api-slim/hindsight_api/extensions/operation_validator.py

@@ -82,6 +82,33 @@ def reject(cls, reason: str, status_code: int = 403) -> "ValidationResult":
 # =============================================================================
 
 
+@dataclass
+class PrecheckContext:
+    """Context for a pre-body-parse precheck on an operation.
+
+    Unlike :class:`RetainContext` / :class:`RecallContext` / etc., this
+    context is constructed *before* the request body is deserialised. It
+    therefore intentionally carries only the cheap, already-resolved
+    pieces of request state:
+
+    - ``operation``: a short string identifying the route, e.g. ``"retain"``,
+      ``"recall"``, ``"reflect"``, ``"files_retain"``, ``"mental_model_create"``,
+      ``"mental_model_refresh"``.
+    - ``bank_id``: parsed from the URL path.
+    - ``request_context``: the authenticated :class:`RequestContext` (tenant
+      already resolved by the tenant extension).
+
+    Implementations should keep precheck cheap and side-effect-free. The
+    full per-request validators (``validate_retain`` / ``validate_recall``
+    / ``validate_reflect``) still run after the body is parsed and remain
+    the source of truth for the precise per-call cost / quota arithmetic.
+    """
+
+    operation: str
+    bank_id: str
+    request_context: "RequestContext"
+
+
 @dataclass
 class RetainContext:
     """Context for a retain operation validation (pre-operation).
@@ -407,6 +434,42 @@ class OperationValidatorExtension(Extension, ABC):
         - consolidate (mental models consolidation)
     """
 
+    # =========================================================================
+    # Pre-body-parse hook (optional - default no-op)
+    # =========================================================================
+
+    async def precheck(self, ctx: PrecheckContext) -> ValidationResult:
+        """
+        Cheap pre-body-parse check, called before the request body is read.
+
+        FastAPI resolves ``Depends`` callables before deserialising the route
+        body; routes that wire ``precheck`` as a dependency therefore short
+        -circuit here without ever materialising the JSON payload in memory.
+        That makes this the right hook for "should this caller be allowed to
+        spend resources on this request at all" decisions — e.g. a balance
+        is exhausted, a key is revoked, or a tenant is rate-limited.
+
+        Implementations should:
+        - Be cheap: prefer cached lookups, avoid heavy DB queries.
+        - Use only data on ``ctx`` (operation name + bank_id + request_context);
+          the body is not yet available.
+        - Be conservative on errors: prefer ``ValidationResult.accept()`` so
+          a transient lookup failure doesn't turn into a request rejection.
+          The post-body ``validate_*`` hooks still run and remain the source
+          of truth for the precise per-call cost check.
+
+        Default implementation accepts everything. Override to opt in.
+
+        Args:
+            ctx: Pre-body context with operation name, bank_id, and
+                request_context (tenant already resolved).
+
+        Returns:
+            ValidationResult indicating whether the request may proceed to
+            body parsing and the post-parse validators.
+        """
+        return ValidationResult.accept()
+
     # =========================================================================
     # Pre-operation validation hooks (abstract - must be implemented)
     # =========================================================================