obstat 0.3.0__tar.gz → 0.3.1__tar.gz

{obstat-0.3.0 → obstat-0.3.1}/CLAUDE.md

@@ -7,7 +7,7 @@ that weakens that ordering is a bug, not an optimisation.
 ## Commands
 
 ```bash
-uv run pytest -q          # 26 tests, ~0.3s
+uv run pytest -q          # 42 tests, ~0.9s (TestConcurrency spawns two children)
 uv run ruff check .
 uv run ruff format .
 ```
@@ -44,9 +44,20 @@ when the spec is renumbered.
 uploads via PyPI trusted publishing (OIDC — there is no token anywhere). **A PyPI
 version is immutable**: a bad build can be superseded, never withdrawn.
 
-## Gotcha
+## Gotchas
 
 `uv run --with /path/to/obstat` serves a **cached wheel** and will happily run
 code you edited minutes ago as if you hadn't. `--reinstall-package` does not
 dislodge it; `--refresh` does. Two verification runs were wasted on this — if a
-local install seems to ignore your change, that is why.
+local install seems to ignore your change, that is why. To exercise uncommitted
+work, `--with-editable` sidesteps the question entirely.
+
+**PyPI lags its own publish.** Minutes after `publish.yml` goes green,
+`uv pip install obstat==X` can still fail with *"there is no version of
+obstat==X"* while `https://pypi.org/pypi/obstat/json` reports X as latest — or
+the reverse; 0.2.0 and 0.3.0 each showed one. It cleared inside a minute both
+times. The symptom impersonates a failed upload, and every tempting response
+(re-tag, re-run, `force`) is wrong, one of them irreversibly. **The publish job
+log is authoritative**: it prints the `https://pypi.org/project/obstat/X/` that
+upload.pythonhosted.org returned, which means the file was accepted. Poll the
+install until it succeeds rather than diagnosing it.

