Skip to content

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

Closed

Description

@holden

Purpose

Two different things are called "examples" on this site, and the codebase already separates them without saying so:

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

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/1 is the only ordering, pure over signals; 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. method says who; origin_actor_id says which actor; nothing is displayed as human agreement unless actor_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 other row written by a re-absorb carries metadata["label"]; a health check counts current other rows without one and the count is the residual, printed by mix 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 wbgetentities per 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/war shows an Examples section with its named wars as chips, +N exact, byline naming WordNet and Wikidata; the thing panel no longer duplicates them
  • /define/dictator shows Hitler, Mussolini, Franco, Tojo, the Duvaliers; /define/traitor shows Benedict Arnold; /define/genocide shows the Holocaust — verified on devils_dictionary_v2 on 2026-09-25 through WordPage.build/2; genocide's label fixed in Build 2 of #181: the exemplar layer — cited, evidenced, reviewed before public #186
  • A current other row written after build 1 carries metadata["label"]; mix dd.health prints the unlabeled residual
  • A word with nothing in either layer shows the section's honest empty; /define/logomachy is the fixture → 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)
  • Build 2: a manifest row for a living person with a QID and one evidence URL seeds a needs_review claim, mints the person with origin_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.match hits 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 layer fails; 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_scores matches sum(value) after every vote in a property test; ordering changes when the tally does
  • docs/encyclopedia/README.md gains the three-layer vocabulary and docs/discovery/README.md's not goals line for exemplars points here — docs/encyclopedia/ does not exist; the three-layer table is in docs/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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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


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.

  1. From the registry to the shelves — unchanged, and deliberately not widened. Every identity-matching provider reads PageEvidence.entities/2: the QIDs the page's senses refers_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.

  2. 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 an object_id (resolution_state ∈ matched \| newly_created, 540 rows today), because only a registry object can be the subject of an illustrates row. A result in insufficient_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 same illustrates row through Contributions.propose/6 with metadata: {"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.

  3. 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

  1. "evidence rows, 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_target requires a revision id. The URL is a source_records row under community (S2). This is also the answer to retention: the record holds a URL and a citation, never a body.
  2. confidence on 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 mentions confidence on the claim; the column's meaning on this site is a linker rung's certainty (wiktionary_qid 0.95, wordnet_ili 0.85). An opinion has no rung. Leaving it null keeps the health checks that reason about confidence honest.

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/3 writes 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 as needs_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:

  1. The re-absorb writes 33,898 instance_of assertions under their new keys and re-stamps every other WordNet edge, now with metadata["label"].
  2. The reconcile pass withdraws the 33,898 old other assertions the run no longer emits (lifecycle_state: withdrawn, history kept, reason recorded).
  3. Nothing else moves: the 121,364 other rows 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

  1. holden commented on Sep 24, 2026

    @holden
    MemberAuthor

    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' where subtype = 'instance_hypernym', then matched to assertions by origin_key.

    count
    instance edges in the stored records 36,921 (the issue says 33,898). 8,599 synset pairs, 16,714 subject senses, 7,736 subject synsets
    … resolved, current and active (as other, metadata {}) 36,921, 0 pending
    words gaining examples 1,724 (the issue says 1,663)
    items, one per (word, named thing) 16,482
    R2: subject sense refers_to exactly one entity (mergeable) 4,555 edges
    R2: no link, so the synset stays itself 32,348 edges
    R2: ambiguous, more than one entity, refused 18 edges
    R2: merged with a Wikidata P31 today 20 items
    current other rows, all unlabeled 155,262

    The 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.

    word edges things (chips)
    war 43 29 (+16 Wikidata, 1 of them shared: Peloponnesian War)
    dictator 20 6
    poet 350 145
    painter 225 94
    traitor 2 1 (Benedict Arnold)
    genocide 2 1 (Holocaust / final solution)
    coward, logomachy 0 0

    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

    • Spike posted. Above.
    • /define/war. Measured on a scratch database seeded from devils_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 in docs/design/issue-181/; the test is word_examples_test.exs.
    • The other label and dd.health. write_relations/5 and the pending rows carry subtype into metadata["label"] (wordnet_instances_test.exs: pending other rows read exemplifies). mix dd.health prints <source> other unlabeled n / total under RESOLUTION.
    • Phone, 375. scrollWidth == 375 on every 375 capture: war, dictator, poet, traitor and coward, in light and dark. Taken through CDP device emulation.
    • Conformance. Examples.check/1 fails an item without a layer, an instance with a claim, and an exemplar without a rationale. Rank.order/1 raises on an item without a layer. A fabricated human_up: 500, featured_at: … on an instance leaves the order unchanged (examples_test.exs).

    Not ticked, and why

    • dictator / traitor / genocide. dictator and traitor are shown in the screenshots: Adolf Hitler, Benito Mussolini, Francisco Franco, Francois Duvalier, Hideki Tojo, Jean-Claude Duvalier; Benedict Arnold. genocide was not in the scratch set, and none of the three is on dev until WordNet is re-materialized.
    • The honest empty. The brief for this build said coward renders no section, so a word with nothing has no #examples at all. Say which you want; the empty is a small change.
    • The docs box. docs/encyclopedia/README.md does not exist. The three-layer vocabulary went into docs/discovery/README.md's Composition section, and its not goals line points there.
    • R5's four re-absorb checks. These need the dev re-materialization, which is yours to run.

    Not yet on dev

    1. Claims.Catalog.seed!(), which adds the instance_of sense/- → sense/- endpoint rule. The command is in the PR, with --no-start so it is not a second Oban node.
    2. A WordNet re-materialization. materialize/1 now re-maps stored other edges from their kept key, so this runs from raw alone, with no re-read of the dump. The old other assertions are withdrawn by reconcile/2.

    What the code corrected in the issue

    The PR lists all of it. The short form:

    • Things, not edges (above).
    • instance_of lives in taxonomy.json, not core.json.
    • Stored raw held the mapped type, so the mapping had to be re-applied at materialize time.
    • A6, R1 and the source page counted instance_of as entity-only.
    • The Wikidata read as one semi-join cost 170–200 ms on war; as two statements it costs ~4 ms.
    • The object-side read costs no statement. It is union_all'd into WordPage.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 against main.
  2. added a commit that references this issue on Sep 24, 2026
  3. holden commented on Sep 24, 2026

    @holden
    MemberAuthor

    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.

    Area Grade Basis
    The predicate and the absorb A instance_of gains sense/- → sense/- where the predicate lives (taxonomy.json, not core.json — the issue was corrected); map_type/1 maps instance_hypernym; materialize/1 re-maps stored other edges from subtype so the fix reaches stored records without a re-absorb; every relation keeps its label in metadata["label"]; proved on a real WordNet fixture (Hitler)
    The read model A Examples.for_page/3 with 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/1 pure over layer and signals, exemplar clause written and empty; check/1 is the conformance
    The reverse read A one union_all in 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)
    The section A #examples between 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 adapter
    Report A nine things the code taught the issue, each correct on inspection; six out-of-brief files named; the dev-database steps stated and left to the owner

    Live now: /define/war on 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 ran Claims.Catalog.seed!/0; the sense → sense endpoint rule exists; 0 instance_of sense 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.compare will 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.

  4. holden commented on Sep 24, 2026

    @holden
    MemberAuthor

    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.

    Box Evidence
    A living person, a QID and one URL → a needs_review claim, the person minted, not visible to the public; accept → a card test/devils_dictionary/examples/exemplars_test.exs (first describe), test/devils_dictionary_web/live/word_exemplars_test.exs; on a scratch DB, first-v1 created 3 claims and minted 3 people from one real wbgetentities call
    The same subject and meaning → held, no second claim the same file, held describe. A replay writes 0 rows and makes 0 requests, and the /connect form holds too
    sense.match hits 0 or several senses → refused, with the glosses refused describe. The issue's own example row is refused: "person who lacks courage" is Wiktionary's gloss; WordNet's is "a person who shows fear or timidity"
    No QID and no entity → refused refused describe
    The person page groups by word, in order, with both counts, and the record's instances Examples.cited_as/2 / named_under/2, the person-page tests, and docs/design/issue-181/issue-181-build2-person-*.png

    Corrections the code forced (details in the PR):

    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.

  5. added a commit that references this issue on Sep 25, 2026
  6. holden commented on Sep 25, 2026

    @holden
    MemberAuthor

    Closing on the prototype scope: builds 1 and 2 are merged

    Dev database, checked read-only on 2026-09-25:

    Nothing was seeded or accepted. The dev database has no community row yet. When you want the drafts in:

    1. run Sources.Catalog.seed!/0;
    2. edit first-v1.json as you see fit and re-stamp it with mix dd.exemplars.seed priv/exemplars/first-v1.json --stamp;
    3. seed it with --as <reviewer email>;
    4. accept each claim on /connections/:id.

    Decisions:

    1. Placement: built as proposed, in the main column between Definitions and the culture block.
    2. Cards before chips: built.
    3. The sense as the exemplar's target: built.
    4. The first manifest rows: three drafts are committed for you to edit (Bezos under coward, Zuckerberg under hypocrite, Chamberlain under appeaser).
    5. Build 3's timing: deferred to Exemplar votes: assertion_votes.reason, cached assertion_scores, the vote control and endorse-on-duplicate (#181 build 3) #189.
    6. The review gate: person-only for the prototype, and imports are exempt. The broader illustrates-wide gate is Gate every illustrates nomination until accepted before bots or the public can nominate (#181 decision 6, deferred) #190.

    Tracked elsewhere:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions