@@ -80,8 +80,9 @@ The `content` field decrypts to a UTF-8 JSON object:
8080 " harness" : " goose" , // REQUIRED: harness identifier
8181 " model" : " claude-sonnet-4-5" , // model id, or null if unknown
8282 " channelId" : " <channel_uuid>" | null ,
83- " sessionId" : " <session_id>" | null ,
83+ " sessionId" : " <session_id>" | null , // REQUIRED when "cumulative" is present
8484 " turnId" : " <turn_id>" | null ,
85+ " turnSeq" : 17 | null , // REQUIRED when "cumulative" is present
8586 " timestamp" : " 2026-07-01T20:11:03.213Z" , // REQUIRED: RFC 3339, end of turn
8687
8788 // Usage for THIS turn (computed delta). Fields are null when the harness
@@ -111,14 +112,49 @@ The `content` field decrypts to a UTF-8 JSON object:
111112```
112113
113114` harness ` and ` timestamp ` are REQUIRED. All other fields are OPTIONAL or
114- nullable. Consumers MUST ignore unknown fields (forward compatibility).
115+ nullable, except as constrained below. Consumers MUST ignore unknown fields
116+ (forward compatibility).
117+
118+ ### Ordering and delta recomputation
119+
120+ When a ` cumulative ` object is present, ` sessionId ` and ` turnSeq ` are
121+ REQUIRED. ` turnSeq ` is a per-session monotonically increasing integer
122+ starting at any value, incremented by the publisher on every published turn
123+ metric for that session; a publisher restart that loses the counter MUST
124+ start a new ` sessionId ` rather than reuse the old one with a reset ` turnSeq ` .
125+ Cumulative values form a series only * within* one ` sessionId ` , ordered by
126+ ` turnSeq ` — consumers MUST NOT diff cumulative values across different
127+ ` sessionId ` s, and MUST NOT rely on ` created_at ` (seconds precision, ambiguous
128+ for same-second turns) for ordering within a session.
129+
130+ If a consumer recomputing deltas observes a cumulative counter that decreases
131+ between consecutive ` turnSeq ` values (counter reset, harness bug), it MUST
132+ treat the affected turn's usage as unknown (null), not as negative usage.
133+ Publishers likewise MUST NOT emit negative values in ` turn ` ; when the
134+ computed delta would be negative or the previous baseline is unknown, the
135+ publisher sets the affected ` turn ` counters to null and `deltaReliable:
136+ false`.
115137
116138Where the harness reports only cumulative counters, the publisher computes
117139` turn ` as the difference between consecutive cumulative snapshots within one
118- session. Publishers MUST set ` deltaReliable: false ` when the baseline is
119- unknown; consumers doing exact accounting SHOULD prefer recomputing deltas
140+ session. Consumers doing exact accounting SHOULD prefer recomputing deltas
120141from consecutive ` cumulative ` values and treat ` turn ` as a convenience.
121142
143+ ### Numeric validity and token semantics
144+
145+ All token counts MUST be non-negative integers. ` costUsd ` MUST be a finite,
146+ non-negative number. ` totalTokens ` is the harness- or provider-reported
147+ total when available; publishers MUST NOT derive it by summing ` inputTokens `
148+ and ` outputTokens ` (providers may count categories a simple sum misses) —
149+ when no total is reported, ` totalTokens ` is null. ` inputTokens ` is the
150+ inclusive input-side total: where the provider reports cache reads/writes
151+ separately (e.g. Anthropic ` cache_read_input_tokens ` /
152+ ` cache_creation_input_tokens ` ), the publisher folds them into ` inputTokens ` .
153+ Publishers MAY additionally report the cache components in optional
154+ ` cacheReadTokens ` / ` cacheWriteTokens ` fields inside ` turn ` and ` cumulative ` ;
155+ when present these are informational subsets of ` inputTokens ` , not additions
156+ to it.
157+
122158` costUsd ` values are estimates (provider list prices at publish time, or a
123159harness-reported estimate). They are advisory, not billing records.
124160
@@ -148,8 +184,13 @@ On receiving a kind 44200 event, a relay MUST:
148184 searchable and must not enter search indexes).
149185
150186Reads MUST be gated: only an authenticated ([ NIP-42] ( 42.md ) ) reader whose
151- pubkey equals the ` #p ` tag value may receive the event. Unauthorized publish
152- or subscribe attempts MUST be rejected with ` AUTH required ` .
187+ pubkey equals the ` #p ` tag value may receive the event. This gate applies to
188+ ** every** read path, including explicit ` ids ` filters — knowing an event id
189+ MUST NOT grant access. (Some p-gated kinds exempt id-addressed lookups on the
190+ theory that knowing the id implies authorization; kind 44200 events are
191+ long-lived and their cleartext envelope leaks turn activity, so no such
192+ exemption is permitted.) Unauthorized publish or subscribe attempts MUST be
193+ rejected with ` AUTH required ` .
153194
154195Relays SHOULD rate-limit kind 44200 to a rate consistent with real turn
155196frequency (RECOMMENDED: 60 events/minute per agent pubkey).
@@ -164,7 +205,10 @@ Owners recover usage history with:
164205
165206On receiving an event, a client MUST verify the signature, decrypt with its
166207own secret key and ` event.pubkey ` , and ignore events that fail to decrypt or
167- parse. Clients SHOULD deduplicate by event id and sort by ` created_at ` .
208+ parse. Clients SHOULD deduplicate by event id. For within-session ordering,
209+ clients MUST use ` (sessionId, turnSeq) ` from the decrypted payload as
210+ described above; ` created_at ` is suitable only for coarse time-window
211+ queries.
168212
169213## Relationship to Other NIPs
170214
0 commit comments