policy-pattern 0.1.0__py3-none-any.whl

policy_pattern/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .memory import MemoryTupleStore
+
+__all__ = ["MemoryTupleStore"]

policy_pattern/adapters/memory.py

@@ -0,0 +1,135 @@
+"""
+In-memory TupleStore adapter — demo/test adapter, no throughput requirement.
+"""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from heapq import nsmallest
+from threading import Lock
+from typing import override
+
+from policy_pattern.models import Mutation, ObjectReference, Subject, Tuple
+from policy_pattern.ports import ReadResult, TupleStore, View
+
+
+class MemoryTupleStore(TupleStore):
+    """
+    In-memory `TupleStore` — a plain `set[Tuple]` behind a lock, no index.
+
+    `read_relation()` does a linear scan over a snapshot; no
+    `dict[(object, relation), set[Tuple]]` index is maintained. An index
+    would need to stay in lockstep with `write_tuples()` on every call —
+    real complexity bought for a performance property this adapter is
+    explicitly not required to have (`docs/semantics.md` § Threading calls
+    it a "demo/test adapter with no throughput requirement"). Real
+    throughput is `PostgresTupleStore`'s job, not this one's.
+
+    Example:
+        store = MemoryTupleStore()
+        store.write_tuples(Mutation(additions=frozenset({t}), deletions=frozenset()))
+        with store.snapshot() as view:
+            view.read_tuple(subject, "owner", object)
+    """
+
+    def __init__(self) -> None:
+        """
+        Starts empty.
+        """
+        self._tuples: set[Tuple] = set()
+        self._lock = Lock()
+
+    @override
+    def write_tuples(self, mutation: Mutation) -> None:
+        """
+        Atomically applies additions/deletions under the lock.
+
+        `Mutation.__post_init__` already guarantees `additions`/`deletions`
+        are disjoint — this method does not re-validate that.
+        """
+        with self._lock:
+            self._tuples = (self._tuples - mutation.deletions) | mutation.additions
+
+    @override
+    @contextmanager
+    def snapshot(self) -> Generator[View, None, None]:
+        """
+        Copies the current tuple set under the lock, then yields a view over the copy.
+
+        The copy — not a re-held lock — is what makes the view stable: once
+        the copy exists, nothing that happens to the live set afterward can
+        be observed through the already-open view, because the view never
+        looks at the live set again.
+        """
+        with self._lock:
+            frozen = frozenset(self._tuples)
+        yield _MemoryView(frozen)
+
+
+class _MemoryView(View):
+    """
+    Read-only view over one immutable snapshot of a `MemoryTupleStore`.
+
+    Private: nothing outside `MemoryTupleStore.snapshot()` ever constructs
+    one directly.
+    """
+
+    def __init__(self, tuples: frozenset[Tuple]) -> None:
+        """
+        Wraps an already-copied, immutable tuple set.
+        """
+        self._tuples = tuples
+
+    @property
+    def tuples(self) -> frozenset[Tuple]:
+        """
+        Returns the snapshot's tuples.
+
+        Private: nothing outside `MemoryTupleStore.snapshot()` ever needs
+        to see this.
+        """
+        return self._tuples
+
+    @override
+    def read_tuple(self, subject: Subject, relation: str, object: ObjectReference) -> bool:
+        """
+        Checks exact membership by constructing the equivalent Tuple.
+
+        Reuses `Tuple.__post_init__`'s own validation (delegating `relation`
+        to `Identifier`) instead of duplicating it here.
+        """
+        return Tuple(subject=subject, relation=relation, object=object) in self.tuples
+
+    @override
+    def read_relation(self, object: ObjectReference, relation: str, limit: int) -> ReadResult:
+        """
+        Linearly scans the snapshot for matches, bounded by `limit + 1`.
+
+        Args:
+            object: The `ObjectReference` to match.
+            relation: The relation name to match.
+            limit: The maximum number of matches to return. If more than
+                `limit` matches exist, the result is truncated to exactly
+                `limit` and `complete=False`.
+
+        Matches are ranked by `repr()` before truncating — `frozenset`
+        iteration order is not stable (hash randomization), and an
+        unordered scan would make which tuples survive truncation vary
+        between runs with identical data, breaking
+        docs/architecture.md's determinism guarantee. `heapq.nsmallest`
+        keeps only `limit + 1` candidates in memory at a time, rather than
+        `sorted()`'s full match set — with a huge match set and a small
+        limit, that is the difference between O(limit) and O(match count)
+        memory. `limit=0` needs no special-casing: it is already
+        well-defined (immediately incomplete if any match exists,
+        complete-and-empty otherwise).
+        """
+        candidates: list[Tuple] = nsmallest(
+            limit + 1,
+            (t for t in self.tuples if t.object == object and t.relation == relation),
+            key=repr,
+        )
+
+        if len(candidates) > limit:
+            return ReadResult(tuples=frozenset(candidates[:limit]), complete=False)
+
+        return ReadResult(tuples=frozenset(candidates), complete=True)

policy_pattern/errors/__init__.py

@@ -0,0 +1,19 @@
+from .base_error import BaseError
+from .evaluation_error import EvaluationError
+from .identifier_error import InvalidIdentifierError
+from .model_validation_error import ModelValidationError
+from .mutation_error import InvalidMutationError
+from .relation_error import InvalidRelationError
+from .unknown_name_error import UnknownNameError
+from .unknown_type_error import UnknownTypeError
+
+__all__ = [
+    "BaseError",
+    "EvaluationError",
+    "InvalidIdentifierError",
+    "InvalidMutationError",
+    "InvalidRelationError",
+    "ModelValidationError",
+    "UnknownNameError",
+    "UnknownTypeError",
+]

policy_pattern/errors/base_error.py

@@ -0,0 +1,28 @@
+"""
+Base class for all policy pattern errors.
+To create a standardized error response, inherit from this class and set the `code` attribute to a unique error code.
+"""
+
+from typing import ClassVar
+
+
+class BaseError(Exception):
+    """
+    Custom exception class for policy pattern errors.
+    It provides a standardized error response format with a unique error code, message,
+    and optional related information.
+    """
+
+    code: ClassVar[str]
+
+    def __init__(self, *, message: str, related: str | None = None) -> None:
+        """
+        Initialize the BaseError following the standard error response format in the policy pattern docs errors.md.
+
+        Args:
+            message (str): A description of the error.
+            related (str | None): Additional information about the error, such as the field or type that caused it.
+        """
+        self.message = message
+        self.related = related
+        super().__init__(f"[{self.code}] {message}")

policy_pattern/errors/evaluation_error.py

@@ -0,0 +1,16 @@
+"""
+Set of errors related to Evaluator runtime failures (budget exceeded, cycle detected).
+"""
+
+from .base_error import BaseError
+
+
+class EvaluationError(BaseError):
+    """
+    Error raised when check() cannot complete: a cycle was detected, or a configured
+    EvaluationBudget limit (max_depth, max_nodes, max_store_reads) was exceeded.
+    Attributes:
+        code (ClassVar[str]): A unique error code for the specific error type.
+    """
+
+    code = "PP201"

policy_pattern/errors/identifier_error.py

@@ -0,0 +1,15 @@
+"""
+Set of errors related to Identifier class.
+"""
+
+from .base_error import BaseError
+
+
+class InvalidIdentifierError(BaseError):
+    """
+    Error raised when an invalid identifier is encountered.
+    Attributes:
+        code (ClassVar[str]): A unique error code for the specific error type.
+    """
+
+    code = "PP001"

policy_pattern/errors/model_validation_error.py

@@ -0,0 +1,15 @@
+"""
+Set of errors related to Model validation at compile() time.
+"""
+
+from .base_error import BaseError
+
+
+class ModelValidationError(BaseError):
+    """
+    Error raised when a Model fails compile()-time validation.
+    Attributes:
+        code (ClassVar[str]): A unique error code for the specific error type.
+    """
+
+    code = "PP101"

policy_pattern/errors/mutation_error.py

@@ -0,0 +1,15 @@
+"""
+Set of errors related to Mutation class.
+"""
+
+from .base_error import BaseError
+
+
+class InvalidMutationError(BaseError):
+    """
+    Error raised when an invalid mutation is encountered.
+    Attributes:
+        code (ClassVar[str]): A unique error code for the specific error type.
+    """
+
+    code = "PP003"

policy_pattern/errors/relation_error.py

@@ -0,0 +1,15 @@
+"""
+Set of errors related to Relation class.
+"""
+
+from .base_error import BaseError
+
+
+class InvalidRelationError(BaseError):
+    """
+    Error raised when an invalid relation is encountered.
+    Attributes:
+        code (ClassVar[str]): A unique error code for the specific error type.
+    """
+
+    code = "PP002"

