# Chat Provider Provenance Ledger

## Purpose

Chat provider provenance records who initiated model-backed work, where it
belongs, which provider/model executed it, and the usage/cost metadata returned
by the provider or runtime. The ledger supports SaaS tenant reporting, local
debugging, budget gates, and audit review without exposing raw prompts or
provider secrets.

## Dimensions

Each model provenance record is scoped by:

- `tenantId`, `workspaceId`, `task`, `runId`, `phase`, and `sessionId` when
  available.
- `role`, `actor`, and `initiatedBy` to distinguish human, parent agent,
  subagent, and system initiated requests.
- `provider`, `model`, `requestId`, `responseId`, `promptId`, and
  `finishReason`.
- `inputTokens`, `outputTokens`, `estimatedCostUsd`, `usageSource`, and
  `costSource`.

Missing tenant/workspace metadata falls back to local aggregate buckets so
existing local workflows remain compatible while SaaS calls can provide full
scope.

## Chat Message Contract

Chat messages may carry provider metadata in `provenance` when the message is
created from model output:

- `provider`, `model`, `requestId`, and `responseId` identify the execution.
- `inputTokens`, `outputTokens`, and `estimatedCostUsd` provide reporting
  context.
- `usageSource` and `costSource` indicate whether values came from the provider,
  runtime, an estimate, or are unavailable.

Persisted chat content remains governed by the existing redaction, retention,
export, and delete policies. Provenance metadata must not contain raw prompts,
secrets, authorization headers, provider base URLs, or unredacted sensitive
payloads.

## Budget And Policy Gates

Budget checks read model provenance events and aggregate by total, role,
provider, tenant, workspace, actor, initiator, and phase. Provider execution
should run preflight budget and egress policy checks before model calls. Blocks
and warnings should record safe metadata only.

## Reporting Defaults

Local usage reports include:

- `totals`
- `byRole`
- `byProvider`
- `byTenant`
- `byWorkspace`
- `byActor`
- `byInitiator`
- `byPhase`

SaaS reporting can use the same shape for tenant/workspace dashboards. Cost
values are estimates unless `costSource` is provider-backed pricing data.

## Follow-Up Work

- Wire public/chat API model responses through provider-backed execution once
  response generation is in scope.
- Add UI reporting for tenant/workspace usage when SaaS dashboards are ready.
- Align export/delete behavior with GH-498 so evidence exports include safe
  ledger metadata only.
- Apply GH-507 restricted-data decisions before any raw sensitive data can be
  retained or sent to providers.