fix: is_bottom exempt from BottomPropagationError check; add tests; fix quickref

- interpreter.py: is_bottom is the one primitive that must inspect bottom
  values rather than propagate them. Exempt it from the propagation check.
- test_runtime.py: add IsBottomTests (7 tests) covering direct-call pattern,
  BottomWithReason, bind pattern, and conditional expression usage
- test_server.py: add adversarial tests — POST to unknown path, HEAD on
  malformed identity, GET /imports with corrupt stored object
- AGENT_QUICKREF.md: update is_bottom docs — both direct-call and bind
  patterns now work; remove outdated WRONG/RIGHT framing

461 tests passing.

Author: Douglas Jones

codifide/runtime/interpreter.py

@@ -588,9 +588,12 @@ def _call_primitive(self, name: str, arg_exprs: tuple, frame: _Frame) -> Any:
         # an argument. A program that wants to compute over a possibly-refused
         # value must handle it explicitly in a `believe` arm. Without this
         # check, arithmetic on ⊥ surfaces as a host TypeError.
-        for a in args:
-            if isinstance(a, _BottomType):
-                raise BottomPropagationError(fn=name)
+        # Exception: is_bottom is the one primitive whose purpose is to
+        # inspect a bottom value — it must not propagate.
+        if name != "is_bottom":
+            for a in args:
+                if isinstance(a, _BottomType):
+                    raise BottomPropagationError(fn=name)
         try:
             result = spec.fn(*args)
         except CodifideError:

docs/AGENT_QUICKREF.md

@@ -324,42 +324,34 @@ cand
 Both patterns are valid. `cand` + `when` is preferred for three or more
 branches; `if/then/else` is preferred for binary choices inside a body.
 
-**`is_bottom` — value inspector, not propagation catcher.**
+**`is_bottom` — value inspector.**
 
-`is_bottom(x)` returns `true` when `x` is a literal `bottom` value.
-It **cannot** catch a `bottom` that propagated through a bind:
+`is_bottom(x)` returns `true` when `x` is a `bottom` value (including `bottom "reason"`).
+Both the direct-call and bind patterns work:
 
 ```codifide
-# WRONG — bottom propagates through the bind before is_bottom sees it
+# Direct-call — is_bottom sees the value before any bind
 cand
-  r <- function_that_refuses()
-  if is_bottom(r) then "caught" else r   # raises BottomPropagationError
+  if is_bottom(function_that_refuses()) then "refused" else "ok"
 
-# RIGHT — use a believe arm to handle propagated bottom
+# Bind pattern — also works; is_bottom receives the bottom value
 cand
   r <- function_that_refuses()
-  believe r
-    ge(conf(r), 0.70) => r
-    else              => bottom          # or handle the refusal here
+  if is_bottom(r) then "refused" else r
 ```
 
-`is_bottom` is useful when `bottom` is passed as an explicit argument
-or stored in a data structure, not when it arrives via function return.
-
-**Direct-call `is_bottom` works.** If you need to check whether a function
-refuses *before* binding its result, call `is_bottom` directly on the call
-expression — no bind needed:
+For conditional routing on a possibly-refused value, `believe` is usually
+cleaner and more idiomatic:
 
 ```codifide
-# Works — is_bottom sees the value before any bind propagates it
+# Idiomatic — believe handles refusal explicitly
 cand
-  if is_bottom(moderate(message)) then "refused" else moderate(message)
+  r <- function_that_refuses()
+  believe r
+    ge(conf(r), 0.70) => r
+    else              => bottom
 ```
 
-This short-circuits: if `moderate` refuses, the `else` branch never runs.
-Note that `moderate` is called twice — once for the check and once for the
-value. For expensive functions, prefer the `believe` pattern instead.
-
 ## Content-addressed imports
 
 Individual symbol imports bring one symbol into scope by name:

tests/test_runtime.py

@@ -318,5 +318,156 @@ def inner
         self.assertIn("called from", msg)
 
 
