Skip to content
SHC Docs

Marketplace: SIGNALS → SCORES → COLLECTIONS: 2026-08-19

Owner ruling, 2026-08-19, on what the marketplace calls the three kinds of number it puts on an app: the raw changing facts, the things computed from them, and the ranked lists computed from those.

“ensure our marketplace also captures this information. what do we call all the data around an app in the marketplace that is like metrics and shit like around downloads, reviews (stars), etc… like the stuff that’s always changing and shit that we use to calculate things from like trending and shit, and then what do we call the aggregated stuff like trending for example or like a security score.”

Asked over a screenshot of Flathub’s tab row: Trending · Popular · New · Updated.


Three tiers, three words. Two are adopted as proposed; the third KEEPS THE NAME IT ALREADY HAD IN THE CODE.

tiernamewhat it iswhere it lives
1SIGNALa raw, observed, always-changing fact about ONE app at ONE moment. Observed, never computed. Append-only and point-in-time.App Signal Snapshot, App Review, App Comment Vote, Install Dispatch
2SCOREa scalar DERIVED from signals on a schedule. A deterministic function of (signals, window), recomputable from scratch, one number per app.denormalised columns on App Listing
3COLLECTIONan ordered SLICE derived from scores. A ranked list, not a number.features/marketplace/src/collections/, /apps/collection/<id>

★ Tier 3 is Collection, not Chart, and that is the one amendment

Section titled “★ Tier 3 is Collection, not Chart, and that is the one amendment”

“Chart” was the proposed word and it is not adopted, because the storefront shipped a word for this first and shipped it everywhere:

  • the type CollectionId and the table COLLECTIONS (features/marketplace/src/collections/collections.ts);
  • the route apps/marketplace/routes/apps/collection/[collection].tsx, so /apps/collection/trending is a published URL;
  • the i18n namespace marketplace.collection.*, 20-odd keys, translated into English and Spanish;
  • catalogueFooterLinks(), which the storefront footer is built from.

Renaming buys nothing and costs a URL contract, a translation pass and a migration of keys somebody will half-finish. The rule stands the way the owner stated it: adopt the vocabulary unless the codebase already has a better-established term, and keep the existing one when it does. It does, so it is kept.

Tiers 1 and 2 had no established term at all (nothing in the tree was named signal or carried a per-app score), so they are adopted verbatim.

★ The one collision, and how it is disambiguated

Section titled “★ The one collision, and how it is disambiguated”

App Comment.score already exists and means ups minus downs on one comment (marketplace/community/ranking.py). That is a per-COMMENT integer, not a per-APP scalar, and it is not renamed either. Tier-2 fields on App Listing are therefore always qualified by what they measure (install_cluster_count, install_trend_delta, rating_average), and the bare word score is reserved for prose. No field is named score.


What each tier holds today: the honest inventory

Section titled “What each tier holds today: the honest inventory”

Measured against origin/main and against the live bench (api.marketplace.selfhostedcloud.org, read-only, 2026-08-19).

signalmodelledcollectedretained over time
install dispatches (state, settled_on, code)✅ Install Dispatch (portal app)⛔ zero rows; no portal_dispatch_key minted✅ rows are append-only and dated
heartbeat inventory (Cluster.app_inventory)✅ Cluster (portal app)⛔ no registered clusters⛔ current state only: a JSON blob overwritten by each heartbeat
review stars✅ App Review⛔ zero; the module is absent from production✅ rows are append-only and dated
comment votes✅ App Comment Vote⛔ zero, same reason✅
install-count observations✅ App Signal Snapshot, NEW, this lanepending deploy✅ one reading per app per day
CVE / advisory counts⛔ vapour⛔⛔
page viewsrefused; see below
scoremodelledcomputeddisplayed
install_cluster_count✅✅ hourly sweep, k-anonymity floor of 5 applied at write✅ listing page + Popular
install_trend_delta✅ NEW, this lane✅ hourly, second floor on the delta✅ Trending
rating_average / rating_histogram / comment_count✅✅ on every community write✅ listing page
App Comment.rank (Wilson lower bound, 95%, no time decay)✅✅✅ comment order
trust / security / freshness / operability⛔ VAPOUR, designed in docs/proposals/2026-08-18-app-metrics-and-trust.md, nothing landed⛔⛔
collectionbasisranks today
newApp Listing.creation✅ 167 rows
updatedApp Listing.modified✅ 167 rows
popularinstall_cluster_count⛔ 0 rows
trendinginstall_trend_delta⛔ 0 rows

Also in tier 3 but NOT measurements, and deliberately kept apart from the three tiers: App Featuring (a curator’s time-boxed promotion with a blurb) and App Badge (flagship, derived or hand-curated). Featuring is an EDITORIAL act by a named person with a date on it. It is not a signal, it does not derive a score, and it must never be folded into one; otherwise the store is ranking itself.


Section titled “★ Trending is now computable. Here is exactly what changed.”

It was refused, correctly, on the grounds that install_cluster_count “is one integer per app” with “no time dimension at all”. That was a statement about retention, not about ranking code: the hourly sweep overwrote the integer and the previous reading was thrown away, so there was never anything to take a difference of.

