> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pending Advisories Schema

> Wire format for pending_advisories rows + the closed source taxonomy and its compatibility rules.

`pending_advisories` is the unified cross-turn carryover surface. One table, read by the gateway at the start of each runtime turn, multiple sources via a closed `source` enum spanning runtime + sideband + manual contexts.

This page documents the row shape every consumer can rely on (gateway, observer, dashboard, CLI, webhook subscribers) and the compatibility rules for new and retired sources.

## Row shape

```typescript theme={null}
interface PendingAdvisory {
  id: string;                    // pa-<12 hex chars>
  agent_id: string;              // mnm-<uuid>
  session_id: string | null;     // null for sideband.* (cross-session); set for runtime.*
  text: string;                  // injected nudge_content; bracket-wrapped
  source: SourceValue;           // closed enum (see §"Source taxonomy")
  source_ref: SourceRef;         // JSONB; shape per source (see §"source_ref shapes")
  status: "pending" | "consumed" | "expired";
  created_at: string;            // ISO-8601 UTC
  consumed_at: string | null;    // ISO-8601 UTC; set when gateway injects
  expires_at: string;            // ISO-8601 UTC; default created_at + 24h
}
```

**TTL.** Default 24 hours. Configurable platform-wide by Mnemom platform admins; not configurable per-org or per-agent.

**Status transitions.** Always forward: `pending → consumed` (gateway injected on a turn) or `pending → expired` (TTL elapsed without injection). No revivals.

## Source taxonomy

