omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/bindings/__init__.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Operation bindings models for declarative handler parameter mapping.
+
+This module provides models for binding expressions used in declarative
+handler parameter resolution from contract.yaml.
+
+.. versionadded:: 0.2.6
+    Added ModelOperationBindingsSubcontract and ModelBindingResolutionResult
+    as part of OMN-1518 - Declarative operation bindings.
+"""
+
+from omnibase_infra.models.bindings.constants import (
+    DEFAULT_JSON_RECURSION_DEPTH,
+    EXPRESSION_PATTERN,
+    MAX_EXPRESSION_LENGTH,
+    MAX_JSON_RECURSION_DEPTH,
+    MAX_PATH_SEGMENTS,
+    MIN_JSON_RECURSION_DEPTH,
+    VALID_CONTEXT_PATHS,
+    VALID_SOURCES,
+)
+from omnibase_infra.models.bindings.model_binding_resolution_result import (
+    ModelBindingResolutionResult,
+)
+from omnibase_infra.models.bindings.model_operation_binding import (
+    ModelOperationBinding,
+)
+from omnibase_infra.models.bindings.model_operation_bindings_subcontract import (
+    MAX_EXPRESSION_LENGTH_LIMIT,
+    MAX_PATH_SEGMENTS_LIMIT,
+    MIN_EXPRESSION_LENGTH,
+    MIN_PATH_SEGMENTS,
+    ModelOperationBindingsSubcontract,
+)
+from omnibase_infra.models.bindings.model_parsed_binding import (
+    ModelParsedBinding,
+)
+
+__all__: list[str] = [
+    # Constants
+    "DEFAULT_JSON_RECURSION_DEPTH",
+    "EXPRESSION_PATTERN",
+    "MAX_EXPRESSION_LENGTH",
+    "MAX_EXPRESSION_LENGTH_LIMIT",
+    "MAX_JSON_RECURSION_DEPTH",
+    "MAX_PATH_SEGMENTS",
+    "MAX_PATH_SEGMENTS_LIMIT",
+    "MIN_EXPRESSION_LENGTH",
+    "MIN_JSON_RECURSION_DEPTH",
+    "MIN_PATH_SEGMENTS",
+    "VALID_CONTEXT_PATHS",
+    "VALID_SOURCES",
+    # Models
+    "ModelBindingResolutionResult",
+    "ModelOperationBinding",
+    "ModelOperationBindingsSubcontract",
+    "ModelParsedBinding",
+]

omnibase_infra/models/bindings/constants.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Shared constants for binding expression parsing and validation.
+
+This module contains guardrail constants and patterns used by both:
+- :mod:`omnibase_infra.runtime.binding_resolver` (runtime resolution)
+- :mod:`omnibase_infra.runtime.contract_loaders.operation_bindings_loader` (load-time validation)
+
+These constants define the security and validation boundaries for binding expressions.
+
+.. versionadded:: 0.2.6
+    Created as part of OMN-1518 - Declarative operation bindings.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+# =============================================================================
+# Guardrail Constants
+# =============================================================================
+
+MAX_EXPRESSION_LENGTH: Final[int] = 256
+"""Maximum allowed length for binding expressions (characters).
+
+Prevents denial-of-service via extremely long expressions that could
+exhaust memory or CPU during regex matching.
+"""
+
+MAX_PATH_SEGMENTS: Final[int] = 20
+"""Maximum allowed path depth (dot-separated segments).
+
+Prevents deep nesting attacks and potential stack overflow during
+path traversal. Also limits complexity of binding expressions.
+"""
+
+# =============================================================================
+# JSON Recursion Depth Limits
+# =============================================================================
+
+DEFAULT_JSON_RECURSION_DEPTH: Final[int] = 100
+"""Default maximum recursion depth for JSON compatibility validation.
+
+This constant limits how deeply nested structures are validated in
+``_is_json_compatible_recursive()``. It prevents stack overflow on
+pathological inputs such as deeply nested dicts/lists or cyclic
+references that somehow bypass Python's normal recursion limit.
+
+The value of 100 is chosen to:
+- Allow normal JSON structures (rarely exceed 10-20 levels)
+- Prevent stack overflow on malicious or malformed inputs
+- Align with common JSON parser depth limits
+
+.. versionadded:: 0.2.6
+"""
+
+MIN_JSON_RECURSION_DEPTH: Final[int] = 10
+"""Minimum configurable JSON recursion depth.
+
+Values below this threshold would be too restrictive for practical use,
+as even simple nested structures (like user -> address -> country)
+can easily reach 5+ levels.
+
+.. versionadded:: 0.2.6
+"""
+
+MAX_JSON_RECURSION_DEPTH: Final[int] = 1000
+"""Maximum configurable JSON recursion depth.
+
+Values above this threshold increase risk of stack overflow and would
+exceed any reasonable JSON structure depth. Most JSON parsers use
+similar limits (e.g., Python's json module has implicit limits).
+
+.. versionadded:: 0.2.6
+"""
+
+# =============================================================================
+# Valid Sources and Context Paths
+# =============================================================================
+
+VALID_SOURCES: Final[frozenset[str]] = frozenset({"payload", "envelope", "context"})
+"""Valid source names for binding expressions.
+
+Binding expressions must start with one of these sources:
+- ``payload``: Access fields from the event payload
+- ``envelope``: Access fields from the event envelope (correlation_id, etc.)
+- ``context``: Access runtime context values (now_iso, dispatcher_id, etc.)
+"""
+
+VALID_CONTEXT_PATHS: Final[frozenset[str]] = frozenset(
+    {
+        "now_iso",
+        "dispatcher_id",
+        "correlation_id",
+    }
+)
+"""Exhaustive allowlist of valid context paths.
+
+Context paths are special runtime-provided values injected by the
+dispatch infrastructure. Adding new context paths requires:
+
+1. Update this allowlist
+2. Update the dispatch context provider to supply the value
+3. Document the new context path in relevant docstrings
+
+Current paths:
+- ``now_iso``: Current timestamp in ISO 8601 format
+- ``dispatcher_id``: Unique identifier of the dispatcher instance
+- ``correlation_id``: Request correlation ID for distributed tracing
+"""
+
+# =============================================================================
+# Expression Pattern
+# =============================================================================
+
+EXPRESSION_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"^\$\{([a-z]+)\.([a-zA-Z0-9_.]+)\}$"
+)
+"""Compiled regex for parsing binding expressions.
+
+Pattern breakdown:
+- ``^\\$\\{``: Literal ``${`` at start
+- ``([a-z]+)``: Group 1 - source (lowercase letters only)
+- ``\\.``: Literal dot separator
+- ``([a-zA-Z0-9_.]+)``: Group 2 - path (letters, numbers, underscores, dots)
+- ``\\}$``: Literal ``}`` at end
+
+Examples of valid expressions:
+- ``${payload.user.id}`` -> source="payload", path="user.id"
+- ``${envelope.correlation_id}`` -> source="envelope", path="correlation_id"
+- ``${context.now_iso}`` -> source="context", path="now_iso"
+"""
+
+__all__: list[str] = [
+    "DEFAULT_JSON_RECURSION_DEPTH",
+    "EXPRESSION_PATTERN",
+    "MAX_EXPRESSION_LENGTH",
+    "MAX_JSON_RECURSION_DEPTH",
+    "MAX_PATH_SEGMENTS",
+    "MIN_JSON_RECURSION_DEPTH",
+    "VALID_CONTEXT_PATHS",
+    "VALID_SOURCES",
+]

omnibase_infra/models/bindings/model_binding_resolution_result.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Binding resolution result model.
+
+This model represents the outcome of resolving operation bindings, containing
+the resolved parameters and debug information for troubleshooting.
+
+.. versionadded:: 0.2.6
+    Created as part of OMN-1518 - Declarative operation bindings.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelBindingResolutionResult(BaseModel):
+    """Result of binding resolution - execution fact, never mutated.
+
+    Contains resolved parameters plus debug information for troubleshooting.
+    Once created, this is immutable - bindings become execution facts.
+
+    Attributes:
+        operation_name: Operation that was resolved.
+        resolved_parameters: Mapping of parameter name to resolved value.
+        resolved_from: Mapping of parameter name to original expression (debug gold).
+        success: True if all required bindings resolved successfully.
+        error: Error message if success=False.
+
+    Example:
+        >>> result = resolver.resolve(envelope, "db.query")
+        >>> if result:
+        ...     execute_query(result.resolved_parameters)
+        ... else:
+        ...     log_error(result.error)
+
+    .. versionadded:: 0.2.6
+    """
+
+    operation_name: str = Field(
+        ...,
+        description="Operation that was resolved",
+    )
+    resolved_parameters: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Parameter name -> resolved value",
+    )
+    resolved_from: dict[str, str] = Field(
+        default_factory=dict,
+        description="Parameter name -> original expression (debug gold)",
+    )
+    success: bool = Field(
+        ...,
+        description="True if all required bindings resolved successfully",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Error message if success=False",
+    )
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    def __bool__(self) -> bool:
+        """Return True if resolution succeeded.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``success`` is True. This differs from typical
+            Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+            any valid model instance.
+
+            This design enables idiomatic conditional checks for resolution results::
+
+                result = resolver.resolve(envelope, "db.query")
+                if result:
+                    # Resolution succeeded - use parameters
+                    execute_query(result.resolved_parameters)
+                else:
+                    # Resolution failed - handle error
+                    log_error(result.error)
+
+            If you need to check model existence instead, use explicit attribute access::
+
+                # Check for resolution success (uses __bool__)
+                if result:
+                    ...
+
+                # Check model is not None
+                if result is not None:
+                    ...
+
+                # Explicit success check (preferred for clarity)
+                if result.success:
+                    ...
+
+        Returns:
+            True if resolution succeeded, False otherwise.
+
+        .. versionadded:: 0.2.6
+        """
+        return self.success

omnibase_infra/models/bindings/model_operation_binding.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Operation binding model for contract.yaml entries."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelOperationBinding(BaseModel):
+    """Single binding entry from contract.yaml.
+
+    Maps a handler parameter to an expression that extracts data from
+    envelope, payload, or context.
+
+    Example YAML:
+        - parameter_name: "correlation_id"
+          expression: "${envelope.correlation_id}"
+          required: true
+    """
+
+    parameter_name: str = Field(
+        ...,
+        description="Target handler input field name",
+    )
+    expression: str = Field(
+        ...,
+        description="Source expression in ${source.path} format",
+    )
+    required: bool = Field(
+        default=True,
+        description="If True, fail fast when field is missing",
+    )
+    default: JsonType | None = Field(
+        default=None,
+        description="Default value if not required and missing",
+    )
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+
+__all__ = ["ModelOperationBinding"]

omnibase_infra/models/bindings/model_operation_bindings_subcontract.py

@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Operation bindings subcontract model for contract.yaml section.
+
+This model represents the full operation_bindings section from a contract.yaml file,
+containing pre-parsed bindings for all operations plus optional global bindings.
+
+.. versionadded:: 0.2.6
+    Created as part of OMN-1518 - Declarative operation bindings.
+
+.. versionchanged:: 0.2.7
+    Added max_expression_length and max_path_segments for per-contract guardrail overrides.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.models.bindings.constants import (
+    DEFAULT_JSON_RECURSION_DEPTH,
+    MAX_EXPRESSION_LENGTH,
+    MAX_JSON_RECURSION_DEPTH,
+    MAX_PATH_SEGMENTS,
+    MIN_JSON_RECURSION_DEPTH,
+)
+from omnibase_infra.models.bindings.model_parsed_binding import ModelParsedBinding
+
+# =============================================================================
+# Guardrail Bounds Constants
+# =============================================================================
+
+# Expression length bounds
+MIN_EXPRESSION_LENGTH: int = 32
+"""Minimum allowed value for max_expression_length override.
+
+Prevents trivially small expressions that would be unusable for real bindings.
+A minimal valid expression like ${payload.x} is 12 characters.
+"""
+
+MAX_EXPRESSION_LENGTH_LIMIT: int = 1024
+"""Maximum allowed value for max_expression_length override.
+
+Prevents DoS via excessively long expressions that could exhaust memory
+or CPU during regex matching.
+"""
+
+# Path segment bounds
+MIN_PATH_SEGMENTS: int = 3
+"""Minimum allowed value for max_path_segments override.
+
+Need at least source.path.field (3 segments) for useful bindings.
+"""
+
+MAX_PATH_SEGMENTS_LIMIT: int = 50
+"""Maximum allowed value for max_path_segments override.
+
+Prevents absurdly deep paths that could cause stack issues or DoS.
+"""
+
+
+class ModelOperationBindingsSubcontract(BaseModel):
+    """Full operation_bindings section from contract.yaml.
+
+    Contains pre-parsed bindings for all operations, plus optional
+    global bindings applied to every operation.
+
+    Example YAML:
+        operation_bindings:
+          version: { major: 1, minor: 0, patch: 0 }
+          max_expression_length: 512  # Override default (256)
+          max_path_segments: 30       # Override default (20)
+          max_json_recursion_depth: 50  # Override default (100)
+          additional_context_paths:
+            - "request_id"      # Handler needs request ID
+            - "tenant_id"       # Multi-tenant context
+          global_bindings:
+            - parameter_name: "correlation_id"
+              expression: "${envelope.correlation_id}"
+          bindings:
+            "db.query":
+              - parameter_name: "sql"
+                expression: "${payload.sql}"
+              - parameter_name: "tenant"
+                expression: "${context.tenant_id}"
+                required: true
+
+    Attributes:
+        version: Schema version for evolution tracking.
+        additional_context_paths: Additional context paths this handler can resolve
+            beyond the base set (now_iso, dispatcher_id, correlation_id).
+            When declared, the dispatch engine is CONTRACTED to provide these
+            values in the context dict. Pattern: ^[a-z][a-z0-9_]*$
+        bindings: Mapping of operation name to list of parsed bindings.
+        global_bindings: Optional bindings applied to all operations (can be overridden).
+        max_expression_length: Override default expression length limit (32-1024).
+        max_path_segments: Override default path segment limit (3-50).
+        max_json_recursion_depth: Maximum depth for JSON compatibility validation (10-1000).
+            Limits how deeply nested structures are validated to prevent stack overflow.
+
+    .. versionadded:: 0.2.6
+    .. versionchanged:: 0.2.7
+        Added max_expression_length, max_path_segments, and max_json_recursion_depth
+        for per-contract guardrail overrides.
+        Added additional_context_paths for extensible context resolution.
+    """
+
+    version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Schema version for evolution tracking",
+    )
+    additional_context_paths: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Additional context paths this handler can resolve beyond the base set "
+            "(now_iso, dispatcher_id, correlation_id). When declared, the dispatch "
+            "engine is CONTRACTED to provide these values. "
+            "Pattern: ^[a-z][a-z0-9_]*$ (lowercase letters, numbers, underscores)"
+        ),
+    )
+    bindings: dict[str, list[ModelParsedBinding]] = Field(
+        default_factory=dict,
+        description="Operation name -> list of parsed bindings",
+    )
+    global_bindings: list[ModelParsedBinding] | None = Field(
+        default=None,
+        description="Bindings applied to all operations (can be overridden)",
+    )
+    max_expression_length: int = Field(
+        default=MAX_EXPRESSION_LENGTH,
+        ge=MIN_EXPRESSION_LENGTH,
+        le=MAX_EXPRESSION_LENGTH_LIMIT,
+        description="Override default expression length limit (32-1024)",
+    )
+    max_path_segments: int = Field(
+        default=MAX_PATH_SEGMENTS,
+        ge=MIN_PATH_SEGMENTS,
+        le=MAX_PATH_SEGMENTS_LIMIT,
+        description="Override default path segment limit (3-50)",
+    )
+    max_json_recursion_depth: int = Field(
+        default=DEFAULT_JSON_RECURSION_DEPTH,
+        ge=MIN_JSON_RECURSION_DEPTH,
+        le=MAX_JSON_RECURSION_DEPTH,
+        description=(
+            f"Maximum depth for JSON compatibility validation ({MIN_JSON_RECURSION_DEPTH}-"
+            f"{MAX_JSON_RECURSION_DEPTH}). Limits how deeply nested structures are "
+            "validated to prevent stack overflow on pathological inputs."
+        ),
+    )
+
+    model_config = {"frozen": True, "extra": "forbid"}

omnibase_infra/models/bindings/model_parsed_binding.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Parsed binding model with pre-compiled expression components."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelParsedBinding(BaseModel):
+    """Binding with pre-parsed expression for fast resolution.
+
+    The loader parses and validates expressions once at load time.
+    The resolver just executes path traversal without re-parsing.
+
+    Example:
+        Original expression: "${payload.user.id}"
+        Parsed:
+            source: "payload"
+            path_segments: ("user", "id")
+    """
+
+    parameter_name: str = Field(
+        ...,
+        description="Target handler input field name",
+    )
+    source: Literal["payload", "envelope", "context"] = Field(
+        ...,
+        description="Data source for binding resolution",
+    )
+    path_segments: tuple[str, ...] = Field(
+        ...,
+        description="Pre-parsed path segments for traversal",
+    )
+    required: bool = Field(
+        default=True,
+        description="If True, fail fast when field is missing",
+    )
+    default: JsonType | None = Field(
+        default=None,
+        description="Default value if not required and missing",
+    )
+    original_expression: str = Field(
+        ...,
+        description="Original ${source.path} expression for error messages",
+    )
+
+    model_config = {"frozen": True, "extra": "forbid"}

omnibase_infra/models/corpus/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""
+Corpus capture models.
+
+.. versionadded:: 0.5.0
+    Added for CorpusCapture (OMN-1203)
+"""
+
+from omnibase_infra.models.corpus.model_capture_config import ModelCaptureConfig
+from omnibase_infra.models.corpus.model_capture_result import ModelCaptureResult
+
+__all__ = [
+    "ModelCaptureConfig",
+    "ModelCaptureResult",
+]