This lane retains the readings and nothing else. App Signal Snapshot stores one observation per app per day (the same tally marketplace/community/installs.py already computed for the column), and install_trend_delta is the difference between the reading at the end of a 30-day window and the newest reading before the start of it.

No new collection. No new wire field. No new telemetry channel. The heartbeat is unchanged, AppEntry gains no field, and an unregistered estate is still not counted; not counted as zero; not counted.

The second privacy floor, which the first one does not cover

Section titled “The second privacy floor, which the first one does not cover”

installs.min_display_count floors the level. It does not floor a difference, and a difference re-identifies on its own:

an app publishing “8 installs from registered clusters” one week and “9” the next has published that one named estate installed that app that week. Joined to a verified-install review from the same window (written by construction by somebody whose cluster ran the app), that is a single identified customer.

That is the identical join the level floor was chosen to break, arriving through the time axis instead of the count axis. So signals.min_display_delta (5) floors the delta, a fall is never published, and the Guest-readable column collapses “no baseline yet”, “a fall” and “a rise below the floor” into one 0, because a column that could tell those apart would leak the distinction the floor exists to hide.

A delta can never exceed the level it was measured to, so a publishable trend always sits on a publishable level. Trending switches on for the same apps Popular does, one window later, never before. Pinned in frappe/apps/marketplace/tests/test_signals.py.

The snapshot table may hold the true count; the listing may not

Section titled “The snapshot table may hold the true count; the listing may not”

App Listing is Guest-readable, so it carries censored values. App Signal Snapshot has no Guest permission row, so it carries true ones and the floors are applied on the way out. Storing censored readings in both places would make the history useless for exactly the case it exists for: an app crossing the floor would show a delta computed from a censored baseline, which is a wrong number rather than a withheld one. A test pins the absence of that permission row.


★ The charts are structurally empty today. Measured, not estimated.

Section titled “★ The charts are structurally empty today. Measured, not estimated.”

The owner needs this before shipping the tab row.

measurementvaluehow
published listings on the live bench167 (90 apps, 77 add-ons)GET /api/resource/App Listing?filters=[["published","=",1]]
listings with a publishable install_cluster_count0the column does not exist on the production bench: 417 DataError: Field not permitted in query: install_cluster_count
listings with a publishable install_trend_delta0ditto, and it needs a 30-day history that starts accruing on deploy
App Version rows90one per app
…carrying a released_on0every one is NULL
marketplace.community module on productionabsent417 ValidationError: … No module named 'marketplace.community'
marketplace.curation module on productionabsentsame shape
distinct creation days across 167 rows2 (90 on 2026-08-15, 77 on 2026-08-18)so New/Updated are real orderings over a two-batch import, which the page already states in numbers it computes

So: two of the four collections rank the whole catalogue and two rank nothing. That is not a bug and it is not hidden; each empty page renders a panel naming the missing measurement and links to the page that fills first.

The structural condition, stated so it is not discovered later: Popular needs five registered clusters reporting the same app, ever. Trending needs five inside one 30-day window, on top of a baseline reading that predates it. On an estate population where the portal has no registered clusters at all, both are empty for as long as that stays true, and the k-anonymity floor means a small population produces an empty page rather than a sparse one. Lowering the floor is not the fix and is not on the table; the floor is what stops the count identifying a customer.


  • Any usage signal. Not a launch, a request, a session, a page view, a login, a user count. There is no field in the heartbeat that could carry one.
  • The per-version install histogram. AppEntry.Version rides the heartbeat and nothing today breaks the count down by version. Joined to a published CVE posture it stops being a metric and becomes a sized, prioritised target list.
  • Anything derived from an unregistered estate. There is nothing to derive.
  • A composite “trust score”. Coverage of its inputs is 0/90 for CVE, 0/167 for ratings and 0/90 for release recency; a weighted sum written today resolves arithmetically to packaging hygiene while printing itself under a heading that says trust. The gate conditions for revisiting it are in docs/proposals/2026-08-18-app-metrics-and-trust.md §5 and are unchanged by this ruling.
  • Installs as a sort key for anything other than the two pages that name them. Adoption is a fact, not a quality judgement.

  • frappe/apps/marketplace/marketplace/community/signals.py: the tier vocabulary, the window, both floors, and the pure delta arithmetic.
  • App Signal Snapshot DocType: append-only, one row per app per signal per day, unique-keyed, no Guest permission.
  • recompute_install_counts also records the observation and denormalises install_trend_delta / install_trend_window_days / install_trend_as_of.
  • prune_signal_snapshots, daily, bounding the table at 400 days.
  • frappe/apps/marketplace/tests/test_signals.py: 27 tests.
  • Storefront: trending moves from basis: "unbuilt" to basis: "install-trend", orderByTrend, the loader read, the card stamp (+11 clusters in 30 days), and the panel copy in en and es.
  1. Deploy. Production is many migrations behind; none of the community, curation or signal schema is on the bench. Nothing above renders until bench migrate runs there.
  2. The portal inventory opt-out. daemon/wiring/portal_wire.go wires Apps: localAppInventory unconditionally, so a registered estate cannot decline the inventory. A trust score must not come to depend on install data before that toggle exists, or the score becomes a reason to keep collecting.
  3. The SCORE tier beyond installs. Nothing computes trust, security, freshness or operability. The ranked work is in the 2026-08-18 proposal §9; it is unchanged and unstarted.