Application Boundary Contract

This reference defines the normalized contract between application implementations, their adapters, and the RAS-driven runtime.

Purpose

The application boundary exists so multiple host-specific application implementations can connect to the same Cerebel runtime without changing the runtime contract.

Examples include CLI applications, HTTP services, websocket gateways, and device-oriented control surfaces.

Boundary roles

Adapter responsibilities

Adapters may:

1. Receive tool-native or transport-native events.
2. Convert those events into normalized interaction requests.
3. Convert normalized responses into tool-native output or commands.
4. Maintain connection or session state local to the tool.
5. Apply local safety checks for physical execution endpoints.

Adapters must not:

1. Perform domain reasoning.
2. Orchestrate substrates directly.
3. Replace runtime routing decisions.

Application responsibilities

Application implementations must:

1. Validate incoming requests.
2. Normalize and propagate interaction metadata.
3. Apply authorization and boundary policy.
4. Delegate interaction and management operations to RAS.
5. Return normalized responses back to adapters.

Application implementations must not:

1. Perform modality-specific decoding or rendering that belongs in runtime substrates.
2. Embed hardware protocol logic.
3. Duplicate decision-making logic from the runtime.

Standard application APIs

Interaction API

Purpose: conversation, command, feedback, and actuation requests.

Operations:

1. submit_interaction(request) -> response
2. submit_feedback(request) -> response

Management API

Purpose: lifecycle and topology management.

Operations:

1. boot(bundle) -> boot_result
2. stop(cerebrum_id) -> stop_result
3. readiness(cerebrum_id) -> bool
4. register_adapter(adapter_descriptor) -> result
5. unregister_adapter(adapter_id) -> result
6. adapter_health(adapter_id) -> health_status

Modulation API

Purpose: system control-state modulation independent of business payloads.

Operations:

1. publish_modulator_cocktail(cocktail, scope) -> result
2. get_modulation_state(scope) -> state

The modulation API is part of the target boundary even if a specific application implementation phases it in later.

Adapter contract

Each adapter should expose the same conceptual contract regardless of transport or tool type.

Identity and capability fields

1. adapter_id
2. tool_type
3. supported_input_modalities
4. supported_output_modalities
5. supports_streaming
6. safety_class

Lifecycle operations

1. start()
2. stop()
3. health()

Inbound path

1. receive_tool_event(event)
2. to_interaction_request(event) -> interaction_request
3. Submit to the application interaction API.

Outbound path

1. from_interaction_response(response) -> tool_output_or_command
2. send_to_tool(output_or_command)

Telemetry and feedback path

1. receive_tool_telemetry(telemetry)
2. to_feedback_request(telemetry) -> interaction_request
3. Submit feedback through the application interaction API.

Required interaction metadata

Requests and responses should carry enough metadata to survive routing, correlation, diagnostics, and degradation handling.

Required request concepts

1. interaction_id
2. session_id or correlation_id
3. intent
4. source_modality
5. target_modality
6. payload
7. target_hints when needed

Required response concepts

1. interaction_id
2. handled
3. output_modality
4. payload
5. diagnostics
6. degraded

Routing selectors

When an application hosts multiple adapters, routing selectors should include:

1. adapter_id
2. source modality
3. target modality
4. interaction intent
5. optional target hints
6. policy and safety constraints

Message model rules

1. Interaction payloads and modulation payloads should remain separate.
2. Interaction metadata should propagate end-to-end.
3. Feedback should be explicit interaction intent rather than a hidden side effect.
4. Diagnostics and degraded-state reporting should be first-class response fields.

Related references

1. Application Boundary Architecture
2. RAS Bridge Contract
3. Substrate Core Contracts