commit 61e3743294648c2e3b8ed97ff4b073924a02757c
parent 7d8b6e849459d6e71667da41aecd30af1f0a1272
Author: triesap <tyson@radroots.org>
Date: Thu, 24 Sep 2026 18:59:06 +0000
C004: replace dispatch sentinel with bounded observer seam (ADR-0027 D47 BP02)
- Delete the HYF_DISPATCH_SENTINEL environment/file append production hook
- Thread a compile-time DispatchAttemptObserver through the real dispatch path
- Use a no-op production observer and a test-owned in-memory recorder
- Assert zero attempts for three v2 and duplicate controls plus a legacy positive
Diffstat:
4 files changed, 174 insertions(+), 90 deletions(-)
diff --git a/src/hyf_stdio/dispatch_observer.mojo b/src/hyf_stdio/dispatch_observer.mojo
@@ -0,0 +1,42 @@
+# ADR-0027 D47 BP02 — bounded in-memory dispatch observation seam.
+#
+# The pre-activation guard's zero-dispatch obligation is proven with an
+# executed counter at the real pre-dispatch boundary. The observer is threaded
+# through the dispatch path as a compile-time type parameter: the production
+# daemon instantiates ``NoopDispatchAttemptObserver`` (a compile-time no-op with
+# no state and no I/O) and tests instantiate
+# ``RecordingDispatchAttemptObserver`` (an ordinary in-memory list owned by the
+# test invocation). There is no environment variable, file path, global
+# observer, dynamic production switch, durable trace facility or runtime
+# dependency, and no observer instance is shared across invocations.
+
+from std.collections import List
+
+
+trait DispatchAttemptObserver:
+ """Bounded pre-dispatch boundary observer.
+
+ Implementations must not perform I/O or retain process-global state; the
+ production implementation is a compile-time no-op.
+ """
+
+ def record_dispatch_attempt(mut self, capability: String):
+ ...
+
+
+@fieldwise_init
+struct NoopDispatchAttemptObserver(Copyable, DispatchAttemptObserver, Movable):
+ """Compile-time no-op production observer."""
+
+ def record_dispatch_attempt(mut self, capability: String):
+ pass
+
+
+@fieldwise_init
+struct RecordingDispatchAttemptObserver(DispatchAttemptObserver, Movable):
+ """Test-owned in-memory observer; never used by the production daemon."""
+
+ var attempts: List[String]
+
+ def record_dispatch_attempt(mut self, capability: String):
+ self.attempts.append(capability)
diff --git a/src/hyf_stdio/dispatch_sentinel.mojo b/src/hyf_stdio/dispatch_sentinel.mojo
@@ -1,32 +0,0 @@
-# ADR-0026 D46 CR04 — bounded local dispatch sentinel.
-#
-# Test observation hook only. When ``HYF_DISPATCH_SENTINEL`` names a file path,
-# every legacy/shortcut business-capability dispatch attempt appends one line
-# naming the capability. The variable is unset in normal runs, so the hook is
-# inert there. It exists so the pre-activation guard's zero-dispatch obligation
-# can be proven with an executed counter (positive control: a legacy dispatch
-# records a line; negative control: a recognized v2 request records nothing)
-# rather than by inferring from the absence of shortcut output alone.
-#
-# This does not add a provider or credential path, and it never records request
-# or source payloads; only the capability name is written.
-
-from std.os import getenv
-
-
-comptime _HYF_DISPATCH_SENTINEL_ENV = "HYF_DISPATCH_SENTINEL"
-
-
-def hyf_dispatch_sentinel_env_name() -> String:
- return _HYF_DISPATCH_SENTINEL_ENV
-
-
-def record_business_dispatch_attempt(capability: String):
- var path = getenv(_HYF_DISPATCH_SENTINEL_ENV, "")
- if path == "":
- return
- try:
- with open(path, "a") as sentinel:
- sentinel.write("dispatch " + capability + "\n")
- except:
- pass
diff --git a/src/hyf_stdio/server.mojo b/src/hyf_stdio/server.mojo
@@ -30,7 +30,10 @@ from hyf_stdio.codec import (
encode_success,
extract_request_correlation,
)
-from hyf_stdio.dispatch_sentinel import record_business_dispatch_attempt
+from hyf_stdio.dispatch_observer import (
+ DispatchAttemptObserver,
+ NoopDispatchAttemptObserver,
+)
from hyf_stdio.control.capabilities import (
build_capabilities_output_with_runtime_context,
)
@@ -192,7 +195,10 @@ def _dispatch_business_capability(
return _dispatch_capability_result(request_id, request.trace_id, result)
-def _route_business_capability(
+def _route_business_capability[
+ O: DispatchAttemptObserver
+](
+ mut observer: O,
request: WireRequest,
request_id: String,
runtime_context: RuntimeStartupContext,
@@ -204,10 +210,10 @@ def _route_business_capability(
if request.operation_context:
return encode_error(_unavailable_response(request))
- # ADR-0026 D46 CR04: every path below is a real dispatch attempt. The
- # bounded local sentinel records it only when explicitly enabled, so the
- # guard above can be proven to short-circuit before this point.
- record_business_dispatch_attempt(String(request.capability))
+ # ADR-0027 D47 BP02: every path below is a real pre-dispatch boundary. The
+ # compile-time no-op production observer records nothing; a test-owned
+ # in-memory observer proves the guard above short-circuits before this point.
+ observer.record_dispatch_attempt(String(request.capability))
if is_gated_operation(request.capability):
if not operation_enabled(runtime_context.config, request.capability):
@@ -242,6 +248,19 @@ def handle_request(request: WireRequest) raises -> String:
def handle_request_with_runtime_context(
request: WireRequest, runtime_context: RuntimeStartupContext
) raises -> String:
+ var observer = NoopDispatchAttemptObserver()
+ return handle_request_with_runtime_context_and_observer(
+ request, runtime_context, observer
+ )
+
+
+def handle_request_with_runtime_context_and_observer[
+ O: DispatchAttemptObserver
+](
+ request: WireRequest,
+ runtime_context: RuntimeStartupContext,
+ mut observer: O,
+) raises -> String:
var request_id = String(request.request_id)
var trace_id = request.trace_id
var diagnostics_dir = effective_diagnostics_dir_for_runtime_paths(
@@ -273,7 +292,7 @@ def handle_request_with_runtime_context(
)
)
return _route_business_capability(
- request.copy(), request_id, runtime_context
+ observer, request.copy(), request_id, runtime_context
)
except e:
_emit_internal_diagnostic(
@@ -312,9 +331,22 @@ def handle_request_line(line: String) raises -> String:
def handle_request_line_with_runtime_context(
line: String, runtime_context: RuntimeStartupContext
) raises -> String:
+ var observer = NoopDispatchAttemptObserver()
+ return handle_request_line_with_runtime_context_and_observer(
+ line, runtime_context, observer
+ )
+
+
+def handle_request_line_with_runtime_context_and_observer[
+ O: DispatchAttemptObserver
+](
+ line: String, runtime_context: RuntimeStartupContext, mut observer: O
+) raises -> String:
try:
var request = decode_request(line)
- return handle_request_with_runtime_context(request^, runtime_context)
+ return handle_request_with_runtime_context_and_observer(
+ request^, runtime_context, observer
+ )
except e:
var correlation = extract_request_correlation(line)
return encode_error(
diff --git a/tests/test_hyf.mojo b/tests/test_hyf.mojo
@@ -1922,9 +1922,13 @@ def test_c004_operation_v2_whitespace_only_identity_is_rejected() raises:
assert_true(_decode_error_message(blank_version).find("blank") >= 0)
-# ADR-0026 D46 CR04: unambiguous duplicate admission, safe correlation and an
-# executed zero-dispatch sentinel for all three corrected operations.
-from hyf_stdio.dispatch_sentinel import hyf_dispatch_sentinel_env_name
+# ADR-0026 D46 CR04 / ADR-0027 D47 BP02: unambiguous duplicate admission,
+# safe correlation and an executed zero-dispatch observer for all three
+# corrected operations.
+from hyf_stdio.dispatch_observer import RecordingDispatchAttemptObserver
+from hyf_stdio.server import (
+ handle_request_line_with_runtime_context_and_observer,
+)
def _v2_farm_request_minimal(request_id: String) -> String:
@@ -2123,9 +2127,8 @@ def test_c004_cr04_context_admission_is_bounded_and_linear() raises:
)
-def test_c004_cr04_zero_dispatch_sentinel_executed_controls() raises:
+def test_c004_cr04_zero_dispatch_observer_executed_controls() raises:
with SafeTempDir() as temp_dir:
- var sentinel_path = temp_dir + "/hyf-dispatch-sentinel.log"
var runtime_context = _temp_runtime_context(temp_dir)
runtime_context.config.effective.runtime.enable_farm_update_interpret = (
True
@@ -2136,58 +2139,97 @@ def test_c004_cr04_zero_dispatch_sentinel_executed_controls() raises:
runtime_context.config.effective.runtime.enable_buyer_request_match = (
True
)
- with ScopedEnvVar(hyf_dispatch_sentinel_env_name(), sentinel_path):
- # Negative controls: every recognized v2 request for all three
- # corrected operations returns capability_unavailable and performs
- # zero dispatch, including with the legacy flags enabled.
- var v2_requests = List[String]()
- v2_requests.append(_v2_farm_request_minimal("sentry-farm"))
- v2_requests.append(
- _v2_buyer_request_minimal(
- "buyer_request.interpret", "sentry-interpret"
- )
+ # The observation state is owned by this test invocation: a bounded
+ # in-memory list threaded through the real pre-dispatch boundary. No
+ # environment variable, file path or global state is involved.
+ var observer = RecordingDispatchAttemptObserver(attempts=List[String]())
+
+ # Negative controls: every recognized v2 request for all three
+ # corrected operations returns capability_unavailable and performs
+ # zero dispatch attempts, including with the legacy flags enabled.
+ var v2_requests = List[String]()
+ v2_requests.append(_v2_farm_request_minimal("sentry-farm"))
+ v2_requests.append(
+ _v2_buyer_request_minimal(
+ "buyer_request.interpret", "sentry-interpret"
)
- v2_requests.append(
- _v2_buyer_request_minimal("buyer_request.match", "sentry-match")
- )
- for line in v2_requests:
- assert_true(
- _operation_enabled(
- runtime_context.config,
- loads(line)["capability"].string_value(),
- )
- )
- var response = loads(
- handle_request_line_with_runtime_context(
- line, runtime_context
- )
+ )
+ v2_requests.append(
+ _v2_buyer_request_minimal("buyer_request.match", "sentry-match")
+ )
+ for line in v2_requests:
+ assert_true(
+ _operation_enabled(
+ runtime_context.config,
+ loads(line)["capability"].string_value(),
)
- assert_equal(response["ok"].bool_value(), False)
- assert_equal(
- response["error"]["code"].string_value(),
- "capability_unavailable",
+ )
+ var response = loads(
+ handle_request_line_with_runtime_context_and_observer(
+ line, runtime_context, observer
)
- assert_true(
- not exists(sentinel_path),
)
-
- # Positive control: an actual legacy dispatch does record a line,
- # proving the sentinel observes dispatch rather than nothing.
- var legacy = (
- '{"version":1,"request_id":"legacy-sentry",'
- '"capability":"farm_update.interpret","input":{'
- + _v2_farm_source_json()
- + "}}"
+ assert_equal(response["ok"].bool_value(), False)
+ assert_equal(
+ response["error"]["code"].string_value(),
+ "capability_unavailable",
)
- var legacy_response = loads(
- handle_request_line_with_runtime_context(
- legacy, runtime_context
+ assert_equal(len(observer.attempts), 0)
+
+ # Malformed duplicate controls are rejected before any dispatch point,
+ # so they record nothing either.
+ var malformed = List[String]()
+ malformed.append(
+ '{"version":1,"request_id":"dup-ctx",'
+ '"capability":"farm_update.interpret",'
+ '"context":{"consumer":"cli"},'
+ '"context":{"evaluation_time":"2026-09-24T09:00:00-07:00",'
+ + _v2_versions_json()
+ + ',"actor_id":"farm-1","farm_id":"farm-1"},"input":{}}'
+ )
+ malformed.append(
+ '{"version":1,"request_id":"dup-rid","request_id":"dup-rid-2",'
+ '"capability":"buyer_request.match",'
+ '"context":{"evaluation_time":"2026-09-24T09:00:00-07:00",'
+ + _v2_versions_json()
+ + ',"actor_id":"buyer-7"},"input":{}}'
+ )
+ malformed.append(
+ '{"version":1,"request_id":"dup-esc",'
+ '"capability":"farm_update.interpret",'
+ '"\\u0063apability":"query_rewrite",'
+ '"context":{"evaluation_time":"2026-09-24T09:00:00-07:00",'
+ + _v2_versions_json()
+ + ',"actor_id":"farm-1","farm_id":"farm-1"},"input":{}}'
+ )
+ for line in malformed:
+ var response = loads(
+ handle_request_line_with_runtime_context_and_observer(
+ line, runtime_context, observer
)
)
- assert_equal(legacy_response["ok"].bool_value(), True)
- assert_true(exists(sentinel_path))
- var recorded = Path(sentinel_path).read_text()
- assert_true(recorded.find("dispatch farm_update.interpret") >= 0)
+ assert_equal(response["ok"].bool_value(), False)
+ assert_equal(
+ response["error"]["code"].string_value(), "invalid_request"
+ )
+ assert_equal(len(observer.attempts), 0)
+
+ # Positive control: an actual legacy dispatch records exactly one
+ # attempt through the same seam, proving it observes the real call path.
+ var legacy = (
+ '{"version":1,"request_id":"legacy-sentry",'
+ '"capability":"farm_update.interpret","input":{'
+ + _v2_farm_source_json()
+ + "}}"
+ )
+ var legacy_response = loads(
+ handle_request_line_with_runtime_context_and_observer(
+ legacy, runtime_context, observer
+ )
+ )
+ assert_equal(legacy_response["ok"].bool_value(), True)
+ assert_equal(len(observer.attempts), 1)
+ assert_equal(observer.attempts[0], "farm_update.interpret")
def test_c004_cr04_large_unknown_key_context_is_bounded() raises:
