quant-net · disprosium8 · May 5, 2026 · Apr 24, 2026
diff --git a/agent.rst b/agent.rst
@@ -18,3 +18,31 @@ The QUANT-NET Agent that registers resources, interfaces with devices, and inter
    :prog: quantnet_agent
    :nested: full
 
+Monitoring Events
+-----------------
+
+The agent scheduler publishes ``MonitorEvent`` messages to the ``monitor``
+topic as tasks complete. Each event includes:
+
+- ``eventType``: ``"agentTaskResult"`` — identifies the message as a local
+  task result (distinct from a full experiment result).
+- ``value.name``: the task name.
+- ``value.exp_id``: the experiment/task ID, used by the controller to
+  correlate results when queried via ``getTasks``.
+- ``value.result``: the task result payload (when present).
+
+Configuration
+-------------
+
+The agent reads its configuration from an INI file. A path can be provided
+explicitly with the ``-c``/``--config`` CLI flag; if the file does not exist
+the agent exits immediately with an error.
+
+Without ``-c``, the config path depends on the environment:
+
+ * If ``$QUANTNET_HOME`` is set: ``$QUANTNET_HOME/etc/agent.cfg``
+ * Otherwise: ``/etc/quantnet/agent.cfg``
+
+If no config file is found the agent continues with defaults and logs a
+warning. Message broker log output is suppressed to warning level by default.
+
diff --git a/comms.rst b/comms.rst
@@ -168,3 +168,46 @@ We may then load and use the schema objects directly using ``quantnet_mq``:
     >>> req.serialize()
     '{"cmd": "myRequest", "agentId": "agent1", "payload": {"arg1": "Hello", "arg2": 99.99}, "agentID": "agent1", "command": "myRequest"}'
     >>>
+
+
+EventType Enum
+**************
+
+``quantnet_mq`` exports an ``EventType`` string enum that provides typed constants
+for all monitor event types used across the control plane:
+
+.. code-block:: python
+
+    from quantnet_mq import EventType
+
+    EventType.AGENT_STATE               # "agentState"
+    EventType.EXPERIMENT_RESULT         # "experimentResult"
+    EventType.AGENT_HEARTBEAT           # "agentHeartbeat"
+    EventType.AGENT_TASK_SCHEDULER_PHASE  # "agentTaskSchedulerPhase"
+    EventType.AGENT_TASK_SCHEDULER_TASK   # "agentTaskSchedulerTask"
+    EventType.AGENT_TASK_RESULT         # "agentTaskResult"
+
+These constants correspond directly to the ``eventType`` field of
+``MonitorEvent`` messages published to the ``monitor`` topic.
+See :doc:`Monitoring </monitoring>` for descriptions of each event type.
+
+Built-in Server RPC Schemas
+****************************
+
+qn-mq ships a set of built-in RPC message types used between agents and the
+controller. Notable additions:
+
+**MonitorTask / MonitorTaskResponse** — enables clients to query recorded
+agent task results from the controller's Monitor database via a ``getTasks``
+RPC call. The request may include an optional agent filter.
+See :doc:`Monitoring </monitoring>` for full details.
+
+Core Object Schemas
+*******************
+
+The core schema bundled with qn-mq provides common object types reusable in
+user-defined schemas. Recent additions:
+
+- ``Channel.length`` — a numeric property added to the ``Channel`` schema,
+  exposing quantum channel length. When the controller topology API is queried
+  in full mode, this field appears within each node's channel data.
diff --git a/history.rst b/history.rst
@@ -5,7 +5,61 @@ Changelog
 1.1.0 (2026-04)
 ------------------
 
+qn-mq
+~~~~~
 
