cards_collection

Each row adds numeric rarity (1 common, 2 rare, 3 epic, 4 legendary), max_level, max_land_base_pp (offline set/rarity/foil reference; null when unknown), bcx_max, maxed, overlevelled and excess_bcx. The level cap comes from definition level arrays or the rarity cap in the official /settings tables; maxed compares BCX against the set/rarity/foil threshold, including excess BCX; black foils are maxed at issue (see https://docs.splinterlands.com/cards/combining-cards). Missing definitions yield null and a warning; unresolved caps stay null. maxed=true/false is applied before paging and can be combined with min_land_base_pp (AND); for maxed OR non-maxed at 1000 PP, make those two filtered calls. For each copy, card_set is the main set and edition is a numeric print identity (see splinterlands://cards/editions). Each copy also returns main_set, main_set_label, print_class and sub_set; unknown editions set edition_unmapped. 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 for the requested page, up to 100, unless the collection is small enough for the index described below, which retains every projected card. Each emitted card contains uid, card_detail_id, edition, gold, foil, level, xp, bcx, collection_power and card_set. Each card also carries owner (the row's player field: the owning account, which differs from the requested username for delegated-in or rented-in cards), delegated_to, rental_type, rental_date, rental_days, next_rental_payment, market_id, market_listing_type, market_listing_status, lock_days, unlock_date and last_transferred_date, as measured on 2026-10-11. A null value is the upstream null. If the wire row omits one of these fields, the card lists it in ownership_unknown; an absent field is unknown, never a value meaning none. rental_type and market_listing_type also appear on cards that are only listed and not rented, so a rental is indicated by rental_date, not by rental_type alone. all=true returns a compact projection of uid, card_detail_id, level, bcx, foil, edition, card_set, land_base_pp, rarity, max_level, maxed, bcx_max, overlevelled and excess_bcx, plus reported_stake_plot_reference when include_plot_references is set, in pages of up to 100. The source card object carried 56 fields in the 2026-09-08 capture and 60 in 2026-10-11; this projection keeps the ten core fields plus the optional land, staking and ownership fields described here, 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, main_set, print_class, 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. A collection of up to 25,000 cards is read once and held as a projected index for 120 seconds per username (40,000 cards across all usernames, least recently used evicted first). Every cursor, filter and compact page is served from that index without another upstream read. Every page reports index.observed_at and index.age_ms, the time of the upstream read. A larger collection is not indexed: one successful page is cached for 60 seconds, and a different page or filter re-streams the full collection. index.source says which path served the page. A card-definition refresh invalidates the index. 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.