omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/snapshot/model_snapshot.py

@@ -0,0 +1,270 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Generic Snapshot Model for Point-in-Time State Capture.
+
+Provides a generic, immutable snapshot model for capturing point-in-time state
+of any entity. Snapshots support versioning, content hashing for idempotency,
+and lineage tracking via parent references.
+
+Thread Safety:
+    This model is frozen (immutable) for safe sharing across threads.
+    Use with_mutations() to create new snapshots from existing ones.
+
+Related Tickets:
+    - OMN-1246: ServiceSnapshot Infrastructure Primitive
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+from omnibase_infra.models.snapshot.model_subject_ref import ModelSubjectRef
+
+
+class ModelSnapshot(BaseModel):
+    """Generic snapshot for point-in-time state capture.
+
+    Snapshots are immutable captures of entity state at a specific point in time.
+    They support:
+    - Subject-based grouping via ModelSubjectRef
+    - Sequence-based ordering within a subject
+    - Content hashing for idempotency checks
+    - Lineage tracking via parent_id for fork scenarios
+
+    Design Notes:
+        - Frozen (immutable): Create new snapshots via with_mutations()
+        - Sequence numbers: For ordering within a subject, not globally unique
+        - Content hash: Deterministic hash of data for idempotency
+        - Version: For optimistic locking in storage backends
+
+    Attributes:
+        id: Unique identifier for this snapshot.
+        subject: Reference to the subject this snapshot belongs to.
+        data: The actual snapshot payload as JSON-compatible dict.
+        sequence_number: Ordering number within the subject.
+        version: Version for optimistic locking (default: 1).
+        content_hash: SHA-256 hash of data for idempotency checks.
+        created_at: Timestamp when snapshot was created.
+        parent_id: Optional parent snapshot ID for lineage tracking.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> subject = ModelSubjectRef(subject_type="agent", subject_id=uuid4())
+        >>> snapshot = ModelSnapshot(
+        ...     subject=subject,
+        ...     data={"status": "active", "config": {"timeout": 30}},
+        ...     sequence_number=1,
+        ... )
+        >>> snapshot.content_hash is not None
+        True
+
+        >>> # Create a fork with mutations
+        >>> new_snapshot = snapshot.with_mutations(
+        ...     mutations={"status": "paused"},
+        ...     sequence_number=2,
+        ... )
+        >>> new_snapshot.parent_id == snapshot.id
+        True
+        >>> new_snapshot.data["status"]
+        'paused'
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Identity
+    id: UUID = Field(
+        default_factory=uuid4,
+        description="Unique identifier for this snapshot",
+    )
+    subject: ModelSubjectRef = Field(
+        ...,
+        description="Reference to the subject this snapshot belongs to",
+    )
+
+    # Data
+    data: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="The actual snapshot payload as JSON-compatible dict",
+    )
+
+    # Versioning & ordering
+    sequence_number: int = Field(
+        ...,
+        ge=0,
+        description="Ordering number within the subject",
+    )
+    version: int = Field(
+        default=1,
+        ge=1,
+        description="Version for optimistic locking",
+    )
+    content_hash: str | None = Field(
+        default=None,
+        description="SHA-256 hash of data for idempotency checks",
+    )
+
+    # Timestamps
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="Timestamp when snapshot was created",
+    )
+
+    # Lineage
+    parent_id: UUID | None = Field(
+        default=None,
+        description="Parent snapshot ID for lineage/fork tracking",
+    )
+
+    def model_post_init(self, _context: object) -> None:
+        """Compute content hash after initialization if not provided.
+
+        Pydantic's frozen models don't allow attribute assignment after init,
+        so we use object.__setattr__ to set the computed hash.
+        """
+        if self.content_hash is None:
+            computed_hash = self.compute_content_hash(self.data)
+            object.__setattr__(self, "content_hash", computed_hash)
+
+    @classmethod
+    def compute_content_hash(cls, data: dict[str, JsonType]) -> str:
+        """Compute deterministic SHA-256 hash of snapshot data.
+
+        Uses JSON serialization with sorted keys to ensure deterministic
+        output regardless of dict key ordering.
+
+        Args:
+            data: The data dictionary to hash.
+
+        Returns:
+            Hexadecimal SHA-256 hash string.
+
+        Example:
+            >>> hash1 = ModelSnapshot.compute_content_hash({"b": 2, "a": 1})
+            >>> hash2 = ModelSnapshot.compute_content_hash({"a": 1, "b": 2})
+            >>> hash1 == hash2  # Same content, same hash
+            True
+        """
+        # Use sort_keys for deterministic ordering
+        json_bytes = json.dumps(data, sort_keys=True, separators=(",", ":")).encode(
+            "utf-8"
+        )
+        return hashlib.sha256(json_bytes).hexdigest()
+
+    def with_mutations(
+        self,
+        mutations: dict[str, JsonType],
+        sequence_number: int,
+        *,
+        new_id: UUID | None = None,
+        created_at: datetime | None = None,
+    ) -> ModelSnapshot:
+        """Create new snapshot with applied mutations (for fork).
+
+        Creates a new snapshot by merging mutations into the current data.
+        The new snapshot tracks lineage via parent_id pointing to this snapshot.
+
+        Args:
+            mutations: Dictionary of changes to apply to data.
+            sequence_number: Sequence number for the new snapshot.
+            new_id: Optional UUID for new snapshot (auto-generated if None).
+            created_at: Optional creation timestamp (now if None).
+
+        Returns:
+            A new ModelSnapshot with mutations applied and parent_id set.
+
+        Example:
+            >>> from uuid import uuid4
+            >>> subject = ModelSubjectRef(subject_type="config", subject_id=uuid4())
+            >>> original = ModelSnapshot(
+            ...     subject=subject,
+            ...     data={"timeout": 30, "retries": 3},
+            ...     sequence_number=1,
+            ... )
+            >>> updated = original.with_mutations(
+            ...     mutations={"timeout": 60},
+            ...     sequence_number=2,
+            ... )
+            >>> updated.data["timeout"]
+            60
+            >>> updated.data["retries"]  # Unchanged
+            3
+            >>> updated.parent_id == original.id
+            True
+        """
+        # Merge mutations into existing data
+        new_data = {**self.data, **mutations}
+
+        return ModelSnapshot(
+            id=new_id if new_id is not None else uuid4(),
+            subject=self.subject,
+            data=new_data,
+            sequence_number=sequence_number,
+            version=1,  # Reset version for new snapshot
+            content_hash=None,  # Will be computed in model_post_init
+            created_at=created_at if created_at is not None else datetime.now(UTC),
+            parent_id=self.id,  # Track lineage
+        )
+
+    def to_kafka_key(self) -> str:
+        """Generate Kafka compaction key for this snapshot.
+
+        Uses the subject reference key for topic compaction, ensuring
+        only the latest snapshot per subject is retained.
+
+        Returns:
+            Compaction key from subject reference.
+
+        Example:
+            >>> from uuid import UUID
+            >>> subject = ModelSubjectRef(
+            ...     subject_type="agent",
+            ...     subject_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
+            ... )
+            >>> snapshot = ModelSnapshot(subject=subject, data={}, sequence_number=1)
+            >>> snapshot.to_kafka_key()
+            'agent:550e8400-e29b-41d4-a716-446655440000'
+        """
+        return self.subject.to_key()
+
+    def is_content_equal(self, other: ModelSnapshot) -> bool:
+        """Check if two snapshots have identical content.
+
+        Compares content hashes for efficient equality check without
+        deep comparison of data structures.
+
+        Args:
+            other: Another snapshot to compare against.
+
+        Returns:
+            True if both snapshots have non-None content hashes that match,
+            False otherwise (including when either hash is None).
+
+        Note:
+            Returns False when either snapshot has a None content_hash,
+            since we cannot reliably compare content without hashes.
+
+        Example:
+            >>> from uuid import uuid4
+            >>> subject = ModelSubjectRef(subject_type="test", subject_id=uuid4())
+            >>> snap1 = ModelSnapshot(subject=subject, data={"a": 1}, sequence_number=1)
+            >>> snap2 = ModelSnapshot(subject=subject, data={"a": 1}, sequence_number=2)
+            >>> snap1.is_content_equal(snap2)
+            True
+        """
+        # Cannot compare content if either hash is None
+        if self.content_hash is None or other.content_hash is None:
+            return False
+        return self.content_hash == other.content_hash
+
+
+__all__: list[str] = ["ModelSnapshot"]

omnibase_infra/models/snapshot/model_snapshot_diff.py

@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Snapshot Diff Model for Structural Comparison.
+
+Provides a model for representing structural differences between two snapshots.
+This is a structural diff (not semantic) - it identifies which keys were added,
+removed, or changed between two data dictionaries.
+
+Thread Safety:
+    This model is frozen (immutable) for safe sharing across threads.
+
+Related Tickets:
+    - OMN-1246: ServiceSnapshot Infrastructure Primitive
+"""
+
+from __future__ import annotations
+
+from typing import Self
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+from omnibase_infra.models.snapshot.model_field_change import ModelFieldChange
+
+
+class ModelSnapshotDiff(BaseModel):
+    """Structural diff between two snapshots.
+
+    Represents the structural differences between a base snapshot and a target
+    snapshot. This is a shallow diff that operates on top-level keys only -
+    nested changes within a key are captured as a single ModelFieldChange.
+
+    Design Notes:
+        - Shallow comparison: Only top-level keys are compared
+        - Structural, not semantic: No interpretation of what changes mean
+        - Immutable: Diffs are point-in-time calculations
+
+    Attributes:
+        base_id: UUID of the base (original) snapshot.
+        target_id: UUID of the target (new) snapshot.
+        added: List of keys present in target but not in base.
+        removed: List of keys present in base but not in target.
+        changed: Dictionary mapping changed keys to their ModelFieldChange.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> base_data = {"name": "alice", "status": "pending"}
+        >>> target_data = {"name": "alice", "status": "active", "score": 100}
+        >>> diff = ModelSnapshotDiff.compute(
+        ...     base_data=base_data,
+        ...     target_data=target_data,
+        ...     base_id=uuid4(),
+        ...     target_id=uuid4(),
+        ... )
+        >>> diff.added
+        ['score']
+        >>> diff.removed
+        []
+        >>> diff.changed["status"].from_value
+        'pending'
+        >>> diff.changed["status"].to_value
+        'active'
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    base_id: UUID = Field(
+        ...,
+        description="UUID of the base (original) snapshot",
+    )
+    target_id: UUID = Field(
+        ...,
+        description="UUID of the target (new) snapshot",
+    )
+    added: list[str] = Field(
+        default_factory=list,
+        description="Keys present in target but not in base",
+    )
+    removed: list[str] = Field(
+        default_factory=list,
+        description="Keys present in base but not in target",
+    )
+    changed: dict[str, ModelFieldChange] = Field(
+        default_factory=dict,
+        description="Keys with different values, mapped to their changes",
+    )
+
+    @classmethod
+    def compute(
+        cls,
+        base_data: dict[str, JsonType],
+        target_data: dict[str, JsonType],
+        base_id: UUID,
+        target_id: UUID,
+    ) -> Self:
+        """Compute structural diff between two data dictionaries.
+
+        Performs a shallow comparison of top-level keys between base and target
+        data dictionaries, identifying which keys were added, removed, or changed.
+
+        Args:
+            base_data: The base (original) data dictionary.
+            target_data: The target (new) data dictionary.
+            base_id: UUID of the base snapshot.
+            target_id: UUID of the target snapshot.
+
+        Returns:
+            A new ModelSnapshotDiff capturing the structural differences.
+
+        Example:
+            >>> from uuid import uuid4
+            >>> base = {"a": 1, "b": 2, "c": 3}
+            >>> target = {"a": 1, "b": 99, "d": 4}
+            >>> diff = ModelSnapshotDiff.compute(
+            ...     base_data=base,
+            ...     target_data=target,
+            ...     base_id=uuid4(),
+            ...     target_id=uuid4(),
+            ... )
+            >>> sorted(diff.added)
+            ['d']
+            >>> sorted(diff.removed)
+            ['c']
+            >>> diff.changed["b"].from_value
+            2
+            >>> diff.changed["b"].to_value
+            99
+        """
+        base_keys = set(base_data.keys())
+        target_keys = set(target_data.keys())
+
+        # Keys only in target (added)
+        added = sorted(target_keys - base_keys)
+
+        # Keys only in base (removed)
+        removed = sorted(base_keys - target_keys)
+
+        # Keys in both - check for value changes
+        changed: dict[str, ModelFieldChange] = {}
+        common_keys = base_keys & target_keys
+        for key in sorted(common_keys):
+            base_value = base_data[key]
+            target_value = target_data[key]
+            if base_value != target_value:
+                changed[key] = ModelFieldChange(
+                    from_value=base_value,
+                    to_value=target_value,
+                )
+
+        return cls(
+            base_id=base_id,
+            target_id=target_id,
+            added=added,
+            removed=removed,
+            changed=changed,
+        )
+
+    def is_empty(self) -> bool:
+        """Check if the diff contains no changes.
+
+        Returns:
+            True if there are no additions, removals, or changes.
+
+        Example:
+            >>> from uuid import uuid4
+            >>> diff = ModelSnapshotDiff.compute(
+            ...     base_data={"a": 1},
+            ...     target_data={"a": 1},
+            ...     base_id=uuid4(),
+            ...     target_id=uuid4(),
+            ... )
+            >>> diff.is_empty()
+            True
+        """
+        return not self.added and not self.removed and not self.changed
+
+    @property
+    def total_changes(self) -> int:
+        """Count total number of changes (added + removed + changed).
+
+        Returns:
+            Total count of all changes.
+
+        Example:
+            >>> from uuid import uuid4
+            >>> diff = ModelSnapshotDiff.compute(
+            ...     base_data={"a": 1, "b": 2},
+            ...     target_data={"a": 99, "c": 3},
+            ...     base_id=uuid4(),
+            ...     target_id=uuid4(),
+            ... )
+            >>> diff.total_changes  # 1 added (c), 1 removed (b), 1 changed (a)
+            3
+        """
+        return len(self.added) + len(self.removed) + len(self.changed)
+
+
+__all__: list[str] = ["ModelSnapshotDiff"]

omnibase_infra/models/snapshot/model_subject_ref.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Subject Reference Model for Snapshot Grouping.
+
+Provides a reference model for identifying subjects (entities) that snapshots
+belong to. Enables grouping and retrieval of snapshots by subject type and ID.
+
+Thread Safety:
+    This model is frozen (immutable) for safe sharing across threads.
+
+Related Tickets:
+    - OMN-1246: ServiceSnapshot Infrastructure Primitive
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelSubjectRef(BaseModel):
+    """Reference to a subject for snapshot grouping.
+
+    A subject reference identifies the entity that a snapshot belongs to,
+    enabling efficient grouping and retrieval of related snapshots.
+
+    Attributes:
+        subject_type: Type identifier for the subject (e.g., "agent", "workflow", "config").
+        subject_id: Unique identifier for the subject instance.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> ref = ModelSubjectRef(
+        ...     subject_type="agent",
+        ...     subject_id=uuid4(),
+        ... )
+        >>> ref.to_key()
+        'agent:550e8400-e29b-41d4-a716-446655440000'
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    subject_type: str = Field(
+        ...,
+        min_length=1,
+        max_length=128,
+        pattern=r"^[a-z][a-z0-9_]*$",
+        description="Type identifier for the subject (e.g., 'agent', 'workflow', 'config')",
+    )
+    subject_id: UUID = Field(
+        ...,
+        description="Unique identifier for the subject instance",
+    )
+
+    def to_key(self) -> str:
+        """Generate storage key for this subject reference.
+
+        Returns a string key suitable for use in storage systems, caches,
+        or Kafka topic compaction.
+
+        Returns:
+            Key in format "{subject_type}:{subject_id}"
+
+        Example:
+            >>> from uuid import UUID
+            >>> ref = ModelSubjectRef(
+            ...     subject_type="agent",
+            ...     subject_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
+            ... )
+            >>> ref.to_key()
+            'agent:550e8400-e29b-41d4-a716-446655440000'
+        """
+        return f"{self.subject_type}:{self.subject_id!s}"
+
+
+__all__: list[str] = ["ModelSubjectRef"]

