virtual-context 0.4.4__tar.gz → 0.4.5__tar.gz

{virtual_context-0.4.4 → virtual_context-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: virtual-context
-Version: 0.4.4
+Version: 0.4.5
 Summary: OS-style virtual memory for LLM session context management
 Project-URL: Homepage, https://virtual-context.com
 Project-URL: Repository, https://github.com/virtual-context/virtual-context

{virtual_context-0.4.4 → virtual_context-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "virtual-context"
-version = "0.4.4"
+version = "0.4.5"
 description = "OS-style virtual memory for LLM session context management"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

virtual_context-0.4.5/tests/test_retrieval_assembler_post_compaction.py

@@ -0,0 +1,250 @@
+"""Regression test for the retriever's ``post_compaction`` gate.
+
+The gate must consult ``_engine_state.compacted_prefix_messages``
+(durable, re-derived from canonical_turns on every hydration) rather
+than ``_engine_state.flushed_prefix_messages`` (session-scoped,
+designed to lag compacted under deferred-payload-mutation
+deployments).
+
+Concretely: when a freshly-hydrated engine carries the
+post-compaction values that ``hydrate_from_session_state``'s
+canonical-turns derivation produces (``compacted_prefix_messages > 0``
+but ``flushed_prefix_messages == 0`` because the loaded SessionState
+predates the next ``prepare_payload`` flush gate write), the first
+inbound message of the request MUST still see ``post_compaction =
+True`` so the retriever's ``summary_floor`` prefetch fires. Gating on
+``flushed_prefix_messages`` made that first request fail closed.
+
+These tests also assert the converse — pre-compaction state stays
+gated False — and pin that the gate change does NOT mutate
+``flushed_prefix_messages`` (preserving the deferred-payload
+invariant ``flushed <= compacted`` and the session-scoped semantics
+of the flushed watermark).
+"""
+
+from __future__ import annotations
+
+import os
+
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from virtual_context.core.retrieval_assembler import RetrievalAssembler
+from virtual_context.types import (
+    AssembledContext,
+    AssemblerConfig,
+    EngineState,
+    RetrievalResult,
+    RetrieverConfig,
+    TagGeneratorConfig,
+    VirtualContextConfig,
+)
+
+
+def _make_assembler(
+    *,
+    compacted_prefix_messages: int,
+    flushed_prefix_messages: int,
+) -> tuple[RetrievalAssembler, MagicMock]:
+    """Build a RetrievalAssembler with stubbed delegates, captured retriever.
+
+    Returns ``(assembler, retriever_mock)`` so tests can inspect the
+    keyword arguments the assembler passes when delegating to
+    ``retriever.retrieve``.
+    """
+    retriever = MagicMock()
+    retriever.retrieve.return_value = RetrievalResult(
+        tags_matched=[],
+        summaries=[],
+        total_tokens=0,
+        facts=[],
+        overflow_summaries=[],
+        retrieval_metadata={},
+    )
+
+    assembler_delegate = MagicMock()
+    assembler_delegate.assemble.return_value = AssembledContext()
+
+    monitor = MagicMock()
+    monitor.build_snapshot.return_value = SimpleNamespace(
+        total_tokens=0,
+        budget_tokens=10_000,
+    )
+
+    paging = MagicMock()
+    paging.working_set = {}
+
+    store = MagicMock()
+    turn_tag_index = MagicMock()
+    turn_tag_index.entries = []
+    fact_curator = None
+
+    engine_state = EngineState()
+    engine_state.compacted_prefix_messages = compacted_prefix_messages
+    engine_state.flushed_prefix_messages = flushed_prefix_messages
+    engine_state.last_completed_turn = max(
+        0, compacted_prefix_messages // 2 - 1,
+    )
+
+    config = VirtualContextConfig(
+        context_window=10_000,
+        tag_generator=TagGeneratorConfig(type="keyword"),
+        retriever=RetrieverConfig(),
+        assembler=AssemblerConfig(),
+    )
+
+    assembler = RetrievalAssembler(
+        retriever=retriever,
+        assembler=assembler_delegate,
+        monitor=monitor,
+        paging=paging,
+        store=store,
+        turn_tag_index=turn_tag_index,
+        engine_state=engine_state,
+        fact_curator=fact_curator,
+        config=config,
+        token_counter=lambda text: len(text) // 4,
+        session_state_provider=None,
+    )
+    # ``_set_semantic`` is required to wire the optional semantic-search
+    # dependency. Pass a mock so ``_get_recent_context`` doesn't blow up
+    # on the bleed-threshold path.
+    assembler._set_semantic(MagicMock())
+    return assembler, retriever
+
+
+def test_post_compaction_gate_true_when_compacted_positive_and_flushed_zero():
+    """The bug shape: SessionState reports zero-flushed (because the
+    loaded blob predates the prepare_payload flush gate) but
+    canonical_turns derivation has bumped compacted to a positive
+    value during ``hydrate_from_session_state``.
+
+    Before the fix, the retriever's ``post_compaction`` argument was
+    computed from ``flushed_prefix_messages > 0`` and stayed False,
+    causing the ``summary_floor`` prefetch path to be skipped on the
+    first request of a freshly-hydrated engine — exactly the
+    user-visible VCATTACH recall failure shape.
+
+    The fix moves the gate onto ``compacted_prefix_messages > 0``,
+    which is the durable signal — re-derived from canonical_turns on
+    every hydration, never zero when compaction has actually happened.
+    """
+    assembler, retriever = _make_assembler(
+        compacted_prefix_messages=958,
+        flushed_prefix_messages=0,
+    )
+
+    assembler.on_message_inbound(message="what topics?", conversation_history=[])
+
+    assert retriever.retrieve.call_count >= 1
+    call_kwargs = retriever.retrieve.call_args.kwargs
+    assert call_kwargs["post_compaction"] is True, (
+        "Gate must consult compacted_prefix_messages — the durable "
+        "watermark — not flushed_prefix_messages, which can be 0 on a "
+        "freshly-hydrated engine before prepare_payload's flush gate "
+        "writes."
+    )
+
+
+def test_post_compaction_gate_false_when_compacted_zero():
+    """Pre-compaction state (no segments yet) must stay gated False
+    regardless of any flushed value. ``compacted_prefix_messages == 0``
+    is the binary "compaction has not happened" signal."""
+    assembler, retriever = _make_assembler(
+        compacted_prefix_messages=0,
+        flushed_prefix_messages=0,
+    )
+
+    assembler.on_message_inbound(message="what topics?", conversation_history=[])
+
+    assert retriever.retrieve.call_count >= 1
+    call_kwargs = retriever.retrieve.call_args.kwargs
+    assert call_kwargs["post_compaction"] is False, (
+        "Pre-compaction state must NOT trigger summary_floor; the gate "
+        "requires compacted_prefix_messages > 0."
+    )
+
+
+def test_post_compaction_gate_true_when_both_positive():
+    """Normal post-flush steady state: both watermarks positive, gate
+    True. Ensures the fix didn't break the happy path."""
+    assembler, retriever = _make_assembler(
+        compacted_prefix_messages=958,
+        flushed_prefix_messages=958,
+    )
+
+    assembler.on_message_inbound(message="what topics?", conversation_history=[])
+
+    assert retriever.retrieve.call_count >= 1
+    call_kwargs = retriever.retrieve.call_args.kwargs
+    assert call_kwargs["post_compaction"] is True
+
+
+def test_active_tags_cleared_under_bug_shape_compacted_positive_flushed_zero():
+    """Companion to the primary post_compaction gate test: the
+    active-tag clearing at the head of ``on_message_inbound``
+    (``retrieval_assembler.py:157-160``) MUST also route through the
+    new compacted-driven gate, not the legacy flushed-driven gate.
+
+    Before the fix the assembler ran ``active_tags =
+    self._get_active_tags(...)`` for the bug-shape input (compacted
+    positive, flushed zero), which suppressed cross-tag retrieval on
+    the first request of a freshly-hydrated post-compaction engine
+    — exactly the comment's "don't suppress retrieval -- stored
+    summaries are needed since raw turns have been compacted away"
+    intent, inverted. The fix routes the same gate through
+    ``_post_compaction``, so the assembler now passes ``active_tags
+    = []`` to the retriever for the bug shape.
+    """
+    assembler, retriever = _make_assembler(
+        compacted_prefix_messages=958,
+        flushed_prefix_messages=0,
+    )
+
+    assembler.on_message_inbound(message="what topics?", conversation_history=[])
+
+    call_kwargs = retriever.retrieve.call_args.kwargs
+    assert call_kwargs["current_active_tags"] == [], (
+        "Bug shape (compacted > 0 with flushed == 0): active_tags "
+        "must clear to []. Routing this gate through the flushed "
+        "watermark suppressed retrieval on the first request of a "
+        "freshly-hydrated post-compaction engine — the same failure "
+        "shape as the primary summary_floor gate."
+    )
+
+
+def test_retrieval_does_not_mutate_flushed_prefix_messages():
+    """Preserve the deferred-payload-mutation invariant that
+    ``flushed_prefix_messages`` is session-scoped and lags
+    ``compacted_prefix_messages``. The gate fix changes which field
+    drives ``post_compaction``; it must NOT have a side effect on
+    the flushed watermark.
+
+    Regression contract:
+        * ``flushed_prefix_messages`` value at request entry equals
+          value at request exit — retrieval is pure-read for this
+          field.
+        * The retriever was invoked with ``post_compaction=True``
+          despite ``flushed == 0`` (the bug-shape input).
+    """
+    assembler, retriever = _make_assembler(
+        compacted_prefix_messages=958,
+        flushed_prefix_messages=0,
+    )
+    before = assembler._engine_state.flushed_prefix_messages
+
+    assembler.on_message_inbound(message="what topics?", conversation_history=[])
+
+    after = assembler._engine_state.flushed_prefix_messages
+    assert after == before == 0, (
+        "Retrieval must not mutate flushed_prefix_messages; that field "
+        "is the proxy's prepare_payload watermark and a session-scoped "
+        "deferred-payload signal owned by a different code path."
+    )
+
+    call_kwargs = retriever.retrieve.call_args.kwargs
+    assert call_kwargs["post_compaction"] is True

{virtual_context-0.4.4 → virtual_context-0.4.5}/virtual_context/__init__.py

@@ -14,7 +14,7 @@ from .types import (
     VirtualContextConfig,
 )
 
-__version__ = "0.4.4"
+__version__ = "0.4.5"
 
 __all__ = [
     "VirtualContextEngine",

{virtual_context-0.4.4 → virtual_context-0.4.5}/virtual_context/core/retrieval_assembler.py

@@ -143,10 +143,21 @@ class RetrievalAssembler:
 
         # Determine active tags from recent tag results
         # Post-compaction: don't suppress retrieval -- stored summaries are needed
-        # since raw turns have been compacted away
+        # since raw turns have been compacted away.
+        #
+        # The post-compaction gate consults ``compacted_prefix_messages``
+        # (durable, re-derived from canonical_turns on every hydration) NOT
+        # ``flushed_prefix_messages`` (session-scoped, lags compacted by
+        # design for deferred-payload-mutation deployments and stays at the
+        # loaded value until the next ``prepare_payload`` flush gate runs).
+        # The retriever's binary "has compaction happened" signal must reflect
+        # durable content progress, not per-session payload mutation progress.
         _active_stage = time.monotonic()
         _ft = self._engine_state.flushed_prefix_messages
-        if _ft > 0:
+        _post_compaction = int(
+            getattr(self._engine_state, "compacted_prefix_messages", 0) or 0
+        ) > 0
+        if _post_compaction:
             active_tags = []
         else:
             active_tags = self._get_active_tags(conversation_history)
@@ -182,7 +193,7 @@ class RetrievalAssembler:
             message=message,
             current_active_tags=active_tags,
             current_utilization=utilization,
-            post_compaction=(_ft > 0),
+            post_compaction=_post_compaction,
             context_turns=context,
         )
         _note("retrieve_primary", _retrieve_stage)
@@ -254,7 +265,7 @@ class RetrievalAssembler:
                     message=message,
                     current_active_tags=active_tags,
                     current_utilization=utilization,
-                    post_compaction=(_ft > 0),
+                    post_compaction=_post_compaction,
                     context_turns=expanded,
                 )
                 _note("retrieve_retry_general", _retry_retrieve_stage)