docs: a family-first order may move the particle stop, and a conjunction-joined run is one word

[derek73]

Docs, plus one code comment. Two records, both needed before #395 can be implemented.

decisions.md#P1 — supersession

The 2026-08-16 order-precedence keystone says "no name_order moves that stopping point". It may. That sentence was a choice made to see where it landed; two implementation attempts on #390 (both closed unmerged) are where it landed, and both failed at the same place — trying to bound a leading particle run on position alone, in a parser that has correctly refused to detect language.

Declaring FAMILY_FIRST or FAMILY_FIRST_GIVEN_LAST is precisely an assertion that what follows the family is not more surname, which is the question the stopping point asks. So the declaration is evidence about it. The grouping/assignment split survives everywhere else; only that one sentence is narrowed.

The accepted cost is recorded with it: under the default order de la Vega Juan stays wholly a surname, and a caller who means otherwise writes the comma. The same greedy reading is what makes de Mesnil Juan parse like pennie von bergen wessels — the same shape, and a real US politician's name.

Per the log's discipline the 2026-08-16 entry is not edited; the new entry supersedes it and names what it does not touch (#368's reversal, P6, and the leading-particle-takes-the-family claim all stand).

Also appends to #3-0-reevaluations: every argument in the thread — de/do Vietnamese, von German, dos Portuguese, das both Portuguese and a borne Bengali surname — is a language judgement, and locale packs are where a caller supplies language instead of the parser guessing. Not 2.x work; it needs packs to carry vocabulary overrides rather than additions.

rules.md#P3 — the conjunction clause

P3 said a connective binds name words into one part, but not how other rules count that part. They count it as one, so a rule taking "one name word" takes the whole join and never half of it. The case that forced the question is #395: a run that stops "after the first name word" would otherwise be free to stop inside a part P3 built, splitting de la Vega y Santos Juan between Vega and Santos.

The clause describes shipped behavior. H1 counts this way today, which the examples now show as a minimal pair:

"Mr. Jack and Jill"  ->  family="Jack and Jill"
"Mr. Jack Jill"      ->  given="Jack"            (boundary)

decisions.md#P3 records the clause, including how it was nearly shipped unexaminable: the first draft asserted that no rule could show it today and carried an Accepted: note saying so. That was reasoning about which rules count instead of parsing a name — the H1 pair had never been run, and Derek caught it by asking whether Jack and Jill was an example.

rules.md#P3 — the examples were all carve-out cases

Separately noticed by Derek: every P3 example used y, E or И, so the rule showed only the single-letter exceptions and never an ordinary join. The boundary line read as if three-word names simply don't join. Two contrast examples fix it:

"Juan y Garcia"      ->  middle="y"                 (boundary — carve-out fires)
"Juan and Garcia"    ->  given="Juan and Garcia"    (multi-letter, joins)
"Juan & Garcia"      ->  given="Juan & Garcia"      (single-character, not a letter)

Measured, the predicate is len(text) == 1 and total < 4 and text.isalpha() — so the carve-out counts letters, and the vocabulary holds six single-letter conjunctions (y e и і й و), not two. All six hit the carve-out; only the Latin ones hit the bare-capital veto, which is the asymmetry #383 is open about.

decisions.md#3-0-reevaluations records the locale consequence, which sharpens yesterday's particle entry: Spanish writes y and would want e read as an initial, Portuguese wants the reverse, Dutch would want every single letter read as an initial. A pack that can only add or replace vocabulary cannot express that — the join threshold and the initial veto have to be per-word, per-pack policy.

rules.md preamble — what · boundary means

"Juan y Garcia" -> middle="y" · boundary reads oddly, since y is inside P3's carve-out rather than outside the rule. Surveying all 39 markers shows that is the convention, not a slip — H1's boundary is "Sir John" (its given-name-title exception), H2's is "J. Smith" (bare initials, which its statement excludes), H3's is a title word mid-name. The marker means the rule's effect does not occur, and the informative case is almost always the rule's own stated exception, which is what makes the exception executable instead of merely asserted. The preamble now says that.

What was actually wrong is mine: P3 had picked up two markers meaning different things. "Mr. Jack Jill" is the contrast half of the H1 pair — no connective present at all — so it is not a limit of P3 and no longer claims to be.

_group.py — a citation where the carve-out is

The module cites rules.md#P3 on _is_conj_piece, the joining predicate. The single-letter carve-out is in the merge loop of a different function and carried only a v1 pointer ("Google Code issue 11"), so a reader standing at the code that implements the exception had no route to the rule. Comment-only.

It also records something the code says and the rule does not: the threshold counts rootnames, so a conjunction that is also suffix vocabulary is not counted and raises its own bar by one name word. #397 measures that on i.

3472 tests pass (every example line executes). Prerequisite for #395. #390 was closed as superseded before this PR, so nothing here closes it.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.51%. Comparing base (315c399) to head (89f31f8).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #396   +/-   ##
=======================================
  Coverage   98.51%   98.51%           
=======================================
  Files          44       44           
  Lines        2895     2895           
=======================================
  Hits         2852     2852           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.