Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/nameparser/_pipeline/_group.py: 9%

1"""Stage: group. 

2 

3Consumes: tokens (classified), segments, structure, one_case, extracted 

4(the role + inner span per delimited region, for the #329 pass below; 

5post_rules reads it too, for S13); and, through 

6`_comma.decide`, comma_offsets (the own-words span of the name's case 

7contrast) and dropped, which decide extends. 

8Produces: structure -- its head decides a comma form once the words 

9are tagged (rules/C1, #613, `_comma.decide`), binding the SUFFIX and 

10TITLE roles of a postnominal part after the comma, emptying its 

11segment and dropping its delimiter cores before any join, plus the SUFFIX_OR_NAME 

12ambiguities that decision reports, those the particle chain and a 

13maiden clause report on a trailing member they take into the name 

14(an ambiguous acronym, or since #718 a declined numeral), and the 

15caps shape's acronym tags on 

16a bound all-caps word (#564); pieces + piece_tags per segment 

17(runs of token indices -- tokens are NEVER joined into strings: the 

18anti-#100 invariant); maiden tail tokens get role=MAIDEN, and the 

19trailing run a maiden take gives up gets its SUFFIX and TITLE roles 

20here (#601), so no join can reach it; marker tokens land in dropped; 

21and tail_reads, rules/S2's trailing run of each main segment read 

22ONCE, after P3's connective joins and before the particle chain and 

23the bound-given join, and split off so neither reaches it (#614), 

24which assign places and reports rather than peeling again; and, 

25last in each part, P12's join of a listed pair past the start, the 

26classify tag left only on the bound word of a pair it joined (#694). 

27Reads: token tags (from classify), Lexicon.given_name_titles (the 

28P5 licence, #369), Policy.name_order (rules/P13's joins at the end 

29of a name read given-first, #1098) and Policy.extra_suffix_delimiters, whose 

30delimiter-core tokens part a tail segment as a comma would and are 

31dropped (v1 suffix_delimiter parity, #549), as the built-in cores' 

32are (rules/C10, #889); and, through 

33`_comma.decide`, what that module's own header lists 

34(Policy.lenient_comma_suffixes and Policy.unlisted_caps_suffixes among 

35them). The v1 

36"derived titles/prefixes" registration becomes piece_tags entries -- 

37per-parse state that dissolves with the state (v1 kept per-parse sets 

38for the same reason). 

39 

40Implements rules P2, P3, P4, P12 and M2, S2's trailing read (#614), C1's 

41decision through _comma, and 

42the 

43group half of M1 (#329: the marker dropped inside EXTRACTED maiden 

44content, which M2's pieces walk cannot reach because extract's 

45content never enters pieces); each is cited at its code below. Also 

46implements rule P5 (cited below at the bound-given join) and ports 

47the "Ph. D."-split merge (v1 fix_phd; decisions/phd-merge). 

48 

49The piece-level predicates moved to _pieces in #439 -- the S2 

50trailing peel, the leading-title and title-piece tests, the 

51suffix-piece test, the no-name-segment test. Most are shared with 

52assign; trailing_start is group's alone and travelled because the 

53shared ones call it (is_title_piece was too, until #602 and #603 gave 

54assign calls of its own). They had collected here 

55by import direction rather than by topic (assign imported group and 

56could not be imported back), which is the accumulation 

57mechanisms.md#ONE-PREDICATE-PER-QUESTION describes; group imports them 

58back like any other caller, and still does the work H3 and S2 describe 

59with them. is_prefix_piece and is_conj_piece followed in #617, with 

60the merge and rules/P3's connective joins (join_connectives), when 

61the comma decision's own copy of those joins was folded into them. 

62What remains defined here is group's own: _is_rootname and 

63_is_maiden_marker_piece. 

64""" 

65from __future__ import annotations 

66 

67import bisect 

68from collections.abc import Iterable, Sequence, Set 

69from enum import IntEnum 

70from typing import assert_never 

71 

72from nameparser._lexicon import _run_addresses_by_given 

73from nameparser._pipeline._pieces import ( 

74 split_credential_report, 

75 Peel, TailRead, chain_lead, chain_run_end, is_conj_piece, is_leading_title, is_prefix_piece, 

76 is_suffix_piece, is_title_piece, is_trailing_title_word, 

77 join_connectives, joined_tags, 

78 leading_titles, merge_particle_runs, merge_pieces, peel_walk, 

79 read_trailing_run, settled_by_case, tail_reading, trailing_candidates, 

80 trailing_run_start, trailing_start, 

81 trailing_start_past_titles, 

82) 

83from nameparser._pipeline._state import ( 

84 AMBIGUOUS_ACRONYM_TAG, BOUND_PHRASE_TAG, SPLIT_CREDENTIAL_TAG, 

85 SPLIT_MEMBER_TAG, TRAILING_TITLE_TAG, ParseState, 

86 Deferred, PendingAmbiguity, Structure, WorkToken, 

87 _AMBIGUOUS_CREDENTIAL_TAGS, copy_with, 

88) 

89import nameparser._pipeline._comma as _comma 

90from nameparser._pipeline._vocab import ( 

91 ROMAN, comma_follows_marker, delimiter_cores, ends_in_a_generation, 

92 composed, name_reading, numeral_settled_by_case, 

93 reads_as_a_reported_numeral, suffix_reading, 

94) 

95from nameparser._types import AmbiguityKind, Role 

96 

97# the split credential is `_vocab.split_pair`, which classify asks of 

98# every adjacent pair and writes on the pair's first word, and which 

99# is_wholly_suffix asks to merge the same Ph./D. pair, as 

100# `_comma._pieces` reads the tag -- so that predicate's callers read 

101# what this stage merges: `_comma.decide`'s reading of the part after 

102# the comma, segment's C2 flag on a tail part, and script_segment's 

