Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/design/decisions/C15-comma-with-nothing-before-it.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,19 @@

- A comma with nothing before it is a family comma naming no surname, the part after it read as the given part after a family comma reads, held by an invariant over two inputs rather than by a sweep shape: `, X` reads as `Smith, X` reads, less the surname, its fields and ambiguity kinds alike; a particle P6 attaches is then the family alone (`, Jane van` → family 'van') — 2026-10-27 #892.
- H1 is the one exception: a title and one name word, or a bound pair standing for it, read as the family (`, Dr. John` → family 'John', `, Dr. abdul Rahman` → family 'abdul Rahman'), the comma naming no surname to decide the field by, as a comma with nothing but titles after it names no given part — 2026-10-27 (Derek).
- No code is written for the empty head alone: P6 attaches behind it as behind any family comma, ahead of H1, so a particle ending the name leaves H1 two name words and the exception does not apply (`, Dr. Jones vd` → given 'Jones', family 'vd') — 2026-10-27 #892 (Derek).

Open: whether the code written for the empty head alone (#890's floor for `, Dr. fils`, the P6 attachment site in post_rules) can go, the question #892's fourth point asks; the invariant answers it by mutation, one site at a time.
Open: none in this file.

## Log

- 2026-10-27 #892 — A COMMA WITH NOTHING BEFORE IT IS A FAMILY COMMA NAMING NO SURNAME. The shape had no rule: clauses in rules/H8, rules/O6 and rules/M2 and review findings in decisions/C1, S10, A1 and H5 each decided it locally, and nameparser/AGENTS.md made every comma change sweep it. Real names almost never take it: 10 of about 6 million local-corpus names (FEC 4, tse 3, PSC 2, tw-donors 1, the last opening with a fullwidth comma, `,邱詩涵`, which reads as `, 邱詩涵` does), the issue's count of 2026-10-25 missing the fullwidth one; recounted 2026-10-27 by scanning each local corpus's names for one opening, after spaces, with `,` or `,`. The alternative, dropping the comma so `, John Smith` reads as `John Smith`, was declined: the shape's one source is an empty surname field in listing data (#613's review, `, PhD` and `, Jr.`), and reading it as a whole name contradicts that source.
- 2026-10-27 #892 (its `vd` and `mc` bullet superseded by 2026-10-27 #892 (Derek), below) — A COMMA WITH NOTHING BEFORE IT IS A FAMILY COMMA NAMING NO SURNAME. The shape had no rule: clauses in rules/H8, rules/O6 and rules/M2 and review findings in decisions/C1, S10, A1 and H5 each decided it locally, and nameparser/AGENTS.md made every comma change sweep it. Real names almost never take it: 10 of about 6 million local-corpus names (FEC 4, tse 3, PSC 2, tw-donors 1, the last opening with a fullwidth comma, `,邱詩涵`, which reads as `, 邱詩涵` does), the issue's count of 2026-10-25 missing the fullwidth one; recounted 2026-10-27 by scanning each local corpus's names for one opening, after spaces, with `,` or `,`. The alternative, dropping the comma so `, John Smith` reads as `John Smith`, was declined: the shape's one source is an empty surname field in listing data (#613's review, `, PhD` and `, Jr.`), and reading it as a whole name contradicts that source.
- Measured on master (8a65ee18) before any change, over the grid `tests/v2/test_properties.py::test_an_empty_head_reads_as_its_family_comma_twin` builds (10 title runs × 32 bodies × 11 trailing words, 3,519 given parts under each of three orders): every given part reads as its twin but 1,075 per order, all of them H1's, so the rule landed with no code change. A first comparison's eight differing given parts holding `MA`, among them `, MA`, `, (Bob) MA`, `, J. MA` and `, JOHN SMITH MA`, were the twin's doing, not the empty head's: a surname written `Smith` brings a case contrast the given part lacks, so `Smith, MA` reads suffix 'MA' by its capitals (rules/S6) while `, MA` and `SMITH, MA` both read given 'MA'. The test writes the twin's surname in the given part's case for that reason, and rules/C15's Accepted bullet records the reading.
- The particle-and-suffix words `vd` and `mc` ending the name behind H1's family reading (`, Dr. Jones vd`) are the exception's knock-on, not a second one: the twin attaches the word to its surname (rules/P6), the empty head has no family to attach it to once H1 has made the lone word the family, and it reads as the suffix. Behind a given-name title H1 reads no family and P6 attaches as in the twin (`, Sir Jones vd` → family 'vd').
- The exception is stated by its result, not by the comma-less name: `, Jane Mrs` reads family 'Jane' where `Jane Mrs` reads family 'Mrs' (a bare salutation is a title only after a family comma, rules/H8), and `, Dr. abdul Rahman` reads family 'abdul Rahman' where `Dr. abdul Rahman` reads given 'abdul', family 'Rahman'. A first draft compared against the comma-less name and the design-docs review found it false on 493 of the 1,075 H1 rows per order.
- The invariant compares fields and ambiguity KINDS, never a report's detail: `, Sir Jones vd` reports that 'vd' "joins the family the comma named", a comma that names none, and passes. Report-detail grids keep the empty head (nameparser/AGENTS.md).
- Recompute: `uv run pytest -n0 "tests/v2/test_properties.py::test_an_empty_head_reads_as_its_family_comma_twin"`; its docstring records the negative control.

- 2026-10-27 (Derek) — H1 STAYS THE ONE EXCEPTION, stated as the comma deciding nothing. "Keep H1 as the one exception, stated as a comma with nothing before it not deciding the field." `, Dr. John` keeps family 'John', where its twin `Smith, Dr. John` reads given 'John': rules/H1 already says a comma with nothing but titles after it names no given part and so does not decide the field, and a comma with nothing before it names no family, the mirror case. Following the invariant instead would have read given 'John' for every such row, 1,075 per order on the grid; rules/H8's Accepted bullet records the trailing spellings' family reading (`, Jane Mrs`, and the period-marked one since H5, #316).

- 2026-10-27 #892 (Derek) — THE EMPTY HEAD'S OWN CODE IS GONE, the question #892's fourth point asked. SUPERSEDES: the `vd` and `mc` bullet of 2026-10-27 #892, which read `, Dr. Jones vd` as suffix 'vd'. A search of the pipeline for code that reads an empty part before the comma found one site: P6's second attachment site, in post_rules after H1 and M4, with the guard in assign's comma site that kept the attachment from acting there (decisions/P6, #613). Switching both off moved 112 given parts per order on the invariant grid, every one a particle-and-suffix word `vd` or `mc` ending the name behind a title that addresses by surname (`, Dr. Jones vd`, `, Mr Jones mc`, `, Jones vd Mrs`), each from family 'Jones', suffix 'vd' to given 'Jones', family 'vd' with a `suffix-or-name` report, and moved them onto the twin: no row failed the invariant, and H1's rows fell from 1,075 to 963 per order. Off the grid the PR review found two more classes, each onto its twin too: the same tail behind a third comma part (`, Dr. Jones vd, PhD` → family 'vd', suffix 'PhD', where it read suffix 'vd, PhD'), and a never-given particle opening the part with no name word behind it (`, de PhD vd` → given 'de', suffix 'PhD vd', as `Smith, de PhD vd` and `, de vd` read, where the removed site, which lacked the comma site's P1 guard, read family 'vd', suffix 'PhD', reported). An ambiguous particle there already read so (`, Dr. Jones van` → family 'van'), and the site had kept the comma-less name's reading (`Dr. Jones vd`). Removed, with "ok, remove it". #890's floor for `, Dr. fils` is not the empty head's: it is rules/C4's count of name words before the comma, which a one-word head meets too (`Sir Alexandre, fils`). None of the 10 real names with the shape holds a trailing particle.
Loading
Loading