+# ---------------------------------------------------------------------------
+# is_bottom — direct-call pattern and propagation footgun regression
+# (Sable audit note: AUD-OVERNIGHT-02 follow-up)
+# ---------------------------------------------------------------------------
+
+class IsBottomTests(unittest.TestCase):
+    """Tests for the is_bottom(f()) direct-call pattern.
+
+    The quickref documents two idioms:
+      - WRONG: r <- f(); is_bottom(r)  — bottom propagates through bind
+      - RIGHT: is_bottom(f())          — is_bottom sees the value before bind
+
+    These tests confirm both behaviours and cover BottomWithReason.
+    """
+
+    def test_is_bottom_on_literal_bottom_returns_true(self) -> None:
+        src = """
+def main
+  intent "is_bottom on literal bottom"
+  sig    () -> Bool
+  effects {}
+  cand
+    is_bottom(bottom)
+"""
+        self.assertTrue(run(parse(src), "main"))
+
+    def test_is_bottom_on_normal_value_returns_false(self) -> None:
+        src = """
+def main
+  intent "is_bottom on a normal value"
+  sig    () -> Bool
+  effects {}
+  cand
+    is_bottom(42)
+"""
+        self.assertFalse(run(parse(src), "main"))
+
+    def test_is_bottom_direct_call_on_refusing_function(self) -> None:
+        # RIGHT pattern: is_bottom(f()) — sees the bottom before any bind.
+        src = """
+def refuses
+  intent "always refuses"
+  sig    () -> Any
+  effects {}
+  cand
+    bottom
+
+def main
+  intent "direct-call is_bottom on a refusing function"
+  sig    () -> Bool
+  effects {}
+  cand
+    is_bottom(refuses())
+"""
+        self.assertTrue(run(parse(src), "main"))
+
+    def test_is_bottom_direct_call_on_non_refusing_function(self) -> None:
+        # RIGHT pattern: is_bottom(f()) where f returns a value.
+        src = """
+def gives_value
+  intent "returns a string"
+  sig    () -> String
+  effects {}
+  cand
+    "hello"
+
+def main
+  intent "direct-call is_bottom on a non-refusing function"
+  sig    () -> Bool
+  effects {}
+  cand
+    is_bottom(gives_value())
+"""
+        self.assertFalse(run(parse(src), "main"))
+
+    def test_is_bottom_on_bottom_with_reason(self) -> None:
+        # BottomWithReason is a subclass of _BottomType — is_bottom must catch it.
+        src = """
+def refuses_with_reason
+  intent "refuses with a reason string"
+  sig    () -> Any
+  effects {}
+  cand
+    bottom "not enough confidence"
+
+def main
+  intent "is_bottom on bottom-with-reason via direct call"
+  sig    () -> Bool
+  effects {}
+  cand
+    is_bottom(refuses_with_reason())
+"""
+        self.assertTrue(run(parse(src), "main"))
+
+    def test_is_bottom_bind_propagation_footgun(self) -> None:
+        # Previously: r <- f(); is_bottom(r) raised BottomPropagationError
+        # because is_bottom was treated like any other primitive.
+        # After the interpreter fix (is_bottom exempt from propagation check),
+        # this pattern now works correctly — is_bottom returns True.
+        # The quickref has been updated to reflect this.
+        src = """
+def refuses
+  intent "always refuses"
+  sig    () -> Any
+  effects {}
+  cand
+    bottom
+
+def main
+  intent "bind-then-is_bottom now works"
+  sig    () -> Bool
+  effects {}
+  cand
+    r <- refuses()
+    is_bottom(r)
+"""
+        # Both the direct-call and bind patterns now return True.
+        self.assertTrue(run(parse(src), "main"))
+
+    def test_is_bottom_in_conditional_expression(self) -> None:
+        # is_bottom used in an inline conditional — common real-world pattern.
+        src = """
+def maybe_refuses
+  intent "refuses when input is zero"
+  sig    (n: Int) -> Any
+  effects {}
+  cand
+    when gt(n, 0)
+    n
+  cand
+    bottom
+
+def main_refuses
+  intent "test refusing path"
+  sig    () -> String
+  effects {}
+  cand
+    if is_bottom(maybe_refuses(0)) then "refused" else "ok"
+
+def main_ok
+  intent "test non-refusing path"
+  sig    () -> String
+  effects {}
+  cand
+    if is_bottom(maybe_refuses(5)) then "refused" else "ok"
+"""
+        m = parse(src)
+        self.assertEqual(run(m, "main_refuses"), "refused")
+        self.assertEqual(run(m, "main_ok"), "ok")
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_server.py

@@ -454,6 +454,41 @@ def test_symbols_root_get_404(self) -> None:
         status, resp = self._get_json("/symbols")
         self.assertEqual(status, 404)
 
+    def test_post_unknown_path_404(self) -> None:
+        # POST to an unknown path must return 404, not 500.
+        status, resp = self._post("/unknown/path", b"{}", "application/json")
+        self.assertEqual(status, 404)
+        self.assertEqual(resp["error"], "not_found")
+
+    def test_head_malformed_identity_404(self) -> None:
+        # HEAD /symbols/not-a-hash — falls through to bare 404.
+        # Regression: must not 500 or hang.
+        status = self._head("/symbols/not-a-hash")
+        self.assertEqual(status, 404)
+
+    def test_head_valid_identity_absent_404(self) -> None:
+        fake = "sha256:" + "e" * 64
+        status = self._head(f"/symbols/{fake}")
+        self.assertEqual(status, 404)
+
+
+# ---------------------------------------------------------------------------
+# Adversarial: corrupt store object in /imports endpoint
+# ---------------------------------------------------------------------------
+
+class CorruptStoreTests(_ServerFixture):
+    def test_imports_corrupt_stored_object_returns_500(self) -> None:
+        """GET /symbols/<id>/imports where the stored object is not a valid module."""
+        import hashlib
+        # Write raw bytes that are valid CBOR but not a valid canonical module.
+        garbage = b"\xa1\x63foo\x63bar"  # {"foo": "bar"} — valid CBOR, invalid module
+        identity = f"sha256:{hashlib.sha256(garbage).hexdigest()}"
+        self.store._write_atomic(identity, garbage, suffix=".cbor")
+
+        status, resp = self._get_json(f"/symbols/{identity}/imports")
+        self.assertEqual(status, 500)
+        self.assertEqual(resp["error"], "store_error")
+
 
 if __name__ == "__main__":
     unittest.main()