103# decline of a wholly-suffix post-comma run, all of which see the 

104# merged reading 

105 

106Piece = list[int] 

107#: What the marker pass took out of a segment: the marker's TOKEN 

108#: indices (more than one where the entry is a phrase, 'z domu'), and 

109#: every other piece it took with the role that piece takes -- the 

110#: maiden name's Role.MAIDEN, and the trailing run's SUFFIX or TITLE 

111#: (#601). `_group_segment` produces it. 

112MaidenTake = tuple[Piece, list[tuple[Piece, Role]]] 

113#: What `_maiden_take` answers with, one index space further out: PIECE 

114#: indices into its own `pieces` argument. `_group_segment` resolves 

115#: them to the token indices MaidenTake declares, which is the only 

116#: reason the two are different types rather than one name used twice. 

117MaidenIndices = tuple[list[int], list[tuple[int, Role]]] 

118 

119 

120class ClauseSite(IntEnum): 

121 """Where a maiden clause stands, which decides whether a marker 

122 counts there at all and which rule reads the end of the part 

123 (rules/M2, #601). 

124 

125 A marker counts only in the part holding the family name, so 

126 GIVEN_SLOT and TAIL are statements, not defaults: a marker there is 

127 an ordinary word. FAMILY_PART is the part before a family comma, 

128 where a marker counts but no trailing rule reads the words after 

129 the clause. 

130 

131 A CLOSED set: `_maiden_take` dispatches on it exhaustively, ONCE 

132 (`typing.assert_never`). group() is the one place (structure, 

133 segment index) is mapped onto it, and tests/v2/pipeline/ 

134 test_group.py's `test_the_site_is_pinned_to_the_structure_it_is_ 

135 read_from` pins that mapping -- by watching the call, not by 

136 restating it -- along with this enum's size. 

137 """ 

138 

139 FAMILY_PART = 0 # FAMILY_COMMA segment 0: a marker counts, nothing trails 

140 TRAILING = 1 # NO_COMMA, SUFFIX_COMMA segment 0: S2 peel + H5 chain 

141 GIVEN_SLOT = 2 # FAMILY_COMMA segment 1: a marker is an ordinary word 

142 TAIL = 3 # every tail segment: a marker is an ordinary word 

143 

144 

145class BoundJoin(IntEnum): 

146 """v1 _join_bound_first_name's reserve_last, as the three states it 

147 actually has. IntEnum: the value IS the number of name pieces 

148 assign's peel must leave in the JOINED view for the join to stand 

149 (#425), so the >= comparison below reads unchanged. Post-comma the 

150 reserve runs no peel -- the pair alone is that one piece; the 

151 decline reads H5's trailing run only where a title word follows 

152 the bound word (#637) -- and DISABLED 

153 is a mode, never compared: as a threshold 0 would join everything, 

154 which is why the block is entered on identity first.""" 

155 

156 DISABLED = 0 # the FAMILY_COMMA family segment (v1 never joined it) 

157 LENIENT = 1 # FAMILY_COMMA's post-comma segment (reserve_last=False) 

158 STRICT = 2 # main segments (reserve_last=True: keep a family piece) 

159 

160 

161# rules/M2: "A marker that counts takes the words after it as the 

162# maiden name, and is itself dropped" -- where a marker counts, and up 

163# to what, are `_maiden_take`'s (history: decisions/M2) 

164# 

165# A marker piece is a LONE marker -- M2's When ("a recognized maiden 

166# marker stands as a word in a name"). The consumer runs before every join but the Ph. D. merge 

167# (see _group_segment), so a marker inside a wider piece is one the 

168# consumer left there: declined ("Jane van der Berg née" reads family 

169# 'van der Berg née'), or never examined (a leading marker, or a second 

170# marker behind the span it took). Matching inside joined pieces would 

171# re-read those. 

172# 

173# With the pass ahead of the joins no default-vocabulary input reaches 

174# the lone-piece half through the one caller left that sees joined 

175# pieces (P5's marker decline, on `fk + 1`): a marker-headed wider 

176# piece needs a connective right after a declined marker, and a 

177# connective after a marker is a word the consumer takes. Measured at 

178# #420's review -- 

179# dropping `len(piece) == 1` leaves the suite and a 337k-name sweep 

180# identical -- so it stays as the rule's definition, not as a guard a 

181# pin holds. 

182def _is_maiden_marker_piece(piece: Sequence[int], 

183 tokens: Sequence[WorkToken]) -> bool: 

184 return (len(piece) == 1 

185 and "vocab:maiden-marker" in tokens[piece[0]].tags) 

186 

187 

188# mechanisms.md#ONE-PREDICATE-PER-QUESTION: "where the reader comes 

189# AFTER the decider, record the answer on the state instead" -- which is 

190# what the marker tags are. classify owns the phrase lookahead; group, 

191# running later, reads what it wrote. 

192def marker_run_length(following: Iterable[Set[str]]) -> int: 

193 """How many tokens a marker run spans, given the tag sets of what 

194 FOLLOWS its head, in order: 1 plus the leading continuations. 

195 

196 One walk for both places group asks -- over pieces below and over 

197 token indices in the clause drop at the end of this module, 700 

198 lines apart and differing only in index space. `following` is 

199 consumed lazily and only until the run ends, so a caller passes a 

200 generator over the rest of its sequence rather than materializing 

201 one.""" 

202 run = 1 

203 for tags in following: 

204 if "vocab:maiden-marker-cont" not in tags: 

205 break 

206 run += 1 

207 return run 

208 

209 

210def _marker_run_pieces(pieces: Sequence[Sequence[int]], 

211 tokens: Sequence[WorkToken], m: int) -> int: 

