Modello dati/contratto

AiCallEnvelope

AiCallEnvelope is the cross-package contract. It is provider-neutral and designed for agentic attribution.

Area Fields
Provider provider, model, modality
Usage input, output, cached, media units
Cost input, output, total, currency, method
Context tenant, user, cost center, purpose
Agent trace id, agent step
Governance status, policy metadata

Ledger tables

usage ledger

Immutable call rows with pricing provenance and billed cost fields.

budgets

Scoped limits, periods, soft thresholds, and hard enforcement.

policies

Declarative rules and actions for spend governance.

Contract gotcha

Nullable scope IDs

Composite uniques with nullable scope IDs can be racy across databases. The package rules prefer explicit sentinels where uniqueness requires equality.

previous Design next ADR