backpack-store 0.1.0__py3-none-any.whl

backpack_store/__init__.py

@@ -0,0 +1,49 @@
+"""Experimental typed local records with explicitly registered codecs."""
+
+from .codecs import Codec, CodecRegistry, DataclassCodec, EncodedValue
+from .errors import (
+    BackpackError,
+    CodecError,
+    DatabaseVersionError,
+    InvalidCursorError,
+    MigrationError,
+    NotFoundError,
+    RegistrationError,
+    RevisionConflictError,
+    StorageError,
+    StoreClosedError,
+    UnknownTypeError,
+    UnknownVersionError,
+    ValidationError,
+)
+from .records import JSONObject, JSONValue, Provenance, RawRecord, Record
+from .store import Backpack, ExportResult, FindPage, WriteResult
+
+__all__ = [
+    "Backpack",
+    "ExportResult",
+    "MigrationError",
+    "FindPage",
+    "WriteResult",
+    "BackpackError",
+    "Codec",
+    "CodecError",
+    "CodecRegistry",
+    "DataclassCodec",
+    "DatabaseVersionError",
+    "EncodedValue",
+    "InvalidCursorError",
+    "JSONObject",
+    "JSONValue",
+    "NotFoundError",
+    "Provenance",
+    "RawRecord",
+    "Record",
+    "RegistrationError",
+    "RevisionConflictError",
+    "StorageError",
+    "StoreClosedError",
+    "UnknownTypeError",
+    "UnknownVersionError",
+    "ValidationError",
+]

backpack_store/codecs.py