212 """How many pieces the marker run at pieces[m] spans: 1 

213 for a single-word marker, more for a phrase entry ('z domu'). 

214 

215 classify already decided where the run ends and recorded it on the 

216 tokens -- "vocab:maiden-marker" on the head, 

217 "vocab:maiden-marker-cont" on the rest. 

218 

219 Each continuation is the NEXT piece, and 

220 that holds because classify REFUSES to tag a run whose tokens are 

221 not structurally contiguous. It is not a property of this walk, and 

222 the reasons a token can be absent between two pieces are wider 

223 than they look. No join has run yet, so a piece is one token. A 

224 tail segment is cut at its delimiter cores and grouped part by 

225 part (#549), and a core between two marker words would be a token 

226 between them, which classify would not have tagged as a run. And 

227 `pieces` comes from a SEGMENT, or a part of one, and segment keeps 

228 only the tokens no stage has given a role, bucketed by the commas 

229 before them -- so a run half inside a bracketed clause, or split across a 

230 structure comma, is one no segment holds whole. Walking cont tags 

231 without classify's refusal read a proper PREFIX of the phrase as 

232 the whole marker, and 'Anna z (domu) Nowak' lost its given name to 

233 a bare preposition. Any future stage that removes a token from a 

234 segment owes this the same refusal. 

235 

236 What classify guarantees is exactly the main stream's half of that 

237 and no more: a run of ROLE-LESS tokens stays inside one segment. It 

238 can also tag a run across two adjacent clauses of the same role, 

239 which this walk never sees because a role-bearing token is in no 

240 segment at all -- see _vocab.tag_marker_runs, which states the limit. 

241 """ 

242 return marker_run_length( 

243 tokens[pieces[k][0]].tags for k in range(m + 1, len(pieces))) 

244 

245 

246def _maiden_take(pieces: Sequence[Sequence[int]], 

247 ptags: Sequence[Set[str]], 

248 tokens: Sequence[WorkToken], 

249 one_case: bool | None, 

250 site: ClauseSite, 

251 ambiguities: list[PendingAmbiguity], 

252 ) -> MaidenIndices | None: 

253 """The PIECE indices the marker pass removes, split the way 

254 MaidenIndices declares them: the marker's pieces (one, or several 

255 for a phrase entry like 'z domu'), then the maiden name's and the 

256 trailing run's, each with the role it takes. None where the marker is 

257 an ordinary word. Piece indices into `pieces`, not the TOKEN 

258 indices `_group_segment` builds out of them. 

259 

260 Three questions, in order (rules/M2, #601): 

261 

262 * WHERE A MARKER COUNTS. Only in the part holding the family name 

263 -- never in the given part after a family comma, never in a tail 

264 part -- and only with a name word straight before it: not a word 

265 of the leading title run (H3's give-back included, so 'Lord 

266 Chancellor née Jones' counts; a lone title is a title), not a 

267 suffix word unless it opens the name (S2), not a connective. A 

268 particle counts: with nothing after it to attach to it is no 

269 particle there ('Mai Le née Nguyen'). 

270 * WHAT IT TAKES. Every word after it up to the trailing run the 

271 name reads as if the clause were not written, and always the 

272 first word after it. The run is read over the VIEW -- the head 

273 plus the vocabulary-shaped tail, and anything from the first 

274 credential that starts a run (S8, #602) -- by `tail_reading`, so 

275 the count of words to spare is the clause-free name's. Before a 

276 family comma no trailing rule reads the part, and the family 

277 part takes a suffix word from anywhere in it: the clause stops 

278 at the first one and hands the rest back unbound. 

279 * THE RUN IS BOUND. Where a trailing rule reads the part, the take 

280 consumes the run and returns the role the reading gave each 

281 piece, so no join below this pass can reach into it. 

282 

283 Computed before any join (the Ph. D. merge aside), as the marker 

284 pass always has been (#420): the joins see a name without the 

285 clause in it. 

286 """ 

287 if site is ClauseSite.GIVEN_SLOT or site is ClauseSite.TAIL: 

288 return None 

289 m = next((v for v in range(1, len(pieces)) 

290 if _is_maiden_marker_piece(pieces[v], tokens)), None) 

291 if m is None: 

292 return None 

293 # the marker may be a phrase, in which case it is several pieces 

294 lo = m + _marker_run_pieces(pieces, tokens, m) 

295 if lo >= len(pieces): 

296 return None 

297 before = m - 1 

298 lead = (1 if m == 1 and is_title_piece(pieces[0], ptags[0], tokens) 

299 else leading_titles(pieces[:m], ptags[:m], tokens)) 

300 if (before < lead 

301 or (before > lead 

302 and is_suffix_piece(pieces[before], ptags[before], tokens)) 

303 or is_conj_piece(pieces[before], ptags[before], tokens)): 

304 return None 

305 # a suffix word straight after the marker: nothing was announced 

306 if is_suffix_piece(pieces[lo], ptags[lo], tokens): 

307 return None 

308 if site is ClauseSite.FAMILY_PART: 

309 end = next((j for j in range(lo + 1, len(pieces)) 

310 if "suffix" in ptags[j] 

311 or is_suffix_piece(pieces[j], ptags[j], tokens)), 

312 len(pieces)) 

313 return list(range(m, lo)), [(j, Role.MAIDEN) 

314 for j in range(lo, end)] 

315 if site is not ClauseSite.TRAILING: 

316 assert_never(site) 

317 c = trailing_candidates(lo, pieces, ptags, tokens) 

318 end = len(pieces) 

319 released: list[tuple[int, Role]] = [] 

320 # the view's picks, for the kept member below (#718) 

321 picked: tuple[tuple[int, ...], ...] = () 

322 # nothing behind the clause that a trailing rule could take: the 

323 # view would be the head alone, and the whole rest is the clause 

324 if c < len(pieces): 

325 left = list(range(m)) + list(range(c, len(pieces))) 

326 view = [pieces[i] for i in left] 

327 vtags = [ptags[i] for i in left] 

