krons 0.1.0__py3-none-any.whl

kronos/core/progression.py

@@ -0,0 +1,296 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, overload
+from uuid import UUID
+
+from pydantic import Field, PrivateAttr, field_validator
+
+from kronos.errors import NotFoundError
+from kronos.protocols import Containable, implements
+
+from .element import Element
+
+__all__ = ("Progression",)
+
+
+@implements(Containable)
+class Progression(Element):
+    """Ordered UUID sequence with O(1) membership via auxiliary set.
+
+    Uses list for ordered storage + set for O(1) `in` checks.
+    Allows duplicates in order (set tracks presence, not count).
+
+    Warning:
+        Do NOT mutate `order` directly - use provided methods to keep
+        internal `_members` set synchronized.
+
+    Attributes:
+        name: Optional identifier for this progression.
+        order: Ordered UUID sequence (allows duplicates).
+
+    Example:
+        >>> prog = Progression(name="queue")
+        >>> prog.append(some_element)
+        >>> some_element.id in prog  # O(1)
+        True
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="Optional name for this progression (e.g., 'execution_order')",
+    )
+    order: list[UUID] = Field(
+        default_factory=list,
+        description="Ordered sequence of UUIDs",
+    )
+    # Auxiliary set for O(1) membership checks (not serialized)
+    _members: set[UUID] = PrivateAttr(default_factory=set)
+
+    @field_validator("order", mode="before")
+    @classmethod
+    def _validate_order(cls, value: Any) -> list[UUID]:
+        """Coerce input to list[UUID]. Accepts None, single item, or iterable."""
+        if value is None:
+            return []
+
+        # Normalize single values to list
+        if isinstance(value, (UUID, str, Element)):
+            value = [value]
+        elif not isinstance(value, list):
+            value = list(value)
+
+        # Coerce all items to UUIDs (let coercion errors raise)
+        return [cls._coerce_id(item) for item in value]
+
+    def model_post_init(self, __context: Any) -> None:
+        """Initialize _members set from order."""
+        super().model_post_init(__context)
+        self._members = set(self.order)
+
+    def _rebuild_members(self) -> None:
+        """Rebuild _members from order (after slice assignment)."""
+        self._members = set(self.order)
+
+    # ==================== Core Operations ====================
+
+    def append(self, item_id: UUID | Element) -> None:
+        """Append item to end. O(1)."""
+        uid = self._coerce_id(item_id)
+        self.order.append(uid)
+        self._members.add(uid)
+
+    def insert(self, index: int, item_id: UUID | Element) -> None:
+        """Insert item at index. O(n)."""
+        uid = self._coerce_id(item_id)
+        self.order.insert(index, uid)
+        self._members.add(uid)
+
+    def remove(self, item_id: UUID | Element) -> None:
+        """Remove first occurrence. O(n). Raises ValueError if not found."""
+        uid = self._coerce_id(item_id)
+        self.order.remove(uid)
+        if uid not in self.order:
+            self._members.discard(uid)
+
+    def pop(self, index: int = -1, default: Any = ...) -> UUID | Any:
+        """Remove and return item at index.
+
+        Args:
+            index: Position to pop (default: -1, last item).
+            default: Return value if index invalid (default: raise NotFoundError).
+
+        Returns:
+            UUID at index, or default if provided and index invalid.
+
+        Raises:
+            NotFoundError: If index out of bounds and no default.
+        """
+        try:
+            uid = self.order.pop(index)
+            if uid not in self.order:
+                self._members.discard(uid)
+            return uid
+        except IndexError as e:
+            if default is ...:
+                raise NotFoundError(
+                    f"Index {index} not found in progression of length {len(self)}",
+                    details={"index": index, "length": len(self)},
+                ) from e
+            return default
+
+    def popleft(self) -> UUID:
+        """Remove and return first item. O(n) due to list shift.
+
+        Raises:
+            NotFoundError: If empty. Use deque for frequent popleft.
+        """
+        if not self.order:
+            raise NotFoundError("Cannot pop from empty progression")
+        uid = self.order.pop(0)
+        if uid not in self.order:
+            self._members.discard(uid)
+        return uid
+
+    def clear(self) -> None:
+        """Remove all items."""
+        self.order.clear()
+        self._members.clear()
+
+    def extend(self, items: list[UUID | Element]) -> None:
+        """Append multiple items. O(k) where k = len(items)."""
+        uids = [self._coerce_id(item) for item in items]
+        self.order.extend(uids)
+        self._members.update(uids)
+
+    # ==================== Query Operations ====================
+
+    def __contains__(self, item: UUID | Element) -> bool:
+        """O(1) membership check via auxiliary set."""
+        with contextlib.suppress(Exception):
+            uid = self._coerce_id(item)
+            return uid in self._members
+        return False
+
+    def __len__(self) -> int:
+        return len(self.order)
+
+    def __bool__(self) -> bool:
+        return len(self.order) > 0
+
+    def __iter__(self):
+        return iter(self.order)
+
+    @overload
+    def __getitem__(self, index: int) -> UUID: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[UUID]: ...
+
+    def __getitem__(self, index: int | slice) -> UUID | list[UUID]:
+        return self.order[index]
+
+    def __setitem__(self, index: int | slice, value: UUID | Element | list) -> None:
+        """Set item(s) at index. Slice assignment requires list value."""
+        if isinstance(index, slice):
+            if not isinstance(value, list):
+                raise TypeError(f"Cannot assign {type(value).__name__} to slice, expected list")
+            new_uids = [self._coerce_id(v) for v in value]
+            self.order[index] = new_uids
+            self._rebuild_members()
+        else:
+            old_uid = self.order[index]
+            new_uid = self._coerce_id(value)
+            self.order[index] = new_uid
+            if old_uid not in self.order:
+                self._members.discard(old_uid)
+            self._members.add(new_uid)
+
+    def index(self, item_id: UUID | Element) -> int:
+        """Return first index of item. O(n). Raises ValueError if not found."""
+        uid = self._coerce_id(item_id)
+        return self.order.index(uid)
+
+    def __reversed__(self):
+        return reversed(self.order)
+
+    def __list__(self) -> list[UUID]:
+        return list(self.order)
+
+    def _validate_index(self, index: int, allow_end: bool = False) -> int:
+        """Normalize and validate index (supports negative indexing).
+
+        Args:
+            index: Index to validate.
+            allow_end: If True, allows index == len (for insertion).
+
+        Returns:
+            Normalized non-negative index.
+
+        Raises:
+            NotFoundError: If index out of bounds.
+        """
+        length = len(self.order)
+        if length == 0 and not allow_end:
+            raise NotFoundError("Progression is empty")
+
+        if index < 0:
+            index = length + index
+
+        max_index = length if allow_end else length - 1
+        if index < 0 or index > max_index:
+            raise NotFoundError(
+                f"Index {index} out of range for progression of length {length}",
+                details={"index": index, "length": length, "allow_end": allow_end},
+            )
+
+        return index
+
+    # ==================== Workflow Operations ====================
+
+    def move(self, from_index: int, to_index: int) -> None:
+        """Move item from one position to another. O(n).
+
+        Args:
+            from_index: Source position (supports negative).
+            to_index: Target position (supports negative).
+        """
+        from_index = self._validate_index(from_index)
+        to_index = self._validate_index(to_index, allow_end=True)
+
+        item = self.order.pop(from_index)
+        if from_index < to_index:
+            to_index -= 1
+        self.order.insert(to_index, item)
+
+    def swap(self, index1: int, index2: int) -> None:
+        """Swap items at two positions. O(1).
+
+        Args:
+            index1: First position (supports negative).
+            index2: Second position (supports negative).
+        """
+        index1 = self._validate_index(index1)
+        index2 = self._validate_index(index2)
+
+        self.order[index1], self.order[index2] = self.order[index2], self.order[index1]
+
+    def reverse(self) -> None:
+        """Reverse order in-place. O(n)."""
+        self.order.reverse()
+
+    # ==================== Set-like Operations ====================
+
+    def include(self, item: UUID | Element) -> bool:
+        """Add item if not present (idempotent). O(1) check + O(1) append.
+
+        Returns:
+            True if added, False if already present.
+        """
+        uid = self._coerce_id(item)
+        if uid not in self._members:
+            self.order.append(uid)
+            self._members.add(uid)
+            return True
+        return False
+
+    def exclude(self, item: UUID | Element) -> bool:
+        """Remove item if present (idempotent). O(1) check + O(n) remove.
+
+        Returns:
+            True if removed, False if not present.
+        """
+        uid = self._coerce_id(item)
+        if uid in self._members:
+            self.order.remove(uid)
+            if uid not in self.order:
+                self._members.discard(uid)
+            return True
+        return False
+
+    def __repr__(self) -> str:
+        name_str = f" name='{self.name}'" if self.name else ""
+        return f"Progression(len={len(self)}{name_str})"

kronos/enforcement/__init__.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Enforcement module - Validation and policy protocols.
+
+Provides:
+- Rule: Base validation rule with auto-correction support
+- Validator: Validates data against Spec/Operable using rules
+- RuleRegistry: Maps types to validation rules
+- Policy protocols: Abstract contracts for policy evaluation
+
+Mental model:
+    Rule = validation (is data valid?) - with optional auto-fix
+    Policy = external evaluation protocol (implementations in domain libs)
+
+Usage:
+    from kronos.enforcement import Rule, Validator, RuleRegistry
+
+    # Register rules
+    registry = RuleRegistry()
+    registry.register(str, StringRule(min_length=1))
+
+    # Validate
+    validator = Validator(registry=registry)
+    result = await validator.validate_spec(spec, value)
+"""
+
+from .context import QueryFn, RequestContext
+from .policy import EnforcementLevel, PolicyEngine, PolicyResolver, ResolvedPolicy
+from .registry import RuleRegistry, get_default_registry
+from .rule import Rule, RuleParams, RuleQualifier, ValidationError
+from .service import ActionMeta, KronConfig, KronService, action, get_action_meta
+from .validator import Validator
+
+__all__ = (
+    # Rule system
+    "Rule",
+    "RuleParams",
+    "RuleQualifier",
+    "RuleRegistry",
+    "ValidationError",
+    "Validator",
+    "get_default_registry",
+    # Policy protocols
+    "EnforcementLevel",
+    "PolicyEngine",
+    "PolicyResolver",
+    "ResolvedPolicy",
+    # Service
+    "ActionMeta",
+    "KronConfig",
+    "KronService",
+    "QueryFn",
+    "RequestContext",
+    "action",
+    "get_action_meta",
+)

