Repository navigation
Description
Problem and intended outcome
The encyclopedia needs to represent words, meanings, people, works, events, definitions, quotations and interpretations without confusing their identities or duplicating them for each role. Ambrose Bierce is one person who can author definitions, author literary works, be the subject of a biography, and appear in attributed interpretations. A definition he wrote remains a definition; his biography remains about him; neither becomes a generic example.
Likewise, a contributor can propose Elon Musk as an example of a particular meaning of “egomaniac.” Musk already has a person entry. We need one attributed, reviewable connection visible from both pages, not a second Musk record or an unqualified assertion in his biography.
Build a durable identity and relationship contract, then prove it through a small complete implementation. Related to #72 (backbone correctness), #69 (original model), #70 (implementation). This issue expands #72's stable attachment work into a dedicated design and implementation milestone. It does not replace source-refresh, recovery or operational work in #72.
Current evidence and constraints
Inspected at commit a2ef867:
Sources.Personstores authors inpeople, with optional Wikidata ID and a single source association. It has no foreign-key connection to the encyclopedia identity.Encyclopedia.Conceptstores encyclopedia subjects with a required QID; its kinds aretaxon,thing,other. Locally created works/events/concepts cannot rely on having a QID.Lexicon.Entryrepresents source-published text with word/concept targets and one author. Authorship already exists and should be preserved, not replaced with an example edge.Lexicon.Senseexplicitly preserves source-specific meanings; sources meet through concepts. Retain this policy unless an explicit ADR changes it. Earlier conceptual sketches of a shared sense must not silently override it.- The unshipped community migration sketch requires a lexical subject, provides one concept field for the example object, and uses unchecked polymorphic vote targets. It cannot express the whole model below with enforced integrity.
Keep Phoenix, Ecto and Postgres. A graph database, universal ontology, fixed table count or wholesale rewrite is not required. Extensibility means a controlled way to add types and relationships, not permitting arbitrary strings between arbitrary rows.
Proposed conceptual model
1. Stable identities, separate roles
| Object | Identity responsibility | Examples |
|---|---|---|
| Lexeme | Language, lemma and grammatical identity; explicit variants | egomaniac / English / noun |
| Source sense | One source's meaning, with durable identity and revisions | A WordNet sense; a Wiktionary sense |
| Entity | A referent independent of any provider | Bierce, Musk, an abstract practice, an organization, an event |
| Work / expression / publication | Distinguish creative work from translation, edition and hosted manifestation as needed | A dictionary, its edition, an artwork, a particular recording |
| Content item / passage | Typed text or media with an addressable identity | Definition, quotation, poem passage, image, article excerpt |
| Assertion | An attributable relationship between addressable objects | Authored by, defines, depicts, illustrates, satirizes |
Use internal IDs that survive provider changes. External identifiers belong in a namespace-aware mapping, with provenance and reconciliation status. Labels, names, URLs and QIDs are not universal primary keys. One person may have many names, sources and roles; identical names do not prove identical people. Login accounts and bots are accountable actors, not automatically identical to public biography subjects.
An encyclopedia page is a view over an identity, not another identity. A word page, person page and work page use different sections while sharing the same underlying linked records.
2. Definitions and examples have different semantics
- A definition is source-authored content describing a lexeme or source sense, with edition and provenance. Historical or satirical definitions retain their genre and era.
- An example claim says an object illustrates a selected sense or concept. The illustrating object, target and claim are separate identities.
- A biography is a publication about a person. The person is not their Wikipedia article.
- A quote has a speaker/author attribution and a work/passage location. A later reader's claim that it illustrates a concept is separate.
- A source's grammatical usage example remains source content. A community classification of a real person remains community interpretation.
- A reader can see several source definitions without treating them as identical senses. Concept-level examples may surface through explicit sense-to-concept mappings; sense-specific examples do not automatically propagate to other senses.
3. Make relationships first-class, typed and contextual
An assertion needs:
| Field group | Required meaning |
|---|---|
| Endpoints | Real foreign-key-backed subject and object identities |
| Predicate | Registered, directional relation with allowed endpoint types and display labels |
| Attribution | Who made the claim; distinguish original claimant, submitting account/bot and importing process |
| Evidence | Zero or more explicit evidence records with supporting/contradicting role, source revision and passage/time locator; requirements vary by claim type |
| Context | Structured qualifiers such as date interval, language, jurisdiction, fictional setting, passage or event; optional readable rationale |
| Lifecycle | Revision, provenance, withdrawal/supersession and review history |
| Independent dimensions | Editorial review state, source support, matching confidence and relevance votes; do not reduce them to one score |
Predicate registry examples:
| Predicate | Subject → object | Reverse page label |
|---|---|---|
| authored_by | Work/content → person or organization | Works / definitions authored |
| published_in | Content → edition/publication | Contents |
| defines | Definition → lexeme/source sense | Definitions |
| about | Article → entity | Articles about |
| depicts | Artwork/image → entity | Depictions |
| illustrates | Artifact/event/entity → sense/concept | Attributed examples |
| satirizes | Work/passage → entity/concept | Satirical treatments |
| participates_in | Person/organization → event | Participants |
| refers_to | Source sense → entity/concept | Words referring to this subject |
Store one directional assertion and derive the inverse display; do not write an independently editable mirror edge. Do not infer same_as, synonymy, truth, endorsement, transitivity or clinical diagnosis from an example relationship. Each predicate explicitly declares any inverse, symmetry or traversal rules. Reject invalid endpoint combinations.
For contested characterizations, a source's saying something and the encyclopedia endorsing it are separate. “Contributor A classifies Musk as an example of this sense” must remain attributed on both pages. Acceptance for display is not a diagnosis or a declaration of objective truth.
4. Bierce: complete worked example
flowchart TD
B["Person: Ambrose Bierce"]
W["Work: The Devil's Dictionary"] -->|authored_by| B
ED["Specific edition / source publication"] -->|edition_of| W
D["Definition content: nepotism"] -->|authored_by| B
D -->|published_in| ED
D -->|defines| L["Lexeme: nepotism, English noun"]
BIO["Biographical article"] -->|about| B
SR["Imported record + revision"] -->|evidence_for| D
U["Reader's interpretation claim"] -->|classifies| D
U -->|as_satire_of| C["Concept: nepotism"]
The content is a source definition whether or not a reader later attaches it as satire. Do not manufacture a modern source-sense alignment from a historical headword. The author identity is shared with Bierce's biography. The original work, edition, digital transcription provider and import run have distinct identities/roles. Coauthors, translators, editors and uncertain attribution require role-aware credits, rather than adding one author column per future case.
5. Enforceable storage approach
Preferred design to evaluate in an ADR: a small addressable-object registry referenced by relationships, with one-to-one typed domain records for lexemes, senses, entities and content. Keep lexical/source-specific constraints in domain tables. A registry gives true relationship-target foreign keys without replacing the application with an EAV store.
- Specify how registry kind and subtype existence are enforced transactionally and at the database boundary (including deferred constraint triggers if needed); a plain
(type, id)pair is insufficient. - Give
peoplea one-to-one link to an entity identity, or migrate author details to an entity-backed person subtype. Preserve existing author references through a compatibility stage. - Generalize existing
conceptsto local entity identity with optional external IDs; preserve QID lookups and taxon behavior. - Keep definitions typed; introduce explicit authorship roles and work/edition links while preserving imported provenance.
- Assertions reference registered endpoints and predicates; evidence, credits and qualifiers support multiple records. Assertions needing votes or challenges must themselves be addressable through a constrained target mechanism.
- Predicate domain/range rules need database-enforced validation as well as changesets, including direct/bulk writes.
- Separate assertion identity from supporting evidence. Two sources can support the same proposition without losing their individual attribution or withdrawal history. Different claimants/contexts must not be collapsed by an overbroad unique index.
- Use typed columns/related tables for contractual fields. JSONB is for versioned provider extras, not a hiding place for endpoint identity, moderation or meaning.
- Bound and paginate incoming/outgoing traversal with indexes; no recursive “everything related” query on ordinary page load.
ADR must compare this approach with explicit typed relationship tables. Choose the smallest model that passes the use cases and integrity tests; the conceptual contract is mandatory, this exact schema is a recommendation.
Source responsibilities
| Source/channel | Supplies | Must not automatically establish |
|---|---|---|
| WordNet | Source senses/groups and typed lexical relationships | Identity with every other dictionary meaning |
| Wiktionary / Kaikki | Lexical attestations, source definitions, forms and usage | Universal sense identity from row position |
| Wikidata | External entity identifiers and qualified statements | Sole eligibility for local encyclopedia identity |
| Wikipedia | Versioned articles about subjects | Person = article; every statement independently verified |
| Bierce / Johnson | Authored historical text and source context | A timeless consensus definition |
| ConceptNet, proposed | Commonsense assertions with native relation and underlying dataset lineage | Every edge is synonymy or independent corroboration |
| Artsy / catalogues, proposed | Artwork records, credits and publication context | That an artwork illustrates nepotism or another concept |
| Community / curator bots | Proposed interpretations, evidence and relevance judgments | Authority to rewrite source definitions or silently merge identities |
Provider, author, publisher, submitter and importer are different roles. Attribution and permission to reproduce content are separate. Store license/rights at the relevant record/media level; rights changes can restrict display while preserving permissible identity and relationship metadata. “All sources” means a reviewed adapter contract for each source, not indiscriminate ingestion.
Wireframes — conceptual, not shipped UI
A. Word page: definitions and attributed examples
egomaniac English · noun
Meanings: [Source A sense 1 ▾]
DEFINITIONS
Source A · edition/revision [Provenance]
Definition text… [Author →]
Source B · distinct source account [View sense]
ATTRIBUTED EXAMPLES for selected meaning
Elon Musk → Person
Proposed by contributor A · Disputed
Rationale: … [Evidence 2]
[View claim] [Relevant] [Not relevant] [Challenge]
[Suggest a connection]
B. Person page: one identity, distinct roles
Ambrose Bierce Person
[Overview] [Works] [Definitions] [Connections]
OVERVIEW
Biographical content… [Sources]
DEFINITIONS AUTHORED
nepotism → The Devil's Dictionary · edition…
… [More]
WORKS
The Devil's Dictionary → Author
ABOUT THIS PERSON
Biographical article → Source/revision
INTERPRETATIONS
Attributed claims, if any [Review state]
C. Connection composer: deliberate endpoints and context
Connect [Existing object ▾] [+ Create minimal object]
Object: [Search person, work, event, passage…]
Relation: [Illustrates ▾] (valid types only)
Target: [Word sense / Concept ▾] [Choose exact target]
Context: [Event, time, passage, language…]
Rationale: [Why does this connection apply? ]
Evidence: [+ Source + passage/timestamp]
Claimant: [Original author, if quoting a claim]
Submitted by: current account (recorded)
Preview: “A proposes X as an illustration of Y.”
[Submit for review]
D. Claim detail: same record from either endpoint
X — illustrates → Y
Attributed to A · submitted by B · Disputed
Context and rationale…
Evidence: [Support] [Counterevidence]
History: proposed → edited → reviewed
[Open X] [Open Y] [Challenge] [Revision history]
On narrow screens these sections stack; target identity, attribution and review state remain visible. Relevance votes never replace the evidence or source definition. Empty sections are omitted. Public displays and server-side actions enforce the same moderation visibility.
Use-case and edge-case matrix
All cultural classifications below are proposed test scenarios, not factual judgments about real people or artworks.
| Case | Objects and connection | Required distinction |
|---|---|---|
| Bierce / nepotism | Person authors a definition in an edition of a work | Author identity also powers biography; definition is not an example |
| Musk / egomaniac | Contributor proposes person as example of a source sense | Attributed evaluation, evidence and disagreement; one person record |
| Nepotism / hiring decision | Event illustrates a practice; relatives participate in event | Family relationship alone does not establish preferential treatment |
| Artsy family portrait | Catalogue describes artwork; curator links it to inherited privilege | Depiction/interpretation separate; no automatic nepotism classification |
| Irony / meme | Meme satirizes a situation; reviewer calls it coincidence instead | Conflicting classifications remain inspectable |
| Alienation | Painting evokes social estrangement; legal passage uses property sense | No propagation across unrelated senses |
| Home | Building is a residence; poem explores belonging; UI uses “Home” | Shared spelling does not merge referents |
| Resilience | Material experiment, ecosystem study, personal account | Scientific evidence and metaphor have distinct contexts |
| Justice | Court decision and opposing philosophical evaluations | Legal outcome differs from “the outcome was just” |
| Metamorphosis | Biological process, titled literary work, transformative sculpture | Title match differs from depiction and metaphor |
| Bank | River-bank photo and financial institution | Sense disambiguation before attaching evidence |
| Apple / apple | Organization, fruit concept, word forms | Case/name similarity does not imply identity |
| Poem passage | Passage illustrates nepotism and favoritism | Store passage once; separate claims and rationales |
| Translated poem | Translator, original author, translated expression | Do not credit translation wording to original author alone |
| Reposted meme | Same image appears at multiple URLs with changed caption | Hosting copies versus materially different versions; origin may be unknown |
| Fictional character | Character portrayed as egomaniacal in one adaptation | Character, actor, adaptation and scene are distinct |
| Misattributed quote | Claimed author later corrected | Attribution revision does not destroy quote or retarget its interpretation |
| Multilingual term | Two source senses map to a shared concept | Concept examples may be shared; linguistic usage examples remain language-specific |
| Organization as author | Institution publishes a report | Creator is not required to be a natural person |
| Anonymous work | Work lacks known author or external ID | Valid local identity without invented attribution/QID |
| Same-name people | Two authors share a name | Disambiguate; merge only with evidence |
| Source withdrawal | One of two supporting records is withdrawn | Preserve history and remaining support; recompute current status |
| Entity split | One mistaken combined person record becomes two | Ambiguous attachments require review, never arbitrary reassignment |
| New future medium | Interactive installation added later | Add typed object/predicate support without rewriting existing claims |
Lifecycle and invariants
- Stable IDs never acquire a different meaning due to source reorder. Retired records remain resolvable with history.
- Merges preserve aliases, provenance and old links; splits explicitly identify ambiguous attachments. Reversible editorial actions have audit trails.
- Import reruns cannot overwrite human rejection/confirmation. Source withdrawal and editorial review are independent states.
- Example claims may target local concepts without a dictionary word; words remain a primary navigation surface, not a required foreign key for every object.
- Every reverse page view reflects the same assertion, status and access policy. No public leakage through the opposite endpoint.
- Relation-type changes or target changes create revisions and trigger appropriate re-review; existing votes do not silently endorse a changed claim.
- Traversal is explicit and bounded. Showing related-concept material must label the path; it cannot masquerade as a direct example.
- Unknown is a valid state for authorship, matching and evidence. A source badge does not imply truth or reproduction rights.
Implementation sequence and acceptance criteria
A. Decide and specify
- ADR: identity registry versus typed relationship tables, entity/person unification, source-specific sense policy, predicate rules and work/edition scope.
- Document the assertion/evidence/actor contract and lifecycle, including disputed characterizations and account-versus-person identity.
- Review wireframes using Bierce, nepotism, egomaniac, alienation and one new local artwork.
B. Migrate identities safely
- Backfill author→entity connections from verified identifiers; ambiguous candidates enter a review report. No name-only automatic merges.
- Preserve every existing definition's source, author and URL; prove Bierce's definitions and biography resolve to one person identity.
- Create local entities without QIDs; adding an external identifier later leaves their IDs and attachments unchanged.
- Enforce subtype/target integrity, namespace uniqueness, predicate compatibility and deletion policy in Postgres as well as Ecto.
- Stage compatibility reads and compare counts/provenance before removing obsolete paths; publish rollback procedure.
C. Ship a narrow vertical slice
- Word, person and work views expose typed incoming/outgoing connections with bounded pagination.
- Authenticated contributor creates an attributed connection with exact target, rationale and evidence; reviewer accepts, disputes or rejects it.
- One claim appears consistently from both endpoints; a challenge and revision are visible from both.
- Definition authorship is navigable independently of cultural claims. Multiple authors/roles and unknown authors are supported.
- Same artifact can support multiple distinct claims without duplication or overly broad uniqueness failures.
D. Prove durability, semantics and extensibility
- Run meaningful integration tests for the matrix, prioritizing polysemy, Bierce dual role, contested person example, passage reuse and local identities.
- Test refresh/reorder/withdrawal, entity merge/split and attribution correction; no silent semantic retargeting or loss of review decisions.
- Test direct invalid writes, orphan targets, prohibited predicate endpoints, account/bot attribution and restricted-claim visibility from either endpoint.
- Test claim edits and voting identity; popularity cannot mutate definition text or source support.
- Add one previously unsupported object kind through the documented extension path, without redesigning existing data or using arbitrary unvalidated metadata.
- Measure ordinary word/person page and incoming-edge queries on representative high-degree entities; establish budgets and indexes before broad rollout.
- Run
mix precommitfor implementation changes; update model docs and replace the unshipped community sketch with the chosen contract.
Done means
We can answer what is this object, what role does it play here, what connects it to another object, who asserts that connection, in what context, and what happens when the evidence changes? Bierce's authorship, biography and definition content stay distinct yet navigable. New kinds of examples can be added through a constrained extension path, without corrupting the lexical backbone or pretending every relationship has the same meaning.
Activity
P3: the connected flow — one identity, three pages, one claim (#74)
holden commentedon Sep 17, 2026
Closing as absorbed by #74: its semantic contract, wireframes and use cases were the spec #74 implemented, and its "required decisions" were resolved in ADR 0001 (
docs/adr/0001-encyclopedia-model.md). Nothing here remains that #74, #82 or #84 does not carry.