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

# AI-disclosure ledger: concept

> What the per-agent AI-disclosure ledger records, why regulators ask for it under the EU AI Act Article 50 and the FCC AI-voice disclosure posture, how the signed export binds conversation→agent→disclosure evidence, and how it differs from the guardrail event stream.

# AI-disclosure ledger

Every completed AI-authored turn on an agent is already recorded in the
agent's immutable decision log (`ai_turn_audit`): which agent produced the
turn, which model spoke, the outcome, and whether a human later overrode it.
The **AI-disclosure ledger** folds that log, together with the tenant's
AI-disclosure posture, into one privacy-preserving, tamper-evident, signed
provenance record that answers the question a regulator or enterprise buyer
asks: *prove when and where an AI — not a human — handled an interaction, and
prove the record has not been edited.*

The dashboard surface is **Agents → your agent → Compliance tab → AI-disclosure
ledger** (mounted next to the conformity dossier). The REST surface is
`GET /api/v1/agents/{id}/ai-disclosure-ledger` with `format=json` (default) or
`format=html`, optional `from` / `to` window bounds, and a detached signature
you can verify without trusting the dashboard.

This page is the concept model; the regulatory walk-through lives in
[EU AI Act Article 50 transparency](/compliance/eu-ai-act) and the endpoint
reference lives in [Agents endpoints](/api-reference/endpoints/agents).

## What the ledger records

Each ledger entry is one AI-authored turn reduced to provenance metadata. It
deliberately carries **no prompt or response text** — this is a compliance
artifact safe to hand to an auditor, not a transcript.

| Field                       | Meaning                                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `entry_id`                  | The stable evidence anchor — the `ai_turn_audit` row id.                                       |
| `agent_id`                  | The agent that produced the turn.                                                              |
| `model` (+ `model_version`) | The model that spoke (e.g. `claude-sonnet-4-6`), with a provider version qualifier when known. |
| `outcome`                   | Turn outcome — `ok`, `escalated`, `refused`, `error`, or `cost_capped`.                        |
| `human_overridden`          | Whether a human contested / overrode the turn (GDPR Art. 22 §3 signal).                        |
| `spoke_at`                  | ISO-8601 timestamp at which the AI produced the turn.                                          |

The `summary` section aggregates the whole covered window (even when the
bounded `entries` page only lists the most recent 100, configurable up to 500
via `limit`): total AI-authored turns, human overrides, per-outcome counts,
per-model counts, and the window bounds. The `disclosure_posture` and
`jurisdiction_resolution` sections record which disclosure toggles (EU AI Act
§50, the platform default, Korea AI Basic Act, California SB 243 minor
reminder, marketing-disclosure-required) were in force and *how* the
applicable rules and a contact's minor status were resolved.

## Why regulators ask for it

Two disclosure regimes converge on the same evidence class:

* **EU AI Act Article 50** — requires that a person be told when they are
  interacting with an AI, and that AI-generated content be marked. The ledger
  is the provenance proof that the AI answered *and* that the disclosure was
  actually delivered for that conversation (paired with `metadata.ai_generated`
  and the `first_disclosure_sent_at` per-conversation stamp, so the "notice
  fired" claim is independently checkable).
* **FCC AI-voice disclosure posture** — US voice AI-disclosure posture asks
  for a provable record of when AI handled a call. The voice intro disclosure
  is recorded per call; the ledger is the per-turn evidence that the AI (not a
  human) held the conversation.

Both share one shape: a timestamped, signed, metadata-only audit trail of AI
authorship. The ledger is Orbit's answer to that shape — tenant-owned,
exported on demand, verifiable without Orbit.

## How the audit trail binds conversation → agent → disclosure

The signed export binds four layers into one record, so the tenant can produce
the audit trail on demand:

1. **Immutable per-turn capture** — every completed AI turn writes one
   `ai_turn_audit` row (agent id, model, outcome, timestamp, human-override
   flag). This layer never deletes.
2. **Tenant disclosure posture** — the tenant-scoped AI-disclosure settings are
   read at export time and embedded, so the proof also records *which* rules
   were in force (and how jurisdiction / minor status was resolved).
3. **Fold + detach signature** — the assembler folds the gathered rows into a
   canonical ledger, then stamps a detached HMAC-SHA256 content credential over
   the canonical body (`content_sha256` binds every byte).
4. **Verify** — post the exported JSON ledger to
   `POST /api/v1/agents/ai-disclosure-ledger/verify`; the re-derived credential
   is compared in constant time (`ok` | `content_mismatch` | `signature_invalid`
   \| `unsupported_version` | `malformed_ledger`), so a copy handed to a
   regulator or partner is independently confirmable.

Because the signature covers the whole body, editing any field — a timestamp,
an outcome, the posture — breaks verification. Because the body is canonical
JSON (recursively sorted keys), verification survives a JSON round-trip that
reorders keys.

## How it differs from the guardrail event stream

The two are complementary, not interchangeable:

|                       | AI-disclosure ledger                                                               | Guardrail event stream                                                    |
| --------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Question answered** | *When / where did an AI (not a human) speak, and was the disclosure shown?*        | *What did the agent do, and which guardrail fired or did not fire?*       |
| **Granularity**       | One provenance entry per completed AI-authored turn, folded into aggregate counts. | One event per guardrail evaluation (block / redact / escalate / rewrite). |
| **Audience**          | Regulator / enterprise buyer / procurement due diligence.                          | Operator tuning, safety review, incident reconstruction.                  |
| **Content posture**   | Metadata only — no prompt or response text.                                        | May carry redacted excerpts to explain why a guardrail fired.             |
| **Verification**      | Detached HMAC-SHA256 content credential; independently verifiable.                 | Audit-log trail; not independently signed.                                |

Use the **guardrail event stream** to answer "why did the agent refuse / get
blocked / get rewritten on this turn"; use the **AI-disclosure ledger** to
answer "prove the AI-disclosure posture and authorship timeline." Both read
from the agent's immutable decision log, so the two views agree by construction.

## Reading the export

```bash theme={null}
GET /api/v1/agents/{id}/ai-disclosure-ledger?format=json
```

The response wraps the ledger in `data.ledger`: `ledger_version`,
`generated_at`, `tenant_id`, `agent`, `disclosure_posture`,
`jurisdiction_resolution`, `summary`, `entries`, `note`, `disclaimer`, and the
detached `signature`. Add `?format=html` for a deterministic, fully-escaped
evidence pack (two renders of the same ledger are byte-identical). Auth:
`owner` | `admin` | `developer`. Each export is audit-logged as
`agent.ai_disclosure_ledger.exported`.

A workspace provisioned before the `ai_turn_audit` backing table shipped reads
out as a degraded-but-signed ledger with a `note` rather than a failed export —
the same fault-isolation posture as the conformity dossier.