API Spec

1. Transport Layer Map

Transport	Endpoint	Auth	Implementation
REST/JSON	/api/v1/*	JWT (Firebase or Internal)	src/api/Routes.ts, CommandAPI.ts, FirmwareRoutes.ts, SessionRoutes.ts
GraphQL	/graphql	JWT	src/api/graphql/Schema.ts + Resolvers.ts (Mercurius)
WebSocket	/ws/state	JWT query param	src/api/Websocket.ts
MCP (SSE)	/mcp	Route-level	src/api/mcp/McpServer.ts (19 registered tools)
MQTT	hxtp/+/+/+	HMAC-SHA256 per-message	src/mqtt/Router.ts, src/mqtt/Client.ts
gRPC	:50051	Internal (no TLS, bridged network)	hx47-core/src/hx47_core/runtime.py

2. MCP Tool Registry (Complete)

All 19 tools registered in McpServer.ts:

Category	Tool Name	Purpose
Observability	get_device_state	Fetch device connectivity/battery status
	get_device_capabilities	List device capability array
	get_device_command_history	Paginated command history
	get_command_status	Single command status lookup
Discovery	list_devices	All devices for tenant
	get_device_detail	Full device metadata
	list_homes	All homes for tenant
	list_rooms	Rooms in a home
	list_groups	Device groups for tenant
Command Dispatch	execute_hxtp_command	Full command dispatch with SafetyGateway (device/room/group targets)
	confirm_hxtp_command	Confirm a dry-run token for CRITICAL actions
Provisioning	provision_device	Register new device (MOCKED in current implementation)
	decommission_device	Revoke device via Repo.RevokeDevice()
Management	setup_home	Create home entity
	create_device_group	Create logical group
	add_devices_to_group	Add devices to group
Firmware	check_firmware_update	Query for available OTA
	get_manifest_capabilities	Global capability definitions
	get_device_capability_schema	Exact JSON parameter schema from manifest
AI Native	execute_plan	Multi-step plan execution with rollback
	get_plan_status	Plan execution progress
	get_state_verification	Post-command state verification lookup
	write_agent_memory	Persist agent observation/preference/routine
	get_agent_memories	Query agent long-term memory
	whoami	User identity lookup

3. HxTP/3.1 Protocol Canonical Framing

The canonical string used for Ed25519 signing consists of exactly 11 pipe-separated fields, in this specific order:

version|device_id|tenant_id|client_id|message_id|request_id|sequence_number|timestamp|nonce|message_type|payload_hash

Critical constraints:

• Strict Order: The pipe-separated sequence is immutable.
• Protocol version: Must be HxTP/3.1.
• Tenant ID: Must be present to prevent cross-tenant replay attacks.
• Client ID: Contains the short-lived MQTT session token (Layer 1 Auth).
• Payload Hash: SHA-256 hex digest of the canonical stringified payload.

4. gRPC Protocol Definition (hx47_runtime.proto)

service CognitiveRuntime {
    rpc Orchestrate(stream RuntimeEvent) returns (stream CognitionProposal);
}

TS → Python Events (RuntimeEvent):

Variant	Purpose
PerceptionUpdate	World state hash + active contexts
ObservationOutcome	Physical action result (command_id, success, device_state)
InterruptSignal	Cancellation or preemption
CapabilitySync	Updated OpenAI-compatible tool schemas
GraphStateUpdate	Node state transition in the DAG

Python → TS Proposals (CognitionProposal):

Variant	Purpose
GraphNodeProposal	New node to add to the runtime DAG
SuspendCognition	Yield — waiting for physical observations
CompleteCognition	Goal achieved, final state
RuntimeError	Unrecoverable sidecar error

5. MQTT Topic Structure

Pattern: hxtp/{tenant_id}/device/{device_id}/{channel}

Channel	Direction	Handler	Purpose
heartbeat	Device → Cloud	HandleHeartbeat	Connectivity monitoring
cmd_ack	Device → Cloud	HandleCommandAck	RPC confirmation
state	Device → Cloud	HandleStateEcho	Digital twin sync
hello	Device → Cloud	HandleHello	Handshake (v3.1)
cmd	Cloud → Device	N/A	Subscribed by device

6. Device Provisioning Protocol (ClaimService.ts)