@finbheara/domain 0.3.0 → 0.5.0

package/README.md

@@ -36,16 +36,47 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@finbheara/domain/place` | `place()`, `createPlaceReader`, `placeRelation`, the `Place` types |
 | `@finbheara/domain/clrg-regions` | `REGIONS`, `regionOf`, `resolvePhrase` |
 | `@finbheara/domain/school` | `createSchoolNameReader`, `DEFAULT_SCHOOL_NAME_READER`, `compareSchoolNames`, `foldSchoolName`, `schoolEncoder`, `schoolColumns` |
-| `@finbheara/domain/tune` | `tune()`, `tuneRelation`, `tempoLegal`, `settingAt`, `TUNE_NODES`: the CLRG set dance list |
+| `@finbheara/domain/tune` | `tune()`, `tuneRelation`, `tempoLegal`, `settingAt`, `TUNE_NODES`: the CLRG set dance list, each tune with its time, speeds and bars |
 | `@finbheara/domain/ceili` | `ceili()`, `ceiliRelation`, `CEILI_NODES`: the céilí handbook dances |
 | `@finbheara/domain/dance` | `dance()`: a print read as a tune and a céilí dance, narrowed by its round |
-| `@finbheara/domain/age` | `Age.from`, `Age.fromYOB`, `ageRelation`, `canOverlap`, `averageAge`, `isAveraged`, `intersectBirthYears`, the `Validated` type, the age constants |
+| `@finbheara/domain/age` | `Age.from`, `Age.fromYOB`, `ageRelation`, `canOverlap`, `averageAge`, `isAveraged`, `intersectBirthYears`, `validYOB`, the age constants |
 | `@finbheara/domain/noun-index` | `createIndex`, `indexSchema`, `personEncoder`, and the `SqlHandle`/`NounEncoder` types: a database-backed name map (below) |
 | `@finbheara/domain/dance-types` | `danceTypes()`, `DANCE_TYPES`, `rhythmOfTime`, and the shared `DanceMatch`/`DanceRelation`/`SetRhythm`/`TimeSignature` types |
+| `@finbheara/domain/promotion` | `samePromotedRow`, `samePromotedSchool`, `samePromotedHeir`, `samePromotedName`, `questionMarksRead`, `foldCharSynonyms`: is a row the same row after a promotion (below) |
 
 The library does no I/O and installs nothing process-wide. Every reader has a default and a
 factory: build your own with options when the default is not what you want.
 
+## Empty, refused, valid
+
+A reader never throws on what was printed. Every value it returns (`Place`, `SchoolName`,
+`Age`, `TuneReading`, `CeiliReading`, `DanceReading`) is `Validated`, and answers three
+questions:
+
+| method | true when |
+|---|---|
+| `isEmpty()` | nothing was printed: an empty or blank cell, no dance named |
+| `isRefused()` | something was printed and the type declines it: a placeholder, a school in a place field, `U2`, a `1900` year of birth |
+| `isValid()` | neither: `!isEmpty() && !isRefused()` |
+
+`invalidReason()` is `null` when the value is valid, `"empty"` when it is empty, and the
+refusal's reason otherwise, in the type's own words. Every entry point exports the `Validated`
+type.
+
+Valid does not mean usable. A print the reader does not know but cannot rule out is valid:
+`place("Ardmore")` is valid and `isPlace()` is false. Ask the type's own question (`isPlace()`,
+`isSchool()`, `isAge()`, `isTune()`, `isCeili()`) for a value you can use.
+
+```ts
+place("").invalidReason();                                    // "empty"
+place("n/a").invalidReason();                                 // "placeholder"
+place("Ardmore").isValid();                                   // true: valid, unknown
+DEFAULT_SCHOOL_NAME_READER.schoolName("N/A").isRefused();     // true
+Age.fromYOB(1900).invalidReason();                            // "year-out-of-range"
+tune("").isEmpty();                                           // true
+tune("Reel").invalidReason();                                 // "dance-type"
+```
+
 ## Read a place
 
 ```ts
@@ -155,6 +186,31 @@ invisible characters dropped and its whitespace collapsed; a `regex` is compiled
 flag and anchors itself. Your rows are asked before the shipped ones and the first match
 answers.
 
+## Read a set dance
+
+`tune()` reads a spoken or printed set dance as the tunes of the official list it may name. A
+stated tempo is taken out of the print and narrows the reading. Each tune answers its time
+signature, its speed (a fixed speed for the seven traditional sets, a minimum for any
+contemporary set) and the bars of music in its two parts, the step and the set.
+
+```ts
+import { tempoLegal, tune } from "@finbheara/domain/tune";
+
+const r = tune("Kilkenny Races at 80");
+r.tune?.name;                     // "Kilkenny Races"
+r.bpm;                            // 80
+r.tune?.time();                   // "4/4"
+tempoLegal(r, 80);                // true: hornpipe time, at or above 76
+r.tune?.stepBars();               // 8
+r.tune?.setBars();                // 24
+
+tune("Blackbird").tune?.speed();  // 144: a traditional set's fixed speed
+tune("Planxty").candidates.length; // 3: Davis, Drury and Hugh O'Donnell
+```
+
+The bars are data on the tune and never read from a print: they say how long a step and a
+set run at a given speed, and are the same in a traditional and a contemporary round.
+
 ## Read an age
 
 Ages are as of 1 January of the competition year. An `Age` is a closed range of birth years,
