Skip to content

Genealogy walkthrough

A genealogist can hold four records naming the same person and no way to say that two of them disagree — because the software asked for a birth year and took the last one typed.

This is a sketch. There is no examples/genealogy/ corpus and no command output on this page — every block below is illustrative YAML showing the shape a corpus would take, not a transcript of a run. What is runnable is the seed set at samudaya/examples/genealogy/, which you can copy into a repository and bootstrap from.

The work, before a corpus

The material is records: parish registers, census schedules, vital records, headstones, a family bible. Each was created at a particular time by somebody with a particular reason to know, and that provenance is the whole of its evidentiary weight — an enumerator walking a district in 1880 and a descendant answering a question in 1940 are not equally good witnesses to a birth in 1849.

Genealogy software models a person with fields. Birth year is a field. So when the parish register says 1849 and the census implies 1851, the interface offers one box, and whoever is typing picks. The disagreement — which is the actual state of the evidence, and often the most interesting thing on the page — becomes a number with no history and no dissent.

The conventional workaround is a research log kept beside the tree: a prose document recording what was searched, what was found, and what conflicts. It is written by the careful and it is not machine-readable, so nothing built on the tree can see it.

The ontology dialogue

Bootstrap asks what the irreducible kinds are, what relates them, and what is out of scope. This domain's answers, and the argument that produced them.

person. Not a record. Two baptismal entries, a census line and a headstone may attest one person or two people who shared a name in one parish, and deciding which is the research. A person has to be something records point at.

record. The artifact, with its creator, date and reason to know. Separate from the person and separate from the fact it asserts.

event. A birth, a marriage, a death, an enumeration. This is the class the dialogue has to argue for, and the argument is below.

The hard call: is a marriage a node or an edge?

The obvious model is an edge: person -married-to-> person. It reads correctly, it is what a family tree draws, and it is wrong for a reason that has nothing to do with taste.

An edge cannot be attested. A marriage has a date, a place, a document that records it, and frequently two documents that disagree about the date. An edge has nowhere to put any of that. Modelling it as an edge does not simplify the corpus — it moves the evidence somewhere it cannot be cited, and then loses it.

So a marriage is a node. Which node is the question a foundational alignment forces you to answer out loud.

Where foundational_type stops being a field

If the bootstrap dialogue chose an alignment, every class carries one (choosing an alignment is the decision, and alignment in practice is the field):

# illustrative — the shape a class file would take, not a run
class: event
label: Event
foundational_type:
  ontology: ufo
  type: event
description: |
  Something that happened at a time and a place, and the thing records attest.

UFO's vocabulary makes a distinction the English word hides. A wedding is an event — an occurrence, with a duration of an afternoon. A marriage is a relator — an entity whose existence depends on two people and which is neither of them, with a duration of decades. They have different start dates, different end conditions, and different records attesting them.

Naming the alignment is what surfaces that. Without it, "marriage" is one word in a class list and nobody notices it is two things.

This corpus models the event and entails the bond, and that is a decision with a cost worth writing down. Every record attests an occurrence — a ceremony took place, an enumeration recorded a household — and no record attests a bond directly. A marriage relator class would therefore be a class whose instances no record supports, populated by inference and looking exactly like the attested classes beside it.

The cost is real: "were they married in 1873" is answerable, and "were they married" is a traversal and a judgement rather than a field. That is the same trade the property walkthrough makes when it refuses an owner class, and for the same reason — a stored conclusion cannot fail visibly, and a computed one can.

A different corpus could decide otherwise, and the point of the alignment is that it would have to decide.

The corpus, in outline

Three classes and the edges between them:

# illustrative — not a run
class: record
foundational_type: { ontology: ufo, type: kind }
edges:
  - relationship: attests
    target: event
    direction: out
    description: An event this record asserts happened.

class: event
foundational_type: { ontology: ufo, type: event }
edges:
  - relationship: involves
    target: person
    direction: out
    description: A person this event happened to or concerned.

Note what is not there: no edge from person to anything. A person node carries a name and nothing else that a record could contradict. Everything assertable hangs off events, and every event hangs off the records attesting it.

Claims, honestly tagged — and the disagreement

This is the shortest argument for claim tags anywhere in these walkthroughs, and it costs no corpus to make.

Two records disagree about a birth year. The parish register, created within days by a clerk with a reason to know, says 1849. The 1880 census, taken thirty-one years later from whoever answered the door, implies 1851.

Genealogy software picks one. The corpus does this:

# illustrative — not a run
class: event
label: Birth of Ellen Marbury
description: |
  The parish register records a baptism on 4 March 1849, which is evidence of a birth shortly
  before. [verified]

  The 1880 census schedule gives an age implying a birth year of 1851. [verified]

  These are incompatible and the corpus does not choose between them. [open] The register is
  the stronger witness — created within days, by a clerk with a duty to record — and the
  census age was reported by an unknown household member thirty-one years later. That is an
  argument for 1849 and it is not a resolution; a resolution requires a third record, and none
  has been found.
properties:
  claim_tag: open

The disagreement is a first-class object. It has a node, it carries both attestations, and yidam open-questions lists it. A gate can see it. Somebody reviewing the work three years later can see it, without reading a research log that may not exist.

And the tag says something precise: not "we are unsure" but "two records disagree and no third has been found." The action item is legible from the claim.

What the seed set gives you

samudaya/examples/genealogy/ holds seven files — the commitments above, written as bootstrap input rather than as prose:

KindWhat it seeds
axiomperson, record and event as irreducible kinds
hintrecords attest in one direction; a marriage is not an edge
constraintthe corpus stops at the living
augmentationa contradiction between records is [open], not an error to fix

Copy it into the repository being bootstrapped, not this one:

yidam clone ../my-genealogy
cp -R samudaya/examples/genealogy/*.md ../my-genealogy/samudaya/
cd ../my-genealogy && yidam samudaya-audit

Then run the bootstrap. A seed set seeds the discovery dialogue and does not replace it — these files state what the domain's practitioners commit to before any dialogue happens, and the bootstrap is still required to ask. Copy the ones that are true of your work and delete the rest: a seed you did not mean is worse than one you did not write, because the dialogue will argue for it and you will have to argue back.

What this sketch does not show

It has no corpus, so it has no run. Nothing on this page is command output, and the [open] birth-year node above has never been linted. The two worked walkthroughs — property research and investigative journalism — ship gated corpora and real transcripts; this one ships an argument and an executable seed set.

It does not model the relator. The marriage-as-relator question is argued above and resolved one way. A corpus that resolved it the other way would need a fourth class and a different account of what its instances rest on, and that account is not written here.

It does not handle identity. Are these two records about the same person is the central labour of genealogy, and the corpus above gives it a place to live — a person node is where the decision is recorded — without saying how the decision is made. That is method, and it belongs in a skill.

No real person appears, living or dead. Ellen Marbury is invented. The conventions are real: the column set of an 1880 census schedule, parish-register field shapes, and the citation form for a vital record. A real dead person has living descendants, and a corpus asserting contested things about them ships here to be copied.