cards_collection

Optional include_plot_references adds reported_stake_plot_reference with verified padded label, numeric ID and deed UID to returned cards using at most one account-scoped deed search (limit 200); the call then permits three logical GETs instead of two. Unresolved or conflicting references remain null with explicit status and separate freshness. This is not complete holdings discovery. Cooling cards have left their old plot; a retained reference is historical. The projected collection cache is reused when only this option changes, and plot references are read afresh. Joined metadata exposes normalized element and secondary_element, plus only the selected level’s land_abilities and land_abilities_status. Missing level entries are unknown, never an invented empty ability list; absent ability tables mean no Land abilities in that definition. Raw numeric land_dec_stake_needed is retained if present. The element filter matches either normalized element. For known edition-19 cards, land_lineup_estimate resolves its dated abilities itself; omit an explicit abilities override there. Other cards can use the returned ability tuples, subject to estimator-supported codes. Optional stake_start_date, stake_end_date and numeric stake_plot are retained when present. staking_status and staking_observed_at classify one capture as staked, unstaking, unstaked, pending or unknown; cached pages preserve that classification time. Missing dates are unknown, not unstaked. Local staked=yes selects active staking, staked=no selects explicitly unstaked cards (not cooling or pending), and staked=plot requires numeric stake_plot_id. Plot labels are not inferred from an unverified numeric reference. These filters make no extra request. Stream the projected collection returned by GET /cards/collection/{username}. The upstream response has exactly {player,cards[]} and no total, count, cursor, page token or other pagination field; no narrower query was available in the measured collection evidence. The route-size and memory measurements are recorded in library/observations/collection-streaming-memory-2026-09-08.md. The server never materialises the upstream body: it parses cards[] incrementally, skips unprojected fields, counts matching cards, and retains only the projected cards in the requested page, up to 100. Each emitted card contains uid, card_detail_id, edition, gold, foil, level, xp, bcx, collection_power and card_set. The source card object carried 56 fields; this projection keeps the ten core fields plus land_base_pp when present, and makes no byte-saving claim. In the upstream wire types, land_base_pp and last_buy_price are numeric-looking JSON strings, while bcx, xp, collection_power and level are real JSON numbers; land_base_pp is retained as its original decimal string and last_buy_price is not projected. A missing land_base_pp stays absent; an observed null stays null. Both mean unknown production and never pass a min_land_base_pp filter, including a zero threshold. Malformed or non-finite production strings are refused; the latter four fields are returned as numbers. Card definitions are joined by card_detail_id, adding name, color, secondary_color when present and sub_type. Color and subtype filters are case-insensitive exact matches; color matches either primary or secondary color. Unknown definitions retain the instance without invented fields, never match metadata filters, and are counted in definition_missing_count across the full scanned collection before filtering. The complete definition catalogue is fetched under the existing 2 MiB cap and projected into one 24-hour cache; only joined page fields are returned. This tool may use two logical GET requests (definitions plus collection). Definition failure stops before reading the collection. Definition refresh invalidates the joined page cache, and metadata freshness is separate. Local filters are color, sub_type, gold, edition, foil, card_set, min_level, min_collection_power and min_land_base_pp; cursor is a zero-based filtered-result offset and limit defaults to 100 with a maximum of 100. This server's heap-occupancy guard is 128 MiB: the highest observed production-path value was 90.71 MiB of unforced heapUsed; the occupancy backstop is wider because GC timing can vary, so it needs operational slack. Production normally has no --expose-gc, so heapUsed is high-water heap occupancy including uncollected garbage, not a retention bound. If global.gc is exposed, as it may be in a diagnostic/test process, the server calls it before sampling to reduce transient garbage. Retention was measured separately at about 9.4 MiB flat under forced GC and is verified by test, not at runtime. A separate 358 MiB RSS operational ceiling is based on the highest RSS observed across the measurement rounds: 286.4 MiB in the forced-GC diagnosis, higher than the 278.08 MiB RSS maximum of the final production-path runs. RSS is a separate process-occupancy backstop, not a retention bound, and includes memory outside the V8 heap and uncollected garbage. Neither runtime number bounds retention: both are occupancy guards at different scopes, while retention is verified by measurement, not enforced at runtime. Memory is sampled every 256 parsed cards, plus once at the end when needed; on the measured 51,799-card run that means at most 203 cadence samples, and a regression is detected within 256 parsed cards without a memory call on every card. The route uses a 90-second timeout chosen by this server behind the measured 41-second fetch; a timeout is attempted once and is not retried. The global 2 MB response cap is unchanged for every other route and is not raised for this exception. One successful page is cached for 60 seconds per username, retaining at most that page; cache reuse requires the same filter, cursor and limit request. A different page or filter is a cache miss, re-streams and re-parses the full collection, and replaces that username's cached page because the upstream has no pagination; the cached page re-streams after expiry. The fixture is deliberately trimmed to three cards with representative raw fields rather than the measured 155 MiB response; the fixture declares every concrete array index and is only a contract sample. No account name is embedded in this server source, and this server remains version 0.0.0 with no remote delivery path.