The community moderation model: built, 2026-08-18
Status: BUILT AND SHIPPED IN THIS BRANCH, not a proposal. Every claim below
is measured against shc main @ 32d44a5, and every file it names exists.
Six owner decisions are open at the end; none of them blocks the code, and each
one is a value or a switch rather than a rewrite.
Downstream of the decision-lane ruling C1: the storefront’s comments stay in Frappe and no second comment backend is adopted. This document is what that ruling costs, delivered.
★ NOTHING HERE TOUCHES ce. No Go migration, no rqlite table, no schema
change of any kind in the ce repository. The whole model is four Frappe
DocTypes and six Python modules under frappe/apps/marketplace/, applied by
bench migrate. The owner’s schema freeze on ce is not approached, let alone
crossed. This is stated first because the brief asked for it to be confirmed
explicitly and loudly.
1. What the owner asked for, and where each requirement now lives
Section titled “1. What the owner asked for, and where each requirement now lives”| # | requirement (verbatim) | where it lives now |
|---|---|---|
| R1 | ”Reddit style, upvoting” | Already existed. Threaded App Comment, App Comment Vote, Wilson lower-bound ranking (ranking.py:95), no time decay. Untouched by this change. |
| R2 | ”support for uploading images… enabled or disabled on a PER USER basis… DISABLED BY DEFAULT” | App Comment Image Grant (the row is the grant), App Comment Image child table, community/images.py, api.submit_comment(images_json=…). |
| R3 | ”block someone from commenting on an INDIVIDUAL app, just block them forever, but NOT actually take away their user account” | App Comment Ban, community/bans.py, api.ban_author / lift_ban / appeal_ban / decide_appeal / my_restrictions. |
| R4 | ”I might even wanna THROTTLE comments” | Community Moderation Settings (Single), community/settings.py, plus a new per-(account, app) ceiling that did not exist. |
| R5 | Report/flag + a moderator queue | App Content Report already existed; the queue did not. community/queue.py, api.moderation_queue, api.resolve_target. |
| R6 | who moderates | New Community Moderator role. community/roles.py, applied by after_migrate. |
| R7 | what the moderator sees | A queue grouped by target, not a list of reports. §4. |
| R8 | tombstone or vanish | Both, decided by a fact about the thread. community/visibility.py. §5. |
| R9 | appeal / undo | One appeal per ban, a lift, and an expiry. §3.4. |
Measured: 172 tests green, up from 60.
$ python3 -m unittest tests.test_community_{policy,ranking,installs,bans,images,moderation}Ran 172 tests in 0.005sOK2. The per-user image capability (R2)
Section titled “2. The per-user image capability (R2)”2.1 “Disabled by default” is structural, not a default value
Section titled “2.1 “Disabled by default” is structural, not a default value”A Check field with default: 0 on User would have been the obvious build.
It was rejected because it is a default somebody can change, and the day it
changes it changes for everyone at once.
The grant is a row: App Comment Image Grant, named by field:user, so a
duplicate is a primary-key collision, and the rule is absence:
no row → no images. There is no value to get wrong, because there is no value. A person who has never been granted the capability has nothing stored about them at all.
The consequence to like: a migration, a restore, a fresh bench and a half-finished feature branch all fail closed. The consequence to accept: a row per granted person, which for a capability a moderator hands out deliberately is the right order of magnitude.
Revoking sets revoked and keeps the row. A revocation that deletes the grant
deletes the evidence for the decision that follows it.
2.2 Two switches, and why not one
Section titled “2.2 Two switches, and why not one”Community Moderation Settings.comment_images_enabled is the panic button:
one flip and no image reaches any comment, whatever anybody was granted,
without touching a single grant row. The per-account grant is the routine
control. A single combined switch would mean that turning uploads off during an
incident revokes everyone’s grant and forgets who had it.
The two refusals deliberately read differently (images.check_grant, pinned by
test_the_two_refusals_say_different_things): “nobody can right now” is a
state of the site, “you have not been given this” is a state of the account
and tells the person there is somebody to ask.
2.3 What may be attached, and why SVG is refused by its bytes
Section titled “2.3 What may be attached, and why SVG is refused by its bytes”SVG is a script format. <svg> may carry <script>, onload= and external
<image href>; served same-origin from the bench that also serves the desk
session, an accepted SVG is stored XSS with a CSRF-capable session next to it.
Refusing the extension would have been theatre. images.sniff() reads the
first 12 bytes of the stored file (the one input the caller does not
choose), and the type must ALSO agree with the extension:
payload.pngwhose content is<svg …>→ sniffs as nothing → refused.payload.svgwhose content is a real PNG → extension fails → refused.
Both directions are pinned (test_svg_bytes_are_not_an_image_whatever_the_file_is_called,
test_a_png_named_svg_is_refused).
Every other fact about the file is re-read from the bench’s own File record,
never from the caller: ownership (your own uploads only; otherwise a
comment can embed any public file on the bench by guessing its path),
privacy, size, and whether it is already attached elsewhere
(api._attachable_file). Third-party URLs, protocol-relative URLs, data:
URIs and .. traversal are all refused by images.safe_file_url.
3. The per-app comment ban (R3): the sharpest requirement
Section titled “3. The per-app comment ban (R3): the sharpest requirement”3.1 Three claims, three properties
Section titled “3.1 Three claims, three properties”App Comment Ban is a (user, app) row. Each clause of the requirement is a
constraint the code holds, and each has a named test:
- Scoped to one app.
test_a_ban_on_one_app_leaves_every_other_app_alone. - Forever is the default.
expires_onempty is permanent;bans.expired()returnsFalsefor an absent value, never “expired because the field is blank”, which is the shape of the bug that silently un-bans everybody.test_a_ban_with_no_expiry_never_expires. - The account survives. Nothing disables, renames or role-changes
anything. The person signs in tomorrow, owns the same clusters, installs the
same apps and is billed the same. A flag on
Userwould have been exactly the thing the requirement rules out.
3.2 The store-wide variant, which was not asked for
Section titled “3.2 The store-wide variant, which was not asked for”A ban row with no app covers every listing. Without it, banning one spam
operation from the store means one row per listing (167 today and growing);
i.e. the control that exists is one nobody will use in the case that needs it
most. Same table, same lift, same appeal, one extra branch in
bans.in_force(). A store-wide ban outranks a per-app one so the person is
told the widest thing that is true.
3.3 What happens to what they already wrote
Section titled “3.3 What happens to what they already wrote”Recorded, not implied. content_action is keep (default) or hide. Lemmy
models the same fork as remove_or_restore_data on BanFromCommunity;
copying the shape keeps the choice explicit instead of accidental.
keep is the shipped default because “stop them adding more” does not imply
their earlier answers were wrong, and retracting those punishes the readers
they were for.
A lift with restore=1 un-hides exactly what this ban hid, matched on the
moderation note the ban wrote (_restore_ban_content). Un-hiding by
(author, app) alone would silently overturn every other decision ever made
about that person’s writing on that page.
3.4 The way back
Section titled “3.4 The way back”A permanent ban with no route back is not a moderation tool, it is a support-ticket generator: the person mails a human and the human has neither the record nor a button. So:
- one appeal per ban (
appeal_ban); a second is refused rather than queued, because an appeal queue one person can fill is a denial of service on the moderator; decide_appealrecords a rejection too, because an unanswered appeal is indistinguishable from an ignored one;lift_banis a moderator action with a note, and a lift answering an open appeal recordsgranted; “granted” and “lifted anyway” are different facts;my_restrictionstells the subject what applies to them, its scope, whether it ends, and whether an appeal is still available. A restriction the subject cannot see is one they cannot appeal.
The refusal the banned person reads never quotes the moderator’s reason
(test_the_refusal_never_quotes_the_moderators_reason). That text is written
for the audit trail by somebody who did not expect the subject to read it back,
and a queue whose notes are public is a queue whose notes stop being candid.
3.5 A moderator cannot be banned by the community surface
Section titled “3.5 A moderator cannot be banned by the community surface”Not a courtesy. Without it two moderators can ban each other and the recovery is a bench console. Removing somebody’s moderation is a role change, a different action, in a different place, on purpose.
4. Throttling (R4) and the queue (R5, R7)
Section titled “4. Throttling (R4) and the queue (R5, R7)”4.1 A second ceiling that did not exist
Section titled “4.1 A second ceiling that did not exist”The per-account hourly ceiling answers “is this account flooding the store”. It cannot answer “is it flooding this page”, which is the shape an argument takes and the shape a competitor’s astroturf takes. A limit low enough to stop twenty comments on one listing in an hour also stops somebody legitimately answering questions across twenty listings.
So max_comments_per_app_per_window (default 5) sits beside
max_comments_per_window (default 20), and its refusal names the app:
“you have posted 5 comments in the last hour” is baffling to somebody who
posted five comments on five different listings.
4.2 The knobs are editable, and clamped
Section titled “4.2 The knobs are editable, and clamped”Community Moderation Settings (Single) carries every rate and threshold;
settings.resolve() clamps each into a range the code owns. The range moves
in a commit and the value moves in the desk, the right split of authority
for a control whose failure mode is a spam flood nobody notices for a week.
Two clamp decisions are load-bearing:
- Zero is allowed on the per-window ceilings and means CLOSED. “Stop all new
comments right now” is a thing an incident needs, and the alternative is a
deploy in the middle of one.
policy.check_raterefuses a zero ceiling with its own sentence rather than the arithmetic’s “you have posted 0 comments in the last hour, which is the limit”. auto_hide_reportsfloors at 2, never 1. At 1, any single account takes any comment off the page until a moderator looks, a one-click heckler’s veto, and the exact tool a brigade wants.
An absent, cleared or unreadable settings row resolves to the shipped controls, never to no controls.
4.3 The queue is grouped by target, and that is the whole difference
Section titled “4.3 The queue is grouped by target, and that is the whole difference”A Desk list over App Content Report filtered state = open is free, and it is
a list of reports. Reports are not the unit of work:
One comment reported by five people is five rows. A moderator working that list opens the same comment five times, decides it five times, and the fifth decision can contradict the first. The auto-hide threshold is three distinct reporters, so the items that matter most appear the most times.
queue.group() collapses them to one item per target, ordered
most-reported-then-oldest, with a total tie-break so the queue does not
reshuffle under a moderator halfway down it. resolve_target() answers it once
with a verb (keep, hide, remove), and closes every open report on
that target in the same motion.
Every action closes the reports, keep included. A queue where only
takedowns close is a queue that grows until nobody opens it, and a log that
records only the removals cannot be audited for over-removal, the failure mode
nobody notices.
The queue carries what is needed to decide (the text, the app, how many
distinct people complained, what they said) and not the reporters’
identities: a moderator who can see who reported a comment can be asked who
reported it, and that is how reporting stops happening. Pinned by
test_the_queue_does_not_carry_who_reported.
moderate(strip_images=1) exists because the common image case is not “this
comment is abuse” but “the words are fine and the picture is not”; a moderator
whose only tool is remove will remove the whole comment, taking a useful
answer and its replies with it.
5. Tombstone or vanish (R8): both, and the thread decides
Section titled “5. Tombstone or vanish (R8): both, and the thread decides”A taken-down comment with published replies leaves a tombstone. A taken-down comment with none vanishes completely.
Why not always vanish. The replies are other people’s writing, and they were
written to something. Dropping a parent silently re-parents its subtree (which
is what the read path did before this change (ranking.thread: a row whose
parent is absent becomes a root)), and re-parenting changes what the replies
mean. “That is wrong, the port is 8443” re-rooted to the top of the page
is a correction of nothing, attributed to somebody who never said it.
Why not always tombstone. A tombstone is a mark: it says something was here.
For a lone spam comment with nothing under it, that mark is the only thing the
spammer achieved, and a page carrying twenty [removed] rows tells a reader the
discussion is a fight rather than that the moderation worked.
A tombstone carries a position and a label and nothing else: no body, no
author, no votes, no verified badge. Not the author in particular: a
tombstone naming who was removed is a public sanction, and the ban model
deliberately keeps the account intact. hidden and removed render
identically, because “under review” published on the page invites people to
take sides in a decision that has not been made yet.
★ It reads correctly on a renderer that has never heard of it: the storefront’s
comment component predates this module and prints body and author_name with
no special case, so a tombstone shows [removed]. The additive removed: 1 is
there for a renderer that wants to style it, and nothing depends on that
renderer existing; no storefront file is touched by this branch.
6. Who moderates (R6), and the reason it could not stay System Manager
Section titled “6. Who moderates (R6), and the reason it could not stay System Manager”Before this change policy.moderator_role was "System Manager". On this bench
that role is not “an administrator”, it is every key in the building. Measured,
on this app’s own DocTypes; each declares exactly one permission row:
cluster_secret.json permissions: [System Manager: read, write]terraform_state.json permissions: [System Manager: read, write]portal_cloud_credential.json permissions: [System Manager: read, write]So “make them a moderator”, spelled the only way it could be spelled, hands a volunteer who is here to read comments the customers’ cloud credentials and their terraform state. No configuration of the old design avoids it, because it is the same role.
Community Moderator is granted the community DocTypes and nothing else
(roles.py:grants), with no delete anywhere (moderation never deletes;
the row is the evidence, and a moderator who could delete could erase the record
of their own call) and no export/email anywhere (App Review.author and
App Comment.author are email addresses; a desk export is a CSV of every one of
them leaving in a browser download).
App Comment Vote is deliberately NOT granted. It holds who voted which way
on what. A moderator investigating a suspected brigade has a real need for it,
and that need is deliberately unmet here: the investigation is rare, it is the
bench owner’s job, and the price of making it one click for every moderator is
that every voter’s ballot is readable by whoever currently holds the role.
The role is created by after_migrate and not referenced from any DocType
JSON: a permission row naming a Role that does not exist yet is a link
bench migrate’s import can refuse, and that ordering is not one this app gets
to control. roles.after_migrate is idempotent and never fatal; a migrate that
dies over a permission row leaves a half-migrated bench, which is far worse than
a role one manual step behind.
7. A defect fixed on the way past
Section titled “7. A defect fixed on the way past”_guard_write called policy.check_rate and policy.check_account_age
without translating policy.Refused. Both raise a plain Python exception, so
hitting the rate limit or the new-account cooldown produced a 500 and a
traceback rather than the sentence policy.py had written for the author. The
messages existed and nobody could reach them. Now wrapped in _refuse.
Not reachable in production yet (there is no write UI), which is exactly why it survived: a guard with no caller is a guard nobody has run.
8. What is NOT built here, and is not owed by this lane
Section titled “8. What is NOT built here, and is not owed by this lane”- The write UI. No comment box, no reply, no vote, no report, no ban button
on the storefront. Owed identically under every option and gated on the owner
decision about where it lives (portal origin vs. storefront with Keycloak
enabled). No storefront file is touched by this branch, so
installFlow.spec.tsx’s zero-fetch/zero-navigation property is untouched. - A bespoke moderator UI. The queue is a whitelisted method plus frappe Desk. If a storefront moderator surface is wanted, that is new scope.
- Auto-granting image rights on a trust signal. The
basiscolumn exists so the answer can be recorded when it arrives (§9, D3). - A per-app comment lock. A natural extension of the zero-ceiling switch,
but the owner did not ask for one and it needs an
App Listingfield.
9. Owner decisions still open
Section titled “9. Owner decisions still open”None of these blocks the branch. Each is a value or a switch; the code ships a defensible default and records which one it took.
| # | decision | shipped default | recommendation |
|---|---|---|---|
| D1 | Ban semantics: does “block forever from this app” retract their history? | content_action = keep; their published words stand, they simply cannot post. | Keep it. The common case is “this person argues in bad faith, stop them adding more”, which does not imply their earlier answers were wrong. hide is per-ban and one field away when a case needs it. |
| D2 | Does a ban cover reporting and voting, or only posting? | Yes; a ban is “no voice on this page”. | Keep it. They can still report and vote on every other listing, so nothing about the store’s defences weakens; what stops is retaliation on the page they were banned from. |
| D3 | How does the image grant turn ON? | A moderator creates the row. basis records manual vs automatic. | Start manual. If it becomes a chore, auto-grant on verified_install + N published comments with no upheld report and write basis = automatic; the column is already there so the two can be told apart afterwards. |
| D4 | Who gets Community Moderator? | Nobody, until granted. System Manager keeps the surface so a fresh bench is still moderatable. | Grant it explicitly. Do not fall back to making people System Managers; §6 is the whole reason the role exists. |
| D5 | Throttle defaults: 20 comments/hour per account, 5 per account per app, 15-minute new-account cooldown, auto-hide at 3 distinct reporters. | As stated. | Ship them and watch. They are now editable in the desk without a deploy, which is the point; the clamp ranges are the part that needs a commit. |
| D6 | Do content removals get an appeal too, or only bans? | Only bans. | Leave it. A removed comment is cheap to rewrite; a permanent ban is not, which is why the appeal is attached to the expensive one. Revisit if the moderator queue starts carrying “why was this removed” reports. |
10. Revisit trigger
Section titled “10. Revisit trigger”Stated so this is falsifiable rather than dogma. Revisit the model if any of:
- moderation volume outgrows the Desk queue (the trigger the decision lane already named for revisiting Frappe itself);
- a second product needs the same layer, which would make the DocTypes an interface rather than an implementation;
- per-app moderators become a requirement; today the role is store-wide, and making it per-app is a new join, not a new column.