> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostics API — Event Log and Swarm Observability

> Inspect network service diagnostics, read the structured event log head, replay or verify the SEL, and advance the swarm tick-by-tick.

The Diagnostics API exposes the internals of the WattSwarm kernel for observability, debugging, and manual swarm control. The network diagnostics endpoint provides a snapshot of the P2P service state and recent structured events. The log endpoints let you read from the kernel's Structured Event Log (SEL), trigger a full projection replay (useful after a crash or upgrade), and verify the log's cryptographic integrity. The swarm endpoints give dashboard tooling a view into the current swarm task state and let operators drive the swarm forward one tick at a time for step-by-step debugging.

***

## GET /api/diagnostics

Returns a comprehensive diagnostic snapshot of the kernel, including the network service status, the latest observability snapshot from the p2p bridge, and a filterable list of recent diagnostic events.

```bash theme={null}
GET /api/diagnostics
```

**Query parameters (all optional):**

<ParamField query="limit" type="integer">
  Maximum number of diagnostic events to return.
</ParamField>

<ParamField query="level" type="string">
  Filter by severity level (e.g. `"error"`, `"warn"`, `"info"`).
</ParamField>

<ParamField query="component" type="string">
  Filter by kernel component name (e.g. `"network_bridge"`, `"run_queue"`).
</ParamField>

<ParamField query="category" type="string">
  Filter by event category string.
</ParamField>

<ParamField query="mode" type="string">
  Filter by network mode.
</ParamField>

<ParamField query="phase" type="string">
  Filter by lifecycle phase string.
</ParamField>

<ParamField query="event_id" type="string">
  Return only the event with this exact event ID.
</ParamField>

<ParamField query="object_id" type="string">
  Filter events related to a specific object (task ID, run ID, peer ID, etc.).
</ParamField>

<ParamField query="source_node_id" type="string">
  Filter events originating from a specific node.
</ParamField>

<ParamField query="search" type="string">
  Full-text search string applied across event payload fields.
</ParamField>

**Example request:**

```bash theme={null}
curl "http://127.0.0.1:7788/api/diagnostics?limit=10&level=error"
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "generated_at": "2024-06-10T12:00:05Z",
  "network_service_started": true,
  "network_service_status": {
    "status": "running",
    "uptime_ms": 300000
  },
  "snapshot": {
    "connected_peer_count": 3,
    "known_peer_count": 7,
    "gossip_message_count": 142,
    "last_snapshot_at": "2024-06-10T12:00:00Z"
  },
  "diagnostics": [
    {
      "event_id": "diag-00000042",
      "level": "error",
      "component": "network_bridge",
      "category": "peer_connect",
      "message": "failed to establish connection to node-xyz",
      "source_node_id": "node-local123",
      "object_id": "node-xyz",
      "created_at": 1718000295000
    }
  ]
}
```

**Response fields:**

<ResponseField name="generated_at" type="string">
  ISO 8601 timestamp when the diagnostic snapshot was generated.
</ResponseField>

<ResponseField name="network_service_started" type="boolean">
  Whether the background P2P network service is currently running.
</ResponseField>

<ResponseField name="network_service_status" type="object | null">
  Status details from the network bridge, or `null` if the service is not running.
</ResponseField>

<ResponseField name="snapshot" type="object | null">
  Latest observability snapshot including peer counts and gossip metrics.
</ResponseField>

<ResponseField name="diagnostics" type="object[]">
  Filtered list of recent diagnostic events matching the query parameters.
</ResponseField>

***

## GET /api/log/head

Returns the current head sequence number of the kernel's Structured Event Log (SEL). The head sequence is the highest event sequence number written so far. Use this to determine how many events are in the log or to compare sequence positions across nodes.

```bash theme={null}
GET /api/log/head
```

**Example request:**

```bash theme={null}
curl http://127.0.0.1:7788/api/log/head
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "head": 1047
}
```

