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.
The question, verbatim
Section titled “The question, verbatim”“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.
The ruling
Section titled “The ruling”Three tiers, three words. Two are adopted as proposed; the third KEEPS THE NAME IT ALREADY HAD IN THE CODE.
| tier | name | what it is | where it lives |
|---|---|---|---|
| 1 | SIGNAL | a 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 |
| 2 | SCORE | a 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 |
| 3 | COLLECTION | an 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
CollectionIdand the tableCOLLECTIONS(features/marketplace/src/collections/collections.ts); - the route
apps/marketplace/routes/apps/collection/[collection].tsx, so/apps/collection/trendingis 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).
Tier 1: SIGNALS
Section titled “Tier 1: SIGNALS”| signal | modelled | collected | retained 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 lane | pending deploy | ✅ one reading per app per day |
| CVE / advisory counts | ⛔ vapour | ⛔ | ⛔ |
| page views | refused; see below |
Tier 2: SCORES
Section titled “Tier 2: SCORES”| score | modelled | computed | displayed |
|---|---|---|---|
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 | ⛔ | ⛔ |
Tier 3: COLLECTIONS
Section titled “Tier 3: COLLECTIONS”| collection | basis | ranks today |
|---|---|---|
new | App Listing.creation | ✅ 167 rows |
updated | App Listing.modified | ✅ 167 rows |
popular | install_cluster_count | ⛔ 0 rows |
trending | install_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.
★ Trending is now computable. Here is exactly what changed.
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.
| measurement | value | how |
|---|---|---|
| published listings on the live bench | 167 (90 apps, 77 add-ons) | GET /api/resource/App Listing?filters=[["published","=",1]] |
listings with a publishable install_cluster_count | 0 | the column does not exist on the production bench: 417 DataError: Field not permitted in query: install_cluster_count |
listings with a publishable install_trend_delta | 0 | ditto, and it needs a 30-day history that starts accruing on deploy |
App Version rows | 90 | one per app |
…carrying a released_on | 0 | every one is NULL |
marketplace.community module on production | absent | 417 ValidationError: … No module named 'marketplace.community' |
marketplace.curation module on production | absent | same shape |
distinct creation days across 167 rows | 2 (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.
What is refused, and stays refused
Section titled “What is refused, and stays refused”- 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.Versionrides 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.
What this lane built
Section titled “What this lane built”frappe/apps/marketplace/marketplace/community/signals.py: the tier vocabulary, the window, both floors, and the pure delta arithmetic.App Signal SnapshotDocType: append-only, one row per app per signal per day, unique-keyed, no Guest permission.recompute_install_countsalso records the observation and denormalisesinstall_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:
trendingmoves frombasis: "unbuilt"tobasis: "install-trend",orderByTrend, the loader read, the card stamp (+11 clusters in 30 days), and the panel copy in en and es.
What is still owed
Section titled “What is still owed”- Deploy. Production is many migrations behind; none of the community,
curation or signal schema is on the bench. Nothing above renders until
bench migrateruns there. - The portal inventory opt-out.
daemon/wiring/portal_wire.gowiresApps: localAppInventoryunconditionally, 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. - 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.