@@ -0,0 +1,318 @@
+"""Trusted, explicit codecs; no stored name is ever treated as an import path."""
+
+from __future__ import annotations
+
+import math
+import types
+from collections.abc import Callable
+from dataclasses import dataclass, fields, is_dataclass
+from typing import (
+    Generic,
+    Literal,
+    Protocol,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from .errors import (
+    CodecError,
+    MigrationError,
+    RegistrationError,
+    UnknownTypeError,
+    UnknownVersionError,
+    ValidationError,
+)
+from .records import JSONObject, json_object, positive_integer, validate_type_key
+
+T = TypeVar("T")
+
+
+class Codec(Protocol[T]):
+    type_key: str
+    schema_version: int
+    model_type: type[T]
+
+    def encode(self, value: T) -> JSONObject: ...
+
+    def decode(self, payload: JSONObject) -> T: ...
+
+
+def _model_fields(model_type: type) -> dict[str, object]:
+    hints = get_type_hints(model_type)
+    declared = fields(model_type)
+    if any(not field.init or field.name not in hints for field in declared):
+        raise RegistrationError("dataclass codecs require annotated constructor fields")
+    return {field.name: hints[field.name] for field in declared}
+
+
+def _check_type(annotation: object, stack: tuple[type, ...] = ()) -> None:
+    if annotation in (str, bool, int, float, type(None)):
+        return
+    origin, args = get_origin(annotation), get_args(annotation)
+    if origin is Literal:
+        if not args or any(type(v) not in (str, bool, int, type(None)) for v in args):
+            raise RegistrationError("Literal fields must contain JSON scalar choices")
+        return
+    if origin in (Union, types.UnionType):
+        for arg in args:
+            _check_type(arg, stack)
+        return
+    if origin in (list, tuple) and args:
+        for arg in args:
+            if arg is not Ellipsis:
+                _check_type(arg, stack)
+        return
+    if origin is dict and len(args) == 2 and args[0] is str:
+        _check_type(args[1], stack)
+        return
+    if isinstance(annotation, type) and is_dataclass(annotation):
+        if annotation in stack:
+            raise RegistrationError("recursive dataclasses require a custom codec")
+        for field_type in _model_fields(annotation).values():
+            _check_type(field_type, (*stack, annotation))
+        return
+    raise RegistrationError("dataclass fields must use concrete supported JSON types")
+
+
+def _convert(annotation: object, value: object, *, decode: bool, path: str) -> object:
+    def invalid() -> ValidationError:
+        return ValidationError(f"{path} does not match its declared type")
+
+    if annotation in (str, bool, int, type(None)):
+        if type(value) is not annotation:
+            raise invalid()
+        return value
+    if annotation is float:
+        if type(value) not in (int, float):
+            raise invalid()
+        try:
+            number = float(value)
+        except OverflowError as exc:
+            raise invalid() from exc
+        if not math.isfinite(number):
+            raise invalid()
+        return number
+    origin, args = get_origin(annotation), get_args(annotation)
+    if origin is Literal:
+        if not any(type(value) is type(option) and value == option for option in args):
+            raise invalid()
+        return value
+    if origin in (Union, types.UnionType):
+        for arg in args:
+            try:
+                return _convert(arg, value, decode=decode, path=path)
+            except ValidationError:
+                continue
+        raise invalid()
+    if origin in (list, tuple):
+        expected = list if decode or origin is list else tuple
+        if type(value) is not expected:
+            raise invalid()
+        if origin is tuple and not (len(args) == 2 and args[1] is Ellipsis):
+            if len(value) != len(args):
+                raise invalid()
+            element_types = args
+        else:
+            element_types = (args[0],) * len(value)
+        result = [
+            _convert(t, v, decode=decode, path=f"{path}[{i}]")
+            for i, (t, v) in enumerate(zip(element_types, value, strict=True))
+        ]
+        return tuple(result) if decode and origin is tuple else result
+    if origin is dict:
+        if type(value) is not dict or any(type(k) is not str for k in value):
+            raise invalid()
+        return {
+            key: _convert(args[1], child, decode=decode, path=f"{path}.*")
+            for key, child in value.items()
+        }
+    if isinstance(annotation, type) and is_dataclass(annotation):
+        model_fields = _model_fields(annotation)
+        if decode:
+            if type(value) is not dict or set(value) != set(model_fields):
+                raise invalid()
+            kwargs = {
+                name: _convert(t, value[name], decode=True, path=f"{path}.{name}")
+                for name, t in model_fields.items()
+            }
+            try:
+                return annotation(**kwargs)
+            except Exception as exc:  # noqa: BLE001 - trusted constructors are an explicit codec boundary
+                raise CodecError("dataclass construction failed") from exc
+        if type(value) is not annotation:
+            raise invalid()
+        return {
+            name: _convert(t, getattr(value, name), decode=False, path=f"{path}.{name}")
+            for name, t in model_fields.items()
+        }
+    raise invalid()
+
+
+@dataclass(frozen=True, init=False)
+class DataclassCodec(Generic[T]):
+    """Finite JSON for concrete dataclasses, nested dataclasses and typed containers."""
+
+    model_type: type[T]
+    type_key: str
+    schema_version: int
+
+    def __init__(self, model_type: type[T], *, type_key: str, schema_version: int = 1):
+        if not isinstance(model_type, type) or not is_dataclass(model_type):
+            raise RegistrationError("model_type must be a dataclass class")
+        validate_type_key(type_key)
+        positive_integer(schema_version, "schema_version")
+        try:
+            _check_type(model_type)
+        except (NameError, TypeError) as exc:
+            raise RegistrationError(
+                "dataclass annotations could not be resolved"
+            ) from exc
+        object.__setattr__(self, "model_type", model_type)
+        object.__setattr__(self, "type_key", type_key)
+        object.__setattr__(self, "schema_version", schema_version)
+
+    def encode(self, value: T) -> JSONObject:
+        return json_object(
+            _convert(self.model_type, value, decode=False, path="payload")
+        )
+
+    def decode(self, payload: JSONObject) -> T:
+        return _convert(
+            self.model_type, json_object(payload), decode=True, path="payload"
+        )
+
+
+@dataclass(frozen=True)
+class EncodedValue:
+    type_key: str
+    schema_version: int
+    payload: JSONObject
+
+
+class CodecRegistry:
+    def __init__(self) -> None:
+        self._by_key: dict[str, Codec] = {}
+        self._by_type: dict[type, Codec] = {}
+        self._migrations: dict[tuple[str, int], Callable[[JSONObject], JSONObject]] = {}
+
+    def register(self, codec: Codec[T]) -> None:
+        try:
+            validate_type_key(codec.type_key)
+            positive_integer(codec.schema_version, "schema_version")
+            if (
+                not isinstance(codec.model_type, type)
+                or not callable(codec.encode)
+                or not callable(codec.decode)
+            ):
+                raise RegistrationError(
+                    "codec requires a model class and encode/decode methods"
+                )
+        except (AttributeError, ValidationError) as exc:
+            raise RegistrationError("codec identity is invalid") from exc
+        if codec.type_key in self._by_key or codec.model_type in self._by_type:
+            raise RegistrationError(
+                "codec type key or model type is already registered"
+            )
+        self._by_key[codec.type_key] = codec
+        self._by_type[codec.model_type] = codec
+
+    @property
+    def registered_keys(self) -> tuple[str, ...]:
+        return tuple(sorted(self._by_key))
+
+    def for_key(self, type_key: str) -> Codec:
+        validate_type_key(type_key)
+        try:
+            return self._by_key[type_key]
+        except KeyError as exc:
+            raise UnknownTypeError(
+                "register a trusted codec for the stored type_key"
+            ) from exc
+
+    def for_type(self, model_type: type[T]) -> Codec[T]:
+        try:
+            return self._by_type[model_type]
+        except (KeyError, TypeError) as exc:
+            raise UnknownTypeError(
+                "register a trusted codec for this exact Python type"
+            ) from exc
+
+    def encode(self, value: T) -> EncodedValue:
+        codec = self.for_type(type(value))
+        try:
+            payload = json_object(codec.encode(value))
+        except ValidationError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - custom codec messages may contain record data
+            raise CodecError("registered codec failed to encode the value") from exc
+        return EncodedValue(codec.type_key, codec.schema_version, payload)
+
+    def register_migration(
+        self,
+        type_key: str,
+        *,
+        from_version: int,
+        to_version: int,
+        migrate: Callable[[JSONObject], JSONObject],
+    ) -> None:
+        codec = self.for_key(type_key)
+        try:
+            positive_integer(from_version, "from_version")
+            positive_integer(to_version, "to_version")
+        except ValidationError as exc:
+            raise RegistrationError(
+                "migration versions must be positive integers"
+            ) from exc
+        if (
+            to_version != from_version + 1
+            or to_version > codec.schema_version
+            or not callable(migrate)
+        ):
+            raise RegistrationError(
+                "migration must advance one version toward the registered codec"
+            )
+        key = (type_key, from_version)
+        if key in self._migrations:
+            raise RegistrationError(
+                "migration from this payload version is already registered"
+            )
+        self._migrations[key] = migrate
+
+    def _upgrade(self, type_key: str, version: int, payload: JSONObject) -> JSONObject:
+        codec = self.for_key(type_key)
+        positive_integer(version, "schema_version")
+        if version > codec.schema_version:
+            raise UnknownVersionError(
+                "stored payload is newer than the registered codec"
+            )
+        current = json_object(payload)
+        while version < codec.schema_version:
+            migrate = self._migrations.get((type_key, version))
+            if migrate is None:
+                raise UnknownVersionError(
+                    "register every explicit payload migration to the current version"
+                )
+            try:
+                current = json_object(migrate(current))
+            except Exception:  # noqa: BLE001 - sanitize trusted migration failures and reject invalid JSON
+                raise MigrationError(
+                    "registered payload migration failed validation or execution"
+                ) from None
+            version += 1
+        return current
+
+    def decode(self, type_key: str, schema_version: int, payload: JSONObject) -> object:
+        codec = self.for_key(type_key)
+        payload = self._upgrade(type_key, schema_version, payload)
+        try:
+            value = codec.decode(payload)
+        except (ValidationError, CodecError):
+            raise
+        except Exception as exc:  # noqa: BLE001 - custom codec messages may contain record data
+            raise CodecError("registered codec failed to decode the payload") from exc
+        if type(value) is not codec.model_type:
+            raise CodecError("registered codec returned a different Python type")
+        return value

backpack_store/errors.py

@@ -0,0 +1,53 @@
+"""Actionable errors that do not include record payloads or configured secrets."""
+
+
+class BackpackError(Exception):
+    """Base error for storage, registration and record validation."""
+
+
+class ValidationError(BackpackError, ValueError):
+    """A value does not satisfy the explicit record or codec contract."""
+
+
+class RegistrationError(BackpackError):
+    """A codec conflicts with an existing registration or is invalid."""
+
+
+class UnknownTypeError(BackpackError):
+    """No trusted codec is registered for a Python type or stable key."""
+
+
+class UnknownVersionError(BackpackError):
+    """The registered codec cannot decode this payload schema version."""
+
+
+class CodecError(BackpackError):
+    """A trusted custom codec failed to encode or decode a value."""
+
+
+class NotFoundError(BackpackError):
+    """The requested local record does not exist."""
+
+
+class RevisionConflictError(BackpackError):
+    """The record changed after the caller's expected revision."""
+
+
+class StorageError(BackpackError):
+    """A database operation failed or stored data is malformed."""
+
+
+class StoreClosedError(StorageError):
+    """The owned database connection has already been closed."""
+
+
+class DatabaseVersionError(StorageError):
+    """This database schema version is not supported."""
+
+
+class InvalidCursorError(ValidationError):
+    """A find cursor is malformed or belongs to a different query."""
+
+
+class MigrationError(CodecError):
+    """An explicitly registered payload migration failed."""

backpack_store/host.py

@@ -0,0 +1,45 @@
+"""Local application binding; no default path, database discovery or model imports."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from .store import Backpack
+
+if TYPE_CHECKING:
+    from hidden_moves.adapters import CapabilityCatalog
+
+
+def build_catalog(
+    store: Backpack, names: Iterable[str], *, allow_writes: bool = False
+) -> CapabilityCatalog:
+    """Select operations on a configured store; writes require separate host intent."""
+    from hidden_moves import Moves, discover_providers, load_provider
+    from hidden_moves.adapters import CapabilityCatalog
+
+    from .integration import WRITE_CAPABILITIES
+
+    names = tuple(names)
+    if not names:
+        raise ValueError("Select at least one Backpack capability.")
+    if not allow_writes and any(name in WRITE_CAPABILITIES for name in names):
+        raise ValueError(
+            "Select the local write profile explicitly with allow_writes=True."
+        )
+    entries = [entry for entry in discover_providers() if entry.name == "backpack"]
+    if len(entries) != 1:
+        raise ValueError("Install exactly one Backpack provider.")
+    moves = Moves(target=store)
+    load_provider(entries[0], moves.registry)
+    return CapabilityCatalog(moves, names)
+
+
+async def serve_store(
+    store: Backpack, names: Iterable[str], *, allow_writes: bool = False
+) -> None:
+    """Serve selected tools over stdio; the calling application owns cleanup."""
+    from hidden_moves_mcp import MCPAdapter, serve_stdio
+
+    catalog = build_catalog(store, names, allow_writes=allow_writes)
+    await serve_stdio(MCPAdapter(catalog).server("backpack"))

backpack_store/integration.py

@@ -0,0 +1,122 @@
+"""Optional selected tools around an explicitly configured local store."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from hidden_moves import MoveAnnotations, MoveSpec
+
+from .errors import BackpackError, CodecError
+from .records import Provenance, Record, json_object
+from .store import Backpack, WriteResult
+
+READ_CAPABILITIES = ("backpack.records.get", "backpack.records.find")
+WRITE_CAPABILITIES = ("backpack.records.put", "backpack.records.delete")
+
+
+@dataclass(frozen=True)
+class RecordView:
+    id: str
+    type_key: str
+    schema_version: int
+    revision: int
+    payload: dict[str, Any]
+    created_at: str
+    updated_at: str
+    tags: list[str]
+    provenance: Provenance | None
+
+
+@dataclass(frozen=True)
+class RecordPage:
+    records: list[RecordView]
+    next_cursor: str | None
+
+
+def _view(record: Record) -> RecordView:
+    return RecordView(
+        record.id,
+        record.type_key,
+        record.schema_version,
+        record.revision,
+        record.payload,
+        record.created_at,
+        record.updated_at,
+        list(record.tags),
+        record.provenance,
+    )
+
+
+def get_record(store: Backpack, record_id: str) -> RecordView:
+    """Read a local record through its explicitly registered codec."""
+    return _view(store.get_record(record_id))
+
+
+def find_records(
+    store: Backpack,
+    type_key: str,
+    tags: list[str] | None = None,
+    limit: int = 50,
+    cursor: str | None = None,
+) -> RecordPage:
+    """Read a bounded page for one registered type and all requested exact tags."""
+    codec = store.codec_for_key(type_key)
+    page = store.find(
+        codec.model_type, tags=() if tags is None else tags, limit=limit, cursor=cursor
+    )
+    return RecordPage([_view(record) for record in page.records], page.next_cursor)
+
+
+def put_record(
+    store: Backpack,
+    type_key: str,
+    payload: dict[str, Any],
+    tags: list[str] | None = None,
+    provenance: Provenance | None = None,
+) -> WriteResult:
+    """Insert a new local UUID after validating the current registered payload type."""
+    codec = store.codec_for_key(type_key)
+    try:
+        value = codec.decode(json_object(payload))
+    except BackpackError:
+        raise
+    except Exception:  # noqa: BLE001 - trusted custom codec failures must not expose payloads
+        raise CodecError(
+            "registered codec failed to decode the supplied payload"
+        ) from None
+    if type(value) is not codec.model_type:
+        raise CodecError("registered codec returned a different Python type")
+    return store.put(value, tags=() if tags is None else tags, provenance=provenance)
+
+
+def delete_record(store: Backpack, record_id: str) -> bool:
+    """Delete one explicit local UUID, reporting whether it existed."""
+    return store.delete(record_id)
+
+
+def provide_moves() -> tuple[MoveSpec, ...]:
+    """Advertise definitions without opening a database or choosing codecs."""
+    read = MoveAnnotations(
+        read_only=True, destructive=False, idempotent=True, external=False
+    )
+    insert = MoveAnnotations(
+        read_only=False, destructive=False, idempotent=False, external=False
+    )
+    delete = MoveAnnotations(
+        read_only=False, destructive=True, idempotent=True, external=False
+    )
+    return tuple(
+        MoveSpec(
+            name=name,
+            namespace="backpack.records",
+            func=operation,
+            bind_target=True,
+            target_types=(Backpack,),
+            annotations=annotations,
+        )
+        for name, operation, annotations in (
+            ("get", get_record, read),
+            ("find", find_records, read),
+            ("put", put_record, insert),
+            ("delete", delete_record, delete),
+        )
+    )

backpack_store/pydantic_codec.py

@@ -0,0 +1,87 @@
+"""Optional Pydantic 2 codec; the core package never imports this extension."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+try:
+    from pydantic import BaseModel
+    from pydantic import ValidationError as PydanticValidationError
+    from pydantic import __version__ as pydantic_version
+except ImportError:
+    raise ImportError(
+        "Install backpack-store with its [pydantic] extra to use this codec."
+    ) from None
+
+from .errors import CodecError, RegistrationError, ValidationError
+from .records import JSONObject, json_object, positive_integer, validate_type_key
+
+if not pydantic_version.startswith("2."):
+    raise ImportError("The Backpack Pydantic codec supports Pydantic 2 only.")
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@dataclass(frozen=True, init=False)
+class PydanticCodec(Generic[T]):
+    """Strict JSON validation for one explicitly registered object-shaped model."""
+
+    model_type: type[T]
+    type_key: str
+    schema_version: int
+
+    def __init__(self, model_type: type[T], *, type_key: str, schema_version: int = 1):
+        if (
+            not isinstance(model_type, type)
+            or not issubclass(model_type, BaseModel)
+            or model_type is BaseModel
+            or model_type.__pydantic_root_model__
+        ):
+            raise RegistrationError(
+                "model_type must be a concrete object-shaped Pydantic 2 model"
+            )
+        validate_type_key(type_key)
+        positive_integer(schema_version, "schema_version")
+        object.__setattr__(self, "model_type", model_type)
+        object.__setattr__(self, "type_key", type_key)
+        object.__setattr__(self, "schema_version", schema_version)
+
+    def encode(self, value: T) -> JSONObject:
+        if type(value) is not self.model_type:
+            raise ValidationError(
+                "value must have the exact registered Pydantic model type"
+            )
+        try:
+            payload = json_object(
+                value.model_dump(
+                    mode="json", round_trip=True, by_alias=True, warnings="error"
+                )
+            )
+        except ValidationError:
+            raise
+        except Exception:  # noqa: BLE001 - serializers may include private model values in errors
+            raise CodecError(
+                "registered Pydantic model could not produce a JSON object"
+            ) from None
+        # Revalidate serialized data even when model_construct/mutation bypassed model validation.
+        self.decode(payload)
+        return payload
+
+    def decode(self, payload: JSONObject) -> T:
+        payload = json_object(payload)
+        try:
+            return self.model_type.model_validate_json(
+                json.dumps(payload, ensure_ascii=False, allow_nan=False),
+                strict=True,
+                extra="forbid",
+            )
+        except PydanticValidationError:
+            raise ValidationError(
+                "payload does not satisfy the registered Pydantic model"
+            ) from None
+        except Exception:  # noqa: BLE001 - trusted validators must not expose payloads in errors
+            raise CodecError(
+                "registered Pydantic model failed to validate the JSON payload"
+            ) from None