Java Gaming Leaderboard — Documentation gap: Change Feed _lsn field undocumented, no deserialization warning for typed consumers (all profiles)

[jaydestro]

Documentation gap: Change Feed _lsn field undocumented, no deserialization warning for typed consumers (all profiles)

Field	Value
GitHub	#29
Type	Documentation Gap
Target	MS Learn Change Feed pages — missing system metadata field documentation
Action	Document _lsn and add deserialization warning for typed POJO consumers
Severity	LOW (Agent Kit) / MEDIUM (MS Learn)
Hit Rate	Structural gap — affects 32/34 runs (94%) indirectly via #28
Profiles	All (systemic documentation gap)
Labels	documentation, SCOPE, rule:change-feed, rule:model

---

Summary

Microsoft Learn Change Feed documentation does not document that Change Feed event payloads include Cosmos DB system metadata fields (_lsn, _rid, _ts, _etag, _self). The Java SDK Change Feed examples are incomplete — they do not show how to handle or ignore these fields during deserialization. This documentation gap is the upstream cause of the @JsonIgnoreProperties failure tracked in #28.

Evidence

System metadata fields present in Change Feed payloads:

Field	Documented	Source
_rid	Yes (resource model)	All Cosmos items
_ts	Yes (resource model)	All Cosmos items
_etag	Yes (resource model)	All Cosmos items
_self	Yes (resource model)	All Cosmos items
_lsn	No	Change Feed-specific

MS Learn documentation gaps:

1. _lsn undocumented — not listed in Cosmos DB resource model, not mentioned in Change Feed processor or design patterns pages
2. No deserialization warning — no guidance that raw CF payloads include system fields that break default Jackson deserialization
3. Java SDK CF examples incomplete — Java tab on CF processor page lacks typed deserialization examples

Runtime Error

com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException:
  Unrecognized field "_lsn" (class com.gameapi.leaderboard.model.ScoreEntry),
  not marked as ignorable

Impact

• LOW for Agent Kit — practical fix covered by Java Gaming Leaderboard — Missing @JsonIgnoreProperties(ignoreUnknown = true) — Change Feed fails on system metadata in 94% of runs (all profiles) #28 and Java Gaming Leaderboard — Rule 9.1: No Change Feed idempotency guidance — 100% of CF + counter runs produce non-idempotent handlers (P02, P03) #25 rule enhancements
• MEDIUM for MS Learn — any Java developer using JsonNode → POJO deserialization with Change Feed hits this silently
• Error is per-document but does not crash the CF processor — events are silently dropped

Recommended Action

This is a documentation gap for the MS Learn / Azure SDK docs team, not an Agent Kit rule change:

1. Add _lsn to Change Feed documentation as a CF-specific system field
2. Add a deserialization warning to the CF processor page for typed POJO consumers
3. Complete the Java SDK tab with typed deserialization examples including @JsonIgnoreProperties

Cross-References

• #28 — model-json-serialization rule enhancement (adds @JsonIgnoreProperties requirement)
• #25 — pattern-change-feed-materialized-views rule enhancement (adds idempotency guidance)

References

• Cosmos DB resource model — documents _rid, _ts, _etag, _self but not _lsn
• Change Feed processor — no deserialization guidance
• Change Feed design patterns — no typed POJO examples

[seesharprun]

Ack @seesharprun

[jaydestro]

Closing as redundant. This is a pure MS Learn documentation gap (Change Feed system metadata fields like _lsn, _ts). The Agent Kit fix is already covered by #28 — adding @JsonIgnoreProperties guidance to model-json-serialization rule, which prevents the deserialization failures caused by these undocumented fields.

[jaydestro]

Reopening — documentation gaps are tracked separately and should remain open.

[jaydestro]

@seesharprun im going to close this issue here, after discussion with @TheovanKraay we should file documentation tickets specifically with the team who would be applying the fixes based on the recommendations post-SCOPE run.