> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/trust/audit-observability-and-compliance.md).

# Audit, Observability & Compliance

Every call leaves a trace; every trace is reconstructable; audit is append-only by enforcement.

> **Every call leaves a trace. Every trace is reconstructable. The evidence chain is append-only.** Audit is not an afterthought bolted onto the gateway — it is one of the gateway's enforcement stages.

***

## The audit posture in one paragraph

Every tool call that crosses the gateway emits a trace ID at entry, threads that trace ID through identity, authorization, billing, and dispatch, and lands a structured audit record on the success path. Errors carry the same trace ID so support can pivot from a customer report to the full call history without asking the customer for anything beyond that one identifier. Audit records are append-only; the data layer enforces it.

***

## The trace ID is the join key

```
Request enters gateway
  ↓ X-Trace-Id stamped at entry
Identity → Org → Authz → Rate → Billing → Audit → Dispatch
  ↓
Family runtime executes (trace ID propagated)
  ↓
Response (X-Trace-Id in headers + error envelopes)
  ↓
Audit row · Billing ledger entry · Runtime log line
   — all keyed by the same trace ID —
```

Wherever the call goes, the trace ID goes with it. That is what makes an audit row, a billing ledger movement, a runtime log line, and a customer-visible error envelope all reconstructable from a single piece of information.

***

## What's in an audit record

Each successful tool call produces one immutable audit row. The shape the platform commits to:

| Field            | What it captures                                                              |
| ---------------- | ----------------------------------------------------------------------------- |
| Trace ID         | The same `X-Trace-Id` returned to the caller and propagated to the runtime.   |
| Organization     | The server-derived tenant context.                                            |
| Principal        | The Auth0-resolved caller identity.                                           |
| Surface called   | The qualified surface name (the tool the agent invoked).                      |
| Resource family  | One of MCP / Skill / MediaClaw / Workflow / Agent.                            |
| Authorization    | The decision the authorization stage produced (allowed, denied, with reason). |
| Cost attribution | The credit ledger movement linked to this call.                               |
| Outcome          | Success / failure with structured error category.                             |
| Timestamp        | The gateway-stamped time at entry.                                            |

What is **not** in an audit row by default: the agent's free-form prompt text, the runtime's full payload, or any credential. Credentials are never included. Prompt text and full payload are excluded by default to keep audit rows operationally clean — customers with regulated workloads that require prompt-level capture can configure deeper retention as part of their enterprise agreement.

***

## Append-only by enforcement

Audit records are immutable. New records are appended; existing records are not edited or removed. The data layer enforces it directly — not by convention, and not by trusting application code to behave.

The same posture applies to other evidence artifacts on the platform:

* **Evidence Cards** that MediaClaws emit during a run are immutable — enforced at the platform's data layer, not by convention.
* **Provenance Passports** in the Media Library are append-only — new events are added; existing events are not edited.

Append-only is the platform's stance on every evidence surface, not a property of one specific log.

***

## Observability beyond audit

Audit answers "what happened, who did it, what did it cost?" That is not the only observability surface. The platform also exposes:

| Layer              | What it shows                                                                                       |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| Per-call telemetry | Tracing, structured logs, error categories, usage analytics — emitted as the call runs.             |
| Per-org analytics  | Spend, surface usage, error rates, latency distribution — rolled up to the organization.            |
| Per-run timeline   | For MediaClaw runs: the plan, every step, every Evidence Card, every cost — readable end-to-end.    |
| Pippa control room | A web/mobile surface that aggregates across MCP servers, MediaClaws, and workflows for an operator. |

Customers running their own observability stack can integrate at the per-call telemetry layer. The platform's posture is: emit structured events with consistent trace correlation, and let the customer's existing log aggregation, error reporting, and analytics pipelines consume them.

***

## What customer-support correlation looks like

A customer reports a failed run. The audit chain works like this:

1. The customer hands support the trace ID — it appeared in the error envelope and in the response headers.
2. Support pivots from the trace ID to the audit row: principal, organization, surface, time, outcome.
3. From the audit row, support pivots to the billing ledger movement for that call: what credit was charged, why.
4. From the audit row, support pivots to the runtime log line: what the runtime received and returned.
5. From the runtime log line, support reaches the Evidence Cards (if the call was part of a MediaClaw run) and the Provenance Passport updates (if the call mutated Media Library state).

That entire chain is keyed by one piece of information. There is no step in the chain that requires the customer to share a secret.

***

## Compliance posture

The platform commits to:

* An immutable audit row on every successful governed call, plus trace-correlated structured error logs on every failure path. The trace ID joins both, so a support investigation pivots on one identifier whether the call ran or not.
* Append-only evidence enforced at the data layer.
* Server-derived tenant context on every authorization and audit decision.
* Trace correlation across audit, billing, and runtime so external evidence requests are reproducible.

What the platform does **not** commit to in launch documentation:

* A specific number for retention. Retention is supported per organization configuration and enterprise policy. Where a customer's procurement or regulatory profile requires a hard retention term, that term is set in the customer agreement.
* A specific compliance certification badge. The platform's enterprise readiness page (43) covers the procurement-facing posture; specific certifications and audit reports are shared under NDA during procurement, not in public documentation.

***

## Where to go next

| If you're…                                   | Read next                                                                           |
| -------------------------------------------- | ----------------------------------------------------------------------------------- |
| Looking at identity and tenant boundaries    | [Identity & Authentication](/trust/identity-and-authentication.md)                  |
|                                              | [Multi-Tenant Organization Model](/trust/multi-tenant-organization-model.md)        |
| Studying the gateway's full chain            | [The Gateway](/platform/gateway.md)                                                 |
| Reviewing decision memory across runs        | [Decision Tracing & Learning Loop](/platform/decision-tracing-and-learning-loop.md) |
| Looking for enterprise procurement readiness | [Enterprise Readiness](/trust/enterprise-readiness.md)                              |