pi-durable-python 1.3.0__py3-none-any.whl

pi_durable/harness/view.py

@@ -0,0 +1,324 @@
+"""Conversation view mount: the active transcript and the built-in documents (spec §9.3).
+
+The Harness keeps at most one mount per conversation. Its first observer builds the revision on
+the Session line from committed state, and the mount advances from the Session's commit
+publications, so every delivered frame is already durable. Document operations keep their exact
+shape under the mount path; entries keep the raw active-transcript shape of ``ContextView``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import partial
+from typing import Any, TypedDict, cast
+
+from ..context import Context, without_abort_signal
+from ..delta import Op, apply_immutable
+from ..ids import ConversationId, DocumentId
+from ..json import JsonObject
+from ..session.observation import CommittedState, CommittedWatch
+from ..session.session import SessionImpl, contained
+from ..types import (
+    CommitPublication,
+    ConversationRecord,
+    EntryRecord,
+    Storage,
+)
+from .agent import AgentDoc
+from .context import capture_context_bounds, derive_context
+from .inbox import InboxDoc
+from .live import LiveDoc
+from .provider import ProviderDoc
+from .usage import UsageDoc
+from .util import cancellation_error, closed_error
+
+
+class ConversationView(TypedDict):
+    """Structural mount of one conversation's active transcript and built-in documents.
+
+    ``conversation`` is the immutable record; ``entries`` is the head marker followed by the
+    non-head entries from its head; ``docs`` holds ``pi.agent``, ``pi.live``, ``pi.inbox``,
+    ``pi.provider``, and ``pi.usage`` keyed by kind, with absent documents absent.
+    """
+
+    conversation: ConversationRecord
+    entries: list[EntryRecord]
+    docs: dict[str, JsonObject]
+
+
+MOUNTED: tuple[Any, ...] = (
+    AgentDoc,
+    LiveDoc,
+    InboxDoc,
+    ProviderDoc,
+    UsageDoc,
+)
+"""The built-in conversation documents every view mounts."""
+
+MOUNTED_KINDS = frozenset(token.definition.kind for token in MOUNTED)
+
+
+@dataclass(slots=True)
+class Mount:
+    """One conversation's current revision, mounted incarnations, and observers."""
+
+    value: ConversationView
+    docs: dict[str, tuple[DocumentId, int]]
+    observers: set[Any] = field(default_factory=set)
+
+
+class ConversationViews:
+    """The Harness's conversation view mounts, one per conversation while observed."""
+
+    def __init__(self, session: SessionImpl, storage: Storage) -> None:
+        self._session = session
+        self._storage = storage
+        self._mounts: dict[ConversationId, Mount] = {}
+        self._closed = False
+        session.observe_commits(self._on_publication)
+        session.subscribe_close(self._on_close)
+
+    def report(self, error: BaseException) -> None:
+        self._session.report(error)
+
+    async def state(self, id: ConversationId, context: Context) -> CommittedState:
+        """A disposable read-only state of the view."""
+
+        return await self.attach(id, _state_observer, context)
+
+    async def watch(self, id: ConversationId, context: Context) -> CommittedWatch:
+        """A serialized exact-frame watch of the view; cancelling ``context`` stops it."""
+
+        observer = await self.attach(id, _watch_observer, context)
+        signal = context.abort_signal
+        if signal is not None and signal.aborted:
+            observer.cancel()
+            raise cancellation_error(signal)
+        if signal is not None:
+            observer.observe_cancellation(signal)
+        return observer
+
+    async def attach(
+        self,
+        id: ConversationId,
+        create: Callable[
+            [ConversationView, Callable[[], None], Storage, ConversationViews],
+            Any,
+        ],
+        context: Context,
+    ) -> Any:
+        """Register an observer created from the current revision, atomically on the Session line."""
+
+        async def job() -> Any:
+            self._session.assert_usable()
+            mount = self._mounts.get(id)
+            if mount is None:
+                mount = await self._build(id, context)
+            detached = False
+
+            def detach() -> None:
+                nonlocal detached
+                if detached:
+                    return
+                detached = True
+                mount.observers.discard(observer)
+                if not mount.observers and self._mounts.get(id) is mount:
+                    del self._mounts[id]
+
+            observer = create(mount.value, detach, self._storage, self)
+            if asyncio.iscoroutine(observer):
+                observer = await observer
+            # Close or cancellation may begin while the mount hydrates; register nothing then.
+            if self._closed:
+                raise closed_error(self._session)
+            self._session.assert_usable()
+            signal = context.abort_signal
+            if signal is not None and signal.aborted:
+                raise cancellation_error(signal)
+            self._mounts[id] = mount
+            mount.observers.add(observer)
+            return observer
+
+        return await self._session.read_on_line(job)
+
+    async def _build(self, id: ConversationId, context: Context) -> Mount:
+        conversation = await self._storage.conversation(id, context)
+        if conversation is None:
+            raise RuntimeError(f"Conversation {id} does not exist")
+        bounds = await capture_context_bounds(self._storage, id, context)
+        derived = await derive_context(self._storage, id, bounds, context)
+        entries = list(derived["entries"])
+        docs: dict[str, JsonObject] = {}
+        incarnations: dict[str, tuple[DocumentId, int]] = {}
+        for token in MOUNTED:
+            loaded = await self._session._document_on_line(token, id, context)
+            if loaded is None:
+                continue
+            kind = token.definition.kind
+            docs[kind] = loaded.value
+            incarnations[kind] = (loaded.record["id"], loaded.value_version)
+        value: ConversationView = {
+            "conversation": conversation,
+            "entries": entries,
+            "docs": docs,
+        }
+        return Mount(value=value, docs=incarnations)
+
+    def _on_publication(self, publication: CommitPublication, context: Context) -> None:
+        for id, mount in list(self._mounts.items()):
+            advance_mount(id, mount, publication, context, self.report)
+
+    def _on_close(self) -> None:
+        self._closed = True
+        failure = self._session.failure
+        for mount in list(self._mounts.values()):
+            for observer in list(mount.observers):
+                contained(partial(observer.close_session, failure), self.report)
+        self._mounts.clear()
+
+
+def _state_observer(
+    value: ConversationView,
+    release: Callable[[], None],
+    _storage: Storage,
+    views: ConversationViews,
+) -> CommittedState:
+    return CommittedState(value, release, views.report)
+
+
+def _watch_observer(
+    value: ConversationView,
+    release: Callable[[], None],
+    _storage: Storage,
+    views: ConversationViews,
+) -> CommittedWatch:
+    return CommittedWatch(value, release, views.report)
+
+
+def advance_mount(
+    id: ConversationId,
+    mount: Mount,
+    publication: CommitPublication,
+    context: Context,
+    report: Callable[[BaseException], None],
+) -> None:
+    """Derive the mount's operations from one publication, apply them, and publish the revision."""
+
+    doc_ops: list[Op] = []
+    entry_ops: list[Op] = []
+    entries: list[EntryRecord] = mount.value["entries"]
+    docs = mount.value["docs"]
+    # Entry writes are published in ID order.
+    for change in publication["changes"]:
+        if change["type"] == "entry" and change["value"]["conversationId"] == id:
+            entry = change["value"]
+            target = entry.get("head")
+            if target is None:
+                entry_ops.append(["p", ["entries"], len(entries), 0, [entry]])
+                entries = [*entries, entry]
+                continue
+            # A head marker keeps the non-head entries from its head, always a suffix, and goes in front.
+            kept = next(
+                (
+                    index
+                    for index, candidate in enumerate(entries)
+                    if "head" not in candidate and candidate["id"] >= target
+                ),
+                len(entries),
+            )
+            entry_ops.append(["p", ["entries"], 0, kept, [entry]])
+            entries = [entry, *entries[kept:]]
+            continue
+        if change["type"] != "document" or change["conversationId"] != id:
+            continue
+        kind = change["record"]["kind"]
+        if kind not in MOUNTED_KINDS or "key" in change["record"]:
+            continue
+        path = ["docs", kind]
+        mounted = mount.docs.get(kind)
+        if change["value"] is None:
+            if mounted is None or mounted[0] != change["record"]["id"]:
+                continue
+            del mount.docs[kind]
+            docs = {current: value for current, value in docs.items() if current != kind}
+            doc_ops.append(["d", path])
+        elif (
+            mounted is not None
+            and mounted[0] == change["record"]["id"]
+            and mounted[1] == change["version"]
+        ):
+            current = docs[kind]
+            docs = {
+                **docs,
+                kind: cast(JsonObject, apply_immutable(current, change["ops"])),
+            }
+            doc_ops.extend(_prefixed(op, path) for op in change["ops"])
+        else:
+            if change["value"] is None or change["version"] is None:
+                continue
+            mount.docs[kind] = (change["record"]["id"], change["version"])
+            docs = {**docs, kind: change["value"]}
+            doc_ops.append(["s", path, change["value"]])
+
+    ops = [*doc_ops, *entry_ops]
+    before = mount.value
+    after = before
+    frame_context = without_abort_signal(context)
+    if ops:
+        value: ConversationView = {
+            "conversation": before["conversation"],
+            "entries": entries,
+            "docs": docs,
+        }
+        mount.value = value
+        after = value
+        for observer in list(mount.observers):
+            advance = getattr(observer, "advance_frame", None) or getattr(
+                observer, "advance", None
+            )
+            if advance is not None:
+                contained(partial(advance, value, ops, frame_context), report)
+    # Every publication reaches event adapters, including one that changes no mounted state.
+    for observer in list(mount.observers):
+        publication_listener = getattr(observer, "publication", None)
+        if publication_listener is not None:
+            contained(
+                partial(
+                    publication_listener,
+                    before,
+                    after,
+                    ops,
+                    publication,
+                    frame_context,
+                ),
+                report,
+            )
+
+
+def _prefixed(op: Op, prefix: list[Any]) -> Op:
+    """Move ``op`` under ``prefix``; a root replacement becomes a set of the prefix."""
+
+    verb = op[0]
+    if verb == "r":
+        return ["s", prefix, op[1]]
+    path = [*prefix, *op[1]]
+    if verb in ("s", "a", "t"):
+        return [verb, path, op[2]]
+    if verb == "d":
+        return ["d", path]
+    if verb == "m":
+        return ["m", path, op[2]]
+    if verb == "p":
+        return ["p", path, op[2], op[3], op[4]]
+    raise TypeError(f"unknown op verb: {verb}")
+
+
+__all__ = [
+    "ConversationView",
+    "ConversationViews",
+    "MOUNTED",
+    "MOUNTED_KINDS",
+    "advance_mount",
+]

