Skip to content
SHC Docs

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.
R5Report/flag + a moderator queueApp Content Report already existed; the queue did not. community/queue.py, api.moderation_queue, api.resolve_target.
R6who moderatesNew Community Moderator role. community/roles.py, applied by after_migrate.
R7what the moderator seesA queue grouped by target, not a list of reports. §4.
R8tombstone or vanishBoth, decided by a fact about the thread. community/visibility.py. §5.
R9appeal / undoOne 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.005s
OK

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.

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.png whose content is <svg …> → sniffs as nothing → refused.
  • payload.svg whose 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”

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:

  1. Scoped to one app. test_a_ban_on_one_app_leaves_every_other_app_alone.
  2. Forever is the default. expires_on empty is permanent; bans.expired() returns False for 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.
  3. 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 User would 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.

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_appeal records a rejection too, because an unanswered appeal is indistinguishable from an ignored one;
  • lift_ban is a moderator action with a note, and a lift answering an open appeal records granted; “granted” and “lifted anyway” are different facts;
  • my_restrictions tells 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.


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.

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_rate refuses 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_reports floors 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.


_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 basis column 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 Listing field.

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.

#decisionshipped defaultrecommendation
D1Ban 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.
D2Does 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.
D3How 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.
D4Who 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.
D5Throttle 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.
D6Do 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.

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.