Repository navigation
decision: keep precise droppedFields vs. introduce a generic write-path warnings envelope #3477
Description
Split out from #3455 / #3468 (the issue's open question).
Context
Single-write (#3448) and bulk (#3468) write responses now carry a precise, typed droppedFields: DroppedFieldsEvent[] — { object, fields, reason: 'readonly' | 'readonly_when' } — surfacing caller-supplied fields that were legally stripped before the write.
The current decision (shipped) is precise droppedFields, reusing DroppedFieldsEventSchema, chosen for symmetry between the single-write and bulk paths.
The open question
If more write-path warning classes are anticipated — e.g. value truncation, silent type coercion, deprecated-field writes, unit/precision normalization — a per-class field on every write response (droppedFields, truncatedFields, coercedFields, …) does not scale. A single generic envelope would:
warnings?: Array<{ code: string; object?: string; fields?: string[]; message?: string; meta?: … }>
with droppedFields becoming one code.
Trade-off
- Keep precise (status quo): strongly typed, self-documenting, zero migration; but a new warning class = a new response field each time.
- Generic envelope: one extensible channel; but a breaking-ish migration that must move single and bulk together (both shipped with
droppedFields), and loses per-class static typing unless the union is well-modeled.
Recommendation
Defer unless/until a second concrete warning class is on the roadmap. If one appears, do the envelope migration once, across single + bulk simultaneously, and keep droppedFields as a typed alias/code for backward compatibility during a deprecation window.
Activity
os-zhuang commentedon Jul 25, 2026
Closing as resolved by decision (2026-07-25): keep the precise, typed `droppedFields` — no generic warnings envelope.
Verified there is no second write-path warning class anywhere today: no value truncation, no silent write-side coercion (`coerceBooleanFields` in the engine is result-side normalization, not a payload mutation), no existing `warnings` field anywhere in the API spec, and none of the anticipated classes (truncation / coercion / deprecated-field writes / unit normalization) is on any roadmap. The soft trigger this issue was waiting on has no candidate.
Migration design, recorded so it never needs re-derivation — if a second class ever materializes:
Hard triggers that should reopen this decision (instead of the soft "on the roadmap"):