{obstat-0.3.0 → obstat-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: obstat
-Version: 0.3.0
+Version: 0.3.1
 Summary: An auditable decision record for agent tool calls. The clearance is written down before the call runs.
 Project-URL: Homepage, https://github.com/marcinmarzeta/obstat
 Project-URL: Issues, https://github.com/marcinmarzeta/obstat/issues

{obstat-0.3.0 → obstat-0.3.1}/docs/obstat-spec.md

@@ -301,10 +301,20 @@ The wrapper's `__signature__` is the wrapped function's, minus `subject`, plus:
 obstat_approval_id: str | None = None  # keyword-only
 ```
 
+The **return annotation is widened** to `R | dict[str, Any]`, where `R` is what
+the body declared. A tool declaring `-> str` is telling the truth about its own
+result and not about its wrapper's: policy may send the call to a human and
+obstat returns §5.1's payload instead. A server validates a tool's result against
+this annotation, so without the widening an approval reaches the client as a
+protocol error — the exact outcome §5.1 returns rather than raises to avoid. An
+undeclared return is left undeclared; there is nothing to validate against.
+
 MCP servers generate their tool schema from that signature, so a client sees the
 approval argument — it needs to, for §5.2 — and cannot see `subject`. Verified
-against the MCP SDK in the example server: `delete_document` advertises
-`['doc_id', 'obstat_approval_id']`.
+against the MCP SDK by calling through it, not by reading the signature:
+`delete_document` advertises `['doc_id', 'obstat_approval_id']`, an allowed call
+returns its result, and an approval-required call returns the §5.1 payload with
+`is_error` false.
 
 ---
 
@@ -336,9 +346,11 @@ Policy said `approve` and no usable approval was supplied. obstat:
 ```
 
 A return rather than an error, so the agent can reason about it and tell the user
-what it is waiting for instead of treating a working control as a failure.
-`waiting` is `True` when this rejoined an existing request, which is how an agent
-distinguishes "asked" from "asked again".
+what it is waiting for instead of treating a working control as a failure. This
+is why §4.2 widens the advertised return: a server that validates results against
+the declared type would otherwise turn this payload back into the error it exists
+not to be. `waiting` is `True` when this rejoined an existing request, which is
+how an agent distinguishes "asked" from "asked again".
 
 The approvals table holds the argument *digest*, so `obstat pending` reads what
 the call was for off the record named in step 2 — anything the tool recorded
@@ -707,7 +719,11 @@ implementation of them, with §2.3's two commands in `tests/test_cli.py`.
 | a removed record is caught | `TestChain::test_a_removed_record_is_caught` |
 | recomputing one hash does not hide the edit | `TestChain::test_a_reused_hash_does_not_hide_an_edit` |
 | a torn line does not swallow the next record | `TestChain::test_a_torn_line_does_not_swallow_the_next_record` |
+| concurrent processes interleave records without splitting one | `TestConcurrency::test_two_processes_write_one_log` |
+| within one process the chain stays a line | `TestConcurrency::test_threads_do_not_split_a_record` |
+| a forked chain verifies | `TestConcurrency::test_a_forked_chain_still_verifies` |
 | `subject` unadvertised, approval id advertised | `test_injected_subject_is_not_advertised…` |
+| an approval is a return value through a real MCP server | `test_an_approval_survives_a_real_mcp_server` |
 | the resource comes from the arguments | `test_resource_comes_from_the_arguments` |
 | a template matches only the spelling it was given | `test_a_template_matches_only_the_spelling_it_was_given` |
 | a callable resource normalises what policy matches | `test_a_callable_resource_normalises_what_policy_matches` |

{obstat-0.3.0 → obstat-0.3.1}/obstat/__init__.py

@@ -8,4 +8,4 @@ from .guard import Denied, Subject, guard, set_subject_resolver
 from .policy import PolicyError
 
 __all__ = ["Denied", "PolicyError", "Subject", "guard", "set_subject_resolver"]
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{obstat-0.3.0 → obstat-0.3.1}/obstat/guard.py

@@ -126,12 +126,33 @@ class _Checked:
     approval_id: str | None
 
 
+def _widened_return(returns: Any) -> Any:
+    """The advertised return: what the body promises, or the §5.1 payload.
+
+    A server validates a tool's result against this. A tool annotated `-> str`
+    therefore fails when policy sends the call to a human and obstat returns the
+    approval payload instead — the control reaches the client as a protocol
+    error, which is the opposite of what §5.1 returns rather than raises for.
+    """
+    if returns is inspect.Signature.empty:
+        return returns  # nothing declared, so nothing to validate against
+    try:
+        return returns | dict[str, Any]
+    except TypeError:
+        # `from __future__ import annotations` leaves the annotation a string,
+        # and a string has no `|`. Servers resolve either form the same way.
+        return f"{returns} | dict[str, Any]"
+
+
 def _public_signature(original: inspect.Signature) -> inspect.Signature:
-    """The signature callers see: `subject` removed, `obstat_approval_id` added.
+    """The signature callers see: `subject` removed, `obstat_approval_id` added,
+    and the return widened to admit the approval payload.
 
     `subject` is injected by obstat, so leaving it in the advertised schema would
     invite a client to supply its own. The approval id is the opposite — the
-    retry protocol needs the caller to send it, so it has to be advertised.
+    retry protocol needs the caller to send it, so it has to be advertised. The
+    return is widened for the same reason both of those are true: this signature
+    describes what the wrapper does, not what the body does.
     """
     kept = [p for name, p in original.parameters.items() if name != "subject"]
     var_keyword = [p for p in kept if p.kind is inspect.Parameter.VAR_KEYWORD]
@@ -142,7 +163,10 @@ def _public_signature(original: inspect.Signature) -> inspect.Signature:
         default=None,
         annotation="str | None",
     )
-    return original.replace(parameters=[*positional, approval_param, *var_keyword])
+    return original.replace(
+        parameters=[*positional, approval_param, *var_keyword],
+        return_annotation=_widened_return(original.return_annotation),
+    )
 
 
 def _resource_for(

{obstat-0.3.0 → obstat-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "obstat"
-version = "0.3.0"
+version = "0.3.1"
 description = "An auditable decision record for agent tool calls. The clearance is written down before the call runs."
 readme = "README.md"
 requires-python = ">=3.11"

{obstat-0.3.0 → obstat-0.3.1}/tests/test_guard.py

@@ -10,6 +10,10 @@ from __future__ import annotations
 
 import inspect
 import json
+import subprocess
+import sys
+import threading
+import time
 
 import pytest
 
@@ -540,6 +544,164 @@ class TestChain:
         assert record.verify(log) == ["line 5: not a record"]
 
 
+CHILD = """
+import pathlib, sys, time
+from obstat import guard
+
+
+@guard()
+def touch(n: int) -> int:
+    return n
+
+
+pathlib.Path(sys.argv[1]).write_text("ready")
+go = pathlib.Path(sys.argv[2])
+while not go.exists():
+    time.sleep(0.005)
+for i in range({calls}):
+    touch(i)
+"""
+
+
+class TestConcurrency:
+    """Two writers, one log. §6 says records interleave but never split; §6.3
+    says the chain forks across processes and verification tolerates it.
+
+    Both are claims about what happens when nothing is coordinating the writers,
+    which is the state a served tool is in and the state no other test puts it
+    in.
+    """
+
+    CALLS = 15
+
+    def test_threads_do_not_split_a_record(self, workspace):
+        """One process, one lock: every record whole, and the chain still a line."""
+        workspace(ALLOW_ALL)
+
+        @guard()
+        def touch(n: int) -> int:
+            return n
+
+        threads = [
+            threading.Thread(target=lambda: [touch(i) for i in range(self.CALLS)]) for _ in range(4)
+        ]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join()
+
+        # read() parses every line, so a split record fails here before anything
+        # is asserted about it.
+        entries = record.read()
+        assert len(entries) == 4 * self.CALLS * 2  # a decision and an outcome each
+
+        # `_chain_lock` covers hashing and appending together, so within one
+        # process the result is a line: one root, and no record followed twice.
+        prevs = [entry["prev"] for entry in entries]
+        assert prevs.count(None) == 1
+        assert len(prevs) == len(set(prevs))
+        assert record.verify() == []
+
+    def test_two_processes_write_one_log(self, workspace, tmp_path):
+        """No inter-process lock, so this is O_APPEND and one write() syscall
+        doing the work (§6). Released together, because two writers that happen
+        to take turns prove nothing."""
+        workspace(ALLOW_ALL)
+        script = tmp_path / "child.py"
+        script.write_text(CHILD.format(calls=self.CALLS), encoding="utf-8")
+
+        go = tmp_path / "go"
+        children = []
+        for name in ("a", "b"):
+            ready = tmp_path / f"ready-{name}"
+            children.append(
+                (
+                    ready,
+                    subprocess.Popen([sys.executable, str(script), str(ready), str(go)]),
+                )
+            )
+        deadline = time.time() + 30
+        while not all(ready.exists() for ready, _ in children):
+            assert time.time() < deadline, "a child never started"
+            time.sleep(0.01)
+        go.write_text("go")
+
+        for _, child in children:
+            assert child.wait(timeout=60) == 0
+
+        entries = record.read()
+        assert len(entries) == 2 * self.CALLS * 2
+        assert record.verify() == []
+
+    def test_a_forked_chain_still_verifies(self, workspace):
+        """What a second process does, done deliberately: carry on from the
+        record you last saw, not from the one that is now on the end.
+
+        Reproduced in-process because two real processes might take turns and
+        never fork at all, and a test that only sometimes tests the thing is
+        worse than no test.
+        """
+        workspace(ALLOW_ALL)
+
+        @guard()
+        def touch(what: str) -> str:
+            return what
+
+        touch("first")
+        branch = record._chain  # what another process would still be holding
+        touch("second")
+        record._chain = branch
+        touch("third")
+
+        prevs = [entry["prev"] for entry in record.read()]
+        assert len(prevs) != len(set(prevs)), "nothing forked, so nothing was tested"
+        # Every `prev` still names a record earlier in the file, which is all
+        # verification asks of it — a fork is not damage.
+        assert record.verify() == []
+
+
+async def test_an_approval_survives_a_real_mcp_server(workspace):
+    """Through the SDK, not past it (§4.2).
+
+    Every other test calls the decorated function directly, which is exactly how
+    a server validating the tool's result against its return annotation went
+    unnoticed: a tool declaring `-> str` raised at the client the moment policy
+    sent a call to a human, turning the control §5.1 designed as a return value
+    into a protocol error.
+    """
+    server = pytest.importorskip("mcp.server", reason="mcp is an optional extra")
+    workspace('[[rule]]\ntool = "read_*"\neffect = "allow"\n[[rule]]\neffect = "approve"\n')
+
+    mcp = server.MCPServer("test")
+
+    @mcp.tool()
+    @guard()
+    def read_thing(doc_id: str) -> str:
+        return f"contents of {doc_id}"
+
+    @mcp.tool()
+    @guard()
+    def delete_thing(doc_id: str) -> str:  # pragma: no cover - waits for a human
+        return f"{doc_id} deleted"
+
+    advertised = await mcp.list_tools()
+    assert {tool.name for tool in advertised} == {"read_thing", "delete_thing"}
+
+    allowed = await mcp.call_tool("read_thing", {"doc_id": "q3"})
+    assert allowed.is_error is False
+    assert allowed.content[0].text == "contents of q3"
+
+    # The one that used to raise.
+    asked = await mcp.call_tool("delete_thing", {"doc_id": "q3"})
+    assert asked.is_error is False
+    assert json.loads(asked.content[0].text)["obstat"] == "approval_required"
+
+    assert [entry["effect"] for entry in record.read() if entry["phase"] == "decision"] == [
+        "allow",
+        "approval_required",
+    ]
+
+
 async def test_async_tools_go_through_the_same_gate(workspace):
     workspace('[[rule]]\ntool = "fetch"\neffect = "allow"\n[[rule]]\neffect = "deny"\n')
 

{obstat-0.3.0 → obstat-0.3.1}/uv.lock

@@ -335,7 +335,7 @@ wheels = [
 
 [[package]]
 name = "obstat"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 
 [package.optional-dependencies]