## Problem Every bridge post object embeds up to 1000 votes (`active_votes`). Hivemind looks them up and serialises them on every feed, profile and post call, and front ends mostly throw them away. - **The cost is real and mostly wasted.** One `bridge.get_ranked_posts` call (`sort=trending`, `limit=20`, api.hive.blog, 2026-10-09) returned 566 KB. 329 KB of it (58%) was `active_votes`: 7,677 vote rows, one post at the 1000 cap. Post bodies were 160 KB (28%). With `sort=created` votes were 21% of 136 KB. Front ends have started stripping them server-side because they don't use them: denser #1011 (`apps/blog/lib/feed-entries.ts`, "roughly half of the server HTML") and ecency (`apps/web/src/core/react-query/strip-active-votes.ts`). They still pay for hivemind to look them up and send them. - **The embedded list is wrong for its main use.** Front ends read `active_votes` to show whether the logged-in user voted. `list_votes(..., 1000, 'get_votes_for_posts', ...)` (`postgrest/utilities/create_bridge_post_object.sql:69`) orders by `voter_id` and cuts at 1000 (`postgrest/utilities/list_votes.sql:94-101`). On a post with more than 1000 votes, newer accounts' votes are dropped. `observer` only filters muted voters (`list_votes.sql:93`); it doesn't guarantee the observer's own vote is included. Reported in Mattermost 2025-05-19 (asgarth, peakd): a user voted about six times on `@themarkymark/how-much-hive-can-we-burn-in-one-post` because his vote never showed. - **Bridge has no paginated vote call.** Front ends use `database_api.list_votes` as the workaround: limit 1–1000, `by_comment_voter` with an inclusive start (`postgrest/database_api/database_api_list_votes.sql`; `list_votes.sql:89`), so every page repeats the last voter. `condenser_api.get_active_votes` and `database_api.find_votes` are capped at 1000 with no pagination. Changing the existing calls has been blocked for years, because every front end, bot, library and mobile app depends on their shape. This issue changes none of them. It adds new calls that sites adopt when they're ready. ## Design ### 1. Vote-free post calls New `bridge` methods, same parameters and behaviour as the existing ones except for votes: | New method | Same as | |---|---| | `bridge.get_ranked_posts_v2` | `bridge.get_ranked_posts` | | `bridge.get_account_posts_v2` | `bridge.get_account_posts` | | `bridge.get_post_v2` | `bridge.get_post` | | `bridge.get_discussion_v2` | `bridge.get_discussion` | Each post object (including `original_entry` / reblogs and every entry in a discussion) differs from the existing shape in exactly these ways: - **`active_votes` is absent.** It is omitted, not `[]`, so no client can read an empty list as "nobody voted". - **`observer_vote`** is `{"rshares": <int>, "percent": <int>}` when `observer` is given and has voted on the post, and `null` otherwise, including when no observer is given. It comes from one index probe on `hive_votes (post_id, voter_id)` (`hive_votes_post_id_voter_id_idx`), so it's correct on posts of any size. - **`top_votes`** (optional): a new parameter `top_votes` (integer, 0–10, default 0) adds a `top_votes` array of the N votes with the largest `|rshares|`, each `{"voter", "rshares", "percent"}`. It's for front ends that show a few voter avatars on cards (peakd). `percent` tells a 0-rshares vote apart from a removed one, the ambiguity #152 raised. At 0 the key is absent and nothing is looked up. - **`stats.total_votes`** is unchanged. It's the authoritative count. Accepted parameters are the existing method's plus `top_votes`. Unknown parameters are refused exactly as today (`validate_json_arguments`). ### 2. `bridge.list_votes` Parameters: `author`, `permlink` (required), `start` (voter name, exclusive, optional), `limit` (1–1000, default 100), `observer` (optional; filters voters the observer muted, as today). Result: an array of `{"voter", "rshares", "percent", "weight", "time", "reputation"}`, ordered by `voter_id` (served by `hive_votes_post_id_voter_id_idx`). The next page starts after the last returned voter, so there are no repeats. An empty array means the list is complete. ### Non-goals - No change to any existing method, its parameters or its output. All existing tavern patterns (including the 265 files under `bridge_api_patterns/` that contain `active_votes`) must pass unchanged. - No condenser_api variants: condenser_api is semi-deprecated, and its consumers can move to bridge. - Fixing `observer`'s vote on the existing calls is a separate, optional follow-up issue. - No deprecation schedule for the old calls. That is decided later, from adoption. ## Implementation 1. **`postgrest/utilities/create_bridge_post_object.sql`**: add `IN _votes_mode SMALLINT DEFAULT 0` (0 = embedded list, as today; 1 = vote-free) and `IN _top_votes INT DEFAULT 0`. In mode 1, skip the `list_votes` call, add `observer_vote` (`SELECT rshares, vote_percent FROM hivemind_app.hive_votes WHERE post_id = _row.id AND voter_id = _observer_id`, only when `_observer_id <> 0`), and when `_top_votes > 0` add `top_votes`: `SELECT voter, rshares, vote_percent ... WHERE post_id = _row.id ORDER BY abs(rshares) DESC LIMIT _top_votes`. Defaults keep every existing caller byte-identical. 2. **Thread the mode through the shared builders**: `utilities/get_ranked_posts.sql` (every `create_bridge_post_object` call site, about 10), `utilities/get_account_posts.sql` (about 6), `bridge_api/bridge_api_get_post.sql`, `bridge_api/bridge_api_get_discussion.sql`. Add a trailing `_votes_mode` / `_top_votes` argument with a default of today's behaviour to the utility functions those endpoints call. The condenser paths (`_called_from_bridge_api = False`) are untouched. 3. **New endpoint functions** `hivemind_endpoints.bridge_api_get_ranked_posts_v2` etc. Each validates the existing parameter set plus `top_votes` (`valid_number`, 0–10), then calls the shared builders with `_votes_mode = 1`. Register them in `postgrest/utilities/get_api_method.sql` `get_bridge_method` (next to the existing `get_ranked_posts` / `get_post` / `get_account_posts` / `get_discussion` arms) and in the script list in `hive/db/schema.py`. 4. **`bridge.list_votes`**: a new `bridge_api/bridge_api_list_votes.sql`. Reuse `utilities/list_votes.sql` with a new `list_votes_case` value for exclusive-start paging, and a new `vote_presentation` value for the result shape (`reputation` via `rep_log10` of the voter's reputation, as other bridge objects do). Register it in `get_bridge_method` and `schema.py`. 5. **Docs**: describe the five new methods wherever the bridge API is documented for clients (`hive/db/sql_scripts/endpoints/endpoint_schema.sql` if bridge methods are listed there; otherwise the README section for bridge). Include one migration paragraph for front ends: switch to `*_v2`, read `observer_vote`, and fall back to the old method when a node answers `unknown method` (older nodes). ## Acceptance - **Old calls unchanged**: every existing tavern pattern passes byte-identically. - **New tavern patterns** under `bridge_api_patterns/` for each `*_v2` method, covering the same sort and parameter matrix as the existing patterns for that method (one pattern per existing directory, e.g. `get_ranked_posts_v2/{trending,hot,created,payout,payout_comments,muted}`): - `active_votes` is absent; - `observer_vote` is `null` without an observer, `null` for an observer who didn't vote, and equals the vote's `rshares`/`percent` for one who did; - `top_votes` is absent at 0, and holds at most N `{voter, rshares, percent}` entries ordered by `|rshares|` desc at N; - all other fields equal the old method's output for the same parameters (a pattern pair or a scripted field-by-field diff). - **The over-1000 case**: a test with a post carrying more than 1000 votes (mock data or a SQL-level test) where the observer's `voter_id` sorts after the first 1000. `bridge.get_post_v2` returns that observer's `observer_vote`, while `bridge.get_post`'s `active_votes` lacks it (documenting today's behaviour). - **`bridge.list_votes`**: paging a post with more votes than `limit` returns every voter exactly once across pages, ends with an empty page, and refuses `limit` > 1000 and a missing `author` or `permlink`. - **Size**: on the mock dataset, `bridge.get_ranked_posts_v2` (`sort=trending`, `limit=20`) returns a smaller response than `bridge.get_ranked_posts` with the same parameters. Record the two sizes in the MR or commit message. - **Negative patterns** (`bridge_api_negative/`): `top_votes` of -1 and 11 are refused, and unknown parameters on `*_v2` are refused. ## Supersedes This covers what #133, #152, #169 and #319 asked for, as new calls rather than changes to the existing ones. Those issues are closed with a pointer here.