pi_durable/ids.py

@@ -0,0 +1,63 @@
+"""Numeric identities and commit sequences.
+
+Brands are compile-time only, exactly as in v1.3.0: IDs and sequences remain ordinary Python
+integers in memory, JSON, JSONL, and SQLite. ``NewType`` gives each record kind a distinct static
+type without changing the runtime value. Apply a brand only at a trusted allocation or decoding
+boundary through :func:`id_from_number` or :func:`seq_from_number`.
+"""
+
+from __future__ import annotations
+
+from typing import NewType, TypeVar, cast
+
+Id = NewType("Id", int)
+"""An erased nominal integer identifying one durable record kind."""
+
+ConversationId = NewType("ConversationId", int)
+EntryId = NewType("EntryId", int)
+TaskId = NewType("TaskId", int)
+SubmissionId = NewType("SubmissionId", int)
+DocumentId = NewType("DocumentId", int)
+
+Seq = NewType("Seq", int)
+"""Strictly increasing sequence assigned to one atomic storage commit; gaps are permitted."""
+
+ROOT_CONVERSATION_ID: ConversationId = ConversationId(1)
+"""The root conversation always uses this reserved ID."""
+
+IdT = TypeVar("IdT", bound=int)
+
+
+def require_positive_int(value: object, label: str) -> int:
+    """Validate an integer at a trusted numeric boundary and return it unchanged."""
+
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise TypeError(f"{value!r} is not a positive {label}")
+    return value
+
+
+def id_from_number(value: int) -> IdT:  # type: ignore[type-var]
+    """Apply an erased ID brand at a trusted numeric allocation or decoding boundary."""
+
+    return cast(IdT, require_positive_int(value, "ID"))
+
+
+def seq_from_number(value: int) -> Seq:
+    """Apply the erased commit-sequence brand at a trusted storage boundary."""
+
+    return Seq(require_positive_int(value, "sequence"))
+
+
+__all__ = [
+    "ROOT_CONVERSATION_ID",
+    "ConversationId",
+    "DocumentId",
+    "EntryId",
+    "Id",
+    "Seq",
+    "SubmissionId",
+    "TaskId",
+    "id_from_number",
+    "require_positive_int",
+    "seq_from_number",
+]

