needlepath 0.2.3__tar.gz → 0.2.4__tar.gz

{needlepath-0.2.3 → needlepath-0.2.4}/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to the `needlepath` Python package are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.4] - 2026-11-05
+
+### Added
+
+- **`SelectionResult.protected` and `SelectionResult.applying()`.** The two
+  rules an adapter must follow once workspace protection is in force, decided
+  in the core so no adapter re-derives them. `protected` is `True` when the
+  response's `governance` forbids raw-context fallback (a blocked verdict
+  included): an adapter's own shadow flag must exempt exactly these results
+  (`shadow and not protected`), mirroring `_finish`, which keeps a protected
+  delivery applied in a shadow run. `applying()` is a context for the install
+  step: an unexpected failure inside it is re-raised as a sanitized
+  `NeedlepathGuardrailError` when the result is protected and passes through
+  to the adapter's ordinary fail-open handler otherwise.
+
+### Fixed
+
+- **A blocked result is canonicalized to an empty delivery.** `_finish` kept
+  the wire's `rendered_context` and `selected` on a `Reason.BLOCKED` result,
+  so a type-valid body that contradicted its own verdict (a render, retained
+  records with excerpts) could be forwarded by a caller reading those fields
+  or by the System One adapter. A blocked result now always exposes an empty
+  render and no selected records; the body is not rejected (the verdict is
+  the engine's word, the render is simply not delivered), and the receipt
+  keeps what the wire reported (`outcome`, `governance`, `usage`,
+  `security_action`, request id, token and record counts).
+  `to_system_one_state` mirrors the rule at the point of use: a blocked
+  result or response, however assembled, contributes no state.
+
 ## [0.2.3] - 2026-11-04
 
 ### Fixed

{needlepath-0.2.3 → needlepath-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: needlepath
-Version: 0.2.3
+Version: 0.2.4
 Summary: Framework-free client for the Needlepath hosted context-selection service.
 Project-URL: Homepage, https://nextmoca.com
 Author: Next Moca Global, Inc.

{needlepath-0.2.3 → needlepath-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "needlepath"
-version = "0.2.3"
+version = "0.2.4"
 description = "Framework-free client for the Needlepath hosted context-selection service."
 readme = "README.md"
 requires-python = ">=3.9"

{needlepath-0.2.3 → needlepath-0.2.4}/src/needlepath/client.py

@@ -19,6 +19,7 @@ The three binding rules of §8.2 are implemented here and nowhere else:
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import json
 import os
 import random
@@ -1375,6 +1376,14 @@ def _finish(
         and raw_context_fallback_allowed(response)
     ):
         reason = Reason.SHADOW
+    if reason == Reason.BLOCKED:
+        # Canonical empty delivery. The verdict is the engine's word; a
+        # type-valid body that contradicts it — a render, retained records
+        # with excerpts — is not rejected, it is simply not delivered, so a
+        # caller reading ``rendered_context`` or ``selected`` off a blocked
+        # result cannot forward bytes the policy withheld. The receipt keeps
+        # what the wire reported: outcome, governance, usage, the counts.
+        response = dataclasses.replace(response, rendered_context="", selected=[])
     return SelectionResult(
         applied=(reason in _APPLIED_REASONS),
         reason=reason,

{needlepath-0.2.3 → needlepath-0.2.4}/src/needlepath/integrations/system_one.py

@@ -43,7 +43,7 @@ from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
 
 from ..errors import NeedlepathConfigError
 from ..models import ContextRecord, ContextResponse, SelectedRecord
-from ..result import SelectionResult
+from ..result import Reason, SelectionResult
 
 #: The keys of one state entry, in order. The receiving service reads them
 #: positionally in its own documentation, so the order is part of the shape.
@@ -138,14 +138,26 @@ def _entries(selection: Selection) -> List[_StateEntry]:
                 "response of a result that did not apply anyway, pass `result.response`."
             )
         response = selection.response
+        if selection.reason == Reason.BLOCKED or _blocked(response):
+            # The client already canonicalizes a blocked result to an empty
+            # delivery; the same rule holds at the point of use, so a result
+            # assembled by hand with the verdict and contradictory records
+            # still delivers nothing. Not an error: the verdict applied.
+            return []
         records: Sequence[Any] = response.selected if response is not None else []
     elif isinstance(selection, ContextResponse):
+        if _blocked(selection):
+            return []
         records = selection.selected
     else:
         records = list(selection)
     return [_entry(record) for record in records]
 
 
+def _blocked(response: Optional[ContextResponse]) -> bool:
+    return response is not None and response.outcome == "blocked"
+
+
 def _entry(record: Union[SelectedRecord, ContextRecord]) -> _StateEntry:
     """One record, four fields, nothing computed.
 

{needlepath-0.2.3 → needlepath-0.2.4}/src/needlepath/result.py

@@ -193,6 +193,43 @@ class SelectionResult:
     def raw_context_fallback_allowed(self) -> bool:
         return self.response is None or raw_context_fallback_allowed(self.response)
 
+    @property
+    def protected(self) -> bool:
+        """Workspace protection is in force on this result.
+
+        ``True`` when the response is present and its ``governance`` forbids
+        raw-context fallback — a blocked verdict included. Two rules follow
+        for an adapter, and this property is where both are decided so no
+        adapter re-implements them:
+
+        * Its own shadow flag never restores an original under protection.
+          The core client already keeps such a delivery applied in a shadow
+          run (see ``_finish``); an adapter's belt-and-braces shadow guard
+          must exempt exactly the same results: ``shadow and not protected``.
+        * A failure to install the result must stop the call rather than
+          fail open — see :meth:`applying`.
+        """
+        return not self.raw_context_fallback_allowed
+
+    def applying(self) -> _ProtectedApply:
+        """A context in which an adapter installs this result.
+
+        ::
+
+            with selection.applying():
+                return self._finish(result, plan, selection)
+
+        Inside it, an unexpected failure — a copy that raises, an annotation
+        that trips on a framework shape, an index slip — is re-raised as a
+        sanitized :class:`NeedlepathGuardrailError` when the result is
+        :attr:`protected`, and passes through untouched otherwise, so the
+        adapter's ordinary fail-open handler sees it. The fail-open rule
+        covers an adapter's own defects; once workspace protection is in
+        force the original may not come back, so a defect there is a stop.
+        A ``NeedlepathGuardrailError`` raised inside passes through as is.
+        """
+        return _ProtectedApply(self)
+
     @property
     def passthrough(self) -> bool:
         """``True`` when the caller must use its original context unmodified.
@@ -360,6 +397,24 @@ class SelectionResult:
         )
 
 
+class _ProtectedApply:
+    """See :meth:`SelectionResult.applying`."""
+
+    __slots__ = ("_result",)
+
+    def __init__(self, result: SelectionResult) -> None:
+        self._result = result
+
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        if exc is None or isinstance(exc, NeedlepathGuardrailError) or not self._result.protected:
+            return False
+        # Sanitized: the original exception's message may carry record text.
+        raise NeedlepathGuardrailError() from None
+
+
 @dataclass
 class SelectionStats:
     """Counters an adapter can expose for a shadow report or a health check.

{needlepath-0.2.3 → needlepath-0.2.4}/src/needlepath/version.py

@@ -5,6 +5,6 @@ is correct when the package is run from a source checkout, which is how every
 one of our own integration tests runs it.
 """
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 __all__ = ["__version__"]

{needlepath-0.2.3 → needlepath-0.2.4}/tests/test_guardrails.py

@@ -324,3 +324,113 @@ async def test_protected_response_remains_fail_closed_if_result_assembly_fails(m
         select(client([protected()]))
     with pytest.raises(Exception, match="Workspace guardrails"):
         await select(client([protected()], asynchronous=True))
+
+
+# The two adapter rules a protected result carries, decided in one place.
+
+
+@pytest.mark.parametrize(
+    ("script", "expected"),
+    [
+        ([protected()], True),
+        (
+            [protected(outcome="blocked", selected=[], records_selected=0, rendered_context="")],
+            True,
+        ),
+        (
+            [
+                protected(
+                    governance={
+                        "enabled": True,
+                        "policies_applied": 0,
+                        "raw_context_fallback_allowed": True,
+                    }
+                )
+            ],
+            False,
+        ),
+        ([NeedlepathTimeoutError("down")], False),
+    ],
+)
+def test_protected_says_whether_workspace_protection_is_in_force(script, expected):
+    result = select(client(script))
+    assert result.protected is expected
+    assert result.protected is (not result.raw_context_fallback_allowed)
+
+
+def test_a_protected_result_under_shadow_stays_applied_and_protected():
+    result = select(client([protected()], shadow=True))
+    assert result.applied is True and result.shadow is True
+    assert result.protected is True
+
+
+def test_applying_turns_a_failure_into_a_sanitized_stop_only_under_protection():
+    protected_result = select(client([protected()]))
+    with (
+        pytest.raises(Exception, match="Workspace guardrails") as caught,
+        protected_result.applying(),
+    ):
+        raise RuntimeError("PRIVATE RAW leaked into an exception message")
+    assert type(caught.value).__name__ == "NeedlepathGuardrailError"
+    assert "PRIVATE RAW" not in str(caught.value)
+    assert caught.value.__cause__ is None
+
+    ordinary = select(client([NeedlepathTimeoutError("down")]))
+    with pytest.raises(RuntimeError), ordinary.applying():
+        raise RuntimeError("an adapter defect, fail open")
+
+    with protected_result.applying():
+        pass  # no failure, nothing raised
+
+
+def test_applying_passes_a_guardrail_error_through_unchanged():
+    result = select(client([protected()]))
+    with pytest.raises(Exception, match="Workspace guardrails") as caught, result.applying():
+        result.declined("no_saving")
+    assert caught.value.__cause__ is None
+
+
+# A blocked result is canonicalized to an empty delivery. The verdict is the
+# engine's word; a type-valid body that contradicts it (a render, retained
+# records) is not rejected, it is simply not delivered. The receipt keeps what
+# the wire reported.
+
+CONTRADICTORY_BLOCKED = dict(
+    outcome="blocked",
+    rendered_context="LEAKED RENDER of PRIVATE RAW",
+    records_selected=1,
+    selected=[{"record_id": "r1", "excerpt": "LEAKED EXCERPT of PRIVATE RAW"}],
+    tokens_before=1000,
+    tokens_after=250,
+    usage={"meter_version": "npm-2026-08-r1", "outcome": "pass_through"},
+)
+
+
+@pytest.mark.parametrize("asynchronous", [False, True])
+@pytest.mark.asyncio
+async def test_a_blocked_result_exposes_an_empty_render_and_no_records(asynchronous):
+    c = client([protected(**CONTRADICTORY_BLOCKED)], asynchronous=asynchronous)
+    result = await select(c) if asynchronous else select(c)
+    assert result.applied is True and result.reason == Reason.BLOCKED
+    assert result.rendered_context == ""
+    assert result.selected_ids == [] and result.excerpts == {}
+    assert result.response.rendered_context == ""
+    assert result.response.selected == []
+    assert "LEAKED" not in repr(result.response.selected) + result.rendered_context
+    # The receipt keeps what the wire reported.
+    meta = result.metadata(prefix="")
+    assert meta["outcome"] == "blocked"
+    assert meta["governance"]["raw_context_fallback_allowed"] is False
+    assert meta["usage"]["outcome"] == "pass_through"
+    assert meta["tokens_before"] == 1000 and meta["tokens_after"] == 250
+    assert meta["records_selected"] == 1
+    assert result.request_id == meta["request_id"]
+
+
+def test_system_one_gets_no_state_from_a_blocked_result():
+    from needlepath.integrations.system_one import to_system_one_state
+
+    result = select(client([protected(**CONTRADICTORY_BLOCKED)]))
+    out = to_system_one_state(result, questions=["is this a refund?"])
+    assert out["state"] == []
+    assert "LEAKED" not in repr(out)

{needlepath-0.2.3 → needlepath-0.2.4}/tests/test_system_one_adapter.py

@@ -335,3 +335,28 @@ def test_a_bare_response_can_issue_its_own_receipt():
     receipt = selection_receipt(resp, prefix="")
     assert receipt["request_id"] == "np-0001"
     assert receipt["selection_id"] == "sel-9"
+
+
+# --------------------------------------------------------------------------- #
+# A blocked verdict delivers nothing, at the point of use too
+# --------------------------------------------------------------------------- #
+
+
+def test_a_hand_built_blocked_result_contributes_no_state():
+    """The client canonicalizes a blocked result to an empty delivery; the
+    adapter mirrors that rule at the point of use, so a result or response
+    assembled by hand with the verdict and contradictory records still
+    delivers nothing. Not an error: the verdict applied, and the state is
+    what it says — empty."""
+    resp = response(selected("r1", excerpt="LEAKED"), outcome="blocked")
+    result = SelectionResult(
+        applied=True,
+        reason=Reason.BLOCKED,
+        request_id=resp.request_id,
+        operating_point="np-2026-08-r4",
+        response=resp,
+    )
+    assert to_system_one_state(result, questions=QUESTIONS)["state"] == []
+    assert to_system_one_state(resp, questions=QUESTIONS)["state"] == []
+    assert to_system_one_state(result, questions=QUESTIONS, mode=MODE_RENDERED)["state"] == ""
+    assert selection_receipt(result)["needlepath.outcome"] == "blocked"