328 vrest, vchained, vpeel = tail_reading( 

329 peel_walk(leading_titles(view, vtags, tokens), vtags), 

330 view, vtags, tokens, one_case) 

331 picked = vpeel.picks 

332 titles = set(vchained) | set(vpeel.run_titles) 

333 in_run = titles | set(vrest[vpeel.names:]) | { 

334 q for q in range(m, len(view)) if "suffix" in vtags[q]} 

335 e = len(view) 

336 while e - 1 >= m and (e - 1) in in_run: 

337 e -= 1 

338 end = c + (e - m) 

339 released = [(j, Role.TITLE if m + (j - c) in titles 

340 else Role.SUFFIX) for j in range(end, len(pieces))] 

341 # rules/S12: "where the count takes the pair, the reading is reported" -- 

342 # the clause-free reading took it, and the take binds it here 

343 for j, role in released: 

344 if "split" in ptags[j] and role is Role.SUFFIX: 

345 ambiguities.append( 

346 split_credential_report( 

347 pieces[j], tokens, 

348 name_reading(tokens[pieces[j][0]], Role.MAIDEN))) 

349 # mechanisms.md#AMBIGUITY-AT-THE-DECISION-SITE: "Emit at the 

350 # site that takes the branch, not where an ambiguous tag sits" 

351 # -- the take consumed the run, so the forks the reading called 

352 # on it are reported here, where assign will never see them 

353 consumed = {i for j in range(end, len(pieces)) for i in pieces[j]} 

354 for piece in (*vpeel.picks, *vpeel.absorbed, 

355 *vpeel.numerals): 

356 if piece[0] in consumed: 

357 ambiguities.append(PendingAmbiguity( 

358 AmbiguityKind.SUFFIX_OR_NAME, 

359 f"{tokens[piece[0]].text!r} after the maiden name " 

360 f"reads as a suffix; it may be a name word", 

361 tuple(piece), 

362 # a name word there ends the clause's maiden name 

363 alternative=name_reading(tokens[piece[0]], 

364 Role.MAIDEN))) 

365 # ...and the member the clause KEEPS as its last word: the reading 

366 # left it a name word, which is a fork too 

367 last = pieces[end - 1] 

368 word = tokens[last[0]] 

369 # a one-word member: a split credential the clause keeps is one the 

370 # count declined, which reports nothing (rules/S12), and its first 

371 # word is not the clause's last 

372 if len(last) == 1 and not word.tags.isdisjoint(_AMBIGUOUS_CREDENTIAL_TAGS): 

373 ambiguities.append(PendingAmbiguity( 

374 AmbiguityKind.SUFFIX_OR_NAME, 

375 f"{word.text!r} ending the maiden name is also a " 

376 f"post-nominal; the maiden marker's clause keeps it rather " 

377 f"than reading it as one", tuple(last), 

378 alternative=suffix_reading(word))) 

379 elif tuple(last) in picked: 

380 # rules/S10: "either reading is reported" -- a numeral the read 

381 # declined, for want of words to spare or for its Title case, 

382 # which the clause keeps 

383 why = ("but the name has no other word to spare for it" 

384 if len(word.text.rstrip(".")) == 1 

385 else "but written in Title case it leans to the name") 

386 ambiguities.append(PendingAmbiguity( 

387 AmbiguityKind.SUFFIX_OR_NAME, 

388 f"{word.text!r} ending the maiden name is a roman numeral, " 

389 f"{why}; the maiden marker's clause keeps it rather than " 

390 f"reading it as a generational suffix", tuple(last), 

391 alternative=suffix_reading(word))) 

392 elif (released and len(last) == 1 and end - 2 >= lo 

393 and reads_as_a_reported_numeral( 

394 word.text, word.tags, tokens[pieces[end - 2][0]].text, 

395 one_case)): 

396 # rules/S10: "a one-letter numeral before a credential is the 

397 # family name, and the reading is reported" -- the clause's 

398 # twin of assign's report (#721's review): the clause keeps the 

399 # numeral its released post-nominal stands behind 

400 ambiguities.append(PendingAmbiguity( 

401 AmbiguityKind.SUFFIX_OR_NAME, 

402 f"{word.text!r} ending the maiden name is a roman numeral, " 

403 f"but a post-nominal follows it; the maiden marker's clause " 

404 f"keeps it rather than reading it as a generational suffix", 

405 tuple(last), alternative=suffix_reading(word))) 

406 return (list(range(m, lo)), 

407 [(j, Role.MAIDEN) for j in range(lo, end)] + released) 

408 

409 

410#: What `_between_name_words` reads instead of walking: two arrays over 

411#: the segment's pieces, giving for each index the nearest piece on 

412#: its left and on its right that is NOT a connective -- `-1` and 

413#: `len(pieces)` where the run reaches the end. Built by 

414#: `_run_neighbours`, and an ALIAS rather than a NamedTuple because a 

415#: NamedTuple's __new__ is a frame of its own (decisions/parse-cost). 

416_Beside = tuple[list[int], list[int]] 

417 

418 

419def _run_neighbours(pieces: Sequence[Sequence[int]], 

420 ptags: Sequence[Set[str]], 

421 tokens: Sequence[WorkToken]) -> _Beside: 

422 """The nearest piece that is not a connective, on each side of 

423 every index. 

424 

425 EVERY MEMBER OF ONE RUN HAS THE SAME ANSWER, which is the whole 

426 of the fix: `_between_name_words` used to walk the run itself, so a 

427 name holding a run of n connectives walked it n times and the 

428 stage went quadratic in the run's length -- measured 2026-09-20, 

429 `"Josep " + "i " * n + "Rovira"` grew 3.8x per doubling against 

430 the 2.0x every other shape holds, 59ms at n=800. Two linear 

431 passes answer the same question once for the whole segment. 

432 `tests/v2/test_benchmark.py`'s `link_run` shape is the guard. 

433 

434 `is_conj_piece` is asked ONCE per piece, into a list the second 

435 pass then reads: asking it in both passes would double the calls, 

436 and it is the only per-piece call this builder makes. Recorded in 

437 the FIRST pass rather than by a comprehension of its own -- which 

438 is a code object on 3.11 and a bytecode saving here rather than a 

439 frame one, measured: the profile hook emits no call event for it. 

440 

441 WHAT IT COSTS A SHORT NAME, because answering for the whole 

442 segment is not free where the walk would have stopped at once: 

443 this call, plus `is_conj_piece` for the pieces the walk never 

444 reached. Re-measured 2026-09-21 on py3.11 against b9ed1429, the 

445 whole pair through `tests/v2/test_benchmark.py`'s own 

446 `_frames_for` shape -- `Josep Carod i Rovira` 311 -> 313 frames 

447 (one call and two more `is_conj_piece` over its four pieces, 

448 less the frame the fold below saved) and `Jane Doe nee Puig i 

449 Soler` 315 -> 319. An O(1) rise per link-bearing name against an 

450 unbounded saving: the same name with a run of 64 links goes 

451 6,741 -> 2,587. (The pair first written here read 304 -> 307 and 

452 307 -> 312, with 6,741 -> 2,652 for the run of 64. Re-measured 

453 2026-09-22 on py3.11, WHICH OF THOSE REPRODUCE is: the two 

454 short-name pairs, neither of them; the run-of-64 pair, its left 

455 half only -- b9ed1429 reads 6,741 exactly, while 6048eb5d, the 

456 tree the 2,652 was taken on, reads 2,651 here. So the interpreter 

457 splice ran through a single arrow, which is what the table 

458 `tools/perf/call_count.py`'s own docstring warns about. Every 

459 figure above is one interpreter, stated.) 

460 `tools/perf/call_count.py` is unmoved (parse=406.00, 

461 facade=443.00) -- its reference name carries no link -- and so are 

462 `John Smith`, `Smith, John`, `Juan Garcia y Lopez` and `Jane Doe 

463 nee Smith`, none of which reaches this at all. 

464 

465 Called only where a generational connective was found in the 

466 segment (the `frozen` loop), so no ordinary name pays for it at 

467 all. 

468 

469 Dropping either pass's `not` fails 

470 test_a_connective_piece_counts_toward_the_carve_outs_total 

471 (mutation-checked 2026-09-20; how the two arrays are READ is 

472 checked in `_between_name_words`, which reads them). 

473 """ 

474 n = len(pieces) 

475 left = [-1] * n 

476 right = [n] * n 

477 conj = [False] * n 

478 prev = -1 

479 for k in range(n): 

480 left[k] = prev 

481 is_conj = is_conj_piece(pieces[k], ptags[k], tokens) 

482 conj[k] = is_conj 

483 if not is_conj: 

484 prev = k 

485 nxt = n 

486 for k in range(n - 1, -1, -1): 

487 right[k] = nxt 

488 if not conj[k]: 

489 nxt = k 

490 return left, right 

491 

492 

493def _is_rootname(piece: Sequence[int], ptags: Set[str], 

494 tokens: Sequence[WorkToken]) -> bool: 

495 if len(piece) == 1 and "initial" in tokens[piece[0]].tags: 

496 return False 

497 # rules/P3: "A connective counts as a name word wherever this 

498 # rule counts them, whatever else the vocabulary says the word is" 

499 # (#397). The order against the `initial` refusal above decides 

500 # nothing, and what makes that safe lives in classify rather than 

501 # here: for a single letter it writes `initial` or `conjunction` 

502 # and never both, so a one-case `I`/`i` arrives with no conjunction 

503 # tag whichever test runs first -- measured, hoisting this arm 

504 # above the refusal moves no field, report or initial on any 

505 # corpus name under three name orders, and no test. INLINE rather 

506 # than a call to is_conj_piece: this runs once per piece of every 

507 # name (frame budget). 

508 if ("conjunction" in ptags 

509 or (len(piece) == 1 and "conjunction" in tokens[piece[0]].tags)): 

510 return True 

511 return not (is_title_piece(piece, ptags, tokens) 

512 or is_prefix_piece(piece, ptags, tokens) 

513 or is_suffix_piece(piece, ptags, tokens)) 

514 

515 

516def _is_lone_letter(piece: Sequence[int], tokens: Sequence[WorkToken], 

517 one_case: bool | None) -> bool: 

518 """A piece of one word that is one letter, with or without its 

519 period: the letter P13 links. Not a connective, the word P13 asks 

520 about, nor a lowercase letter in a name of mixed case, which S10 

521 reads as the generation by its writing.""" 

522 if len(piece) != 1 or "conjunction" in tokens[piece[0]].tags: 

523 return False 

524 letter = composed(tokens[piece[0]].text.rstrip(".")) 

525 return (len(letter) == 1 and letter.isalpha() 

526 and not numeral_settled_by_case(letter, one_case)) 

527 

528 

529def _is_name_word(piece: Sequence[int], ptags: Set[str], 

530 tokens: Sequence[WorkToken]) -> bool: 

531 return not (is_conj_piece(piece, ptags, tokens) 

532 or is_title_piece(piece, ptags, tokens) 

533 or is_suffix_piece(piece, ptags, tokens)) 

534 

535 

536def _link_the_last_letter(pieces: list[list[int]], ptags: list[set[str]], 

537 tokens: Sequence[WorkToken], 

538 one_case: bool | None, keep_a_name: bool) -> None: 

539 """P13's two joins at the end of the part holding the family name, 

540 made ahead of P3's carve-out. `keep_a_name` marks the whole name's 

541 part, where a piece past the title run must stand in front of the 

542 join, so the name keeps a word for its given name. The connective 

543 is looked for before the title run is counted, so a part with no 

544 connective where P13 looks pays only the walk back from the end, 

545 not leading_titles' count.""" 

546 # rules/P13: "A single-letter connective in front of a lone letter 

547 # ending the name words joins it to the word before" and "A 

548 # connective with nothing to link joins the word before it alone" 

549 # -- both joins, made ahead of P3's carve-out (decisions/P13 

550 # (#1097, #1098)) 

551 e = len(pieces) - 1 

552 lone = False 

553 while e >= 0: 

554 piece = pieces[e] 

555 if _is_lone_letter(piece, tokens, one_case): 

556 lone = True 

557 break 

558 # rules/P13: "with nothing behind it but suffixes or a 

559 # trailing title H5 reads" -- H5's own word test, asked rather 

560 # than copied, so the walk steps over every title the chain 

561 # takes (decisions/P13, #1168) 

562 if not (is_trailing_title_word(piece, tokens) 

563 or is_suffix_piece(piece, ptags[e], tokens) 

564 or (e > 0 and len(piece) == 1 

565 # reads_as_generation's own first test, asked at C 

566 # level as _comma._whole_name and _group_segment's 

567 # P3 numeral count ask it, so a word that is no 

568 # numeral pays no frame for the call 

569 and ROMAN.match(tokens[piece[0]].text.rstrip(".")) 

570 is not None 

571 and ends_in_a_generation( 

572 [tokens[pieces[e - 1][-1]].text, 

573 tokens[piece[0]].text], one_case))): 

574 break 

575 e -= 1 

576 if e < 1: 

577 return 

578 # the connective: in front of the lone letter, or the word the walk 

579 # stopped at 

580 at = e - 1 if lone else e 

581 if (at < 1 or len(pieces[at]) != 1 

582 or "conjunction" not in tokens[pieces[at][0]].tags): 

583 return 

584 word = tokens[pieces[at][0]] 

585 text = composed(word.text) 

586 if lone: 

587 if not (len(text) == 1 and text.isalpha()): 

588 return 

589 elif not (text.isalpha() 

590 and not (one_case and len(text) == 1 

591 and text.lower() != text.upper()) 

592 and "vocab:suffix" not in word.tags 

593 and not (len(text) > 1 and e + 1 < len(pieces) 

594 and is_trailing_title_word(pieces[e + 1], tokens))): 

595 return 

596 if (at - 1 >= leading_titles(pieces, ptags, tokens) + keep_a_name 

597 and _is_name_word(pieces[at - 1], ptags[at - 1], tokens)): 

598 merge_pieces(pieces, ptags, at - 1, e + 1) 

599 

600 

601# rules/P3: "a word the rest of the parse reads as a name word 

602# rather than as a generation, a credential or an honorific, looked 

603# for past any run of connectives standing between. A connective with 

604# nothing to its right is connecting nothing, and a word of that 

605# vocabulary ending a name, or standing before the credential a name 

606# ends with, is the generation it also spells" (#397) -- the WHOLE 

607# clause, its second sentence included, because that sentence is what 

608# this predicate answering `False` means. Reading it as a generation 

609# is the CALLER's half: `_group_segment`'s `frozen` set is where a 

610# connective this refuses is placed as the generation. 

611# `Sequence[Sequence[int]]` rather than `Sequence[Piece]`: this reads a 

612# piece and never edits one (widened when the maiden walk was a 

613# second caller, before #601). 

614def _between_name_words(k: int, lo: int, hi: int, 

615 pieces: Sequence[Sequence[int]], 

616 ptags: Sequence[Set[str]], 

617 tokens: Sequence[WorkToken], 

618 beside: _Beside) -> bool: 

619 """Whether such a word stands on EACH side of the connective piece 

620 at `k`. 

621 

622 Both sides in one call because neither caller ever wants one: a 

623 connective is placed to join only where a name word stands on both 

624 sides of it, so the two answers were always ANDed at the call site 

625 and the left one short-circuits the right either way. One frame per 

626 generational connective rather than two, which is the whole of the 

627 saving -- the left arm below is the old left call and the right arm 

628 the old right one, unchanged (#397 follow-up). 

629 

630 `lo` and `hi` bound the name's own words: assign peels the pieces 

631 below `lo` as its leading titles and those from `hi` up as its 

632 trailing suffix run, so a piece outside that span is a credential 

633 or an honorific however it is spelled, and the numeral or bare 

634 acronym the peel takes ('i V', 'i MA') is inside `hi` by 

635 construction rather than by a second reading of the vocabulary 

636 (mechanisms.md#ONE-PREDICATE-PER-QUESTION). 

637 

638 Inside the span the suffix and title tests still run, because 

639 neither bound reaches a credential or an honorific standing in 

640 the MIDDLE of a name ('Josep Jr. i Rovira', 'Josep Dr. i 

641 Rovira'): the peel walks from the end and stops at the first name 

642 word, the title run from the front. 

643 

644 The answer steps over connectives because a RUN of them joins as 

645 one ('Carod i y Rovira'), so the word this rule is about is the 

646 first one past the run -- and where the run runs out ('Juan i e') 

647 there is no name word on that side at all. `beside` is where that 

648 stepping already happened: 

649 `_run_neighbours` walked every run once for the whole segment, so 

650 this reads an index rather than walking to it. A SENTINEL OUT OF 

651 RANGE is how "the run ran out" arrives -- 

652 -1 on the left, `len(pieces)` on the right -- and each bound test 

653 below turns it into False, exactly as the walk did when it ran 

654 here and stopped at the same place. `lo` is never negative and 

655 `hi` never past `len(pieces)`, so neither sentinel can pass the 

656 bound, and the piece tests are never asked about an index that is 

657 not one. 

658 

659 Mutation-checked 2026-09-21, every arm of both sides by a NAMED 

660 test. Reading the LEFT array for the right arm too fails 

661 test_a_connective_with_nothing_to_its_right_does_not_join; 

662 the RIGHT array for the left arm too fails 

663 test_a_leading_title_on_the_left_is_no_name_word. 

664 The bounds, WIDENED to the whole segment rather than dropped -- 

665 dropping the right one indexes past the pieces on the sentinel and 

666 raises instead of failing a test -- fail 

667 test_the_marker_is_not_the_name_word_on_the_links_left (left) and 

668 test_the_right_hand_test_reads_the_peel_not_the_suffix_piece 

669 (right). Either piece test on the LEFT fails 

670 test_a_credential_or_honorific_mid_name_is_no_name_word_either; 

671 either on the RIGHT fails 

672 test_a_credential_or_honorific_mid_name_on_the_right_too, which is 

673 the row the fold asked for: while this was two per-side calls a 

674 mutation hit both sides at once and the left-hand rows covered for 

675 the right-hand ones, whose own rows stand at the END of the name 

676 where `hi` refuses them first. SWAPPING the two arrays outright is 

677 an EQUIVALENT mutant and no test fails: the two arms are ANDed, so 

678 which array answers which side is not a question the conjunction 

679 can see. 

680 """ 

681 left = beside[0][k] 

682 if not (lo <= left < hi 

683 and not is_suffix_piece(pieces[left], ptags[left], tokens) 

684 and not is_title_piece(pieces[left], ptags[left], tokens)): 

685 return False 

686 right = beside[1][k] 

687 return (lo <= right < hi 

688 and not is_suffix_piece(pieces[right], ptags[right], tokens) 

689 and not is_title_piece(pieces[right], ptags[right], tokens)) 

690 

691 

692# rules/S12: "where the count declines it, the pair is the two words 

693# it is written as" -- after the trailing read, which is where the 

694# count is asked in a main segment 

695def _settle_splits(pieces: list[Piece], ptags: list[set[str]]) -> None: 

696 """Split every merged split credential left in `pieces` back into 

697 its two words, in place: a pair the trailing read declined reads 

698 as it reads unmerged. One a connective join took into a wider piece 

699 keeps the join and loses the tag (the only shape that reaches it 

700 is a pair beside a connective, 'Pharm D and').""" 

701 k = 0 

702 while k < len(pieces): 

703 if "split" in ptags[k]: 

704 if len(pieces[k]) == 2 and ptags[k] == {"split"}: 

705 a, b = pieces[k] 

706 pieces[k:k + 1] = [[a], [b]] 

707 ptags[k:k + 1] = [set(), set()] 

708 k += 2 

709 continue 

710 ptags[k] = ptags[k] - {"split"} 

711 k += 1 

712 

713 

714# rules/P12: "the two words are one name unit past the first name word" 

715# -- past the piece P5's leading join reads, which this leaves as it 

716# was, its reserve included; classify's tag says the word and the 

717# token after it are a listed phrase (history: decisions/P12, #694) 

718def _join_bound_phrases(pieces: list[Piece], ptags: list[set[str]], 

719 tokens: Sequence[WorkToken], 

720 joined_heads: set[int]) -> None: 

721 # built in one pass: a merge per pair would shift every piece 

722 # behind it, a quadratic in a run of pairs (merge_pieces' note) 

723 k = leading_titles(pieces, ptags, tokens) + 1 

724 out, out_tags = pieces[:k], ptags[:k] 

725 n = len(pieces) 

726 joined = False 

727 while k < n: 

728 word = pieces[k] 

729 if (k + 1 < n and len(word) == 1 and not ptags[k] 

730 and BOUND_PHRASE_TAG in tokens[word[0]].tags 

731 and pieces[k + 1] == [word[0] + 1] and not ptags[k + 1]): 

732 joined_heads.add(word[0]) 

733 word.extend(pieces[k + 1]) 

734 out.append(word) 

735 out_tags.append(set()) 

736 joined = True 

737 k += 2 

738 continue 

739 out.append(word) 

740 out_tags.append(ptags[k]) 

741 k += 1 

742 if joined: 

743 pieces[:] = out 

744 ptags[:] = out_tags 

745 

746 

747def _group_segment(seg: tuple[int, ...], additional: int, 

748 tokens: Sequence[WorkToken], 

749 bound_join: BoundJoin = BoundJoin.STRICT, 

750 ambiguities: list[PendingAmbiguity] | None = None, 

751 given_name_titles: Set[str] = frozenset(), 

752 opens_the_name: bool = False, 

753 *, 

754 one_case: bool | None, 

755 site: ClauseSite, 

756 reads: list[TailRead | None] | None = None, 

757 phrase_heads: set[int] | None = None, 

758 given_first: bool, 

759 ) -> tuple[list[Piece], list[set[str]], MaidenTake | None]: 

760 pieces: list[Piece] = [[i] for i in seg] 

761 ptags: list[set[str]] = [set() for _ in seg] 

762 # Out-parameter, same shape as _assign_main: forks are reported 

763 # where they are decided. A caller that passes None (or a throwaway 

764 # list) suppresses reporting -- see group() for when that applies. 

765 if ambiguities is None: 

766 ambiguities = [] 

767 # The maiden take reports on this same channel: it reports only at 

768 # the TRAILING site, which group() never suppresses. 

769 

770 # ph-d merge first: "Ph." "D." adjacent -> one suffix piece, 

771 # where the lexicon lists `phd` as unambiguous suffix vocabulary 

772 # (#1000) 

773 # (decisions/phd-merge; v1 fix_phd did this by regex on the 

774 # raw string) 

775 # A suffix never BEGINS a name: position outranks the vocabulary 

776 # match (#371). This merge is what makes a leading "Ph." "D." a 

777 # credential at all -- every other suffix-shaped word standing 

778 # first already falls out as a title (H2's abbreviation clause, or 

779 # TITLES membership) or as a name word, so the pair is the only 

780 # shape that reaches the defect, and it reached it by emptying the 

781 # family: "Ph. D. Van Johnson" read given 'Van Johnson' with no 

782 # surname at all. 

783 # 

784 # WHERE THE INPUT BEGINS, and that is v1's own boundary rather 

785 # than a new one: fix_phd was a regex requiring a preceding space 

786 # (`\s(ph\.?\s+d\.?)`), so it could never fire at the head of the 

787 # string and fired everywhere else -- mid-name as readily as 

788 # trailing. Three tests, because "the head" has three meanings 

789 # here and only one of them is v1's: 

790 # `k == 0` the first PIECE, which is not the first word -- 

791 # extract_delimited removes a bracketed or quoted 

792 # clause before segment runs, so `"Bob" Ph. D. John 

793 # Smith` reaches this with the pair at k == 0 and a 

794 # word standing before it in the input. v1 merges 

795 # there; declining broke parity on 112 measured 

796 # names, every one opening with a quote or bracket. 

797 # `a[0] == 0` the first TOKEN, which is v1's boundary. 

798 # seg_idx 0 and not after a family comma: a credential run 

799 # legitimately opens segment 1 ("Smith, Ph. D. 

800 # Jr.", C8's credential run in the listing form), and segment 0 before a 

801 # comma is the family the comma named, where v1 

802 # merges too ("Ph. D., John" reads last 'Ph. D.'). 

803 # 

804 # A leading TITLE is therefore NOT stepped over, unlike the #367 

805 # scan below, and the two disagree on purpose: that scan asks 

806 # where the NAME begins, this asks where the STRING does. `Sir 

807 # Ph. D. Van Johnson` keeps suffix 'Ph. D.' with an empty family, 

808 # which is #371's symptom surviving one word to the left -- 1.4.0 

809 # parity, stated as a boundary in rules/S2 rather than fixed 

810 # here, because "the first piece of the name" cannot be computed 

811 # before this merge: `is_leading_title` is true of `Ph.` itself, 

812 # so the scan would step over the very piece being judged. 

813 # 

814 # Every other split credential ('Pharm. D.', `_vocab.split_pair`'s 

815 # "split" answer) merges under the same head test as a member of 

816 # the ambiguous class, where a rule reads such a member: in a main 

817 # segment, where S2's read below decides it by the count, kept 

818 # whole where the read takes it and split back into its two words 

819 # where it does not (`_settle_splits`), so a declined pair reads 

820 # exactly as the two words read; and in the given part after a 

821 # family comma behind the given word, where S5's walk reads it, 

822 # merged ahead of the joins so the particle chain stops in front of 

823 # it and P5's bound join declines it as it declines a suffix word, 

824 # and a pair declined there is middle-name text whole or split. 

825 # (A connective beside a pair keeps it from merging at all, in 

826 # classify.) 

827 # Not in the part before a family comma, which reads no member as 

828 # a suffix ('Smith MA, John'). Classify tagged each pair's first 

829 # word, so the test here is a tag. 

830 # 

831 # Written into fresh lists in one pass, `pos` being the index the 

832 # piece stands at once the merges before it are made: a merge in 

833 # place shifts the rest of the list (`merge_pieces`' comment), and 

834 # a run of pairs would shift it once per pair. A merged pair is 

835 # never a member of another, so the scan moves past both words. 

836 splits = False 

837 given_from: int | None = None 

838 out: list[Piece] = [] 

839 out_tags: list[set[str]] = [] 

840 n = len(pieces) 

841 k = 0 

842 while k < n: 

843 a = pieces[k] 

844 add: str | None = None 

845 if k + 1 < n: 

846 b = pieces[k + 1] 

847 tags = tokens[a[0]].tags 

848 pos = len(out) 

849 if (len(a) == 1 and len(b) == 1 

850 and not (opens_the_name and pos == 0 and a[0] == 0)): 

851 if SPLIT_CREDENTIAL_TAG in tags: 

852 add = "suffix" 

853 elif SPLIT_MEMBER_TAG in tags: 

854 if site is ClauseSite.TRAILING: 

855 add = "split" 

856 splits = True 

857 elif site is ClauseSite.GIVEN_SLOT: 

858 if given_from is None: 

859 given_from = leading_titles( 

860 out + pieces[k:], out_tags + ptags[k:], 

861 tokens) 

862 if pos > given_from: 

863 add = "split" 

864 if add is None: 

865 out.append(a) 

866 out_tags.append(ptags[k]) 

867 k += 1 

868 continue 

869 a.extend(pieces[k + 1]) 

870 out.append(a) 

871 out_tags.append(joined_tags(ptags, k, k + 2, add={add})) 

872 k += 2 

873 pieces[:] = out 

874 ptags[:] = out_tags 

875 

876 # rules/M2: "A marker that counts takes the words after it as 

877 # the maiden name, and is itself dropped" (history: 

878 # decisions/M2) -- the marker pass (#274), and it runs 

879 # BEFORE every join below. Each join rule asks a question about the 

880 # name -- how many words it has (P3's carve-out, P5's reserve), 

881 # what the word after a particle or a bound word is -- and the 

882 # marker and the maiden name are not part of that name: they leave. 

883 # Asked while they were still pieces, the count answered for a name 

884 # that would not exist ('juan y garcia nee jones' counted five, 'y' 

885 # joined, and the family was empty once the clause left: #418), and 

886 # a join could absorb the marker before the pass looked for a lone 

887 # one ('Jane van der Berg née y Jones' kept the marker in the 

888 # family: #412). Removing the pieces first makes both impossible by 

889 # construction, with no stop on the chain (#399, #417) and no 

890 # exclusion in the reserve (#411) left to keep in step. 

891 #