+* Add ``EventType`` string enum with typed constants for all monitor event types
+  (``agentState``, ``experimentResult``, ``agentHeartbeat``,
+  ``agentTaskSchedulerPhase``, ``agentTaskSchedulerTask``, ``agentTaskResult``).
+* Add ``agentTaskResult`` as a monitor event type in the message schema.
+* Add RPC message types for querying agent task results from the controller
+  (``MonitorTask`` / ``MonitorTaskResponse``).
+* Add a ``length`` property to the ``Channel`` schema, exposing quantum channel
+  length in topology data.
+* Compatible with Python 3.10+.
+
+qn-server
+~~~~~~~~~
+
+* Add agent heartbeat validation: agents not heard from within 60 seconds are
+  excluded when matching nodes to an experiment path.
+* Enhanced topology API: full mode returns complete node definitions including
+  channel data, plus aggregate node, qubit, and channel counts.
+* Monitor plugin tracks heartbeat events to maintain each node's last-seen
+  timestamp in the database.
+* Monitor plugin adds a ``getTasks`` RPC command for querying recorded agent
+  task results.
+* Experiment protocol separates local task results from experiment-level
+  results; supports filtering queries by agent.
+* Routing fixes: correctly handle mixed-direction graph topologies; recover
+  quantum links when graph conversion drops edges in multi-graph topologies.
+* Configuration refactoring: centralized configuration management with explicit
+  config file selection via the ``-c``/``--config`` CLI flag; exits with an
+  error if the specified file does not exist.
+* Config file search path updated — ``$QUANTNET_HOME/etc/quantnet.cfg``
+  (when ``$QUANTNET_HOME`` is set) then ``/opt/quantnet/etc/quantnet.cfg``
+  (always); a previously probed path has been removed.
+* Database and message broker initialization decoupled from global
+  configuration.
+* Calibration and experiment requests now follow separate execution paths,
+  each using its own protocol and schema when communicating with agents.
+* Request parameters are now structured and typed before being forwarded
+  to agents.
+* Allocation and result-retrieval errors now identify the specific agent
+  that failed.
+
+qn-agent
+~~~~~~~~
+
+* Scheduler monitor events now use the ``agentTaskResult`` event type
+  (previously ``experimentResult``) and include the experiment ID in the
+  event value.
+* Configuration refactoring: centralized config management with auto-discovery;
+  ``-c``/``--config`` flag added, mirroring the controller pattern. Explicit
+  ``-c`` path exits with error if not found.
+* Config file search path: ``$QUANTNET_HOME/etc/agent.cfg`` if
+  ``$QUANTNET_HOME`` is set, otherwise ``/etc/quantnet/agent.cfg``.
+* Message broker log output suppressed to warning level by default.
 
 1.0.0 (2025-12-05)
 ------------------

diff --git a/monitoring.rst b/monitoring.rst
@@ -11,25 +11,74 @@ handlers for monitoring messages. A monitoring plugin must implement the
 abstract method ``handle_resource_update()`` to manage monitoring events
 received from a ``msgserver`` that listens to a chosen topic.
 
-The built-in monitoring plugin can be used to handle monitoring events
-received by the controller. It listens to the ``monitoring`` topic for
-messages of type ``NodeState``. Upon receiving a message, the plugin:
+The built-in monitoring plugin handles monitoring events received by the
+controller. It subscribes to the ``monitor`` topic for ``MonitorEvent``
+messages. Upon receiving a message, the plugin:
 
-1. Validates the message format based on the ``monitoring.yaml`` schema
-   defined in ``quantnet_mq/schema/messages``
-2. Stores the event object in the built-in database
+1. Validates the message format against the monitoring message schema.
+2. Dispatches on ``eventType``:
+
+   - **agentHeartbeat** — updates the node's last-seen timestamp in the
+     database (not persisted to the Monitor DB).
+   - **agentState**, **agentTaskResult**, **experimentResult**, and all other
+     event types — persisted to the Monitor database.
 
 Protocol
 --------
 
-The :doc:`QuantNet MQ </comms>` defines a built-in monitoring message
+The :doc:`Message Bus </comms>` defines a built-in monitoring message
 format in JSON, which includes the following fields:
 
-- rid: ``str`` - Resource ID
-- ts: ``str`` - UTC timestamp
-- eventType: ``enum<str>`` - Type of event
-- value: ``str/int/float`` - Value of the monitored resource
+- ``rid``: ``str`` — Resource ID (e.g. agent identifier)
+- ``ts``: ``float`` — UTC Unix timestamp
+- ``eventType``: ``str`` — Type of event (see ``EventType`` below)
+- ``value``: ``str | int | float | object`` — Value of the monitored resource
+
+Event Types
+-----------
+
+All valid event types are defined in the ``EventType`` enum exported by qn-mq
+(see :doc:`Message Bus </comms>`):
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Event Type
+     - Description
+   * - ``agentState``
+     - Agent state transition (e.g. Not Ready / Ready). Persisted to the
+       Monitor DB.
+   * - ``experimentResult``
+     - Result of a completed experiment run. Persisted to the Monitor DB.
+   * - ``agentHeartbeat``
+     - Periodic liveness ping from an agent. Updates the node's last-seen
+       timestamp; not stored in the Monitor DB.
+   * - ``agentTaskSchedulerPhase``
+     - Phase update from the agent task scheduler. Persisted to the Monitor DB.
+   * - ``agentTaskSchedulerTask``
+     - Individual task status from the agent task scheduler. Persisted to the
+       Monitor DB.
+   * - ``agentTaskResult``
+     - Result of a completed agent local task, including the experiment ID and
+       result payload. Persisted to the Monitor DB and queryable via ``getTasks``.
+
+Agent Heartbeat Tracking
+------------------------
+
+The monitor plugin uses incoming ``agentHeartbeat`` events to maintain a
+last-seen timestamp for each node in the database. This timestamp is used
+by the controller to exclude stale agents when matching nodes to an
+experiment path (see :doc:`Scheduling </scheduling>`).
+
+A node is considered stale if no heartbeat has been received within 60 seconds.
+
+getTasks RPC
+------------
+
+The monitor plugin exposes a ``getTasks`` RPC command that allows clients to
+query recorded agent task results from the Monitor database. The request
+accepts an optional agent filter to narrow results to a specific node.
 
-QN agents and other resources connected to the message broker can send
-monitoring messages to the ``monitoring`` topic. These messages will be
-processed by the monitoring plugin in the controller.
+Each entry in the response includes the task and experiment identifiers,
+the result payload, status, timestamps, and the name of the originating task.
diff --git a/routing.rst b/routing.rst
@@ -51,7 +51,19 @@ The routing module generates the entanglement graph.
     Figure 2. Generated Engtanglement Graph
 
 
-The results from the default shortest path algorithm and the one with entanglement constraints ::    
+The results from the default shortest path algorithm and the one with entanglement constraints ::
 
 	Shortest Path hop by hop: ('UCB-Q', 'UCB-SWITCH', 'LBNL-SWITCH', 'LBNL-Q')
-	Entanglement Path hop by hop: ['UCB-Q', 'UCB-SWITCH', 'LBNL-SWITCH', 'LBNL-BSM', 'LBNL-SWITCH', 'LBNL-Q']
+	Entanglement Path hop by hop: ['UCB-Q', 'UCB-SWITCH', 'LBNL-SWITCH', 'LBNL-BSM', 'LBNL-SWITCH', 'LBNL-Q']
+
+Implementation Notes
+--------------------
+
+**MultiGraph support** — the routing module correctly handles
+topologies represented as either directed or undirected graphs, ensuring
+neighbor traversal works regardless of how the topology was constructed.
+
+**Quantum link recovery** — when topology serialization causes quantum link
+data to be lost during graph conversion, the routing module detects this and
+falls back to the original topology source, ensuring path computation is not
+degraded by serialization artifacts.
diff --git a/scheduling.rst b/scheduling.rst
@@ -107,3 +107,13 @@ With the task definitions, it performs the following steps:
 4. If the root node’s state changes between *IN_SPEC* and *OUT_OF_SPEC*, the
    agent sends a monitoring message to the controller to report the
    status change.
+
+Controller-side request dispatch
+---------------------------------
+
+The controller distinguishes between experiment and calibration requests,
+routing each through a dedicated execution path with its own protocol and
+schema. Parameters are structured and typed before being forwarded to agents,
+ensuring consistent handling regardless of request type. Errors during
+allocation or result retrieval are reported with the identity of the
+specific agent involved.
diff --git a/server.rst b/server.rst
@@ -21,11 +21,12 @@ The QUANT-NET Controller provides the centralized controller functions for the c
 Configuration File
 ------------------
 
-The controller makes use of an INI configuration file. The search path for the controller configuration file includes:
+The controller makes use of an INI configuration file. A path can be provided
+explicitly with the ``-c``/``--config`` CLI flag; if the file does not exist
+the controller exits immediately. Without ``-c``, the following paths are probed:
 
- * ``$QUANTNET_HOME/etc/quantnet.cfg``
- * ``/opt/quantnet/etc/quantnet.cfg``
- * ``$VIRTUAL_ENV/etc/quantnet.cfg``
+ * ``$QUANTNET_HOME/etc/quantnet.cfg`` (only when ``$QUANTNET_HOME`` is set)
+ * ``/opt/quantnet/etc/quantnet.cfg`` (always)
 
 Example: ::
 
@@ -91,16 +92,30 @@ The configuration file may contain multiple sections as documented below.
 ====
 
 .. confval:: host
-    
+
    :type: string
 
-   The message queue broker host.
+   The message queue (MQTT) broker host.
 
 .. confval:: port
 
    :type: string
 
-   The message queue broker port.
+   The message queue (MQTT) broker port.
+
+.. confval:: mongo_host
+
+   :type: string
+   :default: ``127.0.0.1``
+
+   The MongoDB host used by the message bus layer.
+
+.. confval:: mongo_port
+
+   :type: string
+   :default: ``27017``
+
+   The MongoDB port used by the message bus layer.
 
 [experiment_definition]
 =======================
@@ -156,6 +171,18 @@ The configuration file may contain multiple sections as documented below.
 
    The name of a Monitoring module to make active in the Controller.
 
+Topology API
+------------
+
+The controller's ``getInfo`` RPC with ``type="topology"`` supports an optional
+``full`` parameter:
+
+- ``full=False`` (default) — returns a lightweight summary with each node's
+  type and qubit/channel counts.
+- ``full=True`` — returns complete node definitions including full channel
+  data, plus aggregate counts of nodes, qubits, and channels across the
+  topology.
+
 Logging File
 ------------
 A Python logging module ``logger.conf`` may be included in the QUANT-NET configuration path.