@@ -180,17 +236,18 @@ Age.fromYOB(1999).fitsIn(Age.from("Over 21", { year: 2026, top: true })); // tru
 canOverlap(u12, Age.from("U14", { year: 2026 }), dancer);                 // true
 ```
 
-A value the reader cannot stand behind is returned, not thrown. Every `Age` answers
-`isValid()` and `invalidReason()`: an age group under `U3` admits nobody old enough to dance,
-and a year of birth outside 1900 to 2099 is not one. An invalid `Age` has no birth years and
-rules nothing out.
+A value the reader cannot stand behind is returned, not thrown. An `Age` is `Validated` (above):
+an age group under `U3` admits nobody old enough to dance, and a year of birth outside 1901 to
+2099 is not one, so the placeholders `1000` and `1900` are refused. An invalid `Age` has no
+birth years and rules nothing out.
 
 ```ts
 Age.from("U2", { year: 2026 }).isValid();               // false
 Age.from("U2", { year: 2026 }).invalidReason();         // "below-youngest-band"
 Age.fromYOB(2222).invalidReason();                      // "year-out-of-range"
 Age.from("All", { year: 2026 }).invalidReason();        // "not-a-band"
-Age.from("", { year: 2026 }).isValid();                 // true: empty, not invalid
+Age.from("", { year: 2026 }).isEmpty();                 // true: empty, not refused
+Age.from("", { year: 2026 }).invalidReason();           // "empty"
 ```
 
 A team's age is the average of its dancers' ages, rounded to two decimals. `averageAge`
@@ -277,6 +334,67 @@ column of your own by spreading one, `{ ...enc, columns: [...enc.columns, "k"],
 type (`{ value: "id", valueType: "INTEGER PRIMARY KEY" }` makes the value the row id); on such a table `map(level)` iterates in value order, and a `set` to a value another row
 holds is refused by the key).
 