pi_durable/json.py

@@ -0,0 +1,186 @@
+"""Strict JSON values and detached copies.
+
+Durable state is JSON: records are copied into strict JSON at every ownership boundary, and a
+value that cannot be represented without losing information is rejected. Objects are plain
+``dict`` values, arrays are plain ``list`` values, and numbers are finite. ``bool`` is accepted
+before ``int`` because it is an ``int`` subclass in Python, but it remains a JSON boolean.
+
+``FrozenDict`` and ``FrozenList`` are the immutable values produced at record-construction
+boundaries. They remain JSON-encodable (they subclass ``dict`` and ``list``) and ``copy_json``
+turns them back into ordinary mutable JSON trees.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any, TypeAlias, TypeGuard
+
+JsonValue: TypeAlias = None | bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"]
+"""A strict JSON value. ``Any`` is intentionally not part of the recursive alias."""
+
+JsonObject: TypeAlias = dict[str, JsonValue]
+"""The JSON object shape used as the root of every durable document."""
+
+
+class FrozenDict(dict[str, Any]):
+    """A JSON object that rejects mutation.
+
+    It subclasses ``dict`` so the standard library's JSON encoder and storage layers can consume
+    it without adapters. Deep freeze helpers produce frozen children as well, so a record cannot
+    be changed through a retained reference.
+    """
+
+    __slots__ = ()
+
+    def _immutable(self, *args: object, **kwargs: object) -> None:
+        raise TypeError("Frozen JSON values are immutable")
+
+    __setitem__ = _immutable
+    __delitem__ = _immutable
+    __ior__ = _immutable  # type: ignore[assignment]
+    clear = _immutable
+    pop = _immutable
+    popitem = _immutable  # type: ignore[assignment]
+    setdefault = _immutable
+    update = _immutable
+
+
+class FrozenList(list[Any]):
+    """A JSON array that rejects mutation while remaining a ``list``."""
+
+    __slots__ = ()
+
+    def _immutable(self, *args: object, **kwargs: object) -> None:
+        raise TypeError("Frozen JSON values are immutable")
+
+    __setitem__ = _immutable
+    __delitem__ = _immutable
+    __iadd__ = _immutable  # type: ignore[assignment]
+    __imul__ = _immutable  # type: ignore[assignment]
+    append = _immutable
+    clear = _immutable
+    extend = _immutable
+    insert = _immutable
+    pop = _immutable
+    remove = _immutable
+    reverse = _immutable
+    sort = _immutable
+
+
+def _is_object(value: object) -> TypeGuard[Mapping[str, Any]]:
+    return type(value) is dict or isinstance(value, FrozenDict)
+
+
+def _is_array(value: object) -> TypeGuard[list[Any]]:
+    return type(value) is list or isinstance(value, FrozenList)
+
+
+def is_json_value(value: object) -> TypeGuard[JsonValue]:
+    """Return whether ``value`` is strict JSON with plain, dense containers and no cycles."""
+
+    return _check(value, set())
+
+
+def _check(value: object, ancestors: set[int]) -> bool:
+    if value is None or isinstance(value, bool) or isinstance(value, str):
+        return True
+    if isinstance(value, int):
+        return True
+    if isinstance(value, float):
+        return math.isfinite(value)
+    if _is_array(value):
+        marker = id(value)
+        if marker in ancestors:
+            return False
+        ancestors.add(marker)
+        try:
+            return all(_check(item, ancestors) for item in value)
+        finally:
+            ancestors.remove(marker)
+    if _is_object(value):
+        marker = id(value)
+        if marker in ancestors:
+            return False
+        ancestors.add(marker)
+        try:
+            for key, item in value.items():
+                if not isinstance(key, str) or not _check(item, ancestors):
+                    return False
+            return True
+        finally:
+            ancestors.remove(marker)
+    return False
+
+
+def copy_json(value: object) -> JsonValue:
+    """Return a detached strict-JSON copy of ``value``.
+
+    No container or scalar object is shared with the input. Aliases in the input become separate
+    copies in the output, and a cycle or any non-JSON value raises ``TypeError`` with a message
+    mentioning strict JSON.
+    """
+
+    return _copy(value, set())
+
+
+def _copy(value: object, ancestors: set[int]) -> JsonValue:
+    if value is None or isinstance(value, bool) or isinstance(value, str):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if math.isfinite(value):
+            return value
+        raise TypeError("Value contains a non-finite number and is not strict JSON")
+    if _is_array(value):
+        marker = id(value)
+        if marker in ancestors:
+            raise TypeError("Value contains cycles and is not strict JSON")
+        ancestors.add(marker)
+        try:
+            return [_copy(item, ancestors) for item in value]
+        finally:
+            ancestors.remove(marker)
+    if _is_object(value):
+        marker = id(value)
+        if marker in ancestors:
+            raise TypeError("Value contains cycles and is not strict JSON")
+        ancestors.add(marker)
+        try:
+            copied: dict[str, JsonValue] = {}
+            for key, item in value.items():
+                if not isinstance(key, str):
+                    raise TypeError("Value must contain strict JSON string keys")
+                copied[str(key)] = _copy(item, ancestors)
+            return copied
+        finally:
+            ancestors.remove(marker)
+    raise TypeError(f"Value contains a non-JSON {type(value).__name__}; expected strict JSON")
+
+
+def freeze_json(value: object) -> JsonValue:
+    """Validate ``value`` as strict JSON and return an immutable, alias-free tree."""
+
+    return _freeze(copy_json(value))
+
+
+def _freeze(value: JsonValue) -> JsonValue:
+    if isinstance(value, list):
+        return FrozenList(_freeze(item) for item in value)
+    if isinstance(value, dict):
+        return FrozenDict({key: _freeze(item) for key, item in value.items()})
+    return value
+
+
+
+
+__all__ = [
+    "FrozenDict",
+    "FrozenList",
+    "JsonObject",
+    "JsonValue",
+    "copy_json",
+    "freeze_json",
+    "is_json_value",
+]