Repository navigation
Examples backbone: the record's instances (WordNet, Wikidata P31) as the pre-adjudicated layer under the cited exemplars (#105), one read model, one section, two registers — so /define/war names its 43 wars now and /define/coward can carry an attributed example later #181
Description
Purpose
Two different things are called "examples" on this site, and the codebase already separates them without saying so:
- An instance is a fact a source asserts: war → Korean War, dictator → Hitler, traitor → Benedict Arnold, philanthropist → Carnegie. WordNet ships these as
instance_hypernymedges and Wikidata as P31. They are pre-adjudicated: nobody on this site decided them, a source did, and the site's only job is to say which source. - An exemplar is a claim someone makes: Jeff Bezos → coward. No source will ever assert that. It needs a nominator, a why, evidence, review and, later, votes. Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105 designed this completely on 2026-09-17 and named it.
This issue builds the backbone that holds both: one read model, one section on the word page, two visual registers, one ordering function whose signals come from each layer and never cross. The instance layer lands first because the data is already in the database and nothing renders it. The exemplar layer lands on top of it through the manifest path the repo already uses for corpora, so a hand-written manifest today and a persona-written manifest later (#97) are one seeder. The assessor (#101) and the personas get a slot and no prerequisite.
Refs #105 (the exemplar as a product object: nomination, endorsement, ranking, reverse view — this issue builds its order-of-work steps 1 and 3 and defers 2, 4–7), #172 (the concept hop and word-level candidates; the same PageEvidence read), #165 (people enter through senses; nominee minting), #164 (Creators.prepare/apply mints a person from a QID), #156 (the entry band's a thing tile, which this section feeds), #101 and #97 (slots), #69 §0 ("Examples from the culture: people and bots attach examples to a word … Votes rank them"), #74 / ADR 0001 (entities enter through senses; nothing here changes a column).
What the database holds (devils_dictionary_v2, 2026-09-24, main @ 0d69346)
| Count | |
|---|---|
WordNet instance_hypernym edges, absorbed and current |
33,898, from a capitalised lexeme's sense into a common noun's sense |
| Words that would gain named examples from them | 1,663 — poet 349, painter 223, war 43, emperor 36, philanthropist 35, dictator 20 (Hitler, Mussolini, Franco, Tojo, the Duvaliers), revolution 17, massacre 6, tyrant 3, traitor 2 (Benedict Arnold), genocide 1 (Holocaust) |
| … and how they are stored | predicate other, metadata {}. The WordNet absorb puts the source label in subtype (wordnet.ex:290) and write_relations/5 drops it (materializer.ex:1309, metadata: r[:metadata] || %{}). The other predicate's own description says "the label is kept in the assertion's metadata so nothing is lost"; it is lost. Korean War → war (an instance) and Korean War → Korea (domain_region) are indistinguishable rows. 155,262 other rows are in this state. |
| … and what renders | nothing on war: WordPage.relations/2 reads subject-side edges only, and the edge points the other way. The named wars exist as lexemes with their own pages. |
| Wikidata P31 instances of Q198 war | 16 held; Encyclopedia.kinds_and_examples/2 shows children that have a word, so 1 renders in the thing panel |
Instance edges whose subject lexeme has a refers_to entity |
4,194 of 33,898 (a thumbnail and an entity page); the rest are words only |
illustrates rows |
5, all #84 test fixtures. 0 votes, 2 reviews, 0 bot actors, 1 reviewer, 2 internal contributors |
Word-page rendering of illustrates |
none. EntityLive lists a thing's outgoing illustrates with review state (entity_page.ex:251) — the reverse view has a stub |
assertion_votes |
(assertion_revision_id, actor_id, value ∈ {-1,1}, review_context_id); no reason, no cached score; Claims.vote/4 and score/1 called only from tests |
| Nominee identity | Bezos, Trump, Zuckerberg, Sandberg absent. Elon Musk present as entity_kind: concept — one of 25,079 concept stubs minted by the linker from a Wiktionary QID and never fetched, so never sharpened by P31 |
sources.kind enum |
already has :crowd and :bot; no community row exists |
| Usage examples (a sentence using the word) | sense_revisions.examples, 312,380 current senses carry a Wiktionary quotation. Not this issue; named here so nobody calls them examples |
| LLM, embedding or local-model wiring | none in the repo |
Vocabulary
- usage example — a sentence showing the word in use. Layer 0. Rendered inside a definition card (Quotes research: which sources are reliable, measured on Voltaire and Vonnegut — Wikiquote re-tested through Parsoid, Wiktionary citations already absorbed, the aggregators fail corroboration, a keyless primary-text check (toward a
:quoterow) #158 absorbed the quotations). Not touched here. - instance — a named thing a source files under a meaning: an
instance_hypernymedge in WordNet, a P31 in Wikidata. Layer 1. Pre-adjudicated; the record's claim. - exemplar — a thing the culture attaches to a meaning, always attributed: an
illustratesclaim with a rationale and evidence (Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105). Layer 2. Adjudicated here, by a reviewer. - register — how a layer draws: instances as chips, exemplars as cards. A reader can tell the layers apart at a glance and by copy.
- signal — a number one layer produces: how many sources assert an instance, at what tier; how many people cite or object to an exemplar, whether a curator featured it. Signals never cross layers.
Design: two layers, one backbone
┌───────────────────────────────────────────────────────────┐
layer 2 │ exemplars · illustrates claims · rationale, evidence │ adjudicated here
(opinionated) │ method: curated | persona:<slug>@<v> · votes, features │ #105 owns the product
└───────────────────────────┬───────────────────────────────┘
│ same read model, same section, own register
┌───────────────────────────┴───────────────────────────────┐
layer 1 │ instances · instance_of claims, source-native │ pre-adjudicated
(the record) │ WordNet instance_hypernym (sense→sense) · Wikidata P31 │ the source's claim
│ (entity→entity) · corroboration = sources agreeing │
└───────────────────────────┬───────────────────────────────┘
│ not in this issue
layer 0 │ usage examples · sense_revisions.examples · inside the card │
The read model. DevilsDictionary.Examples.for_page(lexeme_ids, viewer) returns one list of items, each:
%{
layer: :instance | :exemplar,
subject: %{kind: :lexeme | :entity | :content, id:, label:, slug: | nil, thumbnail: | nil},
target: %{kind: :sense | :entity, id:, gloss: | nil}, # the meaning it is an example of
sources: [%{slug:, tier:}], # instance: every source asserting it
claim: %{assertion_id:, revision_id:, rationale:, evidence_count:, review_state:, method:} | nil, # exemplar only
signals: %{source_count:, best_tier:, human_up:, human_down:, featured_at: | nil},
reason: "…" # one sentence, from fields, full stop
}One ordering function, replaceable. Examples.Rank.order/1 is pure over signals and layer. Today: featured exemplars in featured order, accepted exemplars by human_up − human_down then evidence count then age, then instances by source_count desc, best_tier, lemma. A curation layer later replaces the function, not the shape — the rule #156 codified for the band. No weight crosses a layer: a vote never reorders an instance, a source count never scores an exemplar.
Where it renders. One section, #examples, in the main column between Definitions and the culture block (found things after asserted things, before searched things). Exemplar cards first when any are visible, then instance chips as a dense row, both under one heading with one byline naming the sources. The thing panel's examples chips become this section's Wikidata instances (they are the same query); kinds stay in the panel. The band (#156) draws its a thing tile from the first item here when it has one.
How a claim gets in, per layer.
| Layer | Path | Writes | Method |
|---|---|---|---|
| instance | the absorb (WordNet, Wikidata) | instance_of revisions, source_native, origin_key |
source |
| exemplar, by hand | an exemplar manifest under priv/exemplars/, seeded by mix dd.exemplars.seed through Contributions.propose/6 |
illustrates revision + evidence rows, needs_review |
curated |
| exemplar, by form | /connect, internal contributors, unchanged |
the same | curated |
| exemplar, by persona (#97, later) | the same manifest shape, written by the bot actor | the same | persona:<slug>@<version> |
| exemplar, by the assessor (#101, later) | a candidate claim routed to review, never accepted by itself |
the same, review-only | assessor:<version> |
The manifest is the point: the bot changes the author of the file, not the seeder. Row shape:
{
"word": "coward", "sense": {"source": "wordnet", "match": "person who lacks courage"},
"subject": {"wikidata": "Q312556", "label": "Jeff Bezos", "kind": "person"},
"rationale": "Owns the Washington Post and, in 2025, …",
"evidence": [{"url": "https://…", "attribution": "The Guardian, 3 March 2025", "role": "supports"}],
"curator": "holden"
}sense.match is a substring of the gloss, resolved at seed time and refused when it matches zero or several senses — a manifest names a meaning, never a sense id, so a Wiktionary refresh cannot silently move it (#105's changed since review still fires through review_contexts).
Schema
Read against the live tables above. Everything adds; no existing column changes (#74's rule).
| Change | Kind | Why |
|---|---|---|
instance_of gains endpoint sense/- → sense/- in priv/predicates/core.json |
data, no migration (predicate_endpoint_rules is seeded from the file) |
WordNet's instance edge is the same relation as P31, sense-side. Direction is instance → class, as P31, so no inverse row is written and one predicate answers both layers' "what are the instances of X" |
WordNet instance_hypernym maps to instance_of in wordnet.ex map_type/1 |
absorb change | today it lands as other |
write_relations/5 carries subtype into metadata["label"] for every relation that has one |
absorb change | fixes the 155,262-row label loss; the other predicate's description becomes true |
Examples context: for_page/2, Rank.order/1, instances/1, exemplars/2 |
code | the read model |
WordPage.relations/2 learns one reverse read: instance_of rows whose object is a page sense |
code | the only predicate read object-side; documented as such |
Claims.visible/2 person rule: hide needs_review and disputed from :public when subject_kind = 'entity' AND subject_subkind = 'person' |
code, no migration (both columns exist on assertion_revisions) |
#105 rule 1; today a pending nomination is public |
Contributions.propose/6 requires ≥ 1 evidence row when the subject is a person |
code | #105 rule 2 |
sources row community (kind: crowd, tier: plebs, access: user) |
catalog seed | every claim has a source; hand-curated exemplars and minted nominees carry it |
priv/exemplars/<slug>-v1.json + Examples.Manifest (validate, checksum) + mix dd.exemplars.seed (dry-run, limit, refuses drift) |
code + manifest | the nomination path that a bot reuses; mirrors Corpus.Seeder |
nominee minting: manifest subject with a QID and no entity → Creators.prepare/apply path (#164) with origin_source_id = community; no QID → refused |
code | #105 rule 3; #165 option 1 for nominees |
assertion_votes.reason text null; assertion_scores (assertion_id PK, human_up, human_down, bot_up, bot_down, revision_id, computed_at) |
migration, build 3 only | #105 step 2, taken as written; the only migration in this issue and it can wait |
Not added, on purpose: a separate examples table (retired at #74), voter_weight (#17, retired), a new content type or shelf (this is a section, not a shelf: nothing is requested, no run, no budget), an inverse has_instance predicate (one direction, read both ways).
Wireframes
1. /define/war — build 1, desktop
┌ Definitions ──────────────────────────────── 5 sources · one open at a time ┐
│ ▸ Bierce 👑 … │
│ ▾ WordNet the waging of armed conflict against an enemy … │
└──────────────────────────────────────────────────────────────────────────────┘
┌ Examples ────────────────────────────────── 43 · the record names ─────────┐
│ │
│ [Hundred Years' War] [Korean War] [Vietnam War] [Trojan War] [Gulf War] │ ← chips, dense,
│ [War of 1812] [Thirty Years' War] [Crimean War] [Boer War] [Six-Day War] │ hop to the word
│ [Peloponnesian War] [Punic War] +31 │
│ │
│ Named under a sense of war by WordNet; 16 more by Wikidata as instances │ ← byline: sources,
│ of Q198, 1 of them a word. │ once
└──────────────────────────────────────────────────────────────────────────────┘
┌ the thing ─────────────────────────────────────────────────────────────────┐
│ War · Q198 · organized armed conflict … kinds: [civil war] [world war] … │ ← kinds stay;
└──────────────────────────────────────────────────────────────────────────────┘ examples moved up
Chips keep the related-block affordance (enriched word = solid, bare word = outlined, +N exact remainder). A Wikidata instance with no word links to its entity page and is drawn outlined with a ↗, so the 15 wars the thing panel hid are reachable.
2. /define/dictator — both layers, desktop
┌ Examples ──────────────────── 1 cited · 20 named ─────────────────────────┐
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ ▣ Francisco Franco cited as an example of │ │ ← exemplar card:
│ │ person · Q… sense 2 · a ruler who… │ │ who, the why,
│ │ "Ruled Spain for 36 years after a coup, …" │ │ the evidence,
│ │ 2 evidence · nominated by holden · selected by a reviewer │ │ the state
│ │ ▲ 1 ▽ 0 │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
│ [Adolf Hitler] [Benito Mussolini] [Hideki Tojo] [François Duvalier] │ ← instance chips,
│ [Jean-Claude Duvalier] [Francisco Franco ✓] +14 │ ✓ = also cited above
│ │
│ Named under a sense of dictator by WordNet. Franco is cited by 1 person; │
│ reasons are theirs, not the record's. │
└──────────────────────────────────────────────────────────────────────────────┘
The same subject in both layers is two items, not one: the chip is WordNet's claim, the card is a person's. The chip gains a ✓ and the card is first; nothing is merged, because the signals are different kinds of thing.
3. /define/coward — build 2, the public view and the reviewer's view
PUBLIC (nothing accepted yet) SIGNED-IN REVIEWER
┌ Examples ────── nothing named ──┐ ┌ Examples ──────────── 1 under review ─┐
│ │ │ ┌────────────────────────────────────┐ │
│ No source names an instance of │ │ │ ▣ Jeff Bezos needs review │ │
│ coward, and nothing is cited │ │ │ person · Q312556 · sense 1 │ │
│ yet. │ │ │ "Owns the Washington Post and …" │ │
│ │ │ │ 1 evidence · nominated by holden │ │
└──────────────────────────────────┘ │ │ [Accept] [Dispute] [Reject] ↗ │ │
│ └────────────────────────────────────┘ │
(the section is present and honest: │ Not public until accepted. │
a word with no examples says so) └────────────────────────────────────────┘
AFTER ACCEPTANCE, PUBLIC
┌ Examples ─────────────────────────────────── 1 cited ──────────────────────┐
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ ▣ Jeff Bezos cited as an example of │ │
│ │ person · Q312556 sense 1 · a person who… │ │
│ │ "Owns the Washington Post and …" [more ▾] │ │
│ │ 1 evidence ↗ · nominated by holden · selected by a reviewer │ │
│ │ ▲ 1 ▽ 0 │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ Cited by people who gave a reason; the record names no instance of coward. │
└────────────────────────────────────────────────────────────────────────────┘
Copy rules (#105 rule 4, kept): cited as an example of, never is a; the counts of citing and objecting are always both shown; diagnosed and any clinical framing appear nowhere; the section byline says which layer produced what.
4. Phone, 375
┌ Examples ──── 1 cited · 20 named ┐
│ ┌──────────────────────────────┐ │
│ │ ▣ Francisco Franco │ │ card: full width,
│ │ cited as an example of │ │ the rationale
│ │ sense 2 · a ruler who… │ │ clamped to two
│ │ "Ruled Spain for 36 years │ │ lines, [more ▾]
│ │ after a coup, …" [more ▾]│ │
│ │ 2 evidence · ▲ 1 ▽ 0 │ │
│ └──────────────────────────────┘ │
│ [Adolf Hitler] [Benito Mussolini]│ chips wrap, no
│ [Hideki Tojo] [Duvalier] +16 │ horizontal scroll
│ Named by WordNet · 1 cited │ (measured, as #111)
└──────────────────────────────────┘
5. The person's page — the reverse view, mostly free
/entities/<id>/francisco-franco
Francisco Franco · person · Q…
─ cited as an example of ────────────────────────────────
dictator ▲ 1 ▽ 0 sense 2, "a ruler who…" 2 evidence accepted
─ named by the record under ─────────────────────────────
dictator WordNet · general WordNet
EntityLive already lists outgoing illustrates with review state; it gains the grouping by target word, the ordering by score, and the second list (instance edges whose subject is this entity's word). Objections count on the same line.
6. The read, end to end
WordNet instance_hypernym ──absorb──▶ instance_of (sense→sense, method source) ─┐
Wikidata P31 ──absorb──▶ instance_of (entity→entity) ─────────────┤
├─▶ Examples.for_page ─▶ Rank.order ─▶ #examples
manifest / form / persona ─propose──▶ illustrates (+rationale, evidence) ───────┤ │ │
│ │ │ └─ replaced by curation later
review (accepted) ──▶ visible(:public) ─────┘ └─ Claims.visible/2, person rule
Contracts
- C1 — Additive. No existing column changes, no row is deleted, no predicate is renamed. The related block and the thing panel render as today until the section holds their data; then the thing panel's examples row is removed in the same PR that proves the section shows the same chips plus the unworded ones. A word with nothing in either layer renders the section's honest empty, never filler.
- C2 — A layer is data. Every item carries
layer; an instance never renders a rationale and an exemplar never renders without one. Conformance for the section asserts both, the way shelf conformance asserts every reason is labelled. - C3 — Signals never cross.
Rank.order/1is the only ordering, pure oversignals; votes exist only on layer 2, source counts only on layer 1. A test feeds an instance with fabricated vote fields and asserts they are ignored. - C4 — The record is the record. An instance's byline names the asserting sources and nothing else; corroboration is sources agreeing (WordNet and Wikidata both filing Korean War under war), never a model's score. Under the one rule (
docs/discovery/README.md), an instance is an identity match a source made offline; no provider is called. - C5 — Living people, as Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105 wrote it. Person-subject claims are invisible to the public until accepted; require ≥ 1 evidence row; require a QID or an existing entity; copy is cited as an example of; withdrawal keeps history and clears every view; a duplicate nomination becomes an endorsement, never a second claim. This issue implements rules 1–4 and 6; rate limits (5) wait for public nomination.
- C6 — One nomination path. Manifest, form and persona all reach
Contributions.propose/6.methodsays who;origin_actor_idsays which actor; nothing is displayed as human agreement unlessactor_kind = user. The seeder is idempotent on(subject, predicate, object)— a re-run of a manifest revises nothing and reports held. - C7 — The label loss is fixed once. After build 1 every
otherrow written by a re-absorb carriesmetadata["label"]; a health check counts currentotherrows without one and the count is the residual, printed bymix dd.health. - C8 — No request at read time. The section reads the registry. Wikidata is called only by the absorb (bounded, ADR 0002) and by nominee minting at seed time (one
wbgetentitiesper new person, through the shared client).
Measurement
What the backbone counts from day one, all queries over rows it already writes:
| Signal | Layer | Where |
|---|---|---|
| sources asserting an instance, best tier | 1 | instance_of revisions grouped by (subject, object); source_native rows carry their source through the assertion |
| words with named examples; examples per word | 1 | the build 1 spike, re-run after each absorb; the acceptance table below |
| citing and objecting counts, per exemplar, per revision | 2 | assertion_votes (build 3 adds reason and the cached tally) |
| co-citation: a subject under N words | 2 | rows sharing subject_object_id; the person page's grouping is this query |
evidence per claim, supports vs contradicts |
2 | assertion_evidence |
| time from nomination to decision; backlog under review | 2 | assertion_reviews against revision inserted_at |
| corroborating signals, keyless and dated, attached as evidence rows, never as claims | 2 | a Guardian search count for "coward" AND "Bezos" (boolean q, article count and links, no article text — clause 6(g)); Wikipedia pageviews for the subject's article (#134's signal) |
Not measured, on purpose: a relevance score for an instance (the record asserted it or it did not), a bot's judgment inside a human tally (#105 and #97), any weighting by reputation.
Builds
Build 1 — the record's examples. map_type("instance_hypernym") → {:instance_of, "instance_hypernym"}; subtype carried into metadata["label"]; the sense/- → sense/- endpoint; the reverse read in WordPage; Examples.for_page/2 layer 1 only; the #examples section with chips and byline; the thing panel's examples folded in; WordNet re-absorbed (idempotent on origin_key). Spike first, posted here: how many of the 33,898 resolve, how many words gain examples, the top 30 words, and the twelve #158 probe words. No migration.
Build 2 — the cited examples, by hand. Claims.visible/2 person rule; evidence-required for person subjects; the community source; Examples.Manifest + mix dd.exemplars.seed + nominee minting through the #164 path; layer 2 in for_page/2 with Claims.visible/2 applied per viewer; the card register; the person page grouping; priv/exemplars/first-v1.json with the owner's first rows. No migration.
Build 3 — counting. assertion_votes.reason, assertion_scores, recomputed inside Claims.vote/4; the vote control on the card and on /connections/:id for signed-in users; endorse-on-duplicate in the form and the seeder; Rank.order/1 reads the cached tally. One migration.
Build 4 — slots, no code here. The assessor (#101) writes candidate illustrates claims with method: "assessor:<v>", review-only, through the manifest shape. A persona (#97) writes method: "persona:<slug>@<v>" as a bot actor with its own sources row (kind: bot); its assessments live in its own table and never in assertion_scores.human_*. Neither is a prerequisite for builds 1–3 and neither is blocked by them.
Order: build 1 (one PR, small, spike posted first), build 2 (one PR), build 3 (one PR, the migration). Each PR: gate green, CodeRabbit addressed, owner merges with a merge commit.
Acceptance
- Build 1 spike posted: edges resolved, words gaining examples, top 30, the twelve probe words
-
/define/warshows an Examples section with its named wars as chips,+Nexact, byline naming WordNet and Wikidata; the thing panel no longer duplicates them -
/define/dictatorshows Hitler, Mussolini, Franco, Tojo, the Duvaliers;/define/traitorshows Benedict Arnold;/define/genocideshows the Holocaust — verified ondevils_dictionary_v2on 2026-09-25 throughWordPage.build/2; genocide's label fixed in Build 2 of #181: the exemplar layer — cited, evidenced, reviewed before public #186 - A current
otherrow written after build 1 carriesmetadata["label"];mix dd.healthprints the unlabeled residual -
A word with nothing in either layer shows the section's honest empty;→ moved to Examples section: honest empty vs absent for a word with nothing in either layer (/define/logomachy) #191 (honest empty vs absent is still undecided)/define/logomachyis the fixture - Build 2: a manifest row for a living person with a QID and one evidence URL seeds a
needs_reviewclaim, mints the person withorigin_source_id = community, and is invisible to the public; a reviewer accepts it on/connections/:id; the card appears with cited as an example of, the rationale, the evidence link and the nominator - A second manifest row for the same subject and meaning is reported held and creates no second claim
- A manifest row whose
sense.matchhits zero or several senses is refused with the gloss list, not seeded - A manifest row with no QID and no existing entity is refused
- The person page groups accepted claims by word, ordered by score, with both counts, and lists the record's instance edges beneath
- Phone, 375: no horizontal scroll on
/define/dictator, measured (the Word page height and shelf templates: fold the prose, one template per content type, the world above the fold — measured on /define/love, phased #111 rule; headless Chrome clamps at 500, so CDP emulation) - Conformance: an item without
layerfails; an instance with a rationale fails; an exemplar without one fails; a fabricated vote on an instance does not reorder it -
Build 3→ moved to Exemplar votes: assertion_votes.reason, cached assertion_scores, the vote control and endorse-on-duplicate (#181 build 3) #189: the 2nd vote from one actor on one revision replaces the 1st;assertion_scoresmatchessum(value)after every vote in a property test; ordering changes when the tally does -
docs/encyclopedia/README.mdgains the three-layer vocabulary anddocs/discovery/README.md's not goals line for exemplars points here —docs/encyclopedia/does not exist; the three-layer table is indocs/discovery/README.md§ Composition and its not-goals line points there (Examples backbone, build 1: the record's instances as one section (#181) #183)
Decisions owed by the owner
- Section placement: main column between Definitions and the culture block (proposed), or the left column under related words. The proposal puts asserted things before searched things.
- Cards before chips when both layers hold something (proposed), or the record first because it is pre-adjudicated. Proposed: cards first, because they are few and carry a why; the byline says which is which either way.
- Sense as the exemplar target (Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105's default) until Sense-level shelves show on 1 % of words: the concept hop, the word-level tier from corroborated candidates, and promotion — so Quotes, Artworks and Images appear on most pages without a name match #172's promotion pass; concept only when the word's thing exists and the nominator means the practice.
- The first manifest's rows are yours. The seeder refuses a person without evidence; the copy never says is. Whether Bezos → coward is the first row is an editorial call this issue does not make.
- Build 3 now or after public nomination. With one curator the score is one; the migration can wait until a second person can vote.
Relationship to existing issues
- Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105 stays the exemplar product spec: nomination form, endorsements with reasons, Wilson ordering, GIFs as subjects, public nomination and rate limits are its steps 4–7 and stay there. This issue builds its steps 1 and 3, takes step 2 as build 3, and adds the layer beneath it.
- Sense-level shelves show on 1 % of words: the concept hop, the word-level tier from corroborated candidates, and promotion — so Quotes, Artworks and Images appear on most pages without a name match #172 shares the
PageEvidenceread and the word-level, labelled rule; an instance reached through a candidate rather than arefers_towould carrylevel: wordthe same way. Not built here. - Why Voltaire is not in the registry: people enter through senses, not through credits — 6,674 persons are word-referents; decide on-demand minting, a people seed, or both #165: nominee minting is option 1 for one class of person, through Creator identity for every provider: a result credits a person by identifier, the pipeline resolves or mints the person, the card links the entry — built once, before any durable quotation is written (build 2 of #158) #164's path; the seed question stays open there.
- Curated opening section: Bierce-first lead, sourced highlights and inspectable editorial choices #156: the band's a thing tile draws from
Examples.for_page/2's first item once this lands. - Discovery relation assessor: lite ML and LLM judging of provider results before persona curation #101, Explore local AI curation: persona editors, schema, models and compute budgets #97: slots in build 4; the manifest shape is the interface. Curator Bots #17 is retired by Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105 and stays retired.
- 🔁 MVP-0: absorption-first word graph, walking skeleton (WordNet · Wiktionary · Wikidata · Wikipedia · Bierce, Animals scope) — decisions, schema, pipeline, scorecard #69 §0 promised "examples from the culture … votes rank them"; this is that line, with the record's examples underneath it.
Supplement (2026-09-24): the schema in full, the differences between the kinds, discovery, and what makes it future-proof
Everything above stands. This part answers three questions the first draft only pointed at: what exactly each kind of "example" is, column by column; what each table holds today and what each build writes into it; and how the section relates to the discovery pipeline that fills the shelves. Read against devils_dictionary_v2 on 2026-09-24 and main @ 0d69346, including the constraints as the database enforces them.
S1. Four kinds of "example", and what separates them
| usage example (layer 0) | instance (layer 1) | exemplar (layer 2) | shelf item (discovery) | |
|---|---|---|---|---|
| What it is | a sentence using the word | a named thing a source files under a meaning | a thing a person (or bot) attaches to a meaning, with a why | a provider's result for the page's term |
| Lives in | sense_revisions.examples (jsonb on the definition) |
assertion_revisions, predicate instance_of |
assertion_revisions, predicate illustrates |
discovery_results (+ source_records) |
| Subject identity | none: text | a sense (WordNet) or an entity (Wikidata), both objects rows |
an objects row: entity/person|organization|event|artifact|work or content/media|image|quotation|passage |
external_namespace + external_id; object_id only when resolved (540 of 1,355 today) |
| Target | the sense it sits on | a sense (sense/-, new rule) or an entity (entity/*, existing) |
a sense (sense/-) or a concept (entity/concept) |
the page's lexeme set, term-level (relevance: term_unverified) |
| Who asserted it | the dictionary | the source: assertions.source_id = wordnet or wikidata, method: "source", origin_key from the source's own edge |
an actor: assertions.origin_actor_id (the claimant), submitted_by_actor_id (who typed it), source_id = community (or a bot's source), method: "curated" | "persona:…" | "assessor:…" |
the provider, via a versioned discovery_mappings recipe |
| The why | — | none, by construction | assertion_revisions.rationale (required non-empty, contributions.ex:74) |
a MatchReason computed from match_details |
| Evidence | the ref in the json |
the source record it was materialized from (source_record_id on the assertion) |
assertion_evidence rows, supports | contradicts, ≥ 1 for a person subject |
match_details (identity / attestation / query) |
| Reviewed? | no | no — the source is the adjudicator | yes: assertion_reviews, derived latest-wins, review_contexts snapshot the endpoint revisions seen |
no; display_allowed and display_policy_reason on the record are the only gate |
| Voted? | no | never | yes, per revision, ±1, one per actor (build 3 adds reason and the cached tally) |
no |
| Visibility | with the card | with the word: lifecycle_state = active, is_current |
Claims.visible/2: hides rejected/withdrawn; this issue adds hide-until-accepted for person subjects |
display_allowed on run and record; retention deletes |
| Lifetime | until the source is re-absorbed | until the source is re-absorbed (a re-absorb revises the same assertion by origin_key, materializer.ex:1165) |
forever, as revisions; withdrawal keeps history | disposable: expires_at, refresh_after, retention_seconds per source (#144 Phase 2) |
| Reaches the page by | WordPage folding the sense's examples into the card |
Examples.for_page/2 → instance_of rows whose object is a page sense, or whose object is the page's refers_to entity |
Examples.for_page/2 → illustrates rows whose object is a page sense / the page's entity, through Claims.visible/2 for the viewer |
Discovery.state/2 → Shelf → Culture, over PubSub after first paint |
| Register | inside the definition | chip | card | shelf card, per content type |
| Copy | as the source wrote it | named under a sense of X by WordNet | cited as an example of | the reason sentence, held locally / searched for on this visit |
| Signals | — | source_count, best_tier |
human_up, human_down, featured_at, evidence count |
none (order is tier then slug, #116 K2) |
The line between the two middle columns is the whole design: an instance has no rationale column to fill and no vote to cast; an exemplar has no source-native flag and no origin_key from a dump. Neither can be confused for the other in the database, which is why one section can hold both.
S2. The tables, what they hold today, and what each build writes
Column lists are the live ones. "Writes" names only what this issue adds; every existing row and column is untouched.
objects — id, kind, lifecycle_state. The one identity every endpoint points at (assertion_revisions.subject_object_id / object_object_id → objects.id, ON DELETE RESTRICT). A sense, a lexeme, an entity and a content item are all objects, so a subject may be any of them and a future subject kind needs no schema. Writes: build 2 mints an objects row per new nominee (through Registry.create_entity).
lexemes — object_id, language_tag, lemma, part_of_speech, slug, canonical_lexeme_id, enriched_at, source_ids[]. Reads: the chip's label, slug and enriched state. Writes: none. A WordNet instance whose subject is a lexeme with a page (Hundred Years' War, noun) is a chip that hops; one without is not written (WordNet's graph is closed, so all 33,898 resolve or wait in pending_relations with to_lemma).
senses — object_id, lexeme_id, source_id, external_key, identity_state; sense_revisions — sense_id, gloss, group_key, examples, is_current, lifecycle_state, source_record_revision_id. Reads: the target's gloss on a card (sense 2 · a ruler who…), the manifest's sense.match against the current gloss. Writes: none. A refresh that rewrites a gloss creates a new sense_revisions row; the claim's review_contexts.fingerprint no longer matches and the card reads changed since review (already built, #84).
entities — object_id, entity_kind ∈ concept\|taxon\|work\|person\|organization\|place\|event\|artifact\|edition, preferred_label, description, metadata; person_details — entity_id, birth_date, death_date; external_identifiers — object_id, namespace, external_id, status ='verified', source_record_revision_id. Reads: the card's label, kind badge and thumbnail (metadata.image_url, 3,826 persons have one), the entity page. Writes: build 2, a nominee absent from the registry: one entities row (entity_kind: person, metadata from the wbgetentities answer, origin_source_id = community), one person_details, one external_identifiers (wikidata, verified). Through Creators.prepare/apply (#164) so the QID is the identity and a label is never one. A nominee with no QID is refused (rule 3).
predicates — key, forward_label, reverse_label, is_symmetric, is_transitive, cycles_allowed, source_native, description; predicate_endpoint_rules — (predicate_id, subject_kind, subject_subkind, object_kind, object_subkind), the composite target of assertion_revisions_endpoints FK. Both seeded from priv/predicates/*.json by mix dd.reset. Today instance_of has 100 rules, all entity/* → entity/*; illustrates has its person/organization/event/artifact/work/media/image/quotation/passage → sense/concept set. Writes: build 1 adds one rule, instance_of: sense/- → sense/-, as a line in core.json. Nothing else. An illustrates row from a subject kind not in the rules (a place, a taxon) is refused by the FK at insert, which is what makes "a new subject kind" a data change and never a code change.
assertions — id, source_id, origin_key, origin_actor_id, submitted_by_actor_id. The durable claim; revisions hang off it. Writes, build 1: one per WordNet instance edge, source_id = wordnet, origin_key = the edge's own key (so a re-absorb finds and revises rather than duplicates), actors null. Writes, build 2: one per exemplar, source_id = community, origin_actor_id = the curator's actor, submitted_by_actor_id = the seeder's actor (the same person today; a bot later).
assertion_revisions — assertion_id, revision_number, subject_object_id, predicate_id, object_object_id, subject_kind, subject_subkind, object_kind, object_subkind, rationale, method, confidence ∈ [0,1], lifecycle_state ∈ active\|withdrawn\|superseded\|rejected, is_current, metadata, valid_from/to, context_object_id. Two rows this issue writes, side by side:
| column | instance (build 1) | exemplar (build 2) |
|---|---|---|
subject_* |
sense/- — the sense of Korean War |
entity/person — Jeff Bezos's object id |
predicate_id |
instance_of |
illustrates |
object_* |
sense/- — WordNet's sense of war |
sense/- — the resolved sense of coward |
rationale |
null | required text |
method |
"source" |
"curated" (later "persona:bierce@3", "assessor:1") |
confidence |
null (a source edge is not a probability) | null; confidence is for the linker's rungs, not opinions |
metadata |
{"label": "instance_hypernym"} — the fix; today {} |
{"manifest": "first-v1", "row": 3} for provenance back to the file |
lifecycle_state |
active; a re-absorb that drops the edge → superseded |
active; a reviewer's withdrawal → withdrawn, history kept |
assertion_evidence — assertion_revision_id, source_record_revision_id \| content_revision_id \| sense_revision_id (≥ 1, CHECK), evidence_role ∈ supports\|contradicts, locator, attribution_text. A URL alone cannot be evidence — the CHECK requires a target row. So a manifest's evidence.url is stored as a source_records row under community (url, external_id = the URL's hash, display_allowed) with one source_record_revisions payload holding only {url, title, attribution, observed_at} — never page text, which keeps every news source's retention terms trivially satisfied — and the evidence row points at that revision with attribution_text = The Guardian, 3 March 2025. A quotation already in the registry is content_revision_id; a definition is sense_revision_id. Writes: build 2, one row per manifest evidence entry; contradicts rows allowed and shown.
review_contexts — assertion_revision_id, snapshot, fingerprint; review_context_items — context_id, endpoint_role, content_revision_id \| sense_revision_id; assertion_reviews — assertion_revision_id, review_context_id, reviewer_actor_id, decision ∈ accepted\|disputed\|rejected\|withdrawn\|needs_review, reason, append-only, latest wins (Claims.review_state/1). Writes: none by the seeder; the reviewer on /connections/:id writes reviews as today. Reads: Claims.visible/2 for the public view; display_review_states/1 for the card's state word. The person rule is a where on subject_kind = 'entity' AND subject_subkind = 'person' joined to the latest decision — both columns exist, no migration.
assertion_votes — assertion_revision_id, review_context_id, actor_id, value ∈ {-1, 1}, unique (assertion_revision_id, actor_id), ON DELETE CASCADE from the revision. Writes: build 3 only. The migration:
ALTER TABLE assertion_votes ADD COLUMN reason text; -- the endorsement's own why
CREATE TABLE assertion_scores (
assertion_id bigint PRIMARY KEY REFERENCES assertions(id) ON DELETE CASCADE,
revision_id bigint NOT NULL REFERENCES assertion_revisions(id), -- which revision the tally is for
human_up integer NOT NULL DEFAULT 0,
human_down integer NOT NULL DEFAULT 0,
bot_up integer NOT NULL DEFAULT 0, -- displayed apart, never summed in
bot_down integer NOT NULL DEFAULT 0,
computed_at timestamp NOT NULL
);Recomputed inside Claims.vote/4 from assertion_votes joined to actors.actor_kind; a property test asserts human_up − human_down = sum(value) where actor_kind = 'user' after every vote. A new revision zeroes the tally by construction (votes are per revision), which is why endorse-on-duplicate matters: a re-worded claim is a new revision and starts again.
actors — actor_kind ∈ user\|bot\|import\|external\|unknown, user_id, bot_source_id, entity_id, label. Reads: the card's nominated by and the human/bot split of the tally. Writes: none here; a persona (#97) creates one bot actor with bot_source_id → its sources row.
sources — slug, name, tier ∈ aristocracy\|middle\|plebs, kind ∈ dictionary\|encyclopedia\|lexical_db\|knowledge_graph\|media_provider\|crowd\|bot\|corpus, access, license, url_template, attribution, logo. Writes: build 2 adds community (kind: crowd, tier: plebs, access: user), the source of every hand-curated claim, every minted nominee and every URL evidence record. The section's byline is composed from sources rows the way the shelf's is (#152), so the component names no source.
source_records / source_record_revisions — source_id, external_id, url, content_hash, fetched_at, display_allowed, display_policy_reason / payload, checksum, observed_at. Reads: an instance's provenance link (the WordNet synset it came from). Writes: build 2's evidence records, above.
pending_relations — source_id, source_record_id, subject_object_id, predicate_id, to_lemma, to_pos, confidence, method, metadata. Where a WordNet edge waits when its target sense is not yet materialized. Writes: build 1's re-absorb drains any instance edge that was pending, the same way hyponyms drain.
discovery_mappings / discovery_runs / discovery_results — untouched. See S3 for why.
content_items / content_revisions — content_kind, source_id / body, canonical_url, headword, year, rights_metadata. Writes: none until #105's step 5 (a GIF or a headline as a subject mints a content_items row first). The endpoint rules for content/media|image|quotation|passage → sense/- already exist, so that step is a minting function and a form, not a schema.
S3. How it works with discovery
Discovery is a cache; this is the register. DevilsDictionary.Discovery's own moduledoc: "Discovery appearances remain search cache and never create illustrates claims." A discovery_results row has expires_at, refresh_after and a per-source retention_seconds that deletes it and the source_records it owns (#144 Phase 2). An assertion_revisions row has none of those. So the two never share a table, and the section never reads discovery_*: an instance is an offline identity match a source made, an exemplar is a reviewed claim, and both outlive every run. This is the same distinction the README draws between a corpus (committed, held locally) and a provider (asked on this visit), one level up.
Three seams, each one-directional.
-
From the registry to the shelves — unchanged, and deliberately not widened. Every identity-matching provider reads
PageEvidence.entities/2: the QIDs the page's sensesrefers_to. An instance chip is not added to that read. Korean War's Q8663 is not a meaning of war, and a Met search on it would put a Korean War photograph on the war Artworks shelf under a reason that says a sense of war refers to Q8663, which is false. The Korean War's own page gets its own shelves. C4 above ("the record is the record") is this rule. -
From a shelf to the register — the promotion path, gated on identity. Today the only promotion is the Artsy card's deep link that prefills
/connect(word_live.ex:36). This issue keeps that shape and states its rule: a shelf card offers cite this as an example only when its result has anobject_id(resolution_state ∈ matched \| newly_created, 540 rows today), because only a registry object can be the subject of anillustratesrow. A result ininsufficient_evidence(every Guardian, Bing, Pexels, Openverse result: 815 rows) has no subject to claim with; Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105 step 5 mints one. A nomination from a shelf writes the sameillustratesrow throughContributions.propose/6withmetadata: {"from_result": result_id, "provider": slug}so the ledger shows where a reader found it; the result row itself is still deleted on schedule. Nothing flows back. -
From the register to the band (Curated opening section: Bierce-first lead, sourced highlights and inspectable editorial choices #156). The band's a thing tile is defined as the thing panel (concept image + description); later an exemplar (Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105).
Examples.for_page/2's first item is that "later": the tile draws the top accepted exemplar's card, or the top instance's chip with its thumbnail when there is one, linking down to#examples. One read, two surfaces.
News, specifically. The owner's example is coward "through news". Guardian and Bing results carry no entity and no QID; their evidence class is :attestation (the article uses the word, at a dated locator) and Bing's is :query. Neither can name Bezos. The path is: a reader sees the headline on the News shelf, and nominates through the form or the manifest with that article's URL as evidence — the URL and byline only, stored as an evidence record under community, which is inside every news source's terms (the Guardian's clause 6(g) forbids text-mining and AI over content; a link and a citation are neither). The assessor (#101), when it exists, may propose the same row from a Bing headline it is allowed to read, method: "assessor:…", review-only. Nothing proposes from Guardian text.
What the section inherits from the discovery kit, and what it does not.
Kit promise (docs/discovery/README.md) |
Applies to the section? |
|---|---|
| 1 — identity or attestation, never a search's ranking | yes, stronger: every item is an identifier a source or a person asserted; there is no :query class at all |
| 3 — every item says why it is here, from fields | yes: item.reason, one sentence, full stop; conformance asserts it |
| 4 — what a licence owes | not applicable: chips are words, cards are registry entities; the Wikidata image credit on a card uses the entity's image_attribution as the thing panel does |
| 7 — an honest empty | yes: the section renders its empty for a word with nothing (/define/logomachy) |
| 8 — composition is read-time; persisted rows never rewritten | yes: Rank.order/1 is pure; the tally is a cache, not a rewrite |
| 9 — the component knows no provider by name | yes, and no source by name: byline from sources rows |
| 2 — one shelf per content type | no: this is not a shelf. It is one section with two registers, and it has no content-type row, no retrieve/4, no run, no budget. Adding it touches ContentTypes not at all |
Evidence class naming. MatchReason's classes (:identity, :attestation, :query, and #172's :word_identity) describe how a provider's result met the page. They are not extended here. The section's items carry basis: :record | :cited instead — different vocabulary on purpose, so nobody reads a chip as a shelf result or a card as a match.
S4. What makes it future-proof
The properties below are what let every later change be data, a new function, or a new row, and never a rewrite. Each names the mechanism that holds it.
| When this arrives | What changes | What does not | Held by |
|---|---|---|---|
| A third instance source (Wiktionary's proper-noun hyponyms, a museum's "example of" tags) | one absorb mapping to instance_of; the byline gains a source name |
the section, the read, the rank | source_native predicate + assertions.source_id; source_count is count(distinct source_id) per (subject, object) |
| WordNet and Wikidata both file the same thing (corroboration) | nothing | — | two assertions with one (subject, object) pair once #172's promotion links the instance lexeme's sense to its entity; source_count = 2 |
| A new exemplar subject kind (GIF, meme, headline) | one content_items minting function; the endpoint rule already exists |
the illustrates predicate, the card, the rank |
subject is an objects id; legality is the composite FK |
| A subject kind nobody planned (a place: Enron's Houston) | one line in core.json |
everything else | predicate_endpoint_rules seeded from the file; the FK refuses until the line exists |
| Concept as target after #172's promotion pass | the manifest's sense block gains a concept alternative |
the read (it already joins the page's refers_to entity) |
illustrates: * → entity/concept rules exist today |
| Public voting | build 3's two columns; rate limits | the vote API (Claims.vote/4 upserts already) |
unique (revision, actor); per-revision votes |
| Reasons on votes vs. an endorsements table | start with the column (#105's call); a table later is additive | the tally | assertion_scores counts rows, whichever table holds them |
| Wilson ordering, recency, a curator's hand order | Rank.order/1 replaced or assertion_features (#105) added |
the item shape, the section | ordering is one pure function over signals; the band already proved "curation replaces the rule, not the component" (#156) |
| Personas (#97) | a bot actor, a bot source, method: "persona:<slug>@<v>", their own curation_nominations work table |
the illustrates row they end in; the review; the card (which says selected by Bierce-inspired AI) |
actors.actor_kind splits human_* from bot_* in the tally; method is a free string |
| The assessor (#101) | method: "assessor:<v>", review-only |
the same | Claims.visible/2 hides needs_review for persons; a reviewer accepts or nothing shows |
| A sense refresh rewrites a gloss | the card reads changed since review | the claim stays attached | review_contexts.fingerprint vs. the current endpoint revisions (#84, built) |
| Identity reconciliation splits or merges a nominee (#164's cases) | the claim's endpoint moves with the object | the claim | endpoints are objects ids; Contributions already re-maps evidence on a split (contributions.ex:268) |
| A source is withdrawn (the Artsy precedent) | its assertions go withdrawn; the section drops them on the next read |
history | lifecycle_state; no row deleted |
| The JSON API and the PWA (#69 decision 13) | none | — | Examples.for_page/2 returns plain maps; the LiveView is one client of it |
| A model upgrade re-runs a persona over every word | zero duplicates | — | the seeder's and the form's idempotence on (subject, predicate, object); a re-run is an endorsement or held |
Two invariants underneath all of it, both already in the database rather than in a convention: every endpoint is an objects id, and every endpoint pair is legal only if a rule row says so. A layer is therefore a predicate plus a method vocabulary plus a register, and a new layer (an editorial pick that is neither the record's nor a citizen's, say) is a third predicate, a third basis atom and a third register on the same section — with no table.
S5. Two details the supplement fixes in the schema section above
- "
evidencerows, a URL locator" in Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105 and in the schema table above is not enough on its own:assertion_evidence_has_targetrequires a revision id. The URL is asource_recordsrow undercommunity(S2). This is also the answer to retention: the record holds a URL and a citation, never a body. confidenceon an exemplar is null. Exemplars: people, works and media as attributed examples of a meaning — nomination, the why, votes, ranking and the reverse view on a person's page #105 mentionsconfidenceon the claim; the column's meaning on this site is a linker rung's certainty (wiktionary_qid0.95,wordnet_ili0.85). An opinion has no rung. Leaving it null keeps the health checks that reason aboutconfidencehonest.
Specification revision (2026-09-24, after review)
A review of the issue raised six points. Each was checked against the code before being taken; what follows amends the contracts above where the check held and says where it did not. Nothing above is rewritten; where a rule here contradicts one above, this section wins, and the build that touches it updates the earlier text in the same PR.
R1. "Pre-adjudicated" means adjudicated by the source, not settled
The review objected that "pre-adjudicated" reads as "objectively true". Taken. The term stays, defined: an instance is source-listed — the source adjudicated it, this site did not, and that is why it bypasses the nomination queue. It is not exempt from dispute. assertion_reviews targets any revision, and Claims.visible/2 already hides rejected and withdrawn regardless of predicate, so a reviewer can reject WordNet filing Judas under traitor on /connections/:id exactly as they reject an exemplar, and the chip disappears. Two rules follow:
- A re-absorb does not resurrect a rejected instance:
write_assertions/3writes a new revision only if something changed, and the rejection sits on the revision. If the source changes the edge, a new revision is written and the reviewer sees it again asneeds_review-equivalent (the changed since review label); that is correct, because the source changed its claim. - Copy stays named under a sense of X by WordNet, which says who listed it and does not say it is so. The vocabulary entry for instance above gains the words source-listed; disputable here.
R2. Corroboration needs an identity rule, because a sense is not an entity
Confirmed against the schema: WordNet's instance is sense → sense, Wikidata's is entity → entity, and "two assertions with one (subject, object) pair" above was hand-waving. The rule:
An item's key is {subject_family, target_family}, where a family is the registry object a sense resolves to when it resolves, and the sense's lexeme otherwise:
| endpoint | resolves through | family |
|---|---|---|
| a subject sense (WordNet's Korean War sense) | senses.lexeme_id → the lexeme's senses' current refers_to |
the refers_to entity when the lexeme has exactly one; else the lexeme |
| a subject entity (Wikidata's Q8663) | — | the entity |
| a target sense (WordNet's sense of war) | its current refers_to |
the entity when one exists; else the sense |
| a target entity (Q198) | — | the entity |
So Korean War is one item with source_count = 2 when its lexeme refers to Q8663 (it does: refers_to 1) and war's sense refers to Q198 (it does), and two chips when either link is missing — deliberately, because merging by label is the identity-by-string mistake #74 exists to end. A lexeme with two refers_to entities (polysemy) never merges; its chips stay per sense. Every original assertion is retained on the item: item.sources is [%{slug:, tier:, assertion_id:, subject_object_id:, object_object_id:}], so a reader can open either claim. The build 1 spike reports the three counts: merged, unmergeable for want of a link, refused for ambiguity. Today at most 4,194 of 33,898 subjects can resolve to an entity, so most instances are single-source chips until #172's promotion pass lands; that is the honest number, not a defect.
R3. Visibility is by predicate, not by subject kind
The review is right on both halves, and the code confirms the first: a blanket person subjects wait for acceptance rule in Claims.visible/2 would hide imported facts — today 7 current Wikidata instance_of rows with a person subject, and every future participates_in. The second half is a hole in #105's rule 1: an assessor's or persona's nomination of an organization or an event would be public before review.
Amended rule, replacing the person rule in the Schema table and in C5: every illustrates claim is invisible to :public until its latest review is accepted, whatever its subject kind and whoever wrote it. The exemplar layer is, by definition, the one adjudicated here; a claim nobody here has accepted is not yet an exemplar. This is stricter than #105 rule 1 (which gated persons only) and simpler to hold: one where on predicates.key = 'illustrates' joined to the latest decision, no subject_subkind test. Person-specific protections (evidence required, a QID required, the copy rules) stay layered on top. Endpoint refresh: an accepted exemplar whose target sense or evidence revision changes is labelled changed since review and stays visible; it is hidden only by a new decision. Hiding on every Wiktionary refresh would empty the section without anyone deciding anything. This changes Decision 3's neighbour: added to Decisions owed as decision 6 below.
R4. Contributions.propose/6 is not yet the shared path; here is the interface it has to grow
Read at contributions.ex:66-104: propose/6 requires a user scope (internal_user!/1), hardcodes method: "curated", and Map.takes the attrs down to rationale, context, jurisdiction, language and validity — so metadata and method from a manifest are dropped on the floor. The interface, specified now so the seeder and, later, a bot call one function:
Contributions.propose(scope, subject, predicate, object, attrs, evidence)
# scope: %{user: %{id}} — a person; actor = their user actor
# %{actor: %Actor{actor_kind: :bot}} — a persona or the assessor; requires bot_source_id (existing constraint)
# attrs: rationale (required), method (∈ "curated" | "persona:<slug>@<v>" | "assessor:<v>"; default "curated";
# a user scope may only pass "curated"), metadata (map, kept whole), claimant, context/jurisdiction/… as today
# source: the actor's source — `community` for a user, `actor.bot_source_id` for a bot; never passed in
# returns: {:ok, %{claim:, outcome: :created | :held | :endorsed}}Duplicate handling, reconciled (the review caught that held and endorsement were both claimed for one event): the semantic key is (subject, predicate, object).
| the same key already exists, and… | outcome | writes |
|---|---|---|
the caller's actor is the existing claim's origin_actor_id |
:held |
nothing — replaying a manifest is a no-op |
| a different actor, build 3 not yet merged | :held, with the existing claim id and already cited by N |
nothing; the seeder prints it |
| a different actor, build 3 merged | :endorsed |
one assertion_votes row (+1, the caller's reason), never a second claim |
A bot actor's endorsement lands in bot_up, never human_up. The form on /connect gets the same three outcomes as copy.
R5. The WordNet repair has a transition, and it is the reconcile pass
Confirmed at materializer.ex:1409: relation_key/1 is rel|<subject>|<type>|<target>, so mapping instance_hypernym from other to instance_of produces a new origin_key, and write_assertions/3 will mint a new assertion rather than revise the old one. The old other row is not orphaned, though: outputs are owned by the run that stamped them, and reconcile/2 (materializer.ex:1669-1718) withdraws every assertion a completed run did not re-stamp, with the reason no longer emitted by its source. So the transition is:
- The re-absorb writes 33,898
instance_ofassertions under their new keys and re-stamps every other WordNet edge, now withmetadata["label"]. - The reconcile pass withdraws the 33,898 old
otherassertions the run no longer emits (lifecycle_state: withdrawn, history kept, reason recorded). - Nothing else moves: the 121,364
otherrows that were not instance edges are re-stamped in place with their label added, which is a metadata-only revision.
Acceptance, added to build 1: after two consecutive re-absorbs, (a) the count of current active instance_of sense→sense rows equals the count of instance_hypernym edges in the dump; (b) zero current active other rows have an instance_hypernym label; (c) the second run writes zero new assertions and zero new revisions; (d) mix dd.health prints the withdrawn-by-reconcile count once and zero the second time. The spike measures step 2's count before the run so a mismatch is visible.
R6. The item shape, finished
The shape above was missing what its own wireframes draw. The full contract, with every field the card or chip renders and nothing it does not:
%{
id: "inst:<subject_family>:<target_family>" | "ex:<assertion_id>", # stable across renders and re-absorbs
layer: :instance | :exemplar,
basis: :record | :cited,
subject: %{kind: :lexeme | :entity | :content, object_id:, label:, slug: | nil, entity_kind: | nil, thumbnail: %{url:, attribution:} | nil},
target: %{kind: :sense | :entity, object_id:, gloss: | nil, source_slug: | nil, sense_key: | nil}, # the meaning
sources: [%{slug:, tier:, assertion_id:, subject_object_id:, object_object_id:, record_url: | nil}], # instance: ≥ 1; exemplar: [community | bot source]
claim: nil | %{
assertion_id:, revision_id:, method:, rationale:,
nominated_by: %{actor_id:, label:, kind: :user | :bot},
evidence: [%{role: :supports | :contradicts, url: | nil, attribution: | nil, locator: | nil}],
review: %{state: :accepted | :disputed | :needs_review | …, by: %{actor_id:, label:} | nil, decided_at: | nil, changed_since_review?: boolean},
manifest: %{slug:, row:} | nil
},
signals: %{source_count:, best_tier:, human_up:, human_down:, bot_up:, bot_down:, evidence_count:, featured_at: | nil},
reason: "…"
}And around the list: for_page/3 takes (lexeme_ids, viewer, opts) and returns %{items: [...], totals: %{instance: n, exemplar: n}, cap: %{instance: 12, exemplar: 6}} — exact totals beside a capped list, as kinds_and_examples/2 does, because knowing there are 349 poets is worth more than seeing twelve. Ordering is Rank.order/1 then id ascending as the final tie-break, so two renders of one page agree. Pagination is not in this issue: the entity page has cursors already (entity_page.ex), the section shows the cap and links to the word's entity page or to /connections for the rest.
The manifest records what it resolved. sense.match is an authoring convenience. At seed time the seeder writes into the claim's metadata the resolved sense.external_key, its source_id and the sense_revision_id it matched against, and stores the same on the manifest row's result file. A later run that resolves sense.match to a different sense key refuses the row and prints both; it never silently retargets. A gloss rewrite that keeps the key is the ordinary changed since review case (R3).
Amendments to the sections above, in one place
| Section | Was | Now |
|---|---|---|
| Vocabulary · instance | "Pre-adjudicated; the record's claim" | "Source-listed and disputable here; adjudicated by the source, not by this site" (R1) |
| Design · read model | the short shape | the R6 shape; for_page/3 with totals and caps |
| Design · corroboration | "sources agreeing" | the family rule in R2; item.sources keeps every assertion |
Schema · Claims.visible/2 row |
person rule | the illustrates rule (R3); no subject_subkind test |
| Schema · new row | — | Contributions.propose/6 accepts a bot scope, a whitelisted method, metadata; returns :created | :held | :endorsed (R4) |
| Contract C5 | rules 1–4 and 6 of #105 | rule 1 replaced by the illustrates-wide gate; the rest unchanged |
| Contract C6 | "idempotent on (subject, predicate, object)… reports held" |
the three-outcome table (R4) |
| Contract C7 | the label fix | plus the reconcile transition and its four checks (R5) |
| Build 1 acceptance | — | the four R5 checks; the R2 spike counts |
| Build 2 acceptance | — | a replayed manifest reports :held with zero writes; a second actor's row is :held with already cited by 1 until build 3; a row whose sense.match moves is refused |
| Decisions owed | 1–5 | 6. The illustrates-wide public gate (R3) is stricter than #105 rule 1: every exemplar, including an artwork under allegory, waits for a reviewer. With one reviewer this costs one click per claim; say if the person-only gate is preferred. Resolved 2026-09-25 for the prototype: person-only (#186). A nomination of a person is hidden from the public until accepted, and imports are exempt. The broader gate is deferred to #190 and must land before bots (#97, #101) or the public (#105) can nominate. |
Not taken from the review: nothing was rejected outright. Its grade of "architecture right, behavioural rules incomplete" is the fair reading of the first draft; this revision is those rules.
Activity
holden commentedon Sep 24, 2026
Build 1: PR #183, with the spike and the evidence
Spike (
devils_dictionary_v2,main@ 0d69346, read-only)WordNet's instance edges are counted from
source_record_revisions.payload->'_edges'wheresubtype = 'instance_hypernym', then matched to assertions byorigin_key.other,metadata {})(word, named thing)refers_toexactly one entity (mergeable)otherrows, all unlabeledThe count that matters is things, not edges. WordNet files every member of a synset under every member of the class. So dictator's 20 edges are 6 people: Hitler, Adolf Hitler and Der Fuhrer are one synset. Keying items by lexeme, as R2 has it, would draw Hitler three times, so build 1 keys them by synset, or by the one entity the synset refers to.
Top 30 by things: city / metropolis / urban-center 662 · author / writer 337 · town 281 · river 200 · port 185 · national-capital 184 · geographic-area / geographic-region / geographical-area / geographical-region 160 · island 146 · poet 145 · composer 132 · national-leader / solon 111 · foreign-terrorist-organization / fto / terrorist-group / terrorist-organization 109 · philosopher 95 · painter 94 · pitched-battle 94 · dramatist / physicist / playwright 92 · state 90 · character 80.
The twelve probe words: war 29 · family 2 · justice 1 · nepotism, grief, love, power, solitude, bank, pop-art, situationship and narcissism 0.
Boxes ticked, with evidence
/define/war. Measured on a scratch database seeded fromdevils_dictionary_v2's own WordNet records through the real adapter and materializer (see Not yet on dev): 44 chips, 12 shown and "32 more named", byline 16 filed as instances of War by Wikidata, 1 of them a word · 29 named under a sense of war by Open English WordNet 2025, and no#thing-examples. Screenshots indocs/design/issue-181/; the test isword_examples_test.exs.otherlabel anddd.health.write_relations/5and the pending rows carrysubtypeintometadata["label"](wordnet_instances_test.exs: pendingotherrows readexemplifies).mix dd.healthprints<source> other unlabeled n / totalunder RESOLUTION.scrollWidth == 375on every 375 capture: war, dictator, poet, traitor and coward, in light and dark. Taken through CDP device emulation.Examples.check/1fails an item without alayer, an instance with a claim, and an exemplar without a rationale.Rank.order/1raises on an item without a layer. A fabricatedhuman_up: 500, featured_at: …on an instance leaves the order unchanged (examples_test.exs).Not ticked, and why
#examplesat all. Say which you want; the empty is a small change.docs/encyclopedia/README.mddoes not exist. The three-layer vocabulary went intodocs/discovery/README.md's Composition section, and its not goals line points there.Not yet on dev
Claims.Catalog.seed!(), which adds theinstance_ofsense/- → sense/-endpoint rule. The command is in the PR, with--no-startso it is not a second Oban node.materialize/1now re-maps storedotheredges from their kept key, so this runs fromrawalone, with no re-read of the dump. The oldotherassertions are withdrawn byreconcile/2.What the code corrected in the issue
The PR lists all of it. The short form:
instance_oflives intaxonomy.json, notcore.json.rawheld the mapped type, so the mapping had to be re-applied at materialize time.instance_ofas entity-only.union_all'd intoWordPage.relations/2, and adds 0.75–6.6 ms of execution (dictator to poet). The section as a whole adds +1 query on a bare page and +2 on a page with a thing, measured againstmain.Merge pull request #183 from razrfly/claude/instance-layer-examples-3…
holden commentedon Sep 24, 2026
Audit of PR #183 (build 1, the instance layer) — grade A. Merged as c423527.
Independent check on the branch, own partition: 16 doctests, 1,944 tests, 0 failures, matching the report. CodeRabbit's one finding (an unlabelled Wikidata instance crashing the page) was real, fixed with a regression test, and its thread resolved.
instance_ofgainssense/- → sense/-where the predicate lives (taxonomy.json, not core.json — the issue was corrected);map_type/1mapsinstance_hypernym;materialize/1re-maps storedotheredges fromsubtypeso the fix reaches stored records without a re-absorb; every relation keeps its label inmetadata["label"]; proved on a real WordNet fixture (Hitler)Examples.for_page/3with the item shape as specified; one synset is one item (members become aliases — the issue's "dictator 20" is 20 edges and six people, corrected);Rank.order/1pure over layer and signals, exemplar clause written and empty;check/1is the conformanceunion_allin the relations statement; the object-side read costs no statement, measured (+1–2 queries for Wikidata's side, ~1 ms each; the first version's semi-join at 170–200 ms was found and split)#examplesbetween definitions and culture, chips capped at 12 with a counted disclosure, byline from sources, badges only when more than one source, entity links for wordless things; thing panel's duplicate removed; 20 screenshots from a scratch database seeded through the real adapterLive now:
/define/waron the running server shows the Examples section from Wikidata's P31 rows. The WordNet side is empty until the re-materialisation the report describes (I ranClaims.Catalog.seed!/0; thesense → senseendpoint rule exists; 0instance_ofsense rows yet). That re-materialisation is the owner's step, and it rewrites 36,921 edges.Residuals: the dictator and logomachy boxes stay unticked until the dev database is re-materialised and the honest-empty decision is made (the builder followed the brief: coward has no section);
mix dd.comparewill show the 36,921 edges as missing against the retired baseline after re-materialisation, as the report warns. Build 2 (exemplars) is unblocked now that #182 has landed.holden commentedon Sep 24, 2026
Build 2: PR #186, with the evidence for the five boxes ticked above
There is no migration. For #165, build 2 takes option 1 for nominees: a QID with no entity is minted through the creator path, with
minted_by: community, and no QID with no entity is refused.needs_reviewclaim, the person minted, not visible to the public; accept → a cardtest/devils_dictionary/examples/exemplars_test.exs(first describe),test/devils_dictionary_web/live/word_exemplars_test.exs; on a scratch DB,first-v1created 3 claims and minted 3 people from one realwbgetentitiescall/connectform holds toosense.matchhits 0 or several senses → refused, with the glossesExamples.cited_as/2/named_under/2, the person-page tests, anddocs/design/issue-181/issue-181-build2-person-*.pngCorrections the code forced (details in the PR):
entitieshas noorigin_source_id. The origin ismetadata["minted_by"], and the claim'sassertions.source_idiscommunity.Creators.apply/4writes a credit, so it cannot mint an exemplar's subject. The newresolve_identified/3is its locate-and-mint half.wikidatabudget needs a run, so the seed paces itself instead.Decision 6 is still owed. I built the brief's person rule, scoped to nominations (submitted by a user or bot), not R3's rule covering all of
illustrates.I did not seed the dev database. The command is in the PR.
Merge pull request #186 from razrfly/claude/exemplar-layer-build-2-32…
holden commentedon Sep 25, 2026
Closing on the prototype scope: builds 1 and 2 are merged
mainat c4f4644 passesmix precommitwith 16 doctests, 2,057 tests and 0 failures.Dev database, checked read-only on 2026-09-25:
instance_ofsense→sense rows, and 0 unlabelled activeotherrows;--dry-runofpriv/exemplars/first-v1.jsonresolves all three rows.Nothing was seeded or accepted. The dev database has no
communityrow yet. When you want the drafts in:Sources.Catalog.seed!/0;first-v1.jsonas you see fit and re-stamp it withmix dd.exemplars.seed priv/exemplars/first-v1.json --stamp;--as <reviewer email>;/connections/:id.Decisions:
illustrates-wide gate is Gate every illustrates nomination until accepted before bots or the public can nominate (#181 decision 6, deferred) #190.Tracked elsewhere:
assertion_scores, the vote control, endorse-on-duplicate), the only migration in this design;