@finbheara/names 0.12.0 → 0.14.0

package/dist/normalize/index.js

@@ -1,13 +1,9 @@
 import {
   repairMojibake2,
   sameGivenFamily2,
+  givenFamilyTable2,
   comparePosition2,
   nameRelation2,
-  nameCompare2,
-  probablySame2,
-  createNameSet2,
-  createNameMap2,
-  createNameClusters2,
   MAX_READINGS2,
   surnameParts2,
   printAttestsOrder2,
@@ -24,6 +20,15 @@ import {
   blockKeysOfReadings2,
   nameBlockKeys2,
   namesFeasible2,
+  KINSHIP_VIAS2,
+  createNameKinship2,
+  nameKinship2,
+  nameCompare2,
+  probablySame2,
+  createNameSet2,
+  createNameMap2,
+  createNameIndex2,
+  createNameClusters2,
   INFEASIBLE_CLASSES2,
   editDistance2,
   nearSpelling2,
@@ -44,7 +49,7 @@ import {
   readNameCell2,
   DEFAULT_NAME_FORMAT_THRESHOLD2,
   deriveNameFormat2
-} from "../chunks/index-vqbvesky.js";
+} from "../chunks/index-kw69ry3j.js";
 import"../chunks/index-kw6gbrnq.js";
 import {
   NAME_REFUSED2,
@@ -90,7 +95,7 @@ import {
   defaultPersonNameFactory2,
   personName2,
   personNameFromIcao2
-} from "../chunks/index-yf904dam.js";
+} from "../chunks/index-ka8nzreg.js";
 import {
   TEAM_WORD2,
   TEAM_DESIGNATION_WORDS2,
@@ -110,6 +115,7 @@ export {
   DEFAULT_PERSON_NAME_CAPACITY2 as DEFAULT_PERSON_NAME_CAPACITY,
   GIVEN_SEPARATOR2 as GIVEN_SEPARATOR,
   INFEASIBLE_CLASSES2 as INFEASIBLE_CLASSES,
+  KINSHIP_VIAS2 as KINSHIP_VIAS,
   MAX_READINGS2 as MAX_READINGS,
   NAME_COLUMNS2 as NAME_COLUMNS,
   NAME_FORMATS2 as NAME_FORMATS,
@@ -135,6 +141,8 @@ export {
   compoundGiven2 as compoundGiven,
   createCachingPersonNameFactory2 as createCachingPersonNameFactory,
   createNameClusters2 as createNameClusters,
+  createNameIndex2 as createNameIndex,
+  createNameKinship2 as createNameKinship,
   createNameMap2 as createNameMap,
   createNameSet2 as createNameSet,
   createPersonNameFactory2 as createPersonNameFactory,
@@ -144,6 +152,7 @@ export {
   foldNameKey2 as foldNameKey,
   formatPersonDisplay2 as formatPersonDisplay,
   givenAbbreviates2 as givenAbbreviates,
+  givenFamilyTable2 as givenFamilyTable,
   givenKeyAbbreviates2 as givenKeyAbbreviates,
   infeasibleClass2 as infeasibleClass,
   inferNameOrder2 as inferNameOrder,
@@ -167,6 +176,7 @@ export {
   nameCompare2 as nameCompare,
   nameFold2 as nameFold,
   nameFormatOrder2 as nameFormatOrder,
+  nameKinship2 as nameKinship,
   nameMeet2 as nameMeet,
   nameReadings2 as nameReadings,
   nameRelation2 as nameRelation,
@@ -204,5 +214,5 @@ export {
   traditionLookupOf2 as traditionLookupOf
 };
 
-//# debugId=5FE4459EB5725BDA64756E2164756E21
+//# debugId=6CAF39AD5BAB8B2064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/normalize/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "5FE4459EB5725BDA64756E2164756E21",
+  "debugId": "6CAF39AD5BAB8B2064756E2164756E21",
   "names": []
 }

package/dist/types/normalize/given-diminutives.d.ts

@@ -11,21 +11,45 @@
  * A RELATION OF A PAIR AND NEVER A KEY. Nothing here rewrites a given name: a stored key,
  * a filing key and every rendering keep the print's own spelling. A caller asks whether
  * TWO given names are one family, at the moment it compares them, and nowhere else, so the
- * root never leaves this module: `sameGivenFamily` is the one export, for that reason.
+ * root never leaves this module: `sameGivenFamily` and `givenFamilyTable` answer about a
+ * pair and neither returns a root, for that reason.
  *
- * THE GATE READS LESS THAN THE LANE. `families` is the Python lane's table, first root
- * wins, and the lane reads every form in it as evidence below an exact match. A GATE that
- * admits a pair is a stronger claim than a comparison level, so `sameGivenFamily` refuses
- * any pair through a form in `notAtGate`: a name in its own right (`Megan`, `Grace`), a
- * translation (`Sean`, `Padraig`) or another gender's name (`Michelle`, `Patricia`).
- * `Tom` and `Thomas`, `Jenny` and `Jennifer`, `Annie` and `Ann` meet; `Sean` and `John` do
- * not.
+ * SPELLINGS, FAMILIES AND THE GATE. Two different given names are related in one of three
+ * ways, and the answer says which:
+ *
+ *   - `given-variant`: two spellings of one name (`Connor` / `Conor`, `Sara` / `Sarah`). A
+ *     spelling is not a familiar form, so `variants` is its own table, and a gate admits it.
+ *   - `given-family`: after each spelling is read as its canonical, the two share a ROOT of
+ *     `families` (`Tom` / `Thomas`, `Kate` / `Katherine`), and a gate admits it.
+ *   - `given-family-not-gate`: they share a root, but only through a `notAtGate` form: a name in
+ *     its own right (`Megan`, `Grace`), a translation (`Sean`, `Padraig`), another gender's
+ *     name (`Michelle`, `Sam`) or a form of more than one root (`Ellie`, `Evie`). The lane
+ *     reads it as evidence below an exact match; a gate refuses it.
+ *
+ * EVERY ROOT, NEVER THE FIRST. A form under several roots meets each of them (`Evie` is
+ * Evelyn's, Genevieve's, Eve's and Eva's), and every such form is `notAtGate`, because the
+ * form alone cannot say which root its bearer carries. Sharing a root is not transitive:
+ * `Eve` and `Eva` share none, though `Evie` meets both. A `notAtGate` form is refused AS A
+ * FORM: where it is the root itself (`Caitlin` / `Cait`), its own forms meet it at a gate.
  */
 /**
  * Do two DIFFERENT given names (NN3, letters only) stand for one another at a gate?
  *
- * True exactly when both are in the table, share a root, and neither is a `notAtGate`
- * form. Two equal names answer `false`: equality is the caller's own test and this is the
- * tolerance past it, so a caller can tell which one admitted a pair.
+ * True exactly when `givenFamilyTable` relates them by a gate-safe answer: two spellings of
+ * one name, or one family through no `notAtGate` form. Two equal names answer `false`:
+ * equality is the caller's own test and this is the tolerance past it, so a caller can tell
+ * which one admitted a pair.
  */
 export declare function sameGivenFamily(a: string, b: string): boolean;
+/**
+ * What the table says about two DIFFERENT given names (NN3, letters only), as a kinship
+ * `via`: `given-variant` for two spellings of one name, `given-family` where the two share a
+ * root and a gate admits the pair, `given-family-not-gate` where every root they share is
+ * reached through a `notAtGate` form, and `null` where the table does not relate them. Two
+ * equal names answer `null`, for `sameGivenFamily`'s reason.
+ *
+ * THE DEFAULT GIVEN-NAME PROVIDER of `createNameKinship` (`./name-kinship.ts`).
+ * `sameGivenFamily` is defined as its gate-safe answers, so the gate and the tolerant relation
+ * cannot disagree about a pair.
+ */
+export declare function givenFamilyTable(a: string, b: string): "given-variant" | "given-family" | "given-family-not-gate" | null;

package/dist/types/normalize/index.d.ts

@@ -18,9 +18,10 @@ export { type CommaReading, type NameOrder, type NameSplit, type ResolvedNameOrd
 export { TEAM_DESIGNATION_WORDS, TEAM_WORD, type TeamSuffixPartition, canonicalTeamName, isCanonicalTeamName, isTeamPrint, partitionTeamSuffix, teamLetter, teamRowDesignation, } from "./team-name.ts";
 export { foldNameKey, nameFold } from "./name-fold.ts";
 export { COMPOUND_SURNAMES, isCompoundSurname } from "./compound-surnames.ts";
-export { sameGivenFamily } from "./given-diminutives.ts";
-export { type ClusterLinkage, type Clusters, type NameMap, type NameSet, createNameClusters, createNameMap, createNameSet, nameCompare, probablySame, } from "./name-compare.ts";
+export { givenFamilyTable, sameGivenFamily } from "./given-diminutives.ts";
+export { type ClusterLinkage, type Clusters, type NameIndex, type NameIndexOptions, type NameMap, type NameMatch, type NameSet, createNameClusters, createNameIndex, createNameMap, createNameSet, nameCompare, probablySame, } from "./name-compare.ts";
 export { type NameReading, type NameRelation, type NameRelationReason, comparePosition, nameRelation, } from "./name-middle.ts";
+export { type GivenProvider, type GivenVia, KINSHIP_VIAS, type KinshipReason, type KinshipVia, type MiddleVia, type MiddleViasAreNn5Reasons, type NameKinship, type NameKinshipOptions, type NameKinshipRelation, createNameKinship, nameKinship, } from "./name-kinship.ts";
 export * from "./name-compose.ts";
 export { INFEASIBLE_CLASSES, type InfeasibleClass, compoundGiven, editDistance, infeasibleClass, middleForm, nearSpelling, } from "./name-infeasible.ts";
 export { type ListedPerson, isListJoiner, personList } from "./person-list.ts";

package/dist/types/normalize/multiset.d.ts

@@ -0,0 +1,9 @@
+/**
+ * multiset.ts — the one sub-multiset test over surname parts.
+ *
+ * MOVED HERE FROM `./name-compose.ts` so that `./name-kinship.ts` reads the same test the
+ * meet of two surnames reads, without either file importing the other and without the test
+ * joining the package's surface (`index.ts` re-exports `name-compose.ts` whole).
+ */
+/** Is `outer` a sub-multiset of `inner`? `[Walter] ⊒ [Walter, Oreskarard]`. */
+export declare function subMultiset(outer: readonly string[], inner: readonly string[]): boolean;

package/dist/types/normalize/name-compare.d.ts

@@ -26,6 +26,7 @@
  * argument at the call site IS the justification, inline and readable, which is
  * why no catalog of imports is owed.
  */
+import { type NameKinship, type NameKinshipRelation } from "./name-kinship.ts";
 import { type Level, type PersonName, type TransitiveLevel } from "./person-name.ts";
 /**
  * Order two parsed names at one level.
@@ -124,6 +125,48 @@ export declare function createNameSet(dop: TransitiveLevel): NameSet;
  * `createNameMap("nn5")` DOES NOT COMPILE — see `createNameSet`.
  */
 export declare function createNameMap<V>(dop: TransitiveLevel, entries?: Iterable<readonly [PersonName, V]>): NameMap<V>;
+/** One held entry a tolerant lookup found, with what the relation said about it. */
+export interface NameMatch<V> {
+    /** the print the entry is held under — the first print filed into its slot */
+    readonly name: PersonName;
+    readonly value: V;
+    readonly kinship: NameKinship;
+}
+/** A `NameMap` that can also answer which held names are RELATED to a print. */
+export interface NameIndex<V> extends NameMap<V> {
+    /**
+     * Every held entry the index's relation does not call `different`, `same` before
+     * `candidate` and otherwise in insertion order. `[]` for a print that names no person.
+     */
+    related(name: PersonName): readonly NameMatch<V>[];
+}
+export interface NameIndexOptions<V> {
+    /** The tolerant relation `related` filters by. Default `nameKinship`. */
+    readonly kinship?: NameKinshipRelation;
+    readonly entries?: Iterable<readonly [PersonName, V]>;
+}
+/**
+ * A map keyed on parsed names at one declared level, with a TOLERANT LOOKUP beside it.
+ *
+ * `get`, `has`, `set` and `delete` ARE `createNameMap`'s, unchanged and delegated to: the
+ * exact answer at a transitive level is still the slot. `related(name)` is the other
+ * question — which held names MAY be this person — and it is answered by a relation, not by
+ * a slot: candidates come from a secondary index on the surname key and every surname part
+ * (so `Mary Larson` finds `Mary Conley-Larson` and the other way round), and each candidate
+ * is kept when the relation does not call it `different`.
+ *
+ * A SIBLING OF `NameMap` AND NOT A METHOD ON IT, for three reasons. The tolerant answer is
+ * NOT TRANSITIVE, and `NameMap`'s contract is an equivalence class; putting a non-transitive
+ * lookup on it would blur exactly the boundary the type split above draws. The lookup needs
+ * a RELATION, and a relation is chosen by options (its given-name providers), which a map
+ * keyed by `dop` alone has no place to hold. And the secondary index costs memory on every
+ * `set`, which a caller that only wants the exact map should not pay. A `NameIndex` IS a
+ * `NameMap`, so a caller that needs both holds one structure.
+ *
+ * A print that names no person is held, counted and iterated as `createNameMap` holds it,
+ * and is never related to anything, in either direction: `probablySame`'s rule.
+ */
+export declare function createNameIndex<V>(dop: TransitiveLevel, options?: NameIndexOptions<V>): NameIndex<V>;
 /** How a clustering decides whether a name joins an existing cluster. */
 export type ClusterLinkage = "single" | "complete" | "average";
 /** A clustering over parsed names. Order-dependent by construction at NN5. */

package/dist/types/normalize/name-kinship.d.ts

@@ -0,0 +1,171 @@
+/**
+ * name-kinship.ts — THE TYPED, TOLERANT NAME RELATION.
+ *
+ * `docs/NAME-NORMALIZATION.md` § *Name kinship — the tolerant relation* is the specification.
+ *
+ * ## WHAT IT ADDS TO NN5
+ *
+ * `nameRelation` (`./name-middle.ts`) is the strict identity relation: the surname and the
+ * first given name must agree at NN3, and only a middle name is tolerated. A different head
+ * is rightly `different` there. The other tolerances already exist, one helper each —
+ * `givenFamilyTable` / `sameGivenFamily` for a given name, `surnameParts` for a compound
+ * surname — and a caller that wanted them had to compose them by hand. This is that
+ * composition, done once, and it REPORTS WHICH TOLERANCES A PAIR PASSED THROUGH so that each
+ * caller decides how much to accept:
+ *
+ *     Kate Smith    / Katherine Smith      candidate  via [given-family]
+ *     Connor Smith  / Conor Smith          candidate  via [given-variant]
+ *     Mary Larson   / Mary Conley-Larson   candidate  via [surname-part]
+ *     Kate M Smith  / Katherine Conley-Smith
+ *                                           candidate  via [surname-part, given-family, middle-absent]
+ *
+ * ## `via` IS A SET, NOT A KIND
+ *
+ * A pair can pass through several tolerances at once, one per field, and naming the
+ * combinations (`both`) grows as the product of the fields. So `via` lists every tolerance
+ * used, in the fixed order of `KINSHIP_VIAS`, and is empty for a pair NN3 already agreed on.
+ *
+ * ## `candidate` IS STILL NOT A MERGE
+ *
+ * The three values are `NameRelation`'s and mean what they mean there. Every tolerance here
+ * is "may be the same person, the rest of the evidence decides". `gateSafe` says something
+ * narrower: every tolerance used is one this package's own gate comparators already admit —
+ * a middle name `probablySame(…, "nn5")` admits, a given-name family `sameGivenFamily`
+ * admits, a compound the print itself carries. A table form that is a name in its own right
+ * (`given-family-not-gate`) or a probabilistic source (`given-maybe`) is a lead for the rest
+ * of the evidence and never a gate.
+ *
+ * ## THE GIVEN-NAME TOLERANCE IS INJECTED
+ *
+ * Which given names are one family is DATA, and the data will move: a probabilistic source
+ * of diminutive pairs is expected beside the curated table, and the table may shrink. So the
+ * relation asks an ordered list of `GivenProvider`s fixed by `createNameKinship`'s options,
+ * and the core knows no table. A new provider is an option; a new kind of answer is one
+ * line in `KINSHIP_VIAS`, which also carries its gate-safety, so no branch here changes.
+ *
+ * ## IT COMPOSES, IT DOES NOT FORK
+ *
+ * The middle-name and suffix rows are `tailRelation`, the half of `nameRelation` below the
+ * head, so `J` against `Jane` is decided in one place. With no tolerance used this answers
+ * exactly what `nameRelation` answers (`normalize-name-kinship.spec.ts` pins it), except that
+ * it splits `head-differs` into the half that differed.
+ */
+import { type NameRelation, type NameRelationReason } from "./name-middle.ts";
+import type { PersonName } from "./person-name.ts";
+/**
+ * EVERY TOLERANCE THE RELATION CAN REPORT, IN THE ORDER IT REPORTS THEM, with the field it
+ * tolerates and whether a gate may admit a pair through it. The one declaration: the
+ * `KinshipVia`, `GivenVia` and `MiddleVia` types are read off it, so adding a kind is a
+ * line here and nothing else in the core.
+ */
+export declare const KINSHIP_VIAS: Readonly<{
+    /** one surname is a whole hyphen- or space-joined part of the other's compound */
+    readonly "surname-part": Readonly<{
+        field: "surname";
+        gateSafe: true;
+    }>;
+    /** the two first given names are two spellings of one name (`Connor` / `Conor`) */
+    readonly "given-variant": Readonly<{
+        field: "given";
+        gateSafe: true;
+    }>;
+    /** the given-name table relates the two first given names, and the gate admits them */
+    readonly "given-family": Readonly<{
+        field: "given";
+        gateSafe: true;
+    }>;
+    /** the table relates them through a form that is a name in its own right */
+    readonly "given-family-not-gate": Readonly<{
+        field: "given";
+        gateSafe: false;
+    }>;
+    /** a probabilistic source says the two MAY be one family; reserved for one */
+    readonly "given-maybe": Readonly<{
+        field: "given";
+        gateSafe: false;
+    }>;
+    /** NN5's own: one side carries no middle name */
+    readonly "middle-absent": Readonly<{
+        field: "middle";
+        gateSafe: true;
+    }>;
+    /** NN5's own: an initial against a full middle whose first letter matches */
+    readonly "initial-agrees": Readonly<{
+        field: "middle";
+        gateSafe: true;
+    }>;
+}>;
+/** A tolerance a pair passed through. */
+export type KinshipVia = keyof typeof KINSHIP_VIAS;
+type ViaOfField<F extends string> = {
+    [K in KinshipVia]: (typeof KINSHIP_VIAS)[K]["field"] extends F ? K : never;
+}[KinshipVia];
+/** The tolerances a `GivenProvider` may answer with. */
+export type GivenVia = ViaOfField<"given">;
+/** The middle-name tolerances: NN5's two `candidate` reasons, by the same names. */
+export type MiddleVia = ViaOfField<"middle">;
+/**
+ * Why the relation came out the way it did. NN5's reasons, except that `head-differs` is
+ * split into the half that differed, because this relation tolerates each half on its own.
+ */
+export type KinshipReason = Exclude<NameRelationReason, "head-differs">
+/** the surnames are neither equal at NN3 nor one a whole part of the other */
+ | "surname-differs"
+/** the first given names are neither equal at NN3 nor related by any provider (or one is missing) */
+ | "given-differs";
+/** The tolerant relation's answer. */
+export interface NameKinship {
+    /** `NameRelation`'s three values, meaning what they mean there: `candidate` is never a merge */
+    readonly relation: NameRelation;
+    /** every tolerance used, in `KINSHIP_VIAS` order; empty for `same` and for `different` */
+    readonly via: readonly KinshipVia[];
+    /** the veto for `different`; NN5's middle-name reason otherwise */
+    readonly reason: KinshipReason;
+    /** true only when the pair is related and every `via` is gate-safe */
+    readonly gateSafe: boolean;
+}
+/**
+ * Might two DIFFERENT first given names (NN3 fields, so upper case and letters) be one
+ * family, and by which tolerance? `null` is "this provider does not relate them".
+ *
+ * IT IS ASKED WITH `a < b` in code-unit order, once per pair, so a provider holding ordered
+ * pairs needs to hold each pair one way only and the relation stays symmetric whatever the
+ * provider does.
+ */
+export type GivenProvider = (a: string, b: string) => GivenVia | null;
+export interface NameKinshipOptions {
+    /**
+     * The given-name tolerances, asked in order; THE FIRST NON-NULL ANSWER WINS, so a caller
+     * lists its most trusted source first. Default `[givenFamilyTable]`; `[]` tolerates no
+     * given name.
+     */
+    readonly given?: readonly GivenProvider[];
+}
+/** A tolerant relation with its providers fixed. */
+export type NameKinshipRelation = (a: PersonName, b: PersonName) => NameKinship;
+/**
+ * Make the tolerant relation over a fixed list of given-name providers.
+ *
+ * The rule table, in the order it is applied:
+ *
+ * | the two sides | relation |
+ * |---|---|
+ * | either names no person | `different`, `not-a-person` |
+ * | surnames differ at NN3 and neither is a whole part of the other | `different`, `surname-differs` |
+ * | first given names differ at NN3 (or one is missing) and no provider relates them | `different`, `given-differs` |
+ * | NN5's suffix and middle rows (`tailRelation`) say `different` | `different`, NN5's reason |
+ * | no tolerance used and the middles are equal | `same` |
+ * | otherwise | `candidate`, via every tolerance used |
+ */
+export declare function createNameKinship(options?: NameKinshipOptions): NameKinshipRelation;
+/** The tolerant relation over the curated given-name table, `givenFamilyTable`. */
+export declare const nameKinship: NameKinshipRelation;
+/**
+ * THE MIDDLE VIAS ARE NN5'S CANDIDATE REASONS, ASSERTED IN TYPECHECKED SOURCE. A middle
+ * `via` is `tailRelation`'s reason passed through, so the day either list moves without the
+ * other, `bun run typecheck` goes red here. Exported for `Nn5IsNotAMemberOfAParse`'s reason.
+ */
+type AssertTrue<T extends true> = T;
+/** Every middle `via` is a reason NN5 can give. */
+export type MiddleViasAreNn5Reasons = AssertTrue<MiddleVia extends NameRelationReason ? true : false>;
+export {};

package/dist/types/normalize/name-middle.d.ts

@@ -156,6 +156,17 @@ export declare function comparePosition(x: string, y: string): NameRelationReaso
  * not this issue's to close.
  */
 export declare function nameRelation(a: PersonName, b: PersonName): NameReading;
+/**
+ * NN5's rule table BELOW THE HEAD: the suffix row and every middle-name row, for two
+ * persons whose surname and first given name the CALLER has already accepted.
+ *
+ * MOVED OUT OF `nameRelation`, NOT FORKED. `nameRelation` checks the head by equality and
+ * hands the rest here; `./name-kinship.ts` accepts the head through its own tolerances
+ * (a given-name family, a surname part) and hands the rest here too, so the two relations
+ * read one middle-name rule and cannot disagree about `J` and `Jane`. It is not on the
+ * package's surface: a caller that has not decided the head has no business asking it.
+ */
+export declare function tailRelation(a: PersonName, b: PersonName): NameReading;
 /**
  * THE OWNER'S RULE, ASSERTED IN TYPECHECKED SOURCE.
  *

package/docs/NAME-NORMALIZATION.md

@@ -448,3 +448,93 @@ tolerating accent, punctuation and order.
   classifier: its declared-order weights were fitted only on documents that declared that
   order, and a guess is not a declaration. With no order, or `unknown`, the classifier
   answers exactly as it does without the argument.
+
+## Name kinship — the tolerant relation
+
+`nameRelation` is the strict identity relation: the surname and the first given name MUST
+agree at NN3, and only a middle name is tolerated. `nameKinship(a, b)` is the tolerant
+relation built on it. It reports **which tolerances a pair passed through**, so each caller
+decides how much to accept.
+
+```ts
+interface NameKinship {
+  relation: "same" | "candidate" | "different";  // NameRelation's values and meanings
+  via: readonly KinshipVia[];                     // every tolerance used, KINSHIP_VIAS order
+  reason: KinshipReason;                          // the veto, or NN5's middle-name reason
+  gateSafe: boolean;                              // related, and every via is gate-safe
+}
+```
+
+| via | field | gate-safe | when |
+|---|---|---|---|
+| `surname-part` | surname | yes | one surname is a whole hyphen- or space-joined part of the other's compound |
+| `given-variant` | given | yes | the two first given names are two spellings of one name (`Connor` / `Conor`) |
+| `given-family` | given | yes | a provider says the two first given names are one family, and a gate admits them |
+| `given-family-not-gate` | given | no | the table relates them only through a `notAtGate` form |
+| `given-maybe` | given | no | a probabilistic source says they MAY be one family |
+| `middle-absent` | middle | yes | NN5's: one side carries no middle |
+| `initial-agrees` | middle | yes | NN5's: an initial against a full middle that starts with it |
+
+- `candidate` is NEVER a merge, as in NN5. Every tolerance means "may be the same person;
+  the rest of the evidence decides".
+- `via` is a SET, one entry per tolerance used, in the table's order. It is empty for
+  `same` and for `different`. `Kate M Smith` / `Katherine Conley-Smith` is a candidate via
+  `surname-part`, `given-family` and `middle-absent`.
+- A surname part is compared WHOLE: `Larson` is a part of `Conley-Larson` and of `Conley
+  Larson, Mary`, and not of `Carlson` or `Conley-Fitzlarson`. Two compounds with the same
+  number of parts are two surnames (`Smith-Jones` / `Jones-Smith` is `different`).
+- The given-name tolerance is INJECTED: `createNameKinship({ given: [p1, p2, …] })` asks
+  each `GivenProvider` in order and the first non-null answer wins. A provider is asked
+  once per pair, with the two NN3 first given names in code-unit order, and never with two
+  equal names. The default is `[givenFamilyTable]`, which answers from
+  `given-diminutives.json`; `sameGivenFamily(a, b)` is exactly "`givenFamilyTable(a, b)` is
+  `given-variant` or `given-family`". `[]` tolerates no given name.
+- A new kind of `via` is one entry in `KINSHIP_VIAS`, which carries its field and its
+  gate-safety. The relation's rules do not change.
+- With no tolerance used, the answer is `nameRelation`'s. `head-differs` is split into
+  `surname-differs` and `given-differs`, because each half is tolerated on its own. The
+  suffix and middle rows are NN5's (`tailRelation`) and still veto.
+- A print that names no person is `different` from everything, itself included.
+
+### The given-name table
+
+`given-diminutives.json` holds three things, each in NN3 upper case:
+
+- `variants`: one name's SPELLINGS, canonical first (`CONNOR` / `CONOR`, `SARAH` / `SARA`,
+  `MEGAN` / `MEGHAN` / `MEAGAN` / `MEAGHAN`). Two spellings are `given-variant`, and a gate
+  admits them. A spelling is read as its canonical before `families` is consulted, so
+  `Cate` meets `Katherine` as `Kate` does. A transposition or a typo (`Oliva`, `Cailtin`,
+  `Naimh`) is NOT a variant: a misprint tolerance is a separate provider.
+- `families`: root -> its familiar forms. Two names are one family when they SHARE A ROOT,
+  a root belonging to itself. A form may sit under several roots and meets EVERY one of
+  them: `Evie` is Evelyn's, Genevieve's, Eve's, Eva's and Evangeline's. Sharing a root is
+  not transitive, so `Eve` and `Eva` stay apart though `Evie` meets both.
+- `notAtGate`: forms a gate refuses — a name in its own right (`Josie`, `Gracie`, `Lily`),
+  a translation (`Sean`), another gender's name (`Sam`, `Charlie`, `Frankie`), and every
+  form under more than one root (`Ellie`, `Maddie`, `Ally`, `Kit`), because the form alone
+  cannot say which root its bearer carries. A pair through such a form is
+  `given-family-not-gate`. The flag refuses a name AS A FORM: where it is the root itself,
+  its own forms still meet it at a gate (`Caitlin` is Catherine's Irish form, refused
+  against `Katherine`, and still meets `Cait`).
+
+`Kate` and `Katie` are Catherine's, and `Katelyn` is a spelling of Caitlin. They meet below
+the gate through Caitlin as a form of Catherine, so `Kate` / `Katherine` keeps its gate.
+
+Over the 421 forms and spellings of the table (88,410 distinct pairs), `givenFamilyTable`
+answers `given-variant` for 90 pairs, `given-family` for 371, `given-family-not-gate` for 553,
+and `null` for the rest; `sameGivenFamily` admits 461.
+
+### The tolerant lookup
+
+`createNameIndex(dop, { kinship?, entries? })` is a `NameMap` whose `get`, `has`, `set` and
+`delete` are `createNameMap`'s, unchanged. It adds `related(name)`: every held entry the
+relation does not call `different`, each with its `NameKinship`, `same` before `candidate`
+and otherwise in insertion order. Candidates come from a secondary index on each entry's
+NN3 surname key and each of its surname parts, so `Mary Larson` finds `Mary Conley-Larson`
+and the other way round. The index does not key on the first initial, because a given-name
+family need not keep one (`Peggy` / `Margaret`).
+
+It is a sibling of `NameMap` and not a method on it. The tolerant answer is not
+transitive, and a `NameMap` is an equivalence class. The lookup needs a relation chosen by
+options. And the secondary index costs memory that a caller wanting only the exact map
+should not pay.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/names",
-	"version": "0.12.0",
+	"version": "0.14.0",
 	"description": "A curated lexicon of personal, school and place names, the surname-particle vocabulary, a phrase classifier and a person-name normalizer",
 	"keywords": [
 		"names",