commit ea61c8fc5a24bf18984e6f1aca110ea447944370
parent 9b6de82c9f2adc9478d4d77c39a1b9a77ca4f4c5
Author: triesap <tyson@radroots.org>
Date: Wed, 8 Apr 2026 18:22:20 +0000
contract: require explicit execution terminology
- rename request context and response meta fields from mode shorthand to explicit execution terminology
- replace opaque deterministic and assisted status and capability keys across the stdio control plane
- align registry naming and deterministic meta builders with the explicit wire contract
- verify with pixi run test, pixi run run, and explicit status plus request-context smoke requests
Diffstat:
8 files changed, 91 insertions(+), 73 deletions(-)
diff --git a/src/hyf_core/capabilities/query_analysis.mojo b/src/hyf_core/capabilities/query_analysis.mojo
@@ -298,7 +298,7 @@ def build_deterministic_meta(
if context.return_provenance:
return CoreResponseMeta(
- mode="a",
+ execution_mode="deterministic",
backend="heuristic",
latency_ms=0,
provenance=ExecutionProvenance(
@@ -311,7 +311,7 @@ def build_deterministic_meta(
)
return CoreResponseMeta(
- mode="a",
+ execution_mode="deterministic",
backend="heuristic",
latency_ms=0,
provenance=None,
diff --git a/src/hyf_core/capabilities/registry.mojo b/src/hyf_core/capabilities/registry.mojo
@@ -4,10 +4,10 @@ from std.collections import List
@fieldwise_init
struct BusinessCapabilityDescriptor(Copyable, Movable):
var id: String
- var mode_a_enabled: Bool
+ var deterministic_enabled: Bool
var implemented: Bool
var callable: Bool
- var mode_b_available: Bool
+ var assisted_available: Bool
var disabled_reason: String
@@ -16,80 +16,80 @@ def canonical_business_capabilities() -> List[BusinessCapabilityDescriptor]:
capabilities.append(
BusinessCapabilityDescriptor(
id="query_rewrite",
- mode_a_enabled=True,
+ deterministic_enabled=True,
implemented=True,
callable=True,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="",
)
)
capabilities.append(
BusinessCapabilityDescriptor(
id="filter_extraction",
- mode_a_enabled=False,
+ deterministic_enabled=False,
implemented=False,
callable=False,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="deferred_bootstrap_capability",
)
)
capabilities.append(
BusinessCapabilityDescriptor(
id="semantic_rank",
- mode_a_enabled=True,
+ deterministic_enabled=True,
implemented=True,
callable=True,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="",
)
)
capabilities.append(
BusinessCapabilityDescriptor(
id="summarize_listing",
- mode_a_enabled=False,
+ deterministic_enabled=False,
implemented=False,
callable=False,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="deferred_bootstrap_capability",
)
)
capabilities.append(
BusinessCapabilityDescriptor(
id="summarize_farm",
- mode_a_enabled=False,
+ deterministic_enabled=False,
implemented=False,
callable=False,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="deferred_bootstrap_capability",
)
)
capabilities.append(
BusinessCapabilityDescriptor(
id="workflow_plan",
- mode_a_enabled=False,
+ deterministic_enabled=False,
implemented=False,
callable=False,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="deferred_bootstrap_capability",
)
)
capabilities.append(
BusinessCapabilityDescriptor(
id="explain_result",
- mode_a_enabled=True,
+ deterministic_enabled=True,
implemented=True,
callable=True,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="",
)
)
capabilities.append(
BusinessCapabilityDescriptor(
id="dedupe_cluster",
- mode_a_enabled=False,
+ deterministic_enabled=False,
implemented=False,
callable=False,
- mode_b_available=False,
+ assisted_available=False,
disabled_reason="deferred_bootstrap_capability",
)
)
@@ -100,32 +100,32 @@ def bootstrap_capability_count() -> Int:
return len(canonical_business_capabilities())
-def implemented_enabled_capability_count() -> Int:
+def implemented_deterministic_capability_count() -> Int:
var implemented = 0
for capability in canonical_business_capabilities():
- if capability.mode_a_enabled and capability.implemented:
+ if capability.deterministic_enabled and capability.implemented:
implemented += 1
return implemented
-def bootstrap_enabled_capabilities() -> List[String]:
+def deterministic_enabled_capabilities() -> List[String]:
var enabled = List[String]()
for capability in canonical_business_capabilities():
- if capability.mode_a_enabled:
+ if capability.deterministic_enabled:
enabled.append(String(capability.id))
return enabled^
-def all_enabled_capabilities_implemented() -> Bool:
- return implemented_enabled_capability_count() == len(
- bootstrap_enabled_capabilities()
+def all_deterministic_capabilities_implemented() -> Bool:
+ return implemented_deterministic_capability_count() == len(
+ deterministic_enabled_capabilities()
)
def deferred_capabilities() -> List[String]:
var disabled = List[String]()
for capability in canonical_business_capabilities():
- if not capability.mode_a_enabled:
+ if not capability.deterministic_enabled:
disabled.append(String(capability.id))
return disabled^
@@ -140,5 +140,5 @@ def is_known_business_capability(capability_id: String) -> Bool:
def is_deferred_capability(capability_id: String) -> Bool:
for capability in canonical_business_capabilities():
if capability.id == capability_id:
- return not capability.mode_a_enabled
+ return not capability.deterministic_enabled
return False
diff --git a/src/hyf_core/provenance.mojo b/src/hyf_core/provenance.mojo
@@ -24,7 +24,7 @@ struct ExecutionProvenance(Copyable, Movable):
@fieldwise_init
struct CoreResponseMeta(Copyable, Movable):
- var mode: String
+ var execution_mode: String
var backend: String
var latency_ms: Int
var provenance: Optional[ExecutionProvenance]
@@ -32,7 +32,7 @@ struct CoreResponseMeta(Copyable, Movable):
def deterministic_response_meta() -> CoreResponseMeta:
return CoreResponseMeta(
- mode="a",
+ execution_mode="deterministic",
backend="heuristic",
latency_ms=0,
provenance=None,
diff --git a/src/hyf_core/request_context.mojo b/src/hyf_core/request_context.mojo
@@ -67,7 +67,7 @@ struct TimeRange(Copyable, Movable):
@fieldwise_init
struct RequestContext(Copyable, Movable):
var consumer: String
- var mode_preference: String
+ var execution_mode_preference: String
var deadline_ms: Int
var scope: Optional[RequestScope]
var time_range: Optional[TimeRange]
@@ -80,7 +80,7 @@ struct RequestContext(Copyable, Movable):
def request_context_feature_names() -> List[String]:
var features = List[String]()
features.append("consumer")
- features.append("mode_preference")
+ features.append("execution_mode_preference")
features.append("deadline_ms")
features.append("scope")
features.append("time_range")
@@ -94,7 +94,7 @@ def request_context_feature_names() -> List[String]:
def default_request_context() -> RequestContext:
return RequestContext(
consumer="unknown",
- mode_preference="a",
+ execution_mode_preference="deterministic",
deadline_ms=2500,
scope=None,
time_range=None,
@@ -187,11 +187,16 @@ def parse_request_context(json: Value) raises -> RequestContext:
context.consumer = get_string(json, "consumer")
_require_non_empty(context.consumer, "request context consumer")
- if _has_key(json, "mode_preference"):
- context.mode_preference = get_string(json, "mode_preference")
- if context.mode_preference != "a" and context.mode_preference != "b":
+ if _has_key(json, "execution_mode_preference"):
+ context.execution_mode_preference = get_string(
+ json, "execution_mode_preference"
+ )
+ if (
+ context.execution_mode_preference != "deterministic"
+ and context.execution_mode_preference != "assisted"
+ ):
raise Error(
- "request context mode_preference must be 'a' or 'b'"
+ "request context execution_mode_preference must be 'deterministic' or 'assisted'"
)
if _has_key(json, "deadline_ms"):
diff --git a/src/hyf_stdio/control/capabilities.mojo b/src/hyf_stdio/control/capabilities.mojo
@@ -28,8 +28,10 @@ def build_capabilities_output() raises -> Value:
value.set("id", Value(String(capability.id)))
value.set("kind", Value("business"))
value.set(
- "mode_a",
- Value("enabled") if capability.mode_a_enabled else Value("disabled"),
+ "deterministic_execution",
+ Value("enabled")
+ if capability.deterministic_enabled
+ else Value("disabled"),
)
value.set(
"implementation_status",
@@ -37,14 +39,16 @@ def build_capabilities_output() raises -> Value:
if capability.implemented
else (
Value("not_implemented")
- if capability.mode_a_enabled
+ if capability.deterministic_enabled
else Value("disabled")
),
)
value.set("callable", Value(capability.callable))
value.set("implemented", Value(capability.implemented))
- value.set("mode_b", Value("unavailable"))
- value.set("backend_assisted", Value(capability.mode_b_available))
+ value.set("assisted_execution", Value("unavailable"))
+ value.set(
+ "assisted_backend_available", Value(capability.assisted_available)
+ )
if capability.disabled_reason != "":
value.set(
"disabled_reason", Value(String(capability.disabled_reason))
@@ -52,7 +56,7 @@ def build_capabilities_output() raises -> Value:
capabilities.append(value)
output.set("business_capabilities", capabilities)
- output.set("backend_assisted_capabilities", loads("[]"))
+ output.set("assisted_backend_capabilities", loads("[]"))
output.set(
"request_context_features",
_string_array(request_context_feature_names()),
diff --git a/src/hyf_stdio/control/status.mojo b/src/hyf_stdio/control/status.mojo
@@ -3,11 +3,11 @@ from std.collections import List
from mojson import Value, loads
from hyf_core.capabilities.registry import (
- all_enabled_capabilities_implemented,
+ all_deterministic_capabilities_implemented,
bootstrap_capability_count,
- bootstrap_enabled_capabilities,
+ deterministic_enabled_capabilities,
deferred_capabilities,
- implemented_enabled_capability_count,
+ implemented_deterministic_capability_count,
)
from hyf_core.request_context import request_context_feature_names
@@ -26,35 +26,35 @@ def build_status_output() raises -> Value:
output.set("request_framing", Value("newline_delimited_json"))
output.set(
"implementation_status",
- Value("bootstrap_registered_mode_a_ready")
- if all_enabled_capabilities_implemented()
- else Value("bootstrap_partial_mode_a"),
+ Value("bootstrap_registered_deterministic_ready")
+ if all_deterministic_capabilities_implemented()
+ else Value("bootstrap_partial_deterministic"),
)
- var modes = loads("{}")
- modes.set("a", Value(True))
- modes.set("b", Value(False))
- output.set("enabled_modes", modes)
+ var execution_modes = loads("{}")
+ execution_modes.set("deterministic", Value(True))
+ execution_modes.set("assisted", Value(False))
+ output.set("enabled_execution_modes", execution_modes)
var backends = loads("{}")
backends.set(
- "mode_a_deterministic",
+ "deterministic_backend",
Value("available")
- if all_enabled_capabilities_implemented()
+ if all_deterministic_capabilities_implemented()
else Value("partially_available"),
)
- backends.set("mode_b_model_assisted", Value("unavailable"))
+ backends.set("assisted_backend", Value("unavailable"))
output.set("backend_reachability", backends)
var counts = loads("{}")
counts.set("canonical_business_capabilities", Value(bootstrap_capability_count()))
counts.set(
- "mode_a_registered_business_capabilities",
- Value(len(bootstrap_enabled_capabilities())),
+ "deterministic_registered_business_capabilities",
+ Value(len(deterministic_enabled_capabilities())),
)
counts.set(
- "mode_a_implemented_business_capabilities",
- Value(implemented_enabled_capability_count()),
+ "deterministic_implemented_business_capabilities",
+ Value(implemented_deterministic_capability_count()),
)
counts.set(
"disabled_business_capabilities",
@@ -63,7 +63,8 @@ def build_status_output() raises -> Value:
output.set("counts", counts)
output.set(
- "mode_a_registered_capabilities", _string_array(bootstrap_enabled_capabilities())
+ "deterministic_registered_capabilities",
+ _string_array(deterministic_enabled_capabilities()),
)
output.set("disabled_capabilities", _string_array(deferred_capabilities()))
diff --git a/src/hyf_stdio/meta.mojo b/src/hyf_stdio/meta.mojo
@@ -48,7 +48,7 @@ def _serialize_provenance(provenance: ExecutionProvenance) raises -> Value:
def serialize_core_response_meta(meta: CoreResponseMeta) raises -> Value:
var value = loads("{}")
- value.set("mode", Value(String(meta.mode)))
+ value.set("execution_mode", Value(String(meta.execution_mode)))
value.set("backend", Value(String(meta.backend)))
value.set("latency_ms", Value(meta.latency_ms))
if meta.provenance:
diff --git a/tests/test_hyf.mojo b/tests/test_hyf.mojo
@@ -21,13 +21,15 @@ def _business_capability(result: Value, capability_id: String) raises -> Value:
def test_decode_request_parses_context_and_input() raises:
var request = decode_request(
- '{"request_id":"req-1","capability":"query_rewrite","context":{"consumer":"radroots-cli","return_provenance":true},"input":{"query":"eggs near me"}}'
+ '{"request_id":"req-1","capability":"query_rewrite","context":{"consumer":"radroots-cli","execution_mode_preference":"deterministic","return_provenance":true},"input":{"query":"eggs near me"}}'
)
assert_equal(request.request_id, "req-1")
assert_equal(request.capability, "query_rewrite")
assert_equal(request.context.consumer, "radroots-cli")
- assert_equal(request.context.mode_preference, "a")
+ assert_equal(
+ request.context.execution_mode_preference, "deterministic"
+ )
assert_equal(request.context.return_provenance, True)
assert_equal(request.input["query"].string_value(), "eggs near me")
@@ -44,7 +46,7 @@ def test_encode_success_and_error_shapes() raises:
output.set("kind", Value("ok"))
var meta = loads("{}")
- meta.set("mode", Value("a"))
+ meta.set("execution_mode", Value("deterministic"))
var success = loads(
encode_success(
@@ -58,7 +60,10 @@ def test_encode_success_and_error_shapes() raises:
assert_equal(success["request_id"].string_value(), "req-success")
assert_equal(success["ok"].bool_value(), True)
assert_equal(success["output"]["kind"].string_value(), "ok")
- assert_equal(success["meta"]["mode"].string_value(), "a")
+ assert_equal(
+ success["meta"]["execution_mode"].string_value(),
+ "deterministic",
+ )
var failure = loads(
encode_error(
@@ -81,7 +86,7 @@ def test_handle_request_line_returns_invalid_request_for_bad_line() raises:
assert_equal(result["error"]["code"].string_value(), "invalid_request")
-def test_status_reports_registered_mode_a_ready() raises:
+def test_status_reports_registered_deterministic_ready() raises:
var result = _dispatch(
'{"request_id":"status-1","capability":"sys.status","input":{}}'
)
@@ -89,21 +94,21 @@ def test_status_reports_registered_mode_a_ready() raises:
assert_equal(result["ok"].bool_value(), True)
assert_equal(
result["output"]["implementation_status"].string_value(),
- "bootstrap_registered_mode_a_ready",
+ "bootstrap_registered_deterministic_ready",
)
assert_equal(
- result["output"]["backend_reachability"]["mode_a_deterministic"].string_value(),
+ result["output"]["backend_reachability"]["deterministic_backend"].string_value(),
"available",
)
assert_equal(
Int(
- result["output"]["counts"]["mode_a_registered_business_capabilities"].int_value()
+ result["output"]["counts"]["deterministic_registered_business_capabilities"].int_value()
),
3,
)
assert_equal(
Int(
- result["output"]["counts"]["mode_a_implemented_business_capabilities"].int_value()
+ result["output"]["counts"]["deterministic_implemented_business_capabilities"].int_value()
),
3,
)
@@ -127,7 +132,10 @@ def test_capabilities_report_implemented_and_disabled_states() raises:
assert_equal(
explain_result["implementation_status"].string_value(), "implemented"
)
- assert_equal(filter_extraction["mode_a"].string_value(), "disabled")
+ assert_equal(
+ filter_extraction["deterministic_execution"].string_value(),
+ "disabled",
+ )
assert_equal(
filter_extraction["disabled_reason"].string_value(),
"deferred_bootstrap_capability",