**Response fields:**

<ResponseField name="head" type="integer">
  The sequence number of the most recently written SEL event.
</ResponseField>

***

## POST /api/log/replay

Triggers a full replay of the Structured Event Log to rebuild all kernel projections from scratch. This is useful after a kernel upgrade that introduces schema changes to the read-model, or to recover from a corrupt projection state. The operation runs synchronously and may take several seconds on large logs.

```bash theme={null}
POST /api/log/replay
```

No request body is required.

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/log/replay
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "message": "replayed"
}
```

<Warning>
  Log replay rewrites all in-memory and on-disk projections by re-processing every event in sequence. It is a write-intensive operation. Do not call this endpoint while the node is actively processing tasks.
</Warning>

***

## POST /api/log/verify

Verifies the cryptographic integrity of the Structured Event Log. The kernel checks that the event chain hashes are consistent from genesis to the current head. Returns `{"ok": true}` if the log is intact, or an error if a hash mismatch or gap is detected.

```bash theme={null}
POST /api/log/verify
```

No request body is required.

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/log/verify
```

**Example response (valid):**

```json theme={null}
{
  "ok": true,
  "message": "verified"
}
```

**Example response (tampered log):**

```json theme={null}
{
  "ok": false,
  "error": "hash mismatch at sequence 512: expected sha256-abc... got sha256-def..."
}
```

***

## GET /api/swarm/state

Returns the current swarm task state as rendered by the dashboard engine. This endpoint is used by the built-in swarm dashboard UI but is equally useful for external monitoring tools or CI pipelines that need a structured view of in-flight tasks, candidates, and votes.

```bash theme={null}
GET /api/swarm/state
```

**Example request:**

```bash theme={null}
curl http://127.0.0.1:7788/api/swarm/state
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "state": {
    "tasks": [
      {
        "task_id": "task-demo-001",
        "task_type": "generic.qa.v1",
        "terminal_state": "Finalized",
        "epoch": 1,
        "candidate_count": 2,
        "committed_candidate_id": "cand-exec-p-abc123",
        "finalized_candidate_id": "cand-exec-p-abc123"
      }
    ],
    "open_task_count": 0,
    "finalized_task_count": 1
  }
}
```

***

## POST /api/swarm/tick

Advances the swarm by one execution tick. A single tick runs the full claim→execute→verify→vote→commit→finalize pipeline for any eligible tasks in the store. This endpoint is designed for development, testing, and step-by-step debugging of swarm behavior without requiring background workers.

```bash theme={null}
POST /api/swarm/tick
```

<ParamField body="executor" type="string">
  Name of the executor to use for this tick. Defaults to the `core_agent` executor configured in the startup config.
</ParamField>

<ParamField body="profile" type="string">
  Executor profile to activate for this tick. Defaults to `"default"`.
</ParamField>

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/swarm/tick \
  -H "Content-Type: application/json" \
  -d '{
    "executor": "local-agent",
    "profile": "default"
  }'
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "state": {
    "tasks": [
      {
        "task_id": "task-demo-001",
        "task_type": "generic.qa.v1",
        "terminal_state": "Committed",
        "epoch": 1,
        "candidate_count": 1,
        "committed_candidate_id": "cand-exec-p-abc123",
        "finalized_candidate_id": null
      }
    ],
    "open_task_count": 1,
    "finalized_task_count": 0
  }
}
```

<Tip>
  Call `/api/swarm/tick` in a loop in integration tests to drive tasks from `Created` all the way to `Finalized` without relying on background workers or timers. Combine with `/api/swarm/state` to assert on intermediate state after each tick.
</Tip>

<Note>
  `/api/swarm/tick` is a blocking call backed by `tokio::task::spawn_blocking`. For tasks that invoke slow executors, the HTTP request will remain open until the tick completes. Set an appropriate client timeout (recommend ≥ 60 s for tasks with non-trivial prompts).
</Note>