policy_pattern/errors/unknown_name_error.py

@@ -0,0 +1,16 @@
+"""
+Set of errors related to referencing a relation/permission name not declared on a type.
+"""
+
+from .base_error import BaseError
+
+
+class UnknownNameError(BaseError):
+    """
+    Error raised when check() references a name that is declared as neither a relation
+    nor a permission on the object's (already-known) type.
+    Attributes:
+        code (ClassVar[str]): A unique error code for the specific error type.
+    """
+
+    code = "PP203"

policy_pattern/errors/unknown_type_error.py

@@ -0,0 +1,16 @@
+"""
+Set of errors related to referencing a type the CompiledModel does not declare.
+"""
+
+from .base_error import BaseError
+
+
+class UnknownTypeError(BaseError):
+    """
+    Error raised when check() (or internal userset-expansion recursion) references an
+    ObjectReference whose type is not declared in the CompiledModel.
+    Attributes:
+        code (ClassVar[str]): A unique error code for the specific error type.
+    """
+
+    code = "PP202"

policy_pattern/evaluator.py

@@ -0,0 +1,285 @@
+"""
+Evaluator: resolves check() over a CompiledModel and a TupleStore.
+"""
+
+from dataclasses import dataclass, field
+
+from .errors import EvaluationError, UnknownNameError, UnknownTypeError
+from .models import (
+    CompiledModel,
+    DirectSubject,
+    Exclusion,
+    Intersection,
+    ObjectReference,
+    PermissionExpression,
+    Reference,
+    Subject,
+    SubjectSet,
+    TupleToUserset,
+    Union,
+)
+from .ports import TupleStore, View
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluationBudget:
+    """
+    Per-`check()` resource limits.
+
+    No `__post_init__` validation — a degenerate value (e.g. `max_depth=0`)
+    is well-defined without a guard: it simply fails on the first node
+    `Evaluator` visits. Same reasoning already applied to `read_relation`'s
+    `limit=0` — no invariant to enforce, trust the caller.
+
+    Example:
+        EvaluationBudget(max_depth=10, max_nodes=500, max_store_reads=100)
+    """
+
+    # Maximum recursion depth for a single `check()` call. Each recursive call
+    # to `_check_name()` adds one to the depth; exceeding this limit raises an
+    # `EvaluationError`.
+    max_depth: int = 25
+
+    # Maximum number of nodes visited during a single `check()` call. Each
+    # call to `_check_name()` increments this count; exceeding this limit raises an `EvaluationError`.
+    max_nodes: int = 10_000
+
+    # Maximum number of store reads during a single `check()` call. Each call
+    # to `_charge_read()` increments this count; exceeding this limit raises an `EvaluationError`.
+    max_store_reads: int = 1_000
+
+
+@dataclass(slots=True)
+class EvaluationContext:
+    """
+    Live bookkeeping for exactly one `check()` call.
+
+    Deliberately mutable, unlike almost everything else in this package —
+    this is not a domain value, it is the in-flight state of one
+    evaluation, never seen or reused outside that call's lifetime.
+
+    `len(visited)` doubles as the current recursion depth: `visited` only
+    ever holds ancestors currently in progress on the live call path
+    (added before recursing, discarded after returning) — anything
+    permanently resolved lives in `memo` instead, so the two never overlap
+    in meaning.
+    """
+
+    view: View
+    budget: EvaluationBudget
+    visited: set[tuple[ObjectReference, str]] = field(default_factory=lambda: set[tuple[ObjectReference, str]]())
+    memo: dict[tuple[ObjectReference, str], bool] = field(
+        default_factory=lambda: dict[tuple[ObjectReference, str], bool]()
+    )
+    node_count: int = 0
+    store_read_count: int = 0
+
+
+class Evaluator:
+    """
+    Resolves check(subject, name, object) against a CompiledModel and a TupleStore.
+
+    Example:
+        evaluator = Evaluator(model=compiled_model, store=memory_store)
+        evaluator.check(subject, "viewer", document)
+    """
+
+    def __init__(self, model: CompiledModel, store: TupleStore) -> None:
+        """
+        Binds this evaluator to one CompiledModel and one TupleStore.
+        """
+        self._model = model
+        self._store = store
+
+    def check(
+        self,
+        subject: Subject,
+        name: str,
+        object: ObjectReference,
+        budget: EvaluationBudget | None = None,
+    ) -> bool:
+        """
+        Returns whether subject holds relation/permission name on object.
+
+        Opens exactly one store.snapshot() for the lifetime of this call —
+        docs/semantics.md's snapshot-consistency requirement — every read
+        this call triggers, however deep the recursion, goes through the
+        same View.
+
+        `budget` defaults to `None`/`EvaluationBudget()` rather than a
+        bare `EvaluationBudget()` default argument — Python evaluates a
+        default argument once, at function-definition time, so every
+        omitted-budget call would share one instance. Harmless here since
+        `EvaluationBudget` is frozen, but `ruff`'s `B008` flags the pattern
+        regardless of mutability, and the codebase doesn't carve out an
+        exception for "this particular immutable case."
+        """
+        if budget is None:
+            budget = EvaluationBudget()
+        with self._store.snapshot() as view:
+            context = EvaluationContext(view=view, budget=budget)
+            return self._check_name(subject, name, object, context)
+
+    def _check_name(self, subject: Subject, name: str, object: ObjectReference, context: EvaluationContext) -> bool:
+        """
+        Dispatches (object, name) to a relation or permission check, with cycle/memo/budget bookkeeping.
+        """
+        key = (object, name)
+        if key in context.memo:
+            return context.memo[key]
+        if key in context.visited:
+            raise EvaluationError(
+                message=f"cycle detected: {name!r} on {object!r} is already being evaluated for {subject!r}",
+                related=f"object={object!r}",
+            )
+
+        if len(context.visited) >= context.budget.max_depth:
+            raise EvaluationError(
+                message=f"max_depth={context.budget.max_depth!r} exceeded evaluating {name!r} on {object!r}",
+                related=f"object={object!r}",
+            )
+        context.node_count += 1
+        if context.node_count > context.budget.max_nodes:
+            raise EvaluationError(
+                message=f"max_nodes={context.budget.max_nodes!r} exceeded evaluating {name!r} on {object!r}",
+                related=f"object={object!r}",
+            )
+
+        context.visited.add(key)
+        try:
+            try:
+                type_declaration = self._model.types[object.type]
+            except KeyError:
+                raise UnknownTypeError(
+                    message=f"type {object.type!r} is not declared in this CompiledModel",
+                    related=f"object={object!r}",
+                ) from None
+            if name in type_declaration.relations:
+                result = self._check_relation(subject, name, object, context)
+            elif name in type_declaration.permissions:
+                result = self._check_permission(subject, type_declaration.permissions[name], object, context)
+            else:
+                raise UnknownNameError(
+                    message=f"{name!r} is not declared as a relation or permission on {object.type!r}",
+                    related=f"object={object!r}",
+                )
+        finally:
+            context.visited.discard(key)
+
+        context.memo[key] = result
+        return result
+
+    def _check_relation(self, subject: Subject, name: str, object: ObjectReference, context: EvaluationContext) -> bool:
+        """
+        Exact tuple lookup, then bounded userset expansion for any SubjectSet found.
+
+        Every candidate subject's shape is checked against this Relation's
+        own `allowed_subject_types` before it counts — `TupleStore` is
+        schema-agnostic by design (docs/architecture.md), so it never
+        rejects a malformed write; this is the one place that knows both
+        the schema and the stored fact, so it is the actual trust boundary.
+        A tuple whose subject shape isn't declared is inert: never a match,
+        never followed.
+        """
+        relation = self._model.types[object.type].relations[name]
+
+        def shape_allowed(candidate: Subject) -> bool:
+            if isinstance(candidate, DirectSubject):
+                return candidate.object.type in relation.allowed_subject_types
+            return f"{candidate.object.type}#{candidate.relation}" in relation.allowed_subject_types
+
+        self._charge_read(context, object, name)
+        if shape_allowed(subject) and context.view.read_tuple(subject, name, object):
+            return True
+
+        self._charge_read(context, object, name)
+        result = context.view.read_relation(object, name, limit=context.budget.max_nodes - context.node_count)
+        if not result.complete:
+            raise EvaluationError(
+                message=f"enumeration of {name!r} on {object!r} truncated by remaining max_nodes budget",
+                related=f"object={object!r}",
+            )
+
+        return any(
+            isinstance(t.subject, SubjectSet)
+            and shape_allowed(t.subject)
+            and self._check_name(subject, t.subject.relation, t.subject.object, context)
+            for t in sorted(result.tuples, key=repr)
+        )
+
+    def _check_permission(
+        self, subject: Subject, expression: PermissionExpression, object: ObjectReference, context: EvaluationContext
+    ) -> bool:
+        """
+        Recursively evaluates a PermissionExpression tree.
+
+        Union/Intersection may use Python's or/and directly: if the left
+        operand already decides the boolean result, skipping the right one
+        cannot produce an incorrect decision (docs/semantics.md forbids
+        short-circuiting only for Exclusion, where skipping `exclude` could
+        hide a real subtraction). Python's or/and evaluate left-to-right by
+        language specification, satisfying the determinism requirement for
+        free.
+        """
+        if isinstance(expression, Reference):
+            return self._check_name(subject, expression.name, object, context)
+        if isinstance(expression, TupleToUserset):
+            return self._check_tuple_to_userset(subject, expression, object, context)
+        if isinstance(expression, (Union, Intersection)):
+            left = self._check_permission(subject, expression.left, object, context)
+            if isinstance(expression, Union):
+                return left or self._check_permission(subject, expression.right, object, context)
+            return left and self._check_permission(subject, expression.right, object, context)
+        if isinstance(expression, Exclusion):
+            include = self._check_permission(subject, expression.include, object, context)
+            exclude = self._check_permission(subject, expression.exclude, object, context)
+            return include and not exclude
+        raise EvaluationError(
+            message=f"unknown expression type {type(expression).__name__!r}",
+            related=f"object={object!r}",
+        )
+
+    def _check_tuple_to_userset(
+        self, subject: Subject, expression: TupleToUserset, object: ObjectReference, context: EvaluationContext
+    ) -> bool:
+        """
+        Follows expression.tupleset to each related object, then checks expression.computed there.
+
+        Only DirectSubject entries are followed — a SubjectSet stored under
+        the tupleset relation has no single "related object" to jump to, so
+        it does not participate in traversal. A DirectSubject whose type
+        isn't declared in the tupleset Relation's own `allowed_subject_types`
+        is malformed data and is skipped the same way `_check_relation`
+        skips a malformed direct/userset match.
+        """
+        relation = self._model.types[object.type].relations[expression.tupleset]
+
+        self._charge_read(context, object, expression.tupleset)
+        result = context.view.read_relation(
+            object, expression.tupleset, limit=context.budget.max_nodes - context.node_count
+        )
+        if not result.complete:
+            raise EvaluationError(
+                message=f"enumeration of {expression.tupleset!r} on {object!r} truncated by remaining max_nodes budget",
+                related=f"object={object!r}",
+            )
+
+        return any(
+            isinstance(t.subject, DirectSubject)
+            and t.subject.object.type in relation.allowed_subject_types
+            and self._check_name(subject, expression.computed, t.subject.object, context)
+            for t in sorted(result.tuples, key=repr)
+        )
+
+    def _charge_read(self, context: EvaluationContext, object: ObjectReference, name: str) -> None:
+        """
+        Counts one store read, raising EvaluationError if max_store_reads is now exceeded.
+        """
+        context.store_read_count += 1
+        if context.store_read_count > context.budget.max_store_reads:
+            raise EvaluationError(
+                message=(
+                    f"max_store_reads={context.budget.max_store_reads!r} exceeded evaluating {name!r} on {object!r}"
+                ),
+                related=f"object={object!r}",
+            )

policy_pattern/models/__init__.py

@@ -0,0 +1,34 @@
+from .compiled_model import CompiledModel
+from .direct_subject import DirectSubject
+from .identifier import Identifier
+from .model import Model
+from .mutation import Mutation
+from .object_reference import ObjectReference
+from .operators import Exclusion, Intersection, PermissionExpression, Union
+from .reference import Reference
+from .relation import Relation
+from .subject import Subject
+from .subject_set import SubjectSet
+from .tuple import Tuple
+from .tuple_to_userset import TupleToUserset
+from .type import Type
+
+__all__ = [
+    "CompiledModel",
+    "DirectSubject",
+    "Exclusion",
+    "Identifier",
+    "Intersection",
+    "Model",
+    "Mutation",
+    "ObjectReference",
+    "PermissionExpression",
+    "Reference",
+    "Relation",
+    "Subject",
+    "SubjectSet",
+    "Tuple",
+    "TupleToUserset",
+    "Type",
+    "Union",
+]