Repository navigation
Description
Current status and curation boundary — 26 September 2026
This remains the exemplar product design. The original dated design is preserved below; its database counts and “not built” inventory are historical, not current implementation status.
#181 is closed on implemented prototype builds 1 and 2 (PRs #183/#186): instance/exemplar read model, word-page examples, reverse views, invitation-only nominations and person-subject review gating. #189 owns vote reasons/cached scores/UI and endorse-on-duplicate; #190 owns extending the nomination publication gate to every illustrates subject kind before any bot writes. #191 separately owns the existing Examples section's honest-empty/absent decision.
#193 is the persona-curation delivery tracker: #156 opening section, #195 local runtime, #196 persistence/approval, #197 five-profile pilot, #198 refresh, #199 Mini handoff. A saved composition selects sourced material across page meanings; it need not create a claim. A nomination that a thing illustrates a specific meaning still uses this issue's existing assertion revisions, rationale, evidence and review contexts. Human composition acceptance does not accept a pending claim or establish its truth. Neither lead/highlight selection nor internal panel support is a human vote.
All bot illustrates nominations require the #190 public gate, including work/media subjects. Accepted claims must remain current and evidence/review-context eligible before a composition can display them; no automatic resurrection of rejection/withdrawal. The five-profile 4/5 recommendation in #197 is advisory, preserves dissent/abstention and is not independent corroboration. Psychiatric diagnoses must not be inferred from public behavior; sensitive personal interpretations need specific evidence and explicit human claim review. Use fictional adverse subjects in new acceptance fixtures; the older real-person examples below are historical product sketches, not factual findings or approved nominations.
Remaining exemplar work continues here/#189/#190 rather than being recreated as a parallel curation graph. Current remote code reference: Claims and contribution path.
Original 17 September exemplar design and backlog (historical measurements; current status above supersedes)
Working case, in Holden's words: sociopath. People want to say "here is an example of a sociopath" and name public figures — Thomas Midgley Jr. (leaded petrol, then CFCs: arguably the most lethal single inventor), Sheryl Sandberg (knew what Instagram was doing to teenage girls while publishing books about leaning in), Mark Zuckerberg (knew and did not care), Elon Musk, Donald Trump, historical figures. The same person turns up under several words: Sandberg under hypocrisy (espousing one thing, doing the other) as much as sociopath; Zuckerberg under hypocrisy (appalled in Trump's first term, seated behind him in the second). And the questions this issue has to answer are the ones that fall out of that:
- How does a person, a film, an artwork, a GIF or a quotation get on the list for a meaning — nominated by a person, by a persona bot, or curated by a reviewer?
- How do we record why they are on it, and quantify that why, rather than a bare name?
- How does voting work on top of nomination and curation: who votes, on what, what the score means, what it does and does not decide?
- How do the cross-word links work: N people cite Sandberg for hypocrisy, M for sociopath, K for greed — how does that read on the word page, and how does it read backwards on her page?
- What schema is missing, and what do we do about the identity of a nominee who is not in the encyclopedia yet (none of the five people above are)?
- How does the same machinery serve memes, GIFs, art and quotations, not only people?
This issue is the design for that: what we have, what we lack, how the system works, and what it needs. It does not re-own the curation pipeline: #85 owns the propose → review → select → feature rollout and its roles, #97 owns the persona editors (the "Bierce-inspired AI" that would nominate candidates by his criteria), #101 owns the persona-free assessor that ranks provider results, and #96 owns which sections lead an entry. Where this issue needs one of those, it points at it. What none of them owns, and this issue does, is the exemplar itself as a product object: the claim, its reasons, its votes, its rank, and its reverse view.
Vocabulary
Two things are both called "examples" in this codebase and they must stop sharing a word:
- A usage example is a sentence showing the word in use.
sense_revisions.examplesholds
these from Wiktionary and WordNet ({"text","ref","type"}maps) and nothing renders them. - An exemplar is a thing that illustrates a meaning: a person, an organization, an event, a work, an artwork, a film, a GIF, a quotation, a passage. The map's rule applies: a definition is what a source says about a word; an exemplar is what the culture attaches to a meaning.
From here: exemplar for the thing, nomination for the pending claim that it illustrates a meaning, endorsement and objection for a vote with a reason, selection for a reviewer or curator accepting and featuring it, score for the human vote tally on the current revision.
What we have (measured 2026-09-17 on devils_dictionary_v2)
The structure is almost entirely built. The product is not.
The predicate exists and has exactly the endpoints this needs. illustrates in priv/predicates/core.json — forward "illustrates", reverse "Attributed examples", description: "The culture's claim that some thing exemplifies a meaning or a concept. An interpretation, always attributed, never a definition." Endpoints: entity/{person,organization,event,artifact,work} and content/{media,image,quotation,passage} → sense/- or entity/concept. Endpoint legality is a composite foreign key (predicate_endpoint_rules), not a convention. satirizes (work or media → person/concept/organization) and depicts (work or image → person/place/event) sit beside it for the art and meme cases that are not "illustrates".
Current illustrates rows: 6, every one a test or browser-walkthrough fixture from #84 (Cupid with the Wheel of Time → allegory, Interlude, "Issue 84 artwork choice A"…). Zero real exemplars.
The claim carries the why. assertion_revisions.rationale (required non-empty by Contributions.propose/6, lib/devils_dictionary/claims/contributions.ex:74), method ("curated" for human proposals), confidence, and assertion_evidence rows (supports / contradicts, a URL locator, attribution text, or a content/sense revision) targeted at the revision. review_contexts snapshot the endpoint revisions a reviewer saw, so editing a sense's gloss does not inherit its approval. Original claimant (origin_actor_id) and submitter (submitted_by_actor_id) are distinct.
Votes exist as schema and API, and nowhere else. assertion_votes: value IN (-1, 1), unique on (assertion_revision_id, actor_id), cast per revision by design (a reworded claim does not inherit approval). Claims.vote/4 (upsert) and Claims.score/1 (sum(value)) exist and are called only from tests. 0 votes in the database. No vote UI. score is computed into the connection view and never displayed or sorted on. No cached score, no rate limit, no per-actor budget.
Reviews exist end to end. assertion_reviews.decision ∈ {accepted, disputed, rejected, withdrawn, needs_review}, append-only, latest wins; the Accept / Dispute / Reject form is on /connections/:id for reviewers. 2 reviews in the database, both #84 walkthroughs. Claims.visible/2 hides only rejected and withdrawn from the public — a pending nomination is publicly visible today, which is wrong for a living person under sociopath and is the first rule this issue changes.
Actors and roles. actors.actor_kind ∈ {user, bot, import, external, unknown}; a bot actor requires bot_source_id and its entity_id must not point at the historical person. No bot actor has ever been created. Users have two booleans, reviewer and internal_contributor; /connect, /connections/:id/edit and /connections/:id/challenge require internal_contributor; registration grants neither. So nomination is invitation-only, which is #85 stage 1 as intended.
Entities. 6,674 persons, 1,523 organizations, 918 works, 14 events — all from the Wikidata absorb of the animals and emotions scopes plus Artsy artists and the Bierce seed. Present: Ambrose Bierce, Melania Trump, Napoleon. Absent: Sheryl Sandberg, Mark Zuckerberg, Elon Musk, Donald Trump, Thomas Midgley Jr. Ways in: Registry.create_person/1; Contributions.create_local_entity/2 (kinds person work artifact event concept, internal contributors only); SourceIdentity.resolve/1 (identifiers only — labels are never identity); Catalog.find_or_create_entity/3 (Wikidata QID first, exact label second); duplicate-by-name is a warning, not a block. Namespaces in use: wikidata (92,985), tmdb_movie, imdb_title, artsy_*. ADR 0002 bounds any Wikidata fetch to explicit IDs, at most 100 exact QIDs per call.
The word. sociopath is lexeme 109401, one WordNet sense (109926) and one Wiktionary sense (2234710); hypocrisy has 4 + 2, greed 2 + 2. Neither sociopath nor nepotism has a single lexeme→entity link (refers_to or lexeme_entity_candidate): both are outside the two scopes, so the concept side of the page is empty and an exemplar must target the sense until the whole-lexicon link pass lands. Bierce defines hypocrite ("One who, professing virtues that he does not respect secures the advantage of seeming to be what he despises"), cynic, egotist, politician, philanthropist, corporation, selfish — the material a Bierce-persona rubric (#97) would nominate from — but not sociopath (the word is younger than he is) or greed.
The reader. /define/:slug renders definitions, relations, the thing panel (whose "examples" chips are instance_of children, a different thing), and the discovery shelves (CineGraph films, Artsy candidates, GIPHY). It does not render illustrates claims at all — grep illustrates lib/devils_dictionary_web is empty. The entity page (EntityLive) lists a thing's claims with review state and rationale, so the reverse view has a stub. Discovery results never become illustrates claims (discovery.ex:8); the one promotion path is the Artsy card's deep link to a prefilled /connect form. GIPHY stores only an id and a fingerprint, so a GIF has no object to be the subject of a claim.
Curation and bots: zero code. No persona, assessor, curator or judge module under lib/. #102 records the same.
What we lack
- A nomination that is not a publication. Today a proposal is a live claim the public can see. For
entity/person→ any meaning it must be review-only until accepted (Curated culture MVP: film-first discovery, quotes, art, GIFs and AI-assisted curation #85's rule: never publish "person is narcissism" as a factual edge; Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101's gate: person under an adverse concept → review-only). - A public path to nominate. Only internal contributors can reach
/connect. Curated culture MVP: film-first discovery, quotes, art, GIFs and AI-assisted curation #85 stage 5 opens submissions "after moderation capacity is demonstrated"; this issue has to say what the public form is when that day comes, because the shape of the claim depends on it. - A way to put a nominee into the encyclopedia. Sandberg is not there. Public nomination needs search-then-mint: trigram search on
entities.preferred_label, then a bounded Wikidata lookup, thenRegistry.create_personwith awikidataexternal id, or refuse. A person with no Wikidata item is not a public figure for our purposes. - The exemplar section on the word page, per sense, ranked, with the why, the count, and the nominator — and its "N more nominated, not yet reviewed" tail.
- Votes as a product: the button, one vote per actor (the unique index already enforces it), a reason on the vote, a cached score, ordering by score, rate limiting, and the rule that bot judgments are displayed apart from human votes (The Dead Editors’ Society: historical personas curate examples and marginalia #75).
- More than one why. A revision has one
rationale, the nominator's. Forty people who agree for forty reasons have nowhere to put them except by revising the claim, which would zero its votes (votes are per revision). The reason has to live on the endorsement. - The reverse view: a person's page ranking the words they are cited under, with counts — and a site-wide way to ask "who is most cited for hypocrisy" (the word page answers it) and "what is Sandberg most cited for" (her page answers it).
- A subject for a GIF or a meme. A GIPHY result has no
content_item; nomination of a transient provider result must mint one (content_kind: media,canonical_url, rights metadata) before a claim can point at it. - A policy for living people. Copy, evidence requirements, objection display, withdrawal, and the word "diagnosis" not appearing anywhere.
- Persona nominations (Explore local AI curation: persona editors, schema, models and compute budgets #97) and the assessor's candidate pool (Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101) both feed this, and both are zero code. This issue must not block on them, and must leave them a slot.
How the system works
One claim per (exemplar, meaning); many endorsements
The unit is the existing illustrates assertion: subject = the exemplar object, object = the sense (the precise meaning; the concept only when the word's thing exists and the nominator means the practice rather than a sense of the word). Sandberg under hypocrisy sense 1 and Sandberg under sociopath sense 1 are two claims, each with its own why, votes and review state. That is the cross-word link: nothing more than two rows sharing a subject.
A second person who wants to nominate Sandberg for hypocrisy does not create a second claim. The form finds the existing one (semantic key: subject, predicate, object — the same key #97 proposes for personas) and offers endorse with your reason instead. The claim's revision — endpoints and the nominator's rationale — rarely changes, so the per-revision vote rule costs nothing.
Three ways onto the list
| Path | Actor | What it produces | Owner |
|---|---|---|---|
| Human nomination | registered user (public later; internal_contributor now) |
illustrates claim, method: "curated", rationale required, ≥ 1 evidence row required for a person subject; state needs_review; not public for person subjects until accepted |
#85 stages 1 → 5 |
| Reviewer or curator selection | reviewer |
accepted review on the claim, optional feature on that meaning's page (a featured position, see schema) |
#85; composition by #96 |
| Persona nomination | actor_kind: bot with bot_source_id = the persona's source row |
the same claim, method: "persona:<slug>@<version>", origin actor the bot, rationale in the persona's voice, plus the structured relevance / novelty / persona-fit assessments kept in curation_nominations — never in the human score |
#97 |
The assessor (#101) never writes illustrates; it ranks and labels provider results and may propose a candidate claim for review. Its pool is where a persona reads from. Neither is a prerequisite: the human path is complete on its own.
"Candidates that might appear based on Ambrose Bierce's criteria" is a persona whose rubric is his entries — hypocrite, cynic, politician, philanthropist — applied to entities already in the graph with Wikipedia articles (the about assertions we already hold), producing nominations that are labelled Selected by Bierce-inspired AI, reviewed like any other, and voted on by people like any other. Its judgments about the world are displayed as its own; they are never counted as people agreeing.
The why, and how it is quantified
Three layers, all already partly in schema:
- The nominator's rationale (
assertion_revisions.rationale, required): "Knew from internal research in 2019 that Instagram harmed teenage girls' mental health and continued to publish and promote Lean In." - Evidence (
assertion_evidence): a URL (the Haugen disclosures, the Senate testimony), a quotation, a passage from a work already in the encyclopedia. For a person subject at least one row is required;contradictsrows are allowed and shown. - Endorsements and objections (
assertion_votes+ a newreason): each ±1 may carry its own sentence. The count is the quantity; the reasons are the quality. "41 people cite her here · 3 object", with the reasons readable under a disclosure, newest first, the nominator's pinned.
Quantification is deliberately counting, not weighting. No voter_weight (#17's idea, retired by #85 and #97), no bot influence in the human tally, no reputation multiplier in this issue. The score is human_up − human_down on the current revision, shown with both parts. When that proves too coarse (a claim with 2 up and 0 down outranking 40 up and 8 down), switch the ordering to a Wilson lower bound and keep displaying the raw counts; that is a query change, not a schema change.
What the score decides and does not: it orders accepted exemplars within a meaning and orders words on a person's page. It does not accept a claim (a reviewer does), does not validate a rationale, does not change a definition, and does not override withdrawal — #85's rule, kept.
Ranking on the word page
Per sense, one Attributed examples section, type-filterable (people · works · art · film · GIFs · quotes — reuse #102's content-type table):
- Featured by a curator, in featured order (at most a few).
- Accepted, by score desc, then evidence count, then oldest first.
- A disclosure: "12 more nominated, not yet reviewed" — listed for signed-in users, hidden for the public when the subject is a person.
Every card: the exemplar (label, thumbnail, kind badge), the rationale (one line, expandable), nominated by @x · N cite · M object · selected by a reviewer / by Bierce-inspired AI, the vote control, and the evidence count. Copy is always cited as an example of, never is a.
The reverse view: the person's page
EntityLive already lists a thing's claims with review state and rationale. It becomes the answer to "what is this person most cited for": every accepted illustrates claim where the entity is the subject, grouped by target word, ordered by score:
Sheryl Sandberg · cited as an example of
hypocrisy ▲ 41 ▽ 3 — sense 1, "professing one thing…" — 2 evidence
sociopath ▲ 12 ▽ 6 — sense 1 — 3 evidence
greed ▲ 3 ▽ 0
Objections are counted on the same line, not hidden. Below it, the persona judgments as their own block (Bierce-inspired AI selected her for hypocrite). Later, and cheap once the rows exist: co-citation on the word page ("people cited here are also cited for hypocrisy") and site-wide feeds (top exemplars this week, README's "Feeds" roadmap line).
Memes, GIFs, art, quotations
Same claim, different subject kind:
- Artworks (Artsy, the Met): already
entity/workwith external ids — the Artsy card's deep link to/connectis this flow's prototype.depictsfor what the picture shows;illustratesfor the interpretation. - Films (CineGraph):
entity/work,work_kind: film, tmdb/imdb ids. Same. - GIFs and memes (GIPHY, later the social providers): no object today. Nomination mints a
content_item(content_kind: mediaorimage) withcanonical_url, provider ids inexternal_identifiers, andrights_metadata; the GIPHY display rules (no bulk storage, attribution) carry over fromdocs/integrations/giphy.md. A meme that is a use of the word rather than an example of the thing isattests(Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101's proposed predicate), notillustrates. - Quotations and passages:
content/quotation|passage→ sense, withauthored_byandexcerpt_ofgiving provenance; Quote layer with provenance scoring #65's provenance tiers apply to the quote, the vote applies to its fit as an exemplar.
Living people: the rules the database and the copy enforce
- A person subject's
illustratesclaim is invisible to the public until accepted, regardless of the target word. (Change toClaims.visible/2: hideneeds_reviewanddisputedwhensubject_kind = 'entity' AND subject_subkind = 'person'.) - A nomination of a person requires ≥ 1 evidence row at submission.
- A nominee must resolve to a Wikidata item or an existing entity. No QID, no public nomination (the reviewer path can still mint a local person for a historical figure Wikidata lacks).
- Copy: cited as an example of, counts of citing and objecting, the reasons attributable to named accounts. No "is", no "diagnosed", no clinical framing; the predicate's reverse label stays Attributed examples.
withdrawnby a reviewer with a reason removes it from every view and keeps the history; the score survives on the revision for the record.- Rate limits on nomination and voting per actor; a duplicate nomination becomes an endorsement, never a second claim.
Schema
Everything below adds; nothing changes an existing column (the #74 rule).
| Change | Why |
|---|---|
assertion_votes.reason text null, assertion_votes.evidence_id → assertion_evidence null |
the endorsement's own why; an objection can point at a contradicts row |
assertion_scores (assertion_id PK, human_up, human_down, human_score, bot_up, bot_down, endorsement_count, revision_id, computed_at) — or the same columns on assertions |
README's "votes with cached scores"; the word page and the person page order on it; recomputed inside Claims.vote/4; revision_id records which revision the tally is for |
assertion_features (assertion_id, target_object_id, position, featured_by_actor_id, reason, timestamps; unique (target_object_id, assertion_id)) |
#85's "feature on this meaning's page"; separate from the vote so a curator's order and the crowd's order are both visible |
sources row community (tier: plebs, new kind: community) and a bot source per persona (#97) |
every claim has a source; a person minted by a nomination has origin_source_id = community |
illustrates endpoint entity/place → sense/- and entity/concept → sense/- |
a place (Enron's Houston) or a practice as an example of a word; data change in core.json, no migration |
Claims.visible/2 person rule |
above |
| vote and nomination rate limits | per-actor counters; Hammer or a contribution_budgets table — decide in implementation |
Not added, on purpose: a votable_type polymorphic vote (#17), voter_weight, a separate examples table (the S5 sketch, retired at #74 because it could not express concept→concept), a people table (#65's) — the entity registry is that table.
The nomination form (public version, for #85 stage 5)
ADD AN EXAMPLE of sociopath › sense 1 · WordNet · "someone with a sociopathic personality…"
Who or what? [ Sheryl Sandberg ] ⌕ → found: Sheryl Sandberg (person · Q…)
→ not found: search Wikidata · 3 matches · pick one
Why? [ Knew from internal research that Instagram harmed… ]
Evidence [ https://…senate testimony… ] [+ add] (required for a person)
Type person · organization · work · artwork · film · GIF · quotation
[Preview] [Submit for review]
If the claim already exists: "Sheryl Sandberg is already cited here by 41 people. Add your reason and cite her too." → an endorsement.
Acceptance walk
On real data, with the negative cases in CI:
- A reviewer nominates Thomas Midgley Jr. under sociopath sense 1 with a rationale and one URL; he is minted as a person with a Wikidata id; the claim is invisible to the public; the reviewer accepts it; it appears in Attributed examples with 1 cites · selected by a reviewer.
- A second contributor nominates him again → offered an endorsement, adds a reason; the card reads 2 cite; the assertion has one revision.
- Three users nominate Sheryl Sandberg under hypocrisy and sociopath with evidence; the first for each is a claim, the rest endorsements; her entity page ranks hypocrisy above sociopath by score with both counts shown.
- A user objects with a reason; the objection is counted and readable; the claim stays.
- An anonymous visitor sees accepted exemplars, their counts and reasons, and no pending person nominations.
- A reviewer withdraws a claim with a reason; it vanishes from the word page and the person page; the history remains on
/connections/:id. - A GIF from the GIPHY shelf is nominated under hypocrisy: a
content_itemis minted with its canonical URL and attribution; the claim is public on acceptance under the GIF filter. - A Wiktionary sense refresh that rewrites the sense gloss leaves the claim attached and flags changed since review (already built; keep it green).
- A persona nomination (when Explore local AI curation: persona editors, schema, models and compute budgets #97 lands) shows Selected by Bierce-inspired AI, votes on it are human votes, and its own assessment never enters the count.
- Rate limit: the 51st vote in an hour from one actor is refused with a reason.
Order of work
- Visibility rule for person subjects, evidence-required for person subjects, endorsement-on-duplicate. (No new tables; closes the "pending is public" hole.)
assertion_votes.reason,assertion_scores, the vote control on/connections/:idand on the word page card.- The Attributed examples section on
/define/:slugper sense, ranked, type-filtered; the person page grouped-by-word ranking. - Nominee search-then-mint (entity trigram search → bounded Wikidata lookup →
Registry.create_person), thecommunitysource,assertion_features. - Transient-provider subjects (GIF →
content_item). - Public nomination, rate limits — gated on Curated culture MVP: film-first discovery, quotes, art, GIFs and AI-assisted curation #85's moderation-capacity condition.
- Slots for Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101 (candidate claims routed to review) and Explore local AI curation: persona editors, schema, models and compute budgets #97 (persona nominations, bot source rows, separate display) — no work here beyond not blocking them.
Open decisions
- Sense or concept as the default target while most words have no linked thing: this issue says sense; revisit when the whole-lexicon link pass lands and sociopathy has a QID.
- Reasons on votes vs. a separate
endorsementstable: a column keeps one tally and one unique index; a table allows several reasons per person. Start with the column. - Wilson vs. net score for ordering: net first, both counts always shown.
- Whether objections can carry evidence (
contradictsrows linked from a vote): yes in schema, UI later. - Should a person's page count pending nominations at all ("and 3 more under review")? For signed-in users only.
Activity
holden commentedon Oct 21, 2026
Folded into #193, the curation programme's one open tracker, on the owner's word (21 October 2026). The specification here stands; reopen when the work starts. Status is in the consolidation comment on #193.