Amends `docs/nips/NIP-AM.md` with three normative publisher-behavior
changes per the cleared Usage v2 plan (plan v3, D4 + D2').
## Changes
### 1. Cache emission semantics (D4)
Replaces the unconditional `MAY` with qualified obligations:
- Publishers SHOULD emit `cacheReadTokens` / `cacheWriteTokens` when the
provider exposes a cache component.
- Publishers MUST preserve an explicit zero when the provider reports
zero.
- Publishers MUST omit the field (never null or fabricated zero) when
that component is unavailable to the publisher — including when the
provider supports it but the harness does not surface it.
An explicit carve-out in both the JSON comment block and the
Numeric-validity prose exempts these fields from the payload-wide null
guidance. Omission is the only valid representation for an unavailable
cache component.
### 2. Optional `pricingIdentity` field (D2')
Adds an optional, non-nullable `pricingIdentity` object (`authority`,
`model`, `cacheClass`), defined as billing authority — distinct from the
transport `Provider` enum.
- `authority` is a registered billing-namespace identifier: exact
lowercase hostname, no scheme, no path, no trailing slash. Registered
values: `api.anthropic.com`, `api.openai.com`, `openrouter.ai`. The set
extends only by NIP amendment. Pricing lookup is an exact string match
on `(authority, model)`.
- Present only when the publisher can prove applicability: direct
official-endpoint connections prove via the actually-requested resolved
model; other routes MUST receive response-supplied authoritative billing
identity.
- MUST omit for custom/overridden base URLs, gateways (unless the
gateway is the named billing authority), unresolved aliases, and turns
where usage contributions carry more than one billing identity
(including identity-bearing mixed with unresolved).
- `cacheClass` is omitted (not null) when not applicable.
- `pricingIdentity` is optional but not nullable — omission is the only
absence representation.
- The existing `model` field retains its non-billing semantics
(configured/session model) and is never overloaded.
- Consumers MUST treat omission as "price unknown" and MUST NOT infer a
price from the session `model` field.
### 3. Consumer cost guidance (D4)
- Consumers MAY recompute cost estimates using the billing identity and
a pricing manifest.
- Consumers MUST retain the provenance of any cost value (e.g.
`manifest-estimated`, `wire-reported`).
- Consumers MUST NOT merge manifest-estimated and wire-reported costs
into an unlabeled total.
Manifest-vs-wire display preference is application policy and
deliberately excluded from this NIP.
## Scope
Doc-only. Single file: `docs/nips/NIP-AM.md`.
---------
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
