muscles-data 0.2.2__tar.gz → 0.2.3__tar.gz

{muscles_data-0.2.2 → muscles_data-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muscles-data
-Version: 0.2.2
+Version: 0.2.3
 Summary: Framework-level named data resources and typed ports for Muscles
 Author-email: "Denis B." <denis@butko.info>
 License: MIT

{muscles_data-0.2.2 → muscles_data-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "muscles-data"
-version = "0.2.2"
+version = "0.2.3"
 description = "Framework-level named data resources and typed ports for Muscles"
 readme = "README.md"
 license = {text = "MIT"}

{muscles_data-0.2.2 → muscles_data-0.2.3}/src/muscles/data/__init__.py

@@ -29,7 +29,9 @@ if TYPE_CHECKING:
         DataPolicyPipeline,
         DataPredicate,
         DataPredicateOperator,
+        DataRelatedExists,
     )
+    from .object_lifecycle import ObjectLifecycle, ObjectLifecycleEvent
     from .ports import (
         DocumentStorePort,
         EventConsumerPort,
@@ -78,6 +80,9 @@ __all__ = [
     "SqliteOperationJournal",
     "DataPredicate",
     "DataPredicateOperator",
+    "DataRelatedExists",
+    "ObjectLifecycle",
+    "ObjectLifecycleEvent",
     "DataResourceConfig",
     "DataResourceHandle",
     "DataRuntime",
@@ -155,9 +160,13 @@ def __getattr__(name: str):
         "DataPolicyPipeline",
         "DataPredicate",
         "DataPredicateOperator",
+        "DataRelatedExists",
     }:
         from . import policies
         return getattr(policies, name)
+    if name in {"ObjectLifecycle", "ObjectLifecycleEvent"}:
+        from . import object_lifecycle
+        return getattr(object_lifecycle, name)
     if name == "DataResourceConfig":
         from .models import DataResourceConfig
         return DataResourceConfig

muscles_data-0.2.3/src/muscles/data/object_lifecycle.py

@@ -0,0 +1,41 @@
+"""Transaction-bound notifications for package-owned objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Literal
+
+from .policies import DataOperationContext
+
+
+@dataclass(frozen=True)
+class ObjectLifecycleEvent:
+    action: Literal["created", "deleted"]
+    object_type: str
+    object_uid: str
+    context: DataOperationContext
+
+
+class ObjectLifecycle:
+    """Dispatch handlers synchronously inside the caller's transaction.
+
+    Handlers receive the transaction used for the object write. Exceptions
+    propagate to the caller so that the transaction can be rolled back.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: list[Callable] = []
+
+    def register(self, handler: Callable) -> None:
+        if not callable(handler):
+            raise TypeError("Lifecycle handler must be callable")
+        if handler not in self._handlers:
+            self._handlers.append(handler)
+
+    def emit(self, transaction, event: ObjectLifecycleEvent) -> None:
+        if event.action not in ("created", "deleted"):
+            raise ValueError("Unsupported object lifecycle action")
+        if not event.object_type or not event.object_uid:
+            raise ValueError("Object type and identifier are required")
+        for handler in tuple(self._handlers):
+            handler(transaction, event)

{muscles_data-0.2.2 → muscles_data-0.2.3}/src/muscles/data/policies.py

@@ -36,6 +36,25 @@ class DataPredicateOperator(str, Enum):
     IN = "in"
     LIKE = "like"
     IS_NULL = "is_null"
+    RELATED_EXISTS = "related_exists"
+
+
+@dataclass(frozen=True)
+class DataRelatedExists:
+    """Match a related table row against a field of the target object."""
+
+    table: str
+    related_field: str
+    filters: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.table, str) or not self.table:
+            raise ValueError("Related table name must be a nonempty string")
+        if not isinstance(self.related_field, str) or not self.related_field:
+            raise ValueError("Related field name must be a nonempty string")
+        if not isinstance(self.filters, Mapping) or any(not isinstance(key, str) or not key for key in self.filters):
+            raise ValueError("Related filters must have nonempty string field names")
+        object.__setattr__(self, "filters", MappingProxyType(dict(self.filters)))
 
 
 def like_regex_body(pattern: str) -> str:
@@ -118,6 +137,7 @@ class DataOperationRequest:
     context: DataOperationContext = field(default_factory=DataOperationContext)
     filters: tuple[DataPredicate, ...] = ()
     values: Mapping[str, Any] = field(default_factory=dict)
+    object_type: str | None = None
 
     def __post_init__(self) -> None:
         object.__setattr__(self, "filters", tuple(self.filters))
@@ -131,6 +151,7 @@ class DataPolicyDecision:
     allowed: bool = True
     predicates: tuple[DataPredicate, ...] = ()
     reason: str | None = None
+    replaces_owner_scope: bool = False
 
 
 class DataOperationPolicy(Protocol):
@@ -166,13 +187,20 @@ class DataPolicyPipeline:
         self._policies.append(policy)
 
     def evaluate(self, operation: DataOperationRequest) -> tuple[DataPredicate, ...]:
+        return self.evaluate_decision(operation).predicates
+
+    def evaluate_decision(self, operation: DataOperationRequest) -> DataPolicyDecision:
+        """Combine mandatory predicates and explicit owner-scope authority."""
         predicates: list[DataPredicate] = []
+        replaces_owner_scope = False
         for policy in self._policies:
             decision = policy.evaluate(operation)
             if not isinstance(decision, DataPolicyDecision):
                 raise TypeError("Data policies must return DataPolicyDecision")
             if not isinstance(decision.allowed, bool):
                 raise TypeError("DataPolicyDecision.allowed must be a bool")
+            if not isinstance(decision.replaces_owner_scope, bool):
+                raise TypeError("DataPolicyDecision.replaces_owner_scope must be a bool")
             if not decision.allowed:
                 raise DataPolicyDeniedError(
                     decision.reason or f"Data operation '{operation.kind.value}' was denied"
@@ -181,7 +209,10 @@ class DataPolicyPipeline:
                 if not isinstance(predicate, DataPredicate):
                     raise TypeError("Policy predicates must be DataPredicate instances")
                 predicates.append(predicate)
-        return tuple(predicates)
+            if decision.replaces_owner_scope and not decision.predicates:
+                raise ValueError("Owner scope replacement requires a policy constraint")
+            replaces_owner_scope = replaces_owner_scope or decision.replaces_owner_scope
+        return DataPolicyDecision(predicates=tuple(predicates), replaces_owner_scope=replaces_owner_scope)
 
     def explain(self, operation: DataOperationRequest) -> dict[str, Any]:
         """Summarize effective constraints without exposing predicate values."""

{muscles_data-0.2.2 → muscles_data-0.2.3}/src/muscles/data/policy_search.py

@@ -54,6 +54,8 @@ def _matches(values, predicates):
     if not isinstance(values, Mapping):
         return False
     for item in predicates:
+        if item.operator is DataPredicateOperator.RELATED_EXISTS:
+            raise DataUnsupportedOperationError("Related-record conditions are not supported by search adapters")
         if item.field not in values:
             return False
         actual = values.get(item.field)
@@ -85,17 +87,21 @@ def _matches(values, predicates):
 
 
 class _PolicySearch:
-    def __init__(self, adapter, target: str, *, policies, context=None, max_scan=10000):
+    def __init__(self, adapter, target: str, *, policies, context=None, max_scan=10000, object_type=None):
         if not isinstance(target, str) or not target:
             raise ValueError("target must be a nonempty resource name")
         self.adapter, self.target, self.policies = adapter, target, policies
+        if object_type is not None and (not isinstance(object_type, str) or not object_type):
+            raise ValueError("object_type must be a nonempty string")
+        self.object_type = object_type
         self.context = context or DataOperationContext()
         if type(max_scan) is not int or max_scan <= 0:
             raise ValueError("max_scan must be a positive integer")
         self.max_scan = max_scan
 
     def _evaluate(self, kind, filters=(), values=None):
-        return self.policies.evaluate(DataOperationRequest(kind, self.target, self.context, filters, values or {}))
+        return self.policies.evaluate(DataOperationRequest(kind, self.target, self.context, filters, values or {},
+                                                           object_type=self.object_type))
 
     def _item_values(self, values):
         payload = dict(values.get("payload") or {})

{muscles_data-0.2.2 → muscles_data-0.2.3}/src/muscles/data/runtime.py

@@ -141,14 +141,46 @@ class DataRuntime:
         policies: DataPolicyPipeline | None = None,
         migrations: MigrationRegistry | None = None,
     ) -> None:
+        from .object_lifecycle import ObjectLifecycle
+
         self.config = config
         self.catalog = catalog or DataAdapterCatalog.with_defaults()
         self.policies = policies or DataPolicyPipeline()
+        self.object_lifecycle = ObjectLifecycle()
+        self._object_types: dict[str, str] = {}
+        self._object_owner_fields: dict[str, str] = {}
         self.migrations = migrations if migrations is not None else MigrationRegistry()
         self._handles: dict[str, DataResourceHandle] = {}
         self._lock = threading.RLock()
         self._closed = False
 
+    def register_object_type(self, target: str, object_type: str, *, owner_field: str | None = None) -> None:
+        """Declare a stable object type for a data target."""
+        if not isinstance(target, str) or not target or not isinstance(object_type, str) or not object_type:
+            raise ValueError("Target and object type must be nonempty strings")
+        if owner_field is not None and (not isinstance(owner_field, str) or not owner_field):
+            raise ValueError("Owner field must be a nonempty string")
+        with self._lock:
+            existing = self._object_types.get(target)
+            if existing is not None and existing != object_type:
+                raise ValueError("Data target already has a different object type")
+            existing_owner = self._object_owner_fields.get(target)
+            if owner_field is not None and existing_owner is not None and owner_field != existing_owner:
+                raise ValueError("Data target already has a different owner field")
+            self._object_types[target] = object_type
+            if owner_field is not None:
+                self._object_owner_fields[target] = owner_field
+
+    def object_type_for_target(self, target: str) -> str | None:
+        with self._lock:
+            return self._object_types.get(target)
+
+    def registered_object_types(self) -> tuple[tuple[str, str, str | None], ...]:
+        """Describe declared targets for composition and data migration."""
+        with self._lock:
+            return tuple((target, kind, self._object_owner_fields.get(target))
+                         for target, kind in sorted(self._object_types.items()))
+
     def list_resources(self) -> list[dict[str, Any]]:
         return [
             {

{muscles_data-0.2.2 → muscles_data-0.2.3}/src/muscles_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muscles-data
-Version: 0.2.2
+Version: 0.2.3
 Summary: Framework-level named data resources and typed ports for Muscles
 Author-email: "Denis B." <denis@butko.info>
 License: MIT

{muscles_data-0.2.2 → muscles_data-0.2.3}/src/muscles_data.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/muscles/data/errors.py
 src/muscles/data/migration_identity.py
 src/muscles/data/migrations.py
 src/muscles/data/models.py
+src/muscles/data/object_lifecycle.py
 src/muscles/data/operation_journal.py
 src/muscles/data/package.py
 src/muscles/data/policies.py

{muscles_data-0.2.2 → muscles_data-0.2.3}/tests/test_data_runtime.py

@@ -429,3 +429,17 @@ def test_package_public_exports():
     assert md.StreamPort
     assert md.SqlResourcePort
     assert DataPackage.namespace == "data"
+def test_registered_object_type_is_stable_and_idempotent():
+    from muscles.data.config import DataConfig
+    from muscles.data.runtime import DataRuntime
+    import pytest
+
+    runtime = DataRuntime(config=DataConfig.from_raw({"resources": {}}))
+    runtime.register_object_type("contacts_contacts", "contacts:contact")
+    runtime.register_object_type("contacts_contacts", "contacts:contact")
+    assert runtime.object_type_for_target("contacts_contacts") == "contacts:contact"
+    with pytest.raises(ValueError, match="different object type"):
+        runtime.register_object_type("contacts_contacts", "other:object")
+    assert runtime.object_type_for_target("contacts_contacts") == "contacts:contact"
+    runtime.close()
+

{muscles_data-0.2.2 → muscles_data-0.2.3}/tests/test_policies.py

@@ -61,6 +61,31 @@ def test_pipeline_rejects_invalid_policy_decisions_fail_closed():
             DataPolicyPipeline((Policy(decision),)).evaluate(operation)
 
 
+def test_explicit_ownership_scope_requires_a_constraint_and_preserves_other_policies():
+    class Policy:
+        def __init__(self, decision):
+            self.decision = decision
+        def evaluate(self, operation):
+            return self.decision
+
+    operation = DataOperationRequest(DataOperationKind.READ, "items")
+    constraint = DataPredicate("team", DataPredicateOperator.EQ, "one")
+    pipeline = DataPolicyPipeline((Policy(DataPolicyDecision(predicates=(constraint,), replaces_owner_scope=True)),
+                                   Policy(DataPolicyDecision(predicates=(DataPredicate("active", DataPredicateOperator.EQ, True),)))))
+    decision = pipeline.evaluate_decision(operation)
+    assert decision.replaces_owner_scope is True
+    assert len(decision.predicates) == 2
+    assert pipeline.evaluate(operation) == decision.predicates
+    with pytest.raises(ValueError, match="constraint"):
+        DataPolicyPipeline((Policy(DataPolicyDecision(replaces_owner_scope=True)),)).evaluate_decision(operation)
+    with pytest.raises(TypeError):
+        DataPolicyPipeline((Policy(DataPolicyDecision(replaces_owner_scope="yes", predicates=(constraint,))),)).evaluate_decision(operation)
+    assert not DataPolicyPipeline().evaluate_decision(operation).replaces_owner_scope
+    with pytest.raises(DataPolicyDeniedError):
+        DataPolicyPipeline((Policy(DataPolicyDecision(predicates=(constraint,), replaces_owner_scope=True)),
+                            Policy(DataPolicyDecision(allowed=False)))).evaluate_decision(operation)
+
+
 def test_non_atomic_policy_mode_is_explicit_and_defaults_to_deny():
     from muscles.data.errors import DataUnsupportedOperationError
     from muscles.data.policies import DataNonAtomicPolicyMode

{muscles_data-0.2.2 → muscles_data-0.2.3}/tests/test_policy_search.py

@@ -2,7 +2,7 @@ import pytest
 
 from muscles.data.errors import DataBatchWriteError, DataPolicyDeniedError, DataUnsupportedOperationError, DataWriteConflictError
 from muscles.data.models import SearchHit, VectorHit, WriteResult
-from muscles.data.policies import DataNonAtomicPolicyMode, DataOperationContext, DataPolicyDecision, DataPolicyPipeline, DataPredicate, DataPredicateOperator
+from muscles.data.policies import DataNonAtomicPolicyMode, DataOperationContext, DataPolicyDecision, DataPolicyPipeline, DataPredicate, DataPredicateOperator, DataRelatedExists
 from muscles.data.policy_search import PolicySearchIndex, PolicyVectorSearch
 
 
@@ -43,6 +43,22 @@ def test_search_applies_policy_to_backend_and_rejects_array_results():
     assert backend.calls[0] == ("text", {"$and": [{"kind": "note"}, {"workspace": "a"}]}, 2)
 
 
+def test_scoped_search_passes_object_type_and_rejects_unsupported_related_policy():
+    backend = Backend()
+    seen = []
+    class RelatedPolicy:
+        def evaluate(self, request):
+            seen.append(request.object_type)
+            return DataPolicyDecision(predicates=(DataPredicate("uid", DataPredicateOperator.RELATED_EXISTS,
+                DataRelatedExists("links", "object_uid", {"workspace_uid": "a"})),))
+    store = PolicySearchIndex(backend, "articles", policies=DataPolicyPipeline((RelatedPolicy(),)),
+                              object_type="example:article")
+    with pytest.raises(DataUnsupportedOperationError):
+        store.search_text("hello")
+    assert seen == ["example:article"]
+    assert backend.calls == []
+
+
 def test_policy_search_uses_and_closes_snapshot_after_filling_results():
     class SnapshotBackend(Backend):
         def policy_search_snapshot(self, query, filters, batch_size, options):