omnibase_infra/models/types/__init__.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Shared type aliases for omnibase_infra models.
+
+This module re-exports JSON type aliases from omnibase_core.types and adds
+infrastructure-specific type aliases.
+
+Types from omnibase_core:
+    - JsonPrimitive: Atomic JSON values (str, int, float, bool, None, UUID, datetime)
+    - JsonType: Full recursive JSON type (now fixed via TypeAlias pattern)
+
+Local types:
+    - JsonDict: ``dict[str, object]`` for JSON object operations
+    - JsonValue: ``object`` alias for generic JSON-like data in function signatures
+
+JsonType Recursion Fix (OMN-1274) - Type Selection Guide:
+    The original ``JsonType`` recursive type alias caused Pydantic 2.x recursion
+    errors at class definition time. This has been fixed in omnibase_core v0.6.3+
+    using the TypeAlias pattern. Here is how to choose the right type:
+
+    **Use JsonType** (from ``omnibase_core.types``) when:
+    - The field can be ANY valid JSON value (object, array, string, number, etc.)
+    - Example: HTTP response body, generic JSON payloads
+    - ``from omnibase_core.types import JsonType``
+
+    **Use dict[str, object]** when:
+    - The field is specifically a dictionary with string keys
+    - Example: Error details, database rows, configuration dicts
+    - Provides correct semantics without recursion
+
+    **Use object** when:
+    - In function signatures for generic payloads
+    - NEVER use ``Any`` - per ONEX guidelines, use ``object`` instead
+    - ``def process(data: object) -> object:``
+
+    **Technical Background:**
+    The original ``JsonType`` was defined as::
+
+        JsonType = dict[str, "JsonType"] | list["JsonType"] | str | int | float | bool | None
+
+    Pydantic 2.x performs eager schema generation at class definition time,
+    causing infinite recursion when expanding this type alias. The fix in
+    omnibase_core v0.6.3 uses ``TypeAlias`` to prevent this::
+
+        JsonType: TypeAlias = "dict[str, JsonType] | list[JsonType] | str | ..."
+
+See Also:
+    - ADR: ``docs/decisions/adr-any-type-pydantic-workaround.md`` (historical)
+    - Pydantic issue: https://github.com/pydantic/pydantic/issues/3278
+"""
+
+from omnibase_core.types import JsonPrimitive, JsonType
+
+# JsonDict is a more specific type for functions that work with JSON objects.
+# Use this when you need dict operations like .get(), indexing, or `in` checks.
+# Preferred over JsonType when the value is known to be a dictionary.
+JsonDict = dict[str, object]
+
+# JsonValue is an alias for generic JSON-like data in function signatures.
+# Use this instead of Any per ONEX guidelines - object is the proper "unknown type"
+# marker in Python's type system.
+# For Pydantic model fields requiring full JSON support, use JsonType from
+# omnibase_core.types instead.
+JsonValue = object
+
+__all__ = [
+    "JsonDict",
+    "JsonPrimitive",
+    "JsonType",
+    "JsonValue",
+]