Closed, hierarchical, append-only enum. New values are added additively; see [Compatibility](#compatibility).

| Context | Producer | Examples |
| - | - | - |
| `runtime.*` | Gateway (same-turn intervention bookkeeping) | `runtime.front_door.nudge`, `runtime.back_door.modification` |
| `manual.*` | Mnemom API admin handlers (human-attached) | `manual.admin` |

<Warning>
  **Surface-separation invariant.** `sideband.*` sources are no longer accepted into `pending_advisories` — a CHECK constraint on `pending_advisories.source` rejects new `sideband.*` writes (pre-cutover historical rows remain queryable for compliance attestation but were marked `status='expired'`). The fleet-sweep detectors (`sideband.coherence` / `sideband.fault_line` / `sideband.fleet`) write to the operator-actionable [`governance_signals`](/specifications/governance-signals-schema) table instead.
</Warning>

### Current ratified values (post-cutover)

| Source | Producer | Posture-gated | Webhook event |
| - | - | - | - |
| `runtime.front_door.nudge` | gateway (front-door handler) | No | (none) |
| `runtime.front_door.enforce` | gateway (front-door handler) | No | (none) |
| `runtime.inside.autonomy.nudge` | gateway (CLPI handler) | No | (none) |
| `runtime.inside.integrity.nudge` | gateway (AIP handler) | No | (none) |
| `runtime.back_door.modification` | gateway (back-door handler) | No | (none) |
| `manual.admin` | Mnemom API admin attach handler | No | future `manual.advisory_attached` |

`sideband.coherence` / `sideband.fault_line` / `sideband.fleet` previously appeared here; the fleet-sweep detectors behind them now write to [`governance_signals`](/specifications/governance-signals-schema) instead. Runtime drift detection is a separate, agent-scoped detector (not fleet-sweep-driven, not written to `pending_advisories` or `governance_signals`) that fires the `sideband.drift.fired` webhook event directly — see [Webhook events](#webhook-events) below. The legacy `drift.detected` event name has been removed with no replacement alias; subscribers must use `sideband.drift.fired`.

## `source_ref` shapes

JSONB envelope keyed off `source`. Conventions:

* Every `runtime.*` row carries `{checkpoint_id: string, mode_at_fire: "off"|"observe"|"nudge"|"enforce"}`
* Every `manual.*` row carries `{actor_user_id: string, attached_at: string, note?: string}`

For `sideband.*` `source_ref` shapes, see the [`governance_signals` table](/specifications/governance-signals-schema#governance_signals); those observations write to the operator-actionable surface, not to this table.

### `runtime.*` — `source_ref`

```json theme={null}
{
  "checkpoint_id": "ckpt-92e1d8b3",
  "mode_at_fire": "nudge"
}
```

`checkpoint_id` references the `integrity_checkpoints` row created on the same turn. `mode_at_fire` is the agent's effective mode at intervention time (post-cascade, pre-fire).

### `manual.admin` — `source_ref`

```json theme={null}
{
  "actor_user_id": "user-a3f29c1e",
  "attached_at": "2026-05-04T15:32:00Z",
  "note": "Customer support attached after escalation #47291"
}
```

## `nudge_content` format

Every advisory's `text` follows a stable wrapper:

```text theme={null}
[Mnemom advisory: <one-sentence finding>. <one-sentence recommendation>.]
```

The bracket wrapper enables the gateway's user-visible-explanation guarantee to detect that an injection happened. Producers MUST keep the wrapper; if the wrapper is missing on a delivered turn, the gateway suffix-injects its own marker `[Mnemom: <intervention summary>]`.

## `concerns_summary` format

Short structured headline (≤80 chars) used for telemetry, dashboard display, and CLI list output. Convention: `<axis>: <short outcome>`.

| Source | Example |
| - | - |
| `runtime.*` | `<checkpoint>: <mode>-fired` |
| `manual.admin` | `Manual: <one-line note>` |

## Read endpoints

| Endpoint | Auth | Returns |
| - | - | - |
| `GET /v1/agents/:id/sideband-advisories` | user (org member) | All `sideband.*` advisories for one agent (default last 50, max 200). |
| `GET /v1/teams/:id/sideband-advisories` | user (org member) | All `sideband.*` advisories for member agents (default last 100, max 500). |
| `GET /v1/teams/:id/sideband-coverage` | user (org member) | 30-day per-axis sweep summary + raw rows. |

Filters (all optional, on the agent + team listing endpoints):

* `?since=<ISO-8601>` — only advisories created after this timestamp
* `?limit=<n>` — page size (default 50/100, max 200/500)

Service-key paths used by the observer cron (not customer-facing — gated behind `X-Service-Key`, exposed under an internal namespace that does not appear in the customer OpenAPI):

| Operation | Auth | Purpose |
| - | - | - |
| Active-teams enumeration | `X-Service-Key` | Observer cron: enumerate teams to sweep |
| Sideband sweep heartbeat | `X-Service-Key` | Observer heartbeat: UPSERT per-sweep log row |
| `GET /v1/teams/:id/effective-posture` | `X-Service-Key` (or user) | Observer posture read (customer-facing endpoint) |

## Compatibility

* **New `source` values are additive.** Mnemom may add values to the source taxonomy. Treat an unrecognized `source` as a generic advisory instead of rejecting the row.
* **Existing rows are never rewritten to a new source.** When a source stops being produced (as `sideband.*` did), new writes with it are refused, but historical rows keep their original `source` value and remain readable for audit and compliance queries.

## Webhook events

`sideband.drift.fired` fires today for runtime (in-session) drift detection — the legacy `drift.detected` name was removed with no replacement alias, so subscribers must use `sideband.drift.fired`. `sideband.coherence.fired` / `sideband.fault_line.fired` / `sideband.fleet.fired` remain registered event types you can subscribe to, but their detectors currently deliver findings through [`governance_signals`](/specifications/governance-signals-schema) instead — do not rely on them firing today. Subscribers receive the standard webhook envelope:

```json theme={null}
{
  "id": "evt-1f2a8e9c",
  "type": "sideband.drift.fired",
  "created_at": "2026-05-04T15:32:00Z",
  "account_id": "acct-3f9c2b1a",
  "data": {
    "alert_id": "ida-92e1d8b3",
    "agent_id": "mnm-a3f29c1e",
    "session_id": "sess-7d1e2f3a",
    "severity": "medium",
    "drift_direction": "value_erosion",
    "sustained_checks": 5,
    "message": "Detected 5 consecutive non-clear verdicts in session sess-7d1e2f3a"
  }
}
```

See [Webhooks](/guides/webhooks) for the full subscription + signature-verification flow.

## See also

* [Sideband detection](/concepts/sideband-detection) — concept overview and the four-source taxonomy
* [Trust Posture](/concepts/trust-posture) — the policy surface that drives `sideband.*` thresholds
* [Compliance attestation foundation](/guides/compliance-attestation-foundation) — how `sideband_sweep_log` + posture-versioned snapshots feed control mappings


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.