# Recipe for merging name forms into one individual

## When to use it

Use it after `recipe-resolve-names`, when "Elena", "Elena Marsh" and "Dr. Elena Marsh"
stand as three identities. **This recipe is dangerous.** A surplus identity costs nothing;
a wrong merge mixes the facts of two people, and `unmerge` brings the source back without
telling you which of the target's facts were its own. Merge only what the passages show.
If you checked two and they differ, say so with `assert_separate`. If you are unsure,
`raise_conjecture` and leave both standing.

Use this recipe on documents that arrive with structure (Markdown, or HTML from a web capture). For
documents that arrive as raw text or from PDF and still need outlining, wait for guided
outlining, which is planned and not yet available: an outline creates a new version of the
document, and work done on the old version will be offered again.

## What you need first

Identities that carry mentions. Without mentions the dossier has no passages, and there
is nothing to judge by.

## Fetch the context

```
overview {}
list_collection {"name": "<instance_collection of Person>", "limit": 200}
describe_family {"ids": ["<identity ID>", "<identity ID>"], "passage_limit": 20, "quotes_per_id": 3}
```

In `overview`, the entries of `aspects` named `Person`, `Ort` (place) and `Organisation`
each give an `instance_collection`; list all three. Form candidate families from the
labels yourself, across the three, by spelling only: one name contained in the other once salutations and titles are dropped; a
shared last name of four letters or more; or one letter apart where one form is rare and
the other frequent (a typo). A family has 2 to 20 members. `describe_family` returns per
member the titles, the aspect, `is_anchor` (with `curated_name` for an anchor), the
mention count, the spread over documents and sample quotes; then the passages where
members stand together, and `separations`: pairs already judged different. A passage is
one paragraph. Where `passages` is empty, no two members share a paragraph, and the first
rule of the prompt applies in full: expect to escalate more than you merge.

Build the input per family; several families may go into one judgment:

```
FAMILY 1:
- «Elena Marsh» 5x ANCHOR curated='Elena Marsh' docs: Minutes (3x), Inspection report (1x)
    "<sample quote, cut at 300 characters>"
- «Marsh» 1x docs: Inspection report (1x)
    "<sample quote>"
  passages (several members close together):
    "<passage>"
```

`ANCHOR curated=` appears only for an anchor; a member that stands in a passage may have
no quote of its own. Two members with the same wording become «Tina#1» and «Tina#2».

## Judge

```
You consolidate name forms from the documents of this memory. Each numbered FAMILY lists candidate forms that string similarity grouped together, with mention counts, document spread and text passages where several forms stand close.
Decide per family which forms denote the SAME individual, and answer JSON only.
Rules, in order of weight:
- Name equality or similarity alone is NEVER enough to join two forms - in one corpus 'Tina' was once a human and once a dog. Join only when the passages or the distribution make identity plausible.
- Read the passages: an anaphora ('Carola Weber ... later only Carola' in one paragraph) joins; an enumeration ('Carola, Robin and Hella came') separates - names listed side by side are DIFFERENT people.
- When in doubt, keep forms separate or escalate. A wrong join has no clean undo; a missed join costs one later merge.
- Forms marked ANCHOR carry a curated name: an anchor is the preferred surviving identity. Never join two anchors - escalate the family instead.
- A scattered, incompatible document spread on ONE form (a generic word like 'church', 'Lions Club' appearing in unrelated places) signals a lump carrying several referents: escalate it, never deepen it by joining.
- role 'title': a name the corpus uses for the individual (full names, short forms, pet forms: 'Caro', 'Andi'). role 'surface': not a name but a wording - grammatical inflections ('Carola's', German 'Carolas') and obvious typos ('Oberndor' next to 'Oberndorf'). Surfaces never become identities or titles.
- 'Mrs X' and 'Mr X' with a surname X (German 'Frau X' and 'Herr X') name TWO different individuals - a married couple - unless a passage explicitly equates them. Never join them. The bare surname X is ambiguous between the two: attach it only where the passages clearly show one referent; where both exist, leave the bare form separate or escalate it.
- Never mix kinds inside one individual: a person never joins a place or an organization ('Dr. Neuhaus' the physician is not 'Neuhaus' the town).
- curated_name is REQUIRED on every individual: the fullest civil name the corpus supports, normally the longest title without salutation ('Carola Weber', not 'Mrs Carola Weber'; never an inflected surface).
- kind: person, place or organization - judge from the passages. A country, region or city is always place. A family named as a group is an organization only if it is an institution; otherwise leave it out (noise).
- When two members carry the same wording they are distinct identities and appear numbered ('Tina#1', 'Tina#2') - always answer with the numbered token, and join them only on explicit passage evidence (they usually are namesakes on purpose).
Answer with a JSON array, one entry per family, no commentary:
[{"f":1,"individuals":[{"kind":"person","curated_name":"Carola Weber","members":[{"form":"Carola","role":"title"},{"form":"Carola Weber","role":"title"}]}],"noise":["golf course"],"escalate":["Lions Club"]}]
Every form of the family must appear exactly once: in an individual's members, in noise, in escalate - or nowhere, which means 'keep it separate as it is'. Only individuals with two or more members cause any change.
```

