# airdress.agent_bus.*

{/* Generated by scripts/generate-event-reference.mjs from https://schemas.airdress.co/operator/events/v1.json (operator v0.1.138).
    Do not edit by hand: run `pnpm generate:event-reference` and commit the result. */}

The events in the `airdress.agent_bus` family. How to read a section, and what
each audience means, is on the [event reference](/events/) page.

## `airdress.agent_bus.attestation.issued`

The person it concerns info

This operator attested a remote session's bus write with its attestation key. `kid` names the public key; `client` the hub client the session came through. One per remote write.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `client` | string | yes |  |
| `kid` | string | yes |  |
| `op` | string | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `session` | string (uuid) | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "This operator attested a remote session's bus write with its attestation key. `kid` names the public key; `client` the hub client the session came through. One per remote write.",
  "properties": {
    "client": {
      "type": "string"
    },
    "kid": {
      "type": "string"
    },
    "op": {
      "type": "string"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "session": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "client",
    "kid",
    "op",
    "principal_id",
    "session"
  ],
  "title": "AgentBusAttestationIssued",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.claim.acquired`

The person it concerns info

A session acquired a claim, with a new fencing number.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `claim` | string | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `session` | string (uuid) | yes |  |
| `token` | integer (int64) | yes |  |
| `topic` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A session acquired a claim, with a new fencing number.",
  "properties": {
    "claim": {
      "type": "string"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "session": {
      "format": "uuid",
      "type": "string"
    },
    "token": {
      "format": "int64",
      "type": "integer"
    },
    "topic": {
      "type": "string"
    }
  },
  "required": [
    "claim",
    "principal_id",
    "session",
    "token",
    "topic"
  ],
  "title": "AgentBusClaimAcquired",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.claim.broken`

Owner warn Functions

A claim was freed from the host CLI, whoever held it.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `claim` | string | yes |  |
| `last_token` | integer (int64) | yes |  |
| `topic` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A claim was freed from the host CLI, whoever held it.",
  "properties": {
    "claim": {
      "type": "string"
    },
    "last_token": {
      "format": "int64",
      "type": "integer"
    },
    "topic": {
      "type": "string"
    }
  },
  "required": [
    "claim",
    "last_token",
    "topic"
  ],
  "title": "AgentBusClaimBroken",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.claim.handed_off`

The person it concerns info

A held claim was handed to a named session in one step.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `claim` | string | yes |  |
| `from` | string (uuid) | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `to` | string (uuid) | yes |  |
| `token` | integer (int64) | yes |  |
| `topic` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A held claim was handed to a named session in one step.",
  "properties": {
    "claim": {
      "type": "string"
    },
    "from": {
      "format": "uuid",
      "type": "string"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "to": {
      "format": "uuid",
      "type": "string"
    },
    "token": {
      "format": "int64",
      "type": "integer"
    },
    "topic": {
      "type": "string"
    }
  },
  "required": [
    "claim",
    "from",
    "principal_id",
    "to",
    "token",
    "topic"
  ],
  "title": "AgentBusClaimHandedOff",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.claim.lapsed`

The person it concerns info

A claim's lease ran out and another session took it.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `claim` | string | yes |  |
| `previous_holder` | string (uuid) | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `topic` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A claim's lease ran out and another session took it.",
  "properties": {
    "claim": {
      "type": "string"
    },
    "previous_holder": {
      "format": "uuid",
      "type": "string"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "topic": {
      "type": "string"
    }
  },
  "required": [
    "claim",
    "previous_holder",
    "principal_id",
    "topic"
  ],
  "title": "AgentBusClaimLapsed",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.fence.refused`

The person it concerns info

A fenced write was refused: its token no longer holds the claim. `current_token` is the claim's latest fencing number.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `claim` | string | yes |  |
| `current_token` | integer (int64) | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `token` | integer (int64) | yes |  |
| `topic` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A fenced write was refused: its token no longer holds the claim. `current_token` is the claim's latest fencing number.",
  "properties": {
    "claim": {
      "type": "string"
    },
    "current_token": {
      "format": "int64",
      "type": "integer"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "token": {
      "format": "int64",
      "type": "integer"
    },
    "topic": {
      "type": "string"
    }
  },
  "required": [
    "claim",
    "current_token",
    "principal_id",
    "token",
    "topic"
  ],
  "title": "AgentBusFenceRefused",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.message.refused`

The person it concerns info

A refused bus write: an operator-attested write met a topic that accepts only device-signed writes.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `principal_id` | string (uuid) | yes |  |
| `reason` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A refused bus write: an operator-attested write met a topic that accepts only device-signed writes.",
  "properties": {
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "reason": {
      "type": "string"
    }
  },
  "required": [
    "principal_id",
    "reason"
  ],
  "title": "AgentBusMessageRefused",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.policy.changed`

Owner info Functions

A topic's policy changed: by the owner through the route (`relaxed` says whether device signatures stopped being required), or from the host (`by` is `host`).

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `by` | string or null | no |  |
| `relaxed` | boolean or null | no |  |
| `require_device_signature` | boolean | yes |  |
| `retention_hours` | integer (int32) | yes |  |
| `topic` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A topic's policy changed: by the owner through the route (`relaxed` says whether device signatures stopped being required), or from the host (`by` is `host`).",
  "properties": {
    "by": {
      "type": [
        "string",
        "null"
      ]
    },
    "relaxed": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "require_device_signature": {
      "type": "boolean"
    },
    "retention_hours": {
      "format": "int32",
      "type": "integer"
    },
    "topic": {
      "type": "string"
    }
  },
  "required": [
    "require_device_signature",
    "retention_hours",
    "topic"
  ],
  "title": "AgentBusPolicyChanged",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.session.ended`

The person it concerns info

An agent bus session ended, and what it held was released. `reason` is `client`, `owner`, `expired`, `principal_revoked`, `suspended`, `not_enabled`, …

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `principal_id` | string (uuid) | yes |  |
| `reason` | string | yes |  |
| `session` | string (uuid) | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "An agent bus session ended, and what it held was released. `reason` is `client`, `owner`, `expired`, `principal_revoked`, `suspended`, `not_enabled`, …",
  "properties": {
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "reason": {
      "type": "string"
    },
    "session": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "principal_id",
    "reason",
    "session"
  ],
  "title": "AgentBusSessionEnded",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.session.started`

The person it concerns info

An agent bus session started. `attestation` is `device` or `operator`.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `attestation` | string | yes |  |
| `harness` | string | yes |  |
| `label` | string | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `session` | string (uuid) | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "An agent bus session started. `attestation` is `device` or `operator`.",
  "properties": {
    "attestation": {
      "type": "string"
    },
    "harness": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "session": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "attestation",
    "harness",
    "label",
    "principal_id",
    "session"
  ],
  "title": "AgentBusSessionStarted",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.signature.refused`

The person it concerns warn

A device-signed bus write was refused: its signature did not verify over the canonical bytes, or (`reason: replayed`) its nonce was already used. The device is the person's own agent enrollment.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `enrollment` | string (uuid) | yes |  |
| `op` | string | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `reason` | string or null | no |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A device-signed bus write was refused: its signature did not verify over the canonical bytes, or (`reason: replayed`) its nonce was already used. The device is the person's own agent enrollment.",
  "properties": {
    "enrollment": {
      "format": "uuid",
      "type": "string"
    },
    "op": {
      "type": "string"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "enrollment",
    "op",
    "principal_id"
  ],
  "title": "AgentBusSignatureRefused",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.state.conflict`

The person it concerns info

A compare-and-set state write named a version that is no longer current.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `current_version` | integer (int64) | yes |  |
| `if_version` | integer (int64) | yes |  |
| `key` | string | yes |  |
| `principal_id` | string (uuid) | yes |  |
| `topic` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A compare-and-set state write named a version that is no longer current.",
  "properties": {
    "current_version": {
      "format": "int64",
      "type": "integer"
    },
    "if_version": {
      "format": "int64",
      "type": "integer"
    },
    "key": {
      "type": "string"
    },
    "principal_id": {
      "format": "uuid",
      "type": "string"
    },
    "topic": {
      "type": "string"
    }
  },
  "required": [
    "current_version",
    "if_version",
    "key",
    "principal_id",
    "topic"
  ],
  "title": "AgentBusStateConflict",
  "type": "object"
}
```

</details>

## `airdress.agent_bus.sweep.completed`

Owner info

A sweep pass changed something: sessions expired or ended for a revoked device or person, and messages, nonces, ended sessions and empty topics past retention removed. Counts only.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: it is kept off that path as too frequent or too internal. A subscription with a function target still receives it.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `messages` | integer (uint64) | yes |  |
| `nonces` | integer (uint64) | yes |  |
| `sessions_ended_revoked` | integer (uint64) | yes |  |
| `sessions_expired` | integer (uint64) | yes |  |
| `sessions_forgotten` | integer (uint64) | yes |  |
| `topics` | integer (uint64) | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A sweep pass changed something: sessions expired or ended for a revoked device or person, and messages, nonces, ended sessions and empty topics past retention removed. Counts only.",
  "properties": {
    "messages": {
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "nonces": {
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "sessions_ended_revoked": {
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "sessions_expired": {
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "sessions_forgotten": {
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "topics": {
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "messages",
    "nonces",
    "sessions_ended_revoked",
    "sessions_expired",
    "sessions_forgotten",
    "topics"
  ],
  "title": "AgentBusSweepCompleted",
  "type": "object"
}
```

</details>