kronos/enforcement/common/__init__.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Common validation rules for basic types.
+
+Provides built-in rules for:
+- StringRule: String validation with patterns, length constraints
+- NumberRule: Numeric validation with range constraints
+- BooleanRule: Boolean validation with auto-conversion
+- ChoiceRule: Enumerated choice validation
+- MappingRule: Dict/mapping validation
+- BaseModelRule: Pydantic model validation
+- RuleRegistry: Type-to-rule mapping with inheritance
+"""
+
+from ..registry import RuleRegistry, get_default_registry, reset_default_registry
+from .boolean import BooleanRule
+from .choice import ChoiceRule
+from .mapping import MappingRule
+from .model import BaseModelRule
+from .number import NumberRule
+from .string import StringRule
+
+__all__ = (
+    "BaseModelRule",
+    "BooleanRule",
+    "ChoiceRule",
+    "MappingRule",
+    "NumberRule",
+    "RuleRegistry",
+    "StringRule",
+    "get_default_registry",
+    "reset_default_registry",
+)

kronos/enforcement/common/boolean.py

@@ -0,0 +1,85 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from ..rule import Rule, RuleParams, RuleQualifier
+
+__all__ = ("BooleanRule",)
+
+
+def _get_boolean_params() -> RuleParams:
+    """Default params: applies to bool via ANNOTATION qualifier, auto_fix enabled."""
+    return RuleParams(
+        apply_types={bool},
+        apply_fields=set(),
+        default_qualifier=RuleQualifier.ANNOTATION,
+        auto_fix=True,
+        kw={},
+    )
+
+
+class BooleanRule(Rule):
+    """Rule for validating and converting boolean values.
+
+    Features:
+    - Type checking (must be bool)
+    - Auto-conversion from strings ("true", "false", "yes", "no", "1", "0")
+    - Auto-conversion from numbers (0 = False, non-zero = True)
+
+    Usage:
+        rule = BooleanRule()
+        result = await rule.invoke("active", "true", bool)  # → True
+    """
+
+    def __init__(self, params: RuleParams | None = None, **kw):
+        """Initialize boolean rule.
+
+        Args:
+            params: Custom RuleParams (uses default if None)
+            **kw: Additional validation kwargs
+        """
+        if params is None:
+            params = _get_boolean_params()
+        super().__init__(params, **kw)
+
+    async def validate(self, v: Any, t: type, **kw) -> None:
+        """Validate that value is a boolean.
+
+        Raises:
+            ValueError: If not a boolean
+        """
+        if not isinstance(v, bool):
+            raise ValueError(f"Invalid boolean value: expected bool, got {type(v).__name__}")
+
+    async def perform_fix(self, v: Any, _t: type) -> Any:
+        """Attempt to convert value to boolean.
+
+        Conversion rules:
+        - Strings: "true", "yes", "1", "on" → True (case-insensitive)
+        - Strings: "false", "no", "0", "off" → False (case-insensitive)
+        - Numbers: 0 → False, non-zero → True
+        - Other: bool(v)
+
+        Returns:
+            Boolean value
+
+        Raises:
+            ValueError: If conversion fails
+        """
+        try:
+            if isinstance(v, str):
+                v_lower = v.strip().lower()
+                if v_lower in ("true", "yes", "1", "on"):
+                    return True
+                elif v_lower in ("false", "no", "0", "off"):
+                    return False
+                else:
+                    raise ValueError(f"Cannot parse '{v}' as boolean")
+
+            if isinstance(v, (int, float)):
+                return bool(v)
+
+            return bool(v)
+        except Exception as e:
+            raise ValueError(f"Failed to convert {v} to boolean") from e

kronos/enforcement/common/choice.py

@@ -0,0 +1,97 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from ..rule import Rule, RuleParams, RuleQualifier
+
+__all__ = ("ChoiceRule",)
+
+
+class ChoiceRule(Rule):
+    """Rule for validating values against allowed choices.
+
+    Features:
+    - Validates value is in allowed set
+    - Optional case-insensitive matching for strings
+    - Auto-correction to closest match (fuzzy matching)
+
+    Usage:
+        rule = ChoiceRule(
+            choices=["low", "medium", "high"],
+            case_sensitive=False
+        )
+        result = await rule.invoke("priority", "HIGH", str)  # → "high"
+    """
+
+    def __init__(
+        self,
+        choices: set[Any] | list[Any],
+        case_sensitive: bool = True,
+        apply_fields: set[str] | None = None,
+        apply_types: set[type] | None = None,
+        params: RuleParams | None = None,
+        **kw,
+    ):
+        """Initialize choice rule.
+
+        Args:
+            choices: Allowed values
+            case_sensitive: Whether string matching is case-sensitive
+            apply_fields: Field names to apply to
+            apply_types: Types to apply to
+            params: Custom RuleParams (overrides other settings)
+            **kw: Additional validation kwargs
+        """
+        if params is None:
+            params = RuleParams(
+                apply_types=set(apply_types) if apply_types else set(),
+                apply_fields=set(apply_fields) if apply_fields else set(),
+                default_qualifier=(
+                    RuleQualifier.FIELD if apply_fields else RuleQualifier.ANNOTATION
+                ),
+                auto_fix=True,
+                kw={},
+            )
+        super().__init__(params, **kw)
+        self.choices = set(choices) if not isinstance(choices, set) else choices
+        self.case_sensitive = case_sensitive
+
+        if not case_sensitive:
+            self._lower_map = {str(c).lower(): c for c in self.choices if isinstance(c, str)}
+
+    async def validate(self, v: Any, t: type, **kw) -> None:
+        """Validate that value is in allowed choices (exact match only).
+
+        For case-insensitive matching, validation will fail for non-canonical
+        values, triggering perform_fix() to normalize.
+
+        Raises:
+            ValueError: If value not in choices (exact match)
+        """
+        if v in self.choices:
+            return
+
+        raise ValueError(f"Invalid choice: {v} not in {sorted(str(c) for c in self.choices)}")
+
+    async def perform_fix(self, v: Any, _t: type) -> Any:
+        """Attempt to fix value to closest choice.
+
+        For strings with case_sensitive=False, returns canonical case.
+        Otherwise, raises error.
+
+        Returns:
+            Canonical choice value
+
+        Raises:
+            ValueError: If cannot fix
+        """
+        if v in self.choices:
+            return v
+
+        if not self.case_sensitive and isinstance(v, str):
+            v_lower = v.lower()
+            if v_lower in self._lower_map:
+                return self._lower_map[v_lower]
+
+        raise ValueError(f"Cannot fix choice: {v} not in {sorted(str(c) for c in self.choices)}")

kronos/enforcement/common/mapping.py

@@ -0,0 +1,118 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Mapping
+from typing import Any
+
+import orjson
+
+from ..rule import Rule, RuleParams, RuleQualifier
+
+__all__ = ("MappingRule",)
+
+
+def _get_mapping_params() -> RuleParams:
+    """Default params: applies to dict via ANNOTATION qualifier, auto_fix enabled."""
+    return RuleParams(
+        apply_types={dict},
+        apply_fields=set(),
+        default_qualifier=RuleQualifier.ANNOTATION,
+        auto_fix=True,
+        kw={},
+    )
+
+
+class MappingRule(Rule):
+    """Rule for validating and converting mapping/dict values.
+
+    Features:
+    - Type checking (must be dict/Mapping)
+    - Required keys validation
+    - Optional keys validation
+    - Auto-conversion from JSON string
+    - Fuzzy key matching (optional, case-insensitive)
+
+    Usage:
+        rule = MappingRule(
+            required_keys={"name", "value"},
+            optional_keys={"description"},
+            fuzzy_keys=True
+        )
+        result = await rule.invoke("config", '{"Name": "test"}', dict)
+    """
+
+    def __init__(
+        self,
+        required_keys: set[str] | None = None,
+        optional_keys: set[str] | None = None,
+        fuzzy_keys: bool = False,
+        params: RuleParams | None = None,
+        **kw,
+    ):
+        """Initialize mapping rule.
+
+        Args:
+            required_keys: Keys that must be present
+            optional_keys: Keys that may be present (for validation of known keys)
+            fuzzy_keys: Enable case-insensitive key matching
+            params: Custom RuleParams (uses default if None)
+            **kw: Additional validation kwargs
+        """
+        if params is None:
+            params = _get_mapping_params()
+        super().__init__(params, **kw)
+        self.required_keys = required_keys or set()
+        self.optional_keys = optional_keys or set()
+        self.fuzzy_keys = fuzzy_keys
+
+        if fuzzy_keys:
+            all_keys = self.required_keys | self.optional_keys
+            self._key_map = {k.lower(): k for k in all_keys}
+
+    async def validate(self, v: Any, t: type, **kw) -> None:
+        """Validate that value is a mapping with required keys (exact match).
+
+        For fuzzy_keys mode, validation uses exact key matching so that
+        non-canonical keys trigger perform_fix() for normalization.
+
+        Raises:
+            ValueError: If not a mapping or missing required keys
+        """
+        if not isinstance(v, Mapping):
+            raise ValueError(
+                f"Invalid mapping value: expected dict/Mapping, got {type(v).__name__}"
+            )
+
+        if self.required_keys:
+            missing = self.required_keys - set(v.keys())
+            if missing:
+                raise ValueError(f"Missing required keys: {sorted(missing)}")
+
+    async def perform_fix(self, v: Any, t: type) -> Any:
+        """Attempt to convert value to mapping and normalize keys.
+
+        Returns:
+            Dict with normalized keys (if fuzzy_keys enabled)
+
+        Raises:
+            ValueError: If conversion fails
+        """
+        if isinstance(v, str):
+            try:
+                v = orjson.loads(v)
+            except orjson.JSONDecodeError as e:
+                raise ValueError(f"Failed to parse JSON string: {e}") from e
+
+        if not isinstance(v, Mapping):
+            raise ValueError(f"Cannot convert {type(v).__name__} to mapping")
+
+        if self.fuzzy_keys and self._key_map:
+            fixed = {}
+            for k, val in v.items():
+                k_lower = k.lower() if isinstance(k, str) else k
+                fixed[self._key_map.get(k_lower, k)] = val
+            v = fixed
+
+        result = dict(v) if not isinstance(v, dict) else v
+        await self.validate(result, t)
+        return result