## The answer form

The array at the end of the prompt: per family `f`, its `individuals` with `kind`,
`curated_name` and `members` (each a `form` and a `role`), and the lists `noise` and
`escalate`.

## Check your own verdict

A family without an entry is no permission: leave it as it is. For each individual with
two or more members, in this order:

1. **Judged different before.** Two of its members form a pair in `separations`: no merge.
2. **Couple.** A "Mrs X" and a "Mr X" form in one individual: no merge. Use the
   salutations of your corpus.
3. **Title.** An academic title before a bare surname ("Dr. Brahms") next to the bare
   surname ("Brahms"): take the titled form out and escalate it. A full name with a title
   is fine.
4. **Competing extensions.** Two forms, neither contained in the other, that share a name
   word ("Renate A." and "Renate X"): no merge. Such additions keep two people apart.
5. **Kinds.** Members under different aspects: no merge. The house does not refuse this.
6. **Two anchors.** Never merged.

Whatever a check stops, and whatever stands in `escalate` or `noise`, goes to the owner:
`raise_conjecture` on the identity, with the note "Name forms, judged by
recipe-merge-name-forms:" followed by the labels of the family, then `resolve_conjecture`
with `needs_user_resolution` set. Noise that is already an identity is not deleted.

## Apply

The target is the anchor; without one, the member with the most mentions; on a tie, the
fullest name.

```
merge_into {"source_id": "<member ID>", "target_id": "<target ID>"}
get_links {"id": "<target ID>", "direction": "out", "meaning": "Title", "limit": 50}
retract {"link_id": "<Title link of a surface wording>"}
set_property {"thing_id": "<target ID>", "path": ["CurrentName"], "value": "Elena Marsh",
              "versioned": true, "context_id": "<concept.id of the aspect>"}
```

One `merge_into` per member other than the target. Then retract, at the target, the Title
of each member whose role was surface, but never its last title. Set the curated name
only if the target is no anchor yet and every word of the name stands in one of the
family's forms; a name from your own knowledge of the world is not evidence. For a place
the slot is `LocalName`.

Two calls are not part of every run:

```
assert_separate {"first_id": "<identity ID>", "second_id": "<identity ID>"}
unmerge {"source_id": "<the identity that gave way>"}
```

`assert_separate` records a pair that the passages show to be two individuals;
`merge_into` refuses that pair from then on. The verdict has no field for it: it is your
own reading, so use it sparingly. `unmerge` undoes a merge: read the `counterparts` it
reports.

## Say who judged

One note at the target, as `working-by-recipe` shows: the recipe, what you merged into
it, and the passage that decided.

## What this recipe does not do

- The house runs none of the six checks. It refuses a pair recorded as separate and a
  source that is already merged, and little else.
- It writes no stamp, so the same family can be judged twice.
- It does not build families for you and does not split a lump: one identity that
  carries two people needs a judgment per mention, with `reassign_mentions`
  (`get_links` with direction in lists the mentions of an identity).

## Origin

Atlantis, `Intelligence/World/Sweep/FamilyJudge.cs` (prompt, input) and
`Consolidator.Run.cs` (checks, apply), commit cd454e5, read at `main` 966157b.
**Adapted:** the prompt named a German family archive and used German examples; the rules
and their order are unchanged.

## Go deeper

- [recipe-resolve-names](recipe-resolve-names.md)
- [working-by-recipe](working-by-recipe.md)
- [evidence-and-provenance](evidence-and-provenance.md)
- [finding-things](finding-things.md)