+## Decide whether a promoted row is the same row
+
+A results sheet can be collected twice: first as a secondary view (an aggregator's copy), and
+later as the primary transcript read from the publisher's own document, which supersedes it.
+Whoever filed something against a row of the old view must then ask whether the row at the
+same card of the new transcript is the same row. The producer that retires old rows and every
+consumer that moves filed records onto successors must give the same answer, so the rule lives
+here once. **A consumer re-deciding a superseded view's address must use these functions, not a
+copy of them.**
+
+```ts
+import {
+  samePromotedHeir,
+  samePromotedRow,
+  samePromotedSchool,
+} from "@finbheara/domain/promotion";
+
+samePromotedSchool("Brambleton : Mid Region", "Brambleton");    // true: a location tail
+samePromotedSchool("Brambleton :", "Brambleton");               // true: a colon alone
+samePromotedSchool("Brambleton Academy", "Brambleton");         // false
+
+samePromotedRow(
+  { name: "Foireann A", school: "Brambleton" },
+  { name: "Team A", school: "Brambleton" },
+);                                                              // true: one designation
+
+samePromotedHeir(
+  { name: "?ilis O?zumock", school: "Rinceoir? Na Zumock" },
+  { name: "Éilis O'zumock", school: "Rinceoirí Na Zumock" },
+);                                                              // true: `?` for one character
+samePromotedHeir(
+  { name: "LenaZumock", school: "Brambleton" },
+  { name: "Lena (Xia) Zumock", school: "Brambleton" },
+);                                                              // true: glued, an aside added
+samePromotedHeir(
+  { name: "?ilis Zumock", school: "Brambleton" },
+  { name: "Éilis Rervton", school: "Brambleton" },
+);                                                              // false: another surname
+```
+
+What counts as the same row:
+
+- **Both prints go through the character fold first** (`foldCharSynonyms`): the apostrophe,
+  dash and space glyphs each to their lowest code point, then runs of whitespace as one space.
+- **The school** (`samePromotedSchool`) is equal after the fold, or the old print is the new one
+  with an apostrophe restored, or followed by `:` and a location, or by `:` alone.
+- **An ordinary promotion** (`samePromotedRow`): the school the same, and the name equal after
+  the fold, an apostrophe restored, or the same team designation.
+- **The heir of a retired row** (`samePromotedHeir`), where the producer retired the old row and
+  named no successor: the name byte-identical, or the school the same and the name the same
+  person's (`samePromotedName`). A `?` in the old print stands for exactly one character, an
+  apostrophe or a letter outside ASCII, and is read back from the new print at the same
+  position (`questionMarksRead`). The names are then compared through `@finbheara/names` at
+  NN3, which drops case, punctuation and accents and strips a parenthetical aside; a given name
+  and surname the old view glued into one token are compared by the name fold against the new
+  name's fields, in either order.
+
+Anything else is another row: a different surname or given name, one letter printed for
+another, a `?` over an ASCII letter, a school that differs anywhere but a trailing `: location`.
+The caller pairs the card; nothing here reads an address.
+
 ## Known gaps
 
 - `place()` reads `"Derry in Ireland"` and `"Calgary in Western Canada"` as `unread`: it does

package/dist/age.js

@@ -1,3 +1,7 @@
+import {
+  validity
+} from "./chunks/place-q9kwsmzd.js";
+
 var YOUNGEST_FLOOR = 0;
 var ADULT_FLOOR = 18;
 var MAJORS_FLOOR_YEARS = 3;
@@ -7,7 +11,7 @@ var YOUNG_FLOOR = Object.freeze({ hard: 2, soft: 4 });
 var MIN_MAJOR_AGE = 4;
 var MIN_FEIS_AGE = 3;
 var YOUNGEST_BAND_TOP = MAJORS_FLOOR_YEARS;
-var YOB_RANGE = Object.freeze({ first: 1900, last: 2099 });
+var YOB_RANGE = Object.freeze({ first: 1901, last: 2099 });
 var DANCE_UP_YEARS = 1;
 var ageOnJanuary1 = (year, born) => year - born - 1;
 var yearsSinceBirth = (year, born) => year - born;
@@ -169,13 +173,11 @@ function fromPrint(print, context = {}) {
     parts: reading.parts,
     length: ag2.length,
     refusal: reading.refusal,
-    isValid: () => reading.refusal === null,
-    invalidReason: () => reading.refusal,
+    ...validity(arm === "empty", reading.refusal),
     source,
     clauses: reading.clauses,
     ladder,
     year,
-    isEmpty: () => arm === "empty",
     isAge: () => iv !== null,
     isExact: () => {
       if (iv === null || year === null)
@@ -221,13 +223,11 @@ function fromYOB(from, to = from, context = {}) {
     parts: from !== null && from === to ? [from] : [from, to].filter((y) => y !== null),
     length: ag2.length,
     refusal,
-    isValid: () => valid,
-    invalidReason: () => refusal,
+    ...validity(false, refusal),
     source: valid ? "printed-yob" : "open",
     clauses: [],
     ladder: NO_LADDER,
     year: null,
-    isEmpty: () => false,
     isAge: () => valid,
     isExact: () => exact,
     isAndOver: () => valid && from === null,

package/dist/ceili.js

@@ -4,7 +4,7 @@ import {
   ceiliById2,
   ceili2,
   ceiliRelation2
-} from "./chunks/place-0ehc2q69.js";
+} from "./chunks/place-kk48pfja.js";
 import"./chunks/place-htxgptyv.js";
 export {
   CEILI_NODES2 as CEILI_NODES,

package/dist/chunks/{place-qbp3xfb4.js → place-0j6k50wf.js}

@@ -1,3 +1,7 @@
+import {
+  validity
+} from "./place-q9kwsmzd.js";
+
 var PLACE_NODES = [
   {
     id: "world",
@@ -7098,7 +7102,7 @@ function createPlaceReader2(options = {}) {
       refusal: r.refusal,
       misses,
       length: pl2.length,
-      isEmpty: () => pl1 === "",
+      ...validity(pl1 === "", r.refusal),
       isPlace: () => pl1 !== "" && r.refusal === null && chains.length > 0,
       isSingular() {
         return this.arm === "resolved";

package/dist/chunks/{place-0ehc2q69.js → place-kk48pfja.js}

@@ -4,6 +4,9 @@ import {
   candidateRelation,
   isDanceTypePrint2
 } from "./place-htxgptyv.js";
+import {
+  validity
+} from "./place-q9kwsmzd.js";
 
 function node(id, name, irish, family, formation, opts = {}) {
   const kind = "round" in formation ? "round" : ("long" in formation) ? "long" : "set";
@@ -169,6 +172,7 @@ function reading(print, folded, candidates, score, match, refusal, misses) {
     score,
     match,
     refusal,
+    ...validity(refusal === "empty", refusal === "empty" ? null : refusal),
     misses: Object.freeze([...misses]),
     ceili: candidates.length === 1 ? candidates[0] : undefined,
     isCeili: () => candidates.length > 0,

package/dist/chunks/place-q9kwsmzd.js

@@ -0,0 +1,11 @@
+function validity(empty, refusal) {
+  const reason = empty ? "empty" : refusal;
+  return {
+    isEmpty: () => empty,
+    isRefused: () => !empty && refusal !== null,
+    isValid: () => reason === null,
+    invalidReason: () => reason
+  };
+}
+
+export { validity };

package/dist/chunks/{place-2ja9yx08.js → place-yndzaae5.js}

@@ -6,13 +6,16 @@ import {
   rhythmOfTime2,
   isDanceTypePrint2
 } from "./place-htxgptyv.js";
+import {
+  validity
+} from "./place-q9kwsmzd.js";
 
 var SET_MIN_SPEED2 = Object.freeze({
   jig: 66,
   hornpipe: 76
 });
 var PLAUSIBLE_SET_TEMPO_MAX2 = 150;
-function node(id, name, irish, time, opts = {}) {
+function node(id, name, irish, time, [stepBars, setBars], opts = {}) {
   return Object.freeze({
     id,
     name,
@@ -21,124 +24,126 @@ function node(id, name, irish, time, opts = {}) {
     irishPrints: Object.freeze(opts.irishPrints ?? []),
     time,
     traditionalSpeed: opts.traditionalSpeed ?? null,
-    maxSpeed: null
+    maxSpeed: null,
+    stepBars,
+    setBars
   });
 }
 var TUNE_NODES2 = Object.freeze([
-  node("blackbird", "The Blackbird", "An Lon Dubh", "2/4", {
+  node("blackbird", "The Blackbird", "An Lon Dubh", "2/4", [15, 30], {
     prints: ["Blackbird", "Blackbird (Traditional)"],
     irishPrints: ["An Londubh"],
     traditionalSpeed: 144
   }),
-  node("lodge-road", "The Lodge Road", "Bóthar an Lóiste", "2/4", {
+  node("lodge-road", "The Lodge Road", "Bóthar an Lóiste", "2/4", [8, 20], {
     irishPrints: ["Bóthar An Lóiste"]
   }),
-  node("downfall-of-paris", "Downfall of Paris", "Titim Phárais", "2/4", {
+  node("downfall-of-paris", "Downfall of Paris", "Titim Phárais", "2/4", [8, 16], {
     prints: ["The Downfall of Paris"],
     irishPrints: ["Titim Paris", "Titim Páras"]
   }),
-  node("planxty-davis", "Planxty Davis", "Plancstaí Dáibhéis", "2/4", {
+  node("planxty-davis", "Planxty Davis", "Plancstaí Dáibhéis", "2/4", [16, 16], {
     irishPrints: ["Plancstaí Daibhéis"]
   }),
-  node("king-of-the-fairies", "King of the Fairies", "Rí na Síog", "2/4", {
+  node("king-of-the-fairies", "King of the Fairies", "Rí na Síog", "2/4", [8, 16], {
     traditionalSpeed: 130
   }),
-  node("rodneys-glory", "Rodney's Glory", "Glóir Rodney", "2/4", {
+  node("rodneys-glory", "Rodney's Glory", "Glóir Rodney", "2/4", [8, 12], {
     irishPrints: ["Glór Rodnaí"]
   }),
-  node("ace-and-deuce-of-pipering", "Ace and Deuce of Pipering", "Aon agus dó na Píobaireachta", "4/4", {
+  node("ace-and-deuce-of-pipering", "Ace and Deuce of Pipering", "Aon agus dó na Píobaireachta", "4/4", [12, 12], {
     prints: ["Ace & Deuce of Pipering"],
     irishPrints: ["Aon agus Dó na Píobaireachta"]
   }),
-  node("kilkenny-races", "Kilkenny Races", "Rásaí Chill Choinnigh", "4/4", {
+  node("kilkenny-races", "Kilkenny Races", "Rásaí Chill Choinnigh", "4/4", [8, 24], {
     prints: ["Killkenny Races"]
   }),
-  node("blue-eyed-rascal", "The Blue-Eyed Rascal", "Cladhaire na Súile Gorma", "4/4", {
+  node("blue-eyed-rascal", "The Blue-Eyed Rascal", "Cladhaire na Súile Gorma", "4/4", [8, 12], {
     prints: ["Blue Eyed Rascal"]
   }),
-  node("madame-bonaparte", "Madame Bonaparte", "Madame Bonaparte", "4/4"),
-  node("bonapartes-retreat", "Bonaparte's Retreat", "Cúlú Bhonaparte", "4/4", {
+  node("madame-bonaparte", "Madame Bonaparte", "Madame Bonaparte", "4/4", [8, 12]),
+  node("bonapartes-retreat", "Bonaparte's Retreat", "Cúlú Bhonaparte", "4/4", [8, 20], {
     irishPrints: ["Cúlú Bonaparte"]
   }),
-  node("piper", "The Piper Through the Meadow Astraying", "An Píobaire sa Mhóinéar ar Strae/Fáin", "4/4", {
+  node("piper", "The Piper Through the Meadow Astraying", "An Píobaire sa Mhóinéar ar Strae/Fáin", "4/4", [8, 12], {
     prints: ["The Piper", "The Piper thro' the Meadow Straying"],
     irishPrints: ["An Píobaire"]
   }),
-  node("four-masters", "The Four Masters", "Na Ceithre Máistrí", "4/4"),
-  node("rambling-rake", "Rambling Rake", "An Réice Fáin", "4/4", {
+  node("four-masters", "The Four Masters", "Na Ceithre Máistrí", "4/4", [8, 12]),
+  node("rambling-rake", "Rambling Rake", "An Réice Fáin", "4/4", [8, 16], {
     prints: ["The Rambling Rake"]
   }),
-  node("garden-of-daisies", "Garden of Daisies", "Gáirdíní na Nóinín", "4/4", {
+  node("garden-of-daisies", "Garden of Daisies", "Gáirdíní na Nóinín", "4/4", [8, 16], {
     irishPrints: ["Gairdín na Nóiníní", "Gáirdíní na Nóiníní"],
     traditionalSpeed: 138
   }),
-  node("roving-pedlar", "The Roving Pedlar", "An Mangaire Fáin", "4/4"),
-  node("hunt", "The Hunt", "An Fiach", "4/4"),
-  node("white-blanket", "White Blanket", "An Súisín Bán", "4/4", {
+  node("roving-pedlar", "The Roving Pedlar", "An Mangaire Fáin", "4/4", [8, 14]),
+  node("hunt", "The Hunt", "An Fiach", "4/4", [8, 12]),
+  node("white-blanket", "White Blanket", "An Súisín Bán", "4/4", [6, 12], {
     prints: ["The White Blanket"]
   }),
-  node("job-of-journeywork", "Job of Journeywork", "An Greas Giúrnála", "4/4", {
+  node("job-of-journeywork", "Job of Journeywork", "An Greas Giúrnála", "4/4", [8, 14], {
     irishPrints: ["Greas Giúrnála"],
     traditionalSpeed: 138
   }),
-  node("youghal-harbour", "Youghal Harbour", "Cuan Eochaille", "4/4"),
-  node("blackthorn-stick", "Blackthorn Stick", "An Maide Droighneáin", "6/8", {
+  node("youghal-harbour", "Youghal Harbour", "Cuan Eochaille", "4/4", [6, 14]),
+  node("blackthorn-stick", "Blackthorn Stick", "An Maide Droighneáin", "6/8", [15, 15], {
     prints: ["The Blackthorn Stick"],
     irishPrints: ["An Maide Droighnéan"]
   }),
-  node("planxty-drury", "Planxty Drury", "Plancstaí Drúirí", "6/8", {
+  node("planxty-drury", "Planxty Drury", "Plancstaí Drúirí", "6/8", [12, 16], {
     prints: ["Planxy Drury"]
   }),
-  node("charlady", "The Charlady", "An Bhean Ghlantacháin", "6/8", {
+  node("charlady", "The Charlady", "An Bhean Ghlantacháin", "6/8", [8, 24], {
     irishPrints: ["Bean an Ghlantacháin"]
   }),
-  node("planxty-hugh-odonnell", "Planxty Hugh O'Donnell", "Plancstaí Aodh Uí Dhomhnaill", "6/8", {
+  node("planxty-hugh-odonnell", "Planxty Hugh O'Donnell", "Plancstaí Aodh Uí Dhomhnaill", "6/8", [16, 16], {
     irishPrints: ["Plancstaí Aodh Ó Domhnaill"]
   }),
-  node("drunken-gauger", "Drunken Gauger", "An Gaueger Meisceach", "6/8", {
+  node("drunken-gauger", "Drunken Gauger", "An Gaueger Meisceach", "6/8", [15, 15], {
     prints: ["The Drunken Gauger", "The Funny Tailor"]
   }),
-  node("rub-the-bag", "Rub the Bag", "Cuimil an Mála", "6/8"),
-  node("fiddler-around-the-fairy-green", "The Fiddler Around the Fairy Green", "An Bheidhleadóir ag an Crann Sí", "6/8", { prints: ["The Fiddler 'Round the Fairy Tree", "The Fiddler Around the Fairy Tree"] }),
-  node("st-patricks-day", "St. Patrick's Day", "Lá Fhéile Phádraig", "6/8", {
+  node("rub-the-bag", "Rub the Bag", "Cuimil an Mála", "6/8", [8, 14]),
+  node("fiddler-around-the-fairy-green", "The Fiddler Around the Fairy Green", "An Bheidhleadóir ag an Crann Sí", "6/8", [8, 12], { prints: ["The Fiddler 'Round the Fairy Tree", "The Fiddler Around the Fairy Tree"] }),
+  node("st-patricks-day", "St. Patrick's Day", "Lá Fhéile Phádraig", "6/8", [8, 14], {
     irishPrints: ["Lá Fhéile Pádraig", "Lá Féile Phádraig"],
     traditionalSpeed: 94
   }),
-  node("humours-of-bandon", "Humours of Bandon", "Pléarácha na Banndon", "6/8", {
+  node("humours-of-bandon", "Humours of Bandon", "Pléarácha na Banndon", "6/8", [8, 16], {
     prints: ["Humour's of Bandon"],
     irishPrints: ["Pléaracha na Bandan"]
   }),
-  node("story-teller", "The Story-Teller", "An Scéalaí", "6/8", {
+  node("story-teller", "The Story-Teller", "An Scéalaí", "6/8", [8, 16], {
     prints: ["The Storyteller"]
   }),
-  node("hurling-boys", "The Hurling Boys", "Na Buachaillí Báire", "6/8", {
+  node("hurling-boys", "The Hurling Boys", "Na Buachaillí Báire", "6/8", [8, 14], {
     prints: ["The Hurling Boy"]
   }),
-  node("sprig-of-shillelagh", "The Sprig of Shillelagh", "An Ghéag Sail Éille", "6/8", {
+  node("sprig-of-shillelagh", "The Sprig of Shillelagh", "An Ghéag Sail Éille", "6/8", [6, 10], {
     prints: ["The Spring of Shillelagh"],
     irishPrints: ["An Geag Síléaladh"]
   }),
-  node("hurry-the-jug", "Hurry the Jug", "Cuir Thart an Crúsca", "6/8"),
-  node("three-sea-captains", "The Three Sea Captains", "An Triúr Chaptaen Mara", "6/8", {
+  node("hurry-the-jug", "Hurry the Jug", "Cuir Thart an Crúsca", "6/8", [8, 16]),
+  node("three-sea-captains", "The Three Sea Captains", "An Triúr Chaptaen Mara", "6/8", [8, 20], {
     prints: ["Three Sea Captains"],
     irishPrints: ["Na Trí Captéin Maraí", "Triúr Captaen Mara"],
     traditionalSpeed: 96
   }),
-  node("jockey-to-the-fair", "Jockey to the Fair", "An Marcach Chuig an Aonach", "6/8", {
+  node("jockey-to-the-fair", "Jockey to the Fair", "An Marcach Chuig an Aonach", "6/8", [8, 14], {
     traditionalSpeed: 90
   }),
-  node("vanishing-lake", "Vanishing Lake", "An Loch Mhadhma", "6/8", {
+  node("vanishing-lake", "Vanishing Lake", "An Loch Mhadhma", "6/8", [14, 18], {
     prints: ["The Vanishing Lake"],
     irishPrints: ["Luch An Mhadhma"]
   }),
-  node("miss-browns-fancy", "Miss Brown's Fancy", "Rogha Iníon De Brún", "6/8"),
-  node("wandering-musician", "The Wandering Musician", "An Ceoltóir Fáin", "6/8", {
+  node("miss-browns-fancy", "Miss Brown's Fancy", "Rogha Iníon De Brún", "6/8", [8, 16]),
+  node("wandering-musician", "The Wandering Musician", "An Ceoltóir Fáin", "6/8", [8, 16], {
     prints: ["Wandering Musicianr"]
   }),
-  node("orange-rogue", "Orange Rogue", "An Rógaire Buí", "6/8", {
+  node("orange-rogue", "Orange Rogue", "An Rógaire Buí", "6/8", [8, 16], {
     prints: ["The Orange Rogue"]
   }),
-  node("is-the-big-man-within", "Is the Big Man Within?", "An bhfuil an Fear Mór Istigh?", "6/8+9/8", {
+  node("is-the-big-man-within", "Is the Big Man Within?", "An bhfuil an Fear Mór Istigh?", "6/8+9/8", [8, 8], {
     irishPrints: ["An ‘Bhfuil an Fear Mór Istigh?"]
   })
 ]);
@@ -164,7 +169,9 @@ function makeTune(n) {
       if (n.traditionalSpeed !== null)
         return n.traditionalSpeed;
       return setting === "traditional" ? null : range;
-    }
+    },
+    stepBars: () => n.stepBars,
+    setBars: () => n.setBars
   });
 }
 var TUNES = Object.freeze(TUNE_NODES2.map(makeTune));
@@ -231,6 +238,7 @@ function reading(print, folded, bpm, candidates, score, match, refusal, misses)
     score,
     match,
     refusal,
+    ...validity(refusal === "empty", refusal === "empty" ? null : refusal),
     misses: Object.freeze([...misses]),
     tune: candidates.length === 1 ? candidates[0] : undefined,
     isTune: () => candidates.length > 0,

package/dist/dance.js

@@ -1,10 +1,13 @@
 import"./chunks/place-htxgptyv.js";
 import {
   ceili2
-} from "./chunks/place-0ehc2q69.js";
+} from "./chunks/place-kk48pfja.js";
 import {
   tune2
-} from "./chunks/place-2ja9yx08.js";
+} from "./chunks/place-yndzaae5.js";
+import {
+  validity
+} from "./chunks/place-q9kwsmzd.js";
 
 function dance(print, round) {
   const setting = round === "traditional-set" ? "traditional" : undefined;
@@ -25,7 +28,11 @@ function dance(print, round) {
   }
   misses.push(...tunes.misses, ...ceilis.misses);
   const candidates = Object.freeze([...tunes.candidates, ...ceilis.candidates]);
+  const empty = tunes.isEmpty() && ceilis.isEmpty();
+  const refused = !empty && !tunes.isValid() && !ceilis.isValid();
+  const reason = !refused ? null : tunes.invalidReason() === "dance-type" || ceilis.invalidReason() === "dance-type" ? "dance-type" : "unmatched";
   return Object.freeze({
+    ...validity(empty, reason),
     print,
     tunes,
     ceilis,

package/dist/place.js

@@ -15,7 +15,7 @@ import {
   placesRelation2,
   probablySamePlace2,
   sameReading2
-} from "./chunks/place-qbp3xfb4.js";
+} from "./chunks/place-0j6k50wf.js";
 export {
   DEFAULT_PLACE_CAPACITY2 as DEFAULT_PLACE_CAPACITY,
   DEFAULT_PLACE_READER2 as DEFAULT_PLACE_READER,

package/dist/promotion.js

@@ -0,0 +1,105 @@
+import { canonicalTeamName, nameFold, personName, probablySame } from "@finbheara/names/normalize";
+var CHAR_SYNONYM_CLASSES = [
+  {
+    name: "apostrophe",
+    canonical: "'",
+    members: ["'", "’", "ʼ", "‘", "’"]
+  },
+  {
+    name: "dash",
+    canonical: "-",
+    members: ["-", "‐", "‑", "–", "—"]
+  },
+  {
+    name: "space",
+    canonical: " ",
+    members: [" ", " ", " ", " ", " ", "　"]
+  }
+];
+var FOLD_MAP = new Map(CHAR_SYNONYM_CLASSES.flatMap((c) => c.members.map((m) => [m, c.canonical])));
+var FOLD_PATTERN = new RegExp(`[${[...FOLD_MAP.keys()].map((m) => `\\u${(m.codePointAt(0) ?? 0).toString(16).padStart(4, "0")}`).join("")}]`, "gu");
+function foldCharSynonyms(text) {
+  return text.replace(FOLD_PATTERN, (ch) => FOLD_MAP.get(ch) ?? ch);
+}
+var collapse = (s) => foldCharSynonyms(s).replace(/\s+/gu, " ").trim();
+function samePromotedSchool(was, now) {
+  const a = collapse(was);
+  const b = collapse(now);
+  if (a === b || apostropheRestored(was, now))
+    return true;
+  return b !== "" && a.startsWith(b) && /^ ?:( ?\S|$)/u.test(a.slice(b.length));
+}
+function apostropheRestored(was, now) {
+  const count = (s) => (collapse(s).match(/'/gu) ?? []).length;
+  const bare = (s) => collapse(collapse(s).replace(/'/gu, ""));
+  return count(now) >= count(was) && bare(was) === bare(now);
+}
+function samePromotedRow(was, now) {
+  if (!samePromotedSchool(was.school, now.school))
+    return false;
+  if (collapse(was.name) === collapse(now.name))
+    return true;
+  if (apostropheRestored(was.name, now.name))
+    return true;
+  const team = canonicalTeamName(collapse(was.name));
+  return team !== null && team === canonicalTeamName(collapse(now.name));
+}
+var STOOD_FOR = /^(?:'|(?![A-Za-z])\p{L})$/u;
+function questionMarksRead(was, now) {
+  const a = [...collapse(was)];
+  if (!a.includes("?"))
+    return a.join("");
+  const b = [...collapse(now)];
+  if (a.length !== b.length)
+    return null;
+  const out = [];
+  for (let i = 0;i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === "?") {
+      if (!STOOD_FOR.test(y))
+        return null;
+      out.push(y);
+    } else if (x !== y)
+      return null;
+    else
+      out.push(x);
+  }
+  return out.join("");
+}
+function samePromotedName(was, now) {
+  const read = questionMarksRead(was, now);
+  if (read === null)
+    return false;
+  const n = collapse(now);
+  if (read === n)
+    return true;
+  const b = personName(n);
+  if (!b.isPerson())
+    return false;
+  const a = personName(read);
+  if (a.isPerson())
+    return probablySame(a, b, "nn3");
+  const glued = nameFold(read);
+  const given = b.givenFields().join("");
+  const surname = b.surnameKey();
+  return glued !== "" && (glued === nameFold(`${given}${surname}`) || glued === nameFold(`${surname}${given}`));
+}
+function samePromotedHeir(was, now) {
+  if (was.name !== "" && was.name === now.name)
+    return true;
+  const school = questionMarksRead(was.school, now.school);
+  if (school === null || !samePromotedSchool(school, now.school))
+    return false;
+  return samePromotedName(was.name, now.name);
+}
+export {
+  CHAR_SYNONYM_CLASSES,
+  collapse,
+  foldCharSynonyms,
+  questionMarksRead,
+  samePromotedHeir,
+  samePromotedName,
+  samePromotedRow,
+  samePromotedSchool
+};

package/dist/school.js

@@ -5,7 +5,10 @@ import {
   areAllPlaceTokens2,
   placeRelation2,
   sameReading2
-} from "./chunks/place-qbp3xfb4.js";
+} from "./chunks/place-0j6k50wf.js";
+import {
+  validity
+} from "./chunks/place-q9kwsmzd.js";
 
 import { normalizeApostrophes } from "@finbheara/names/lexicon";
 import { SURNAME_SEPARATOR, lexiconKey, titleCaseNamePart } from "@finbheara/names/normalize";
@@ -1782,7 +1785,7 @@ function createSchoolNameReader(options = {}) {
       institution: b.institution,
       location: b.location,
       refusal: b.refusal,
-      isEmpty: () => b.empty,
+      ...validity(b.empty, b.refusal?.reason ?? null),
       isSchool: () => !b.empty && b.refusal === null,
       surnames: () => b.surnames,
       concerns: b.concerns

package/dist/tune.js

@@ -8,7 +8,7 @@ import {
   settingAt2,
   tune2,
   tuneRelation2
-} from "./chunks/place-2ja9yx08.js";
+} from "./chunks/place-yndzaae5.js";
 import"./chunks/place-htxgptyv.js";
 export {
   PLAUSIBLE_SET_TEMPO_MAX2 as PLAUSIBLE_SET_TEMPO_MAX,

package/dist/types/age.d.ts

@@ -1,6 +1,6 @@
 import type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, YOBContext, YoungFloorVerdict } from "./age-types.ts";
-import type { Validated } from "./validated.ts";
-export type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, Validated, YOBContext, YoungFloorVerdict, };
+import { type EmptyReason, type Validated } from "./validated.ts";
+export type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, EmptyReason, Validated, YOBContext, YoungFloorVerdict, };
 export declare const YOUNGEST_FLOOR = 0;
 export declare const ADULT_FLOOR = 18;
 export declare const MAJORS_FLOOR_YEARS = 3;
@@ -17,7 +17,7 @@ export declare const MIN_MAJOR_AGE = 4;
 export declare const MIN_FEIS_AGE = 3;
 export declare const YOUNGEST_BAND_TOP = 3;
 export declare const YOB_RANGE: Readonly<{
-    readonly first: 1900;
+    readonly first: 1901;
     readonly last: 2099;
 }>;
 export declare const DANCE_UP_YEARS = 1;
@@ -38,7 +38,6 @@ export interface Age extends Validated<AgeRefusal> {
     readonly clauses: readonly AgeClause[];
     readonly ladder: AgeLadder;
     readonly year: number | null;
-    isEmpty(): boolean;
     isAge(): boolean;
     isExact(): boolean;
     isAndOver(): boolean;

package/dist/types/ceili.d.ts

@@ -1,4 +1,6 @@
 import { type DanceMatch, type DanceRelation } from "./dance-match.ts";
+import { type Validated } from "./validated.ts";
+export type { EmptyReason, Validated } from "./validated.ts";
 export type CeiliFamily = "eight-hand" | "four-hand" | "handbook";
 export type CeiliFormation = "set" | "long" | "round";
 export interface CeiliNode {
@@ -33,7 +35,7 @@ export interface CeiliContext {
     readonly hands?: number;
 }
 export type CeiliRefusal = "empty" | "dance-type" | "unmatched";
-export interface CeiliReading {
+export interface CeiliReading extends Validated<Exclude<CeiliRefusal, "empty">> {
     readonly [Symbol.toStringTag]: "CeiliReading";
     readonly print: string;
     readonly folded: string;

package/dist/types/dance.d.ts

@@ -1,7 +1,10 @@
 import { type Ceili, type CeiliReading } from "./ceili.ts";
 import { type Tune, type TuneReading } from "./tune.ts";
+import { type Validated } from "./validated.ts";
+export type { EmptyReason, Validated } from "./validated.ts";
 export type DanceRound = "set" | "traditional-set" | "ceili" | "eight-hand" | "four-hand";
-export interface DanceReading {
+export type DanceRefusal = "dance-type" | "unmatched";
+export interface DanceReading extends Validated<DanceRefusal> {
     readonly print: string;
     readonly tunes: TuneReading;
     readonly ceilis: CeiliReading;

package/dist/types/place.d.ts

@@ -1,7 +1,8 @@
 import type { PlaceContext, PlaceKind, PlaceMatch, PlaceNode, PlaceRefusal, PlaceRelation } from "./place-types.ts";
-export type { PlaceContext, PlaceKind, PlaceMatch, PlaceNode, PlaceRefusal, PlaceRelation };
+import { type EmptyReason, type Validated } from "./validated.ts";
+export type { EmptyReason, PlaceContext, PlaceKind, PlaceMatch, PlaceNode, PlaceRefusal, PlaceRelation, Validated, };
 export type PlaceArm = "resolved" | "plural" | "ambiguous" | "unread";
-export interface AbstractPlace {
+export interface AbstractPlace extends Validated<PlaceRefusal> {
     readonly [Symbol.toStringTag]: "Place";
     toString(): string;
     readonly arm: PlaceArm;
@@ -18,7 +19,6 @@ export interface AbstractPlace {
     readonly refusal: PlaceRefusal | null;
     readonly misses: readonly string[];
     readonly length: number;
-    isEmpty(): boolean;
     isPlace(): boolean;
     isSingular(): this is ResolvedPlace;
     isPlural(): this is PluralPlaces;

package/dist/types/promotion.d.ts

@@ -0,0 +1,16 @@
+export interface PromotedPrint {
+    name: string;
+    school: string;
+}
+export declare const CHAR_SYNONYM_CLASSES: readonly {
+    readonly name: string;
+    readonly canonical: string;
+    readonly members: readonly string[];
+}[];
+export declare function foldCharSynonyms(text: string): string;
+export declare const collapse: (s: string) => string;
+export declare function samePromotedSchool(was: string, now: string): boolean;
+export declare function samePromotedRow(was: PromotedPrint, now: PromotedPrint): boolean;
+export declare function questionMarksRead(was: string, now: string): string | null;
+export declare function samePromotedName(was: string, now: string): boolean;
+export declare function samePromotedHeir(was: PromotedPrint, now: PromotedPrint): boolean;

package/dist/types/school-name.d.ts

@@ -1,6 +1,7 @@
 import { type Place } from "./place.ts";
 import { type NotASchool, type RefusalReason, type SchoolNameException } from "./school-exception-vocabulary.ts";
 import { type InstitutionType } from "./school-institution-vocabulary.ts";
+import { type Validated } from "./validated.ts";
 export interface LexiconFlags {
     surname: boolean;
     given: boolean;
@@ -26,7 +27,7 @@ export declare const SCHOOL_REFUSED = "!!!NOTASCHOOL";
 export type SchoolConcern = "institution-inside-name" | "promoted-name" | "no-name-part" | "truncated-tail" | "lexicon-absent" | "ambiguous-part" | "place-from-lexicon";
 export type Refusal = SchoolRefusal;
 export type Concern = SchoolConcern;
-export interface SchoolName {
+export interface SchoolName extends Validated<RefusalReason> {
     readonly [Symbol.toStringTag]: "SchoolName";
     toString(): string;
     readonly sn0: string;
@@ -38,7 +39,6 @@ export interface SchoolName {
     readonly institution: InstitutionType | null;
     readonly location: Place | null;
     readonly refusal: SchoolRefusal | null;
-    isEmpty(): boolean;
     isSchool(): boolean;
     surnames(): readonly string[];
     readonly concerns: readonly SchoolConcern[];

package/dist/types/school.d.ts

@@ -8,4 +8,5 @@ export { compareSchoolNames, compareSchools } from "./school-identity.ts";
 export type { IdentityResult, IdentityVerdict } from "./school-identity.ts";
 export { foldSchoolName, hasSpecificToken, schoolKeyTokens } from "./school-match-key.ts";
 export { NOT_A_SCHOOL, SCHOOL_NAME_EXCEPTIONS, } from "./school-exception-vocabulary.ts";
+export type { EmptyReason, Validated } from "./validated.ts";
 export type { NotASchool, RefusalReason, SchoolNameException, } from "./school-exception-vocabulary.ts";

package/dist/types/tune.d.ts

@@ -1,5 +1,7 @@
 import { type DanceMatch, type DanceRelation } from "./dance-match.ts";
 import { type SetRhythm, type TimeSignature } from "./dance-types.ts";
+import { type Validated } from "./validated.ts";
+export type { EmptyReason, Validated } from "./validated.ts";
 export type TuneSetting = "traditional" | "contemporary";
 export interface SpeedRange {
     readonly min: number;
@@ -16,7 +18,10 @@ export interface TuneNode {
     readonly time: TimeSignature;
     readonly traditionalSpeed: number | null;
     readonly maxSpeed: number | null;
+    readonly stepBars: number;
+    readonly setBars: number;
 }
+export type TuneBars = readonly [step: number, set: number];
 export declare const TUNE_NODES: readonly TuneNode[];
 export interface Tune {
     readonly [Symbol.toStringTag]: "Tune";
@@ -30,6 +35,8 @@ export interface Tune {
     time(): TimeSignature;
     rhythm(): SetRhythm;
     speed(setting?: TuneSetting): number | SpeedRange | null;
+    stepBars(): number;
+    setBars(): number;
 }
 export declare function allTunes(): readonly Tune[];
 export declare function tuneById(id: string): Tune | undefined;
@@ -42,7 +49,7 @@ export interface TuneContext {
     readonly time?: TimeSignature;
 }
 export type TuneRefusal = "empty" | "dance-type" | "unmatched";
-export interface TuneReading {
+export interface TuneReading extends Validated<Exclude<TuneRefusal, "empty">> {
     readonly [Symbol.toStringTag]: "TuneReading";
     readonly print: string;
     readonly folded: string;

package/dist/types/validated.d.ts

@@ -1,4 +1,8 @@
-export interface Validated<Reason extends string> {
+export type EmptyReason = "empty";
+export interface Validated<Refusal extends string> {
+    isEmpty(): boolean;
+    isRefused(): boolean;
     isValid(): boolean;
-    invalidReason(): Reason | null;
+    invalidReason(): EmptyReason | Refusal | null;
 }
+export declare function validity<Refusal extends string>(empty: boolean, refusal: Refusal | null): Validated<Refusal>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "Places, CLRG regions, school names, ages and dances as they are printed: read, compared and told apart",
 	"keywords": [
 		"places",
@@ -53,6 +53,10 @@
 			"types": "./dist/types/noun-index.d.ts",
 			"default": "./dist/noun-index.js"
 		},
+		"./promotion": {
+			"types": "./dist/types/promotion.d.ts",
+			"default": "./dist/promotion.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"files": ["dist/*.js", "dist/chunks/*.js", "dist/types/**/*.d.ts", "README.md", "LICENSE"],