@finbheara/names 0.11.0 → 0.13.0

package/dist/measure/index.js

@@ -4,8 +4,8 @@ import {
 } from "../chunks/index-pncn9y2r.js";
 import {
   createNameCensus2
-} from "../chunks/index-61wk7v9c.js";
-import"../chunks/index-jx97zxtz.js";
+} from "../chunks/index-ztpxgcs1.js";
+import"../chunks/index-yf904dam.js";
 import"../chunks/index-7vvt5hhy.js";
 export {
   composeEvalSet2 as composeEvalSet,

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-n4t288kj.js";
+} from "../chunks/index-wq6kn9jq.js";
 import"../chunks/index-kw6gbrnq.js";
 import {
   NAME_REFUSED2,
@@ -56,6 +61,7 @@ import {
   nameFold2,
   PLATFORM_PLACEHOLDERS2,
   NAME_PLACEHOLDERS2,
+  placeholderOf2,
   isPlaceholderPrint2,
   isNoNamePrint2,
   COMPOUND_SURNAMES2,
@@ -89,7 +95,7 @@ import {
   defaultPersonNameFactory2,
   personName2,
   personNameFromIcao2
-} from "../chunks/index-jx97zxtz.js";
+} from "../chunks/index-yf904dam.js";
 import {
   TEAM_WORD2,
   TEAM_DESIGNATION_WORDS2,
@@ -109,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,
@@ -134,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,
@@ -143,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,
@@ -166,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,
@@ -177,6 +188,7 @@ export {
   personList2 as personList,
   personName2 as personName,
   personNameFromIcao2 as personNameFromIcao,
+  placeholderOf2 as placeholderOf,
   printAttestsOrder2 as printAttestsOrder,
   probablySame2 as probablySame,
   readNameCell2 as readNameCell,
@@ -202,5 +214,5 @@ export {
   traditionLookupOf2 as traditionLookupOf
 };
 
-//# debugId=F6630C203D8EAD8B64756E2164756E21
+//# debugId=6CAF39AD5BAB8B2064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/normalize/index.js.map

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

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

@@ -11,7 +11,8 @@
  * 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
@@ -29,3 +30,15 @@
  * 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-family` where `sameGivenFamily` admits the pair, `given-family-not-gate`
+ * where the two share a root but either is 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`). It reads the
+ * `ROOT` and `NOT_AT_GATE` that `sameGivenFamily` reads, and `sameGivenFamily` is defined as
+ * its `given-family` answer, so the gate and the tolerant relation cannot disagree about a
+ * pair.
+ */
+export declare function givenFamilyTable(a: string, b: string): "given-family" | "given-family-not-gate" | null;

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

@@ -11,16 +11,17 @@ export { type Level, NAME_TRADITIONS, type NamePart, type NameTradition, type Na
 export { NAME_REFUSED, type ParentheticalHandler, type ScrubOptions, type ScrubResult, type ScrubRule, scrubName, scrubNameDetail, stripEveryAside, stripTrailingCredentials, } from "./name-scrub.ts";
 export { repairMojibake } from "./name-mojibake.ts";
 export { type CellVerdict, type NameRefusalRule, type Refusal, classifyCell, } from "./cell-verdict.ts";
-export { NAME_PLACEHOLDERS, type NamePlaceholder, PLATFORM_PLACEHOLDERS, isNoNamePrint, isPlaceholderPrint, } from "./name-placeholder.ts";
+export { NAME_PLACEHOLDERS, type NamePlaceholder, PLATFORM_PLACEHOLDERS, isNoNamePrint, isPlaceholderPrint, placeholderOf, } from "./name-placeholder.ts";
 export { capitalise, nameCase, type SpellingLookup } from "./name-case.ts";
 export { type DisplayLexicon, GIVEN_SEPARATOR, type PersonNameParts, SURNAME_SEPARATOR, formatPersonDisplay, lexiconKey, parsePersonName, personDisplayName, spellingLookup, titleCaseNamePart, } from "./person-display.ts";
 export { type CommaReading, type NameOrder, type NameSplit, type ResolvedNameOrder, commaReading, inferNameOrder, resolveNameOrder, spaceAfterComma, splitPersonName, } from "./name-split.ts";
 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,165 @@
+/**
+ * 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]
+ *     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 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/dist/types/normalize/name-placeholder.d.ts

@@ -8,8 +8,8 @@
  *      (`^[^\p{L}]*$`, any Unicode letter, so a name written in a non-Latin script is a
  *      name);
  *   2. it is a platform sentinel a row's name cell and school cell share (`N/A`, `TBA`,
- *      `Unknown`, `None`): `PLATFORM_PLACEHOLDERS`, asked through `isPlaceholderPrint`, ONE
- *      list for both cells so they cannot drift apart;
+ *      `Unknown`, `None`, `No School`, `Independent`): `PLATFORM_PLACEHOLDERS`, asked through
+ *      `isPlaceholderPrint`, ONE list for both cells so they cannot drift apart;
  *   3. it is one of `NAME_PLACEHOLDERS`: the sentinels only a NAME cell prints, each with
  *      where it was measured.
  *
@@ -26,15 +26,24 @@ export interface NamePlaceholder {
     readonly print: string;
     /** where it was seen, so a reviewer can audit the row */
     readonly authority: string;
+    /**
+     * `prefix`: the folded print STARTS with this row's words, for an entry form's instruction
+     * that runs on (`NO SCHOOL SELECTED - Please change your profile`). Whole words only.
+     * Absent: the folded print is exactly this row.
+     */
+    readonly match?: "prefix";
 }
 /**
- * THE SHARED SENTINELS: what an entry platform writes where nothing was entered, in a name cell
- * or a school cell alike. A school reader asks `isPlaceholderPrint` of its cell, so `N/A` is
- * refused on both sides of a row by this one list. A sentinel worded about a school
- * (`No School`, `-- Choose One --`) is a school-cell fact and stays with the school reader.
+ * THE SHARED SENTINELS: what an entry platform writes where nothing was entered or chosen, in a
+ * name cell or a school cell alike. A school reader asks `isPlaceholderPrint` of its cell, so
+ * `N/A`, `No School` and `Independent` are refused on both sides of a row by this one list. A
+ * sentinel worded about a school is still no name when a name cell prints it, so it is here
+ * too and not in a second list. Ordinary prints that merely CONTAIN one of these words are
+ * not placeholders: a row matches the whole folded print, or its leading words for `prefix`.
  *
- * Measured 2026-10-01 over every stream of the results corpus (3,776,915 rows): rows per
- * cell, matched on the fold.
+ * The first five were measured 2026-10-01 over every stream of the results corpus (3,776,915
+ * rows), the rest 2026-10-05 over the same corpus (3,586,702 rows): rows per cell, matched on
+ * the fold. A row with 0 rows is an entry form's option seen only as a form label.
  */
 export declare const PLATFORM_PLACEHOLDERS: readonly NamePlaceholder[];
 /**
@@ -43,9 +52,15 @@ export declare const PLATFORM_PLACEHOLDERS: readonly NamePlaceholder[];
  * every stream of the results corpus (3,776,915 rows).
  */
 export declare const NAME_PLACEHOLDERS: readonly NamePlaceholder[];
+/**
+ * The PLATFORM_PLACEHOLDERS row this print is, or `undefined`. For a reader that records
+ * which sentinel refused a cell; `isPlaceholderPrint` is the yes/no.
+ */
+export declare function placeholderOf(print: string): NamePlaceholder | undefined;
 /**
  * Is this print one of the PLATFORM PLACEHOLDERS a name cell and a school cell share
- * (`N/A`, `TBA`, `Unknown`, `None`)? The question a school reader asks of its cell.
+ * (`N/A`, `TBA`, `Unknown`, `None`, `No School`, `Independent`)? The question a school reader
+ * asks of its cell.
  */
 export declare function isPlaceholderPrint(print: string): boolean;
 /**

package/docs/NAME-NORMALIZATION.md

@@ -448,3 +448,68 @@ 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-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 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) === "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.
+
+Over the 261 forms of the current table (33,930 distinct pairs), `givenFamilyTable` answers
+`given-family` for 354 pairs, `given-family-not-gate` for 302, and `null` for the rest.
+`sameGivenFamily` answers as it did before the provider existed on every one of them.
+
+### 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.11.0",
+	"version": "0.13.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",