vibe.runtime_typing

Runtime Type Checking Infrastructure.

This module provides the core runtime typing infrastructure for VIBE: - @runtime_checked decorator for function contract enforcement via beartype - Error handling and logging utilities for Pydantic validation failures - Structured logging for runtime type violations

All runtime type checking is always enabled across all environments.

runtime_checked 

runtime_checked(func: F) -> F

Enforce runtime type checking on function parameters and return values.

Use beartype to verify that all arguments and return values match their type annotations. This decorator adds O(1) overhead per call and should be used on: - Public service methods - Handler methods (render_widget, process_form_data, validate_input) - Serialization/deserialization functions - Core probing helpers (after performance verification)

Example

@runtime_checked def process_form_data(name: str, form_data: dict[str, Any]) -> Any: ...

Parameters:
  • func (F) –

    The function to decorate
Returns:
  • F –

    The decorated function with runtime type checking enabled

raise_validation_error 

raise_validation_error(boundary: str, *, error: ValidationError, raw: dict[str, Any], context: dict[str, Any] | None = None) -> NoReturn

Log and raise a validation error with structured context.

This helper provides consistent error handling for Pydantic validation failures at data boundaries (session load, form submission, template loading, etc.).

The error is logged with: - Boundary name (e.g., "session_deserialization", "form_submission") - Full validation error details from Pydantic - Preview of raw input data (first 5 keys) - Optional context (template_id, session_id, etc.)

After logging, raises ValueError with a concise message for the caller to handle.

Parameters:
  • boundary (str) –

    Name of the validation boundary (e.g., "session_load", "template_bundle")

  • error (ValidationError) –

    The Pydantic ValidationError that was caught

  • raw (dict[str, Any]) –

    The raw dictionary that failed validation (will be previewed in logs)

  • context (dict[str, Any] | None, default: None ) –

    Optional additional context to include in logs (session_id, template_id, etc.)
Raises:
  • ValueError –

    Always raised after logging, with boundary name and error summary
Example

try: session_data = SessionModel.model_validate(raw_dict) except ValidationError as e: raise_validation_error( "session_load", error=e, raw=raw_dict, context={"session_id": session_id} )

log_type_error 

log_type_error(function_name: str, *, error: Exception, context: dict[str, Any] | None = None) -> None

Log runtime type errors from beartype without raising.

Used for observability when we want to log type violations but not fail the request. In practice, beartype will raise immediately, so this is primarily for future use.

Parameters:
  • function_name (str) –

    Name of the function where the type error occurred

  • error (Exception) –

    The exception that was raised

  • context (dict[str, Any] | None, default: None ) –

    Optional context (parameters, state, etc.)