jvspatial 0.2.3__tar.gz → 0.2.4__tar.gz

{jvspatial-0.2.3/jvspatial.egg-info → jvspatial-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jvspatial
-Version: 0.2.3
+Version: 0.2.4
 Summary: An asynchronous object-spatial Python library for persistence and business logic application layers.
 Author-email: "TrueSelph Inc." <adminh@trueselph.com>
 License: MIT

{jvspatial-0.2.3 → jvspatial-0.2.4}/jvspatial/__init__.py

@@ -87,7 +87,13 @@ from .core.mixins import (
 )
 
 # Simplified database and cache
-from .db import Database, InsertIfAbsentResult, create_database
+from .db import (
+    Database,
+    GraphBindingSummary,
+    InsertIfAbsentResult,
+    LiteralBindingFact,
+    create_database,
+)
 from .db.work_claim import claim_record, delete_claimed_record, release_claim
 
 # Observability primitives
@@ -165,6 +171,8 @@ __all__ = [
     # Database & Cache
     "Database",
     "InsertIfAbsentResult",
+    "GraphBindingSummary",
+    "LiteralBindingFact",
     "create_database",
     "create_cache",
     # Observability

{jvspatial-0.2.3 → jvspatial-0.2.4}/jvspatial/core/entities/object.py

@@ -950,9 +950,16 @@ class Object(AttributeMixin, BaseModel):
         # Get compound indexes from class decorators
         compound_indexes = get_compound_indexes(cls)
         for comp_index in compound_indexes:
-            # Map field names to context.field_name
+            # Identity/discriminator live at the record root, not in context.
             mapped_fields = [
-                (f"context.{field_name}", direction)
+                (
+                    (
+                        field_name
+                        if field_name in {"id", "entity"}
+                        else f"context.{field_name}"
+                    ),
+                    direction,
+                )
                 for field_name, direction in comp_index["fields"]
             ]
             entry: Dict[str, Any] = {

{jvspatial-0.2.3 → jvspatial-0.2.4}/jvspatial/core/entities/walker.py

@@ -30,6 +30,26 @@ from .walker_components.walker_queue import WalkerQueue
 from .walker_components.walker_trail import WalkerTrail
 
 
+def _class_functions(cls: type):
+    """Match function-member discovery without evaluating class descriptors.
+
+    Resolve the MRO on each call so runtime method replacements remain visible.
+    Unlike inspect.getmembers this does not force Pydantic's lazy signature
+    descriptor while looking for event/exit hook metadata.
+    """
+    members = {}
+    for base in cls.__mro__:
+        for name, value in vars(base).items():
+            if name not in members:
+                members[name] = value
+    for name in sorted(members):
+        value = members[name]
+        if isinstance(value, staticmethod):
+            value = value.__func__
+        if inspect.isfunction(value):
+            yield name, value
+
+
 class WalkerVisitingContext:
     """Context manager for visiting a node with a walker."""
 
@@ -133,12 +153,15 @@ class Walker(AttributeMixin, BaseModel):
         protected=True, transient=True, description="Unique identifier for the walker"
     )
 
+    # Python factories avoid repeated builtin-signature parsing by Pydantic
+    # during private-state initialization, especially on Python 3.14. Each
+    # invocation still allocates fresh mutable state.
     # Reporting system
-    _report: List[Any] = attribute(private=True, default_factory=list)
+    _report: List[Any] = attribute(private=True, default_factory=lambda: [])
 
     # Event system
     _event_handlers: Dict[str, List[Callable]] = attribute(
-        private=True, default_factory=dict
+        private=True, default_factory=lambda: {}
     )
 
     # Walker core attributes
@@ -153,7 +176,9 @@ class Walker(AttributeMixin, BaseModel):
     # Trail tracking. Default factory creates an unbounded trail; Walker
     # ``__init__`` rebuilds with ``max_trail_length`` from kwargs/env so
     # SPEC §6.4 ``max_trail_length`` is actually wired (audit §2.3).
-    _trail_tracker: WalkerTrail = attribute(private=True, default_factory=WalkerTrail)
+    _trail_tracker: WalkerTrail = attribute(
+        private=True, default_factory=lambda: WalkerTrail()
+    )
 
     # Trail-related methods (sync for pure computations, async for I/O)
     def get_trail(self) -> List[str]:
@@ -502,7 +527,7 @@ class Walker(AttributeMixin, BaseModel):
 
     def _register_event_handlers(self):
         """Register all @on_emit methods for event handling."""
-        for _name, method in inspect.getmembers(self.__class__, inspect.isfunction):
+        for _name, method in _class_functions(self.__class__):
             if hasattr(method, "_is_event_handler"):
                 event_types = getattr(method, "_event_types", [])
                 for event_type in event_types:
@@ -1033,7 +1058,7 @@ class Walker(AttributeMixin, BaseModel):
 
     async def _execute_exit_hooks(self) -> None:
         """Execute all @on_exit decorated methods."""
-        for _name, method in inspect.getmembers(self.__class__, inspect.isfunction):
+        for _name, method in _class_functions(self.__class__):
             if hasattr(method, "_on_exit") and method._on_exit:
                 try:
                     if asyncio.iscoroutinefunction(method):

{jvspatial-0.2.3 → jvspatial-0.2.4}/jvspatial/db/__init__.py

@@ -22,6 +22,7 @@ from .factory import (
     unregister_database,
     unregister_database_type,
 )
+from .graph_bindings import GraphBindingSummary, LiteralBindingFact
 from .jsondb import JsonDB
 from .manager import DatabaseManager, get_database_manager, set_database_manager
 from .query import escape_regex
@@ -60,6 +61,8 @@ except ImportError:  # pragma: no cover - postgres optional
 
 __all__ = [
     "Database",
+    "GraphBindingSummary",
+    "LiteralBindingFact",
     "DatabaseError",
     "VersionConflictError",
     "InsertIfAbsentResult",

{jvspatial-0.2.3 → jvspatial-0.2.4}/jvspatial/db/_cache.py

@@ -214,6 +214,40 @@ class CachingDatabase(Database):
         # find() is intentionally NOT cached. See module docstring.
         return await self.inner.find(collection, query, limit=limit, sort=sort)
 
+    async def summarize_graph_bindings(self, query, **kwargs):
+        """Forward current graph facts without caching a summary as authority."""
+        reader = getattr(self.inner, "summarize_graph_bindings", None)
+        return await reader(query, **kwargs) if callable(reader) else None
+
+    @property
+    def supports_native_graph_binding_summary(self) -> bool:
+        """Expose the current underlying adapter's optional aggregate support."""
+        return bool(getattr(self.inner, "supports_native_graph_binding_summary", False))
+
+    async def find_projected(
+        self,
+        collection: str,
+        query: Dict[str, Any],
+        *,
+        fields: List[str],
+        limit: Optional[int] = None,
+        sort: Optional[List[Tuple[str, int]]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Forward current projections; never cache incomplete entity records."""
+        reader = getattr(self.inner, "find_projected", None)
+        if callable(reader):
+            return await reader(
+                collection, query, fields=fields, limit=limit, sort=sort
+            )
+        return await Database.find_projected(
+            self.inner, collection, query, fields=fields, limit=limit, sort=sort
+        )
+
+    @property
+    def supports_native_projected_reads(self) -> bool:
+        """Expose native projection support without promising a complete entity."""
+        return bool(getattr(self.inner, "supports_native_projected_reads", False))
+
     async def graph_edge_page(
         self, node_id: str, *, after: Optional[str] = None, limit: int = 50
     ) -> List[Dict[str, Any]]:

jvspatial-0.2.4/jvspatial/db/_graph_binding_postgres.py

@@ -0,0 +1,120 @@
+"""Native one-hop binding summary; policy belongs to the consuming host."""
+
+import json
+from typing import Any, Dict, Optional, Tuple
+
+from jvspatial.db.graph_bindings import GraphBindingSummary, LiteralBindingFact
+
+
+async def summarize(
+    database: Any,
+    query: Dict[str, Any],
+    *,
+    record_entity: str,
+    edge_entity: str,
+    parent_id: str,
+    facts: Tuple[LiteralBindingFact, ...],
+    max_records: int = 100000,
+    max_edges: int = 400000,
+) -> Optional[GraphBindingSummary]:
+    """Aggregate requested storage facts in one bounded PostgreSQL statement."""
+    from jvspatial.db._postgres_translate import translate_query
+    from jvspatial.db.postgres import _SAFE_IDENT_RE, _safe_collection
+
+    if (
+        not all(
+            isinstance(value, str) and value
+            for value in (record_entity, edge_entity, parent_id)
+        )
+        or not isinstance(facts, tuple)
+        or not all(isinstance(fact, LiteralBindingFact) for fact in facts)
+        or any(
+            type(value) is not int or value <= 0 for value in (max_records, max_edges)
+        )
+    ):
+        raise ValueError("Invalid graph binding summary request")
+    translated = translate_query(query)
+    if translated is None:
+        return None
+    where, values = translated
+    params = list(values)
+
+    def bind(value: Any) -> str:
+        params.append(value)
+        return f"${len(params)}"
+
+    record_param, edge_param, parent_param = (
+        bind(record_entity),
+        bind(edge_entity),
+        bind(parent_id),
+    )
+    constraints = [
+        "jsonb_typeof(data->'context')='object'",
+        "data->'id'=to_jsonb(id)",
+        "id<>''",
+        f"data->'entity'=to_jsonb({record_param}::text)",
+    ]
+    for fact in facts:
+        paths = [fact.path] + ([fact.legacy_path] if fact.legacy_path else [])
+        if any(
+            not _SAFE_IDENT_RE.fullmatch(segment)
+            for path in paths
+            for segment in path.split(".")
+        ):
+            return None
+        canonical = "(data#>'{" + ",".join(fact.path.split(".")) + "}')"
+        legacy = (
+            ("(data#>'{" + ",".join(fact.legacy_path.split(".")) + "}')")
+            if fact.legacy_path
+            else None
+        )
+        chosen = f"COALESCE({canonical},{legacy})" if legacy else canonical
+        allowed = bind([json.dumps(value) for value in fact.allowed_values])
+        valid = f"({chosen}=ANY({allowed}::jsonb[]))"
+        if legacy:
+            valid = f"({valid} AND ({canonical} IS NULL OR {legacy} IS NULL OR {canonical}={legacy}))"
+        if not fact.required:
+            missing = (
+                f"({canonical} IS NULL AND {legacy} IS NULL)"
+                if legacy
+                else f"{canonical} IS NULL"
+            )
+            valid = f"({missing} OR {valid})"
+        constraints.append(valid)
+    limit_records, limit_edges = bind(max_records + 1), bind(max_edges + 1)
+    schema = _safe_collection(database.schema_name)
+    await database._bootstrap_collection("node")
+    await database._bootstrap_collection("edge")
+    node_where = f"entity={record_param}" + (f" AND ({where})" if where else "")
+    sql = f"""
+    WITH candidates AS MATERIALIZED (
+      SELECT id, COALESCE({' AND '.join(constraints)},FALSE) AS facts_valid
+      FROM {schema}.node WHERE {node_where} LIMIT {limit_records}
+    ), links AS NOT MATERIALIZED (
+      SELECT (e.data#>>'{{target}}') AS target, e.data->>'source'={parent_param} AS expected,
+        COALESCE(jsonb_typeof(e.data->'source')='string' AND e.data->>'source'<>''
+          AND jsonb_typeof(e.data->'target')='string'
+          AND jsonb_typeof(e.data->'entity')='string'
+          AND e.data->>'entity'={edge_param}, FALSE) AS valid
+      FROM {schema}.edge e JOIN candidates c ON (e.data#>>'{{target}}')=c.id
+      WHERE e.entity={edge_param} LIMIT {limit_edges}
+    ), parents AS (
+      SELECT target, count(*) AS cardinality, bool_and(expected) AS expected,
+        bool_or(NOT valid) AS invalid_edge FROM links GROUP BY target
+    )
+    SELECT count(*) AS matched,
+      count(*) FILTER(WHERE NOT facts_valid) AS invalid_facts,
+      count(*) FILTER(WHERE invalid_edge) AS invalid_edges,
+      count(*) FILTER(WHERE facts_valid AND NOT invalid_edge AND cardinality=1 AND expected) AS bound,
+      COALESCE(sum(cardinality),0) AS edge_count
+    FROM candidates LEFT JOIN parents ON parents.target=candidates.id
+    """
+    async with database._acquire_conn() as connection:
+        row = await connection.fetchrow(sql, *params)
+    return GraphBindingSummary(
+        matched=row["matched"],
+        bound=row["bound"],
+        invalid_facts=row["invalid_facts"],
+        invalid_edges=row["invalid_edges"],
+        complete=(row["matched"] <= max_records and row["edge_count"] <= max_edges),
+    )

{jvspatial-0.2.3 → jvspatial-0.2.4}/jvspatial/db/_observable.py

@@ -309,6 +309,54 @@ class ObservableDatabase(Database):
             result_count_extractor=lambda r: len(r) if isinstance(r, list) else 0,
         )
 
+    async def summarize_graph_bindings(self, query, **kwargs):
+        """Observe one logical graph fact read, preserving upstream recording."""
+        reader = getattr(self.inner, "summarize_graph_bindings", None)
+        if not callable(reader):
+            return None
+        return await self._instrument(
+            "summarize_graph_bindings",
+            "node",
+            lambda: reader(query, **kwargs),
+            result_count_extractor=lambda result: (
+                result.bound if result is not None else 0
+            ),
+        )
+
+    @property
+    def supports_native_graph_binding_summary(self) -> bool:
+        """Expose the current underlying adapter's optional aggregate support."""
+        return bool(getattr(self.inner, "supports_native_graph_binding_summary", False))
+
+    async def find_projected(
+        self,
+        collection: str,
+        query: Dict[str, Any],
+        *,
+        fields: List[str],
+        limit: Optional[int] = None,
+        sort: Optional[List[Tuple[str, int]]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Instrument a projection read without replacing upstream metrics."""
+        reader = getattr(self.inner, "find_projected", None)
+        return await self._instrument(
+            "find_projected",
+            collection,
+            lambda: (
+                reader(collection, query, fields=fields, limit=limit, sort=sort)
+                if callable(reader)
+                else Database.find_projected(
+                    self.inner, collection, query, fields=fields, limit=limit, sort=sort
+                )
+            ),
+            result_count_extractor=lambda rows: len(rows),
+        )
+
+    @property
+    def supports_native_projected_reads(self) -> bool:
+        """Expose native projection support without promising a complete entity."""
+        return bool(getattr(self.inner, "supports_native_projected_reads", False))
+
     async def graph_edge_page(
         self, node_id: str, *, after: Optional[str] = None, limit: int = 50
     ) -> List[Dict[str, Any]]:

{jvspatial-0.2.3 → jvspatial-0.2.4}/jvspatial/db/database.py

@@ -9,12 +9,48 @@ import json
 import logging
 from abc import ABC, abstractmethod
 from contextvars import ContextVar
+from copy import deepcopy
 from dataclasses import dataclass, field
 from functools import partial
 from typing import Any, AsyncIterator, Dict, List, Optional, Tuple, Union
 
+from jvspatial.db.graph_bindings import GraphBindingSummary, LiteralBindingFact
 from jvspatial.db.query import QueryEngine
 
+
+def projection_fields(fields: Any) -> List[str]:
+    """Validate and deduplicate literal dotted JSON paths."""
+    if not isinstance(fields, (list, tuple)) or not fields:
+        raise ValueError("projection fields must be a nonempty list or tuple")
+    if any(
+        not isinstance(path, str)
+        or not path
+        or any(not part for part in path.split("."))
+        for path in fields
+    ):
+        raise ValueError("projection paths must contain nonempty segments")
+    return list(dict.fromkeys(fields))
+
+
+def project_record_fields(record: Dict[str, Any], fields: List[str]) -> Dict[str, Any]:
+    """Return flat path/value pairs, preserving explicit null versus missing."""
+    result = {}
+    for path in fields:
+        value = record
+        for part in path.split("."):
+            if isinstance(value, dict) and part in value:
+                value = value[part]
+            elif (
+                isinstance(value, list) and part.isdecimal() and int(part) < len(value)
+            ):
+                value = value[int(part)]
+            else:
+                break
+        else:
+            result[path] = deepcopy(value) if isinstance(value, (dict, list)) else value
+    return result
+
+
 # ---- cursor encoding -------------------------------------------------------
 
 # Opaque bytes that callers pass back to ``find_iter(cursor=...)`` to
@@ -370,6 +406,16 @@ class Database(ABC):
     supports_transactions: bool = False
     supports_native_graph_paging: bool = False
 
+    @property
+    def supports_native_projected_reads(self) -> bool:
+        """Whether projection is performed natively by the current adapter."""
+        return False
+
+    @property
+    def supports_native_graph_binding_summary(self) -> bool:
+        """Whether the current adapter provides native graph fact summaries."""
+        return False
+
     async def graph_node_batch(self, ids: List[str]) -> Dict[str, Dict[str, Any]]:
         """Fetch raw projection nodes; wrappers bypass stale record caches."""
         return await self.find_many("node", ids)
@@ -592,6 +638,48 @@ class Database(ABC):
         results = await self.find(collection, query)
         return len(results)
 
+    async def summarize_graph_bindings(
+        self,
+        query: Dict[str, Any],
+        *,
+        record_entity: str,
+        edge_entity: str,
+        parent_id: str,
+        facts: Tuple[LiteralBindingFact, ...],
+        max_records: int = 100000,
+        max_edges: int = 400000,
+    ) -> Optional[GraphBindingSummary]:
+        """Optional native fact aggregate; None means use the caller's fallback.
+
+        This does not authorize any read. A consuming host must prove its
+        principal, current scope and rooted parent independently. It must never
+        use an incomplete result as an exact count, or silently discard invalid
+        authority facts. Unsupported adapters retain their established executor.
+        """
+        return None
+
+    async def find_projected(
+        self,
+        collection: str,
+        query: Dict[str, Any],
+        *,
+        fields: List[str],
+        limit: Optional[int] = None,
+        sort: Optional[List[Tuple[str, int]]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Read flat dotted-path projections after complete filtering/ordering.
+
+        Missing paths are omitted; explicit nulls remain. Returned maps are
+        projections, not complete persistence records or hydrated entities.
+        Adapters may push projection down only when filtering and ordering
+        semantics are preserved. The portable fallback projects after find().
+        """
+        names = projection_fields(fields)
+        return [
+            project_record_fields(row, names)
+            for row in await self.find(collection, query, limit=limit, sort=sort)
+        ]
+
     async def find_iter(
         self,
         collection: str,

jvspatial-0.2.4/jvspatial/db/graph_bindings.py

@@ -0,0 +1,70 @@
+"""Read-only one-hop graph binding facts, without application access policy."""
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+
+@dataclass(frozen=True)
+class LiteralBindingFact:
+    """An exact persisted literal with optional conflict-checked legacy storage.
+
+    Missing and JSON null differ. A present value must belong to allowed_values;
+    when both paths exist their JSON values must agree. This is a storage fact,
+    never an access decision or a hydrated-model default.
+    """
+
+    path: str
+    allowed_values: Tuple[str, ...]
+    legacy_path: Optional[str] = None
+    required: bool = True
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous paths and mutable or malformed literal declarations."""
+        if not isinstance(self.path, str) or not self.path:
+            raise ValueError("A canonical fact path is required")
+        for path in (self.path, self.legacy_path):
+            if path is not None and (
+                not isinstance(path, str)
+                or not path
+                or any(not part for part in path.split("."))
+            ):
+                raise ValueError("Fact paths must contain nonempty segments")
+        if (
+            not isinstance(self.allowed_values, tuple)
+            or not self.allowed_values
+            or any(
+                not isinstance(value, str) or not value for value in self.allowed_values
+            )
+        ):
+            raise ValueError(
+                "allowed_values must be a nonempty tuple of nonempty strings"
+            )
+        if type(self.required) is not bool:
+            raise ValueError("required must be a bool")
+
+
+@dataclass(frozen=True)
+class GraphBindingSummary:
+    """Current matching records and unique-parent bindings in one store read.
+
+    Only complete results describe the full matching audience. Invalid facts or
+    edges remain explicit; callers decide whether to fail closed. No principal,
+    tenancy admission, rooted-ancestor proof or permission lease is supplied.
+    """
+
+    matched: int
+    bound: int
+    invalid_facts: int
+    invalid_edges: int
+    complete: bool
+
+    def __post_init__(self) -> None:
+        """Keep count and completeness types literal and cardinalities coherent."""
+        values = (self.matched, self.bound, self.invalid_facts, self.invalid_edges)
+        if any(type(value) is not int or value < 0 for value in values):
+            raise ValueError("Summary counts must be nonnegative integers")
+        if (
+            any(value > self.matched for value in values[1:])
+            or type(self.complete) is not bool
+        ):
+            raise ValueError("Invalid graph binding summary cardinality")