Skip to content

Commit 19889ba

Browse files
npub1fgdl5qqnh3k3f2xkqrvt7cujalhm623x4s7fdjdj5yrtp5fzjl9qrjpucwwpfleger96
andcommitted
docs(nips): harden NIP-AM read gate and delta ordering semantics
Address design-review findings: forbid the id-lookup exemption from the 44200 owner gate (a non-owner learning an event id must not retrieve the envelope), require sessionId + a monotonic turnSeq whenever cumulative usage is present so consumers can deterministically recompute deltas (created_at is seconds-precision and unordered within a second), define counter-reset behavior as null-not-negative, and add normative numeric validity and cache-token-folding rules. Co-authored-by: Will Pfleger <[email protected]> Signed-off-by: Will Pfleger <[email protected]>
1 parent a44dde0 commit 19889ba

1 file changed

Lines changed: 51 additions & 7 deletions

File tree

‎docs/nips/NIP-AM.md‎

Lines changed: 51 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -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

116138
Where 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
120141
from 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
123159
harness-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

150186
Reads 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

154195
Relays SHOULD rate-limit kind 44200 to a rate consistent with real turn
155196
frequency (RECOMMENDED: 60 events/minute per agent pubkey).
@@ -164,7 +205,10 @@ Owners recover usage history with:
164205

165206
On receiving an event, a client MUST verify the signature, decrypt with its
166207
own 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

Comments
 (0)