@finbheara/archive-client 0.9.0 → 0.10.0

package/README.md

@@ -220,8 +220,9 @@ const r = await rel.dancers.resolve({
 });
 r.arm;         // "unique" | "ambiguous" | "none"
 r.candidates;  // [{ dancer_id, display, scope, score, evidence: { nameLevel, age, school, population, region }, prints, ... }]
-r.excluded;    // the candidates a contradiction set aside (why: "age" | "population" | "region")
-r.preferred;   // NON-BINDING: { dancer_id, why } where the school (else the region) singles one out; never moves arm
+r.excluded;    // the candidates a contradiction set aside (why: "age" | "population" | "region" | "school")
+r.preferred;   // NON-BINDING: { dancer_id, why } where the school (else the region, else recent rows) singles one out
+r.initials;    // an initials-only name with a school: { open, heldByDanceUp, refuted: [{ dancer_id, why, fact }], year }
 r.unlinked;    // rows printing a matched name that the release linked to no dancer
 
 await rel.dancers.search({ surname: "Quellan" });  // or { like: "a* quellan" }, or { name }
@@ -271,6 +272,28 @@ for a caller to weigh, and `arm` stays as counted. A `lineage` match ranks with
 each singles out neither. The `score` orders candidates and is no
 probability.
 
+AN INITIALS-ONLY NAME (`Butler, A`, every given field one letter) with a school the release
+resolves is narrowed by the evidence the question itself carries, where more than one candidate
+is left. A candidate is REFUTED only by a hard fact (`r.initials.refuted`, each with its `fact` in
+words):
+
+- `school`: every school row of the dancer up to the asked year reads to a school id (an id
+  followed through the redirects, a print read by `rel.schools`), and none of them is the asked
+  school or a school its line had joined by that year (lineage edges dated in or before the asked
+  year). A dancer with no school row, or a print no school reads, is unknown and never refuted. A
+  dancer that ever danced for the asked school's line is never refuted by the school.
+- `age`: the birth window misses the asked band even with one band's dance-up (`DANCE_UP_YEARS`
+  of `@finbheara/domain/age`: a dancer may enter the band one year older than the dancer's own). A
+  candidate the age set aside that the dance-up holds stays open (`r.initials.heldByDanceUp`).
+- `population`, `region`: the contradictions above.
+
+`r.initials.open` is every candidate no hard fact refutes. The arm is `unique` ONLY where exactly
+one candidate is open and the age did not set it aside: the candidates the school refuted then
+move to `excluded` (`why: "school"`). Otherwise the arm stays `ambiguous` with every candidate,
+and where the school and the region single out no one, `preferred` names the only open candidate
+with a row in the asked year or the year before. A full given name is never narrowed this way: two
+full given names that differ are two names, and the school only orders them.
+
 THE REGIONAL OIREACHTAS (`oireachtas: { region, year? }`). A dancer enters one
 residence-qualifying regional Oireachtas a year. Two regionals in one year are two dancers, the
 overseas entry excepted. The release already applies that rule to each dancer-year it publishes:

package/dist/chunks/{index-1sj5zr8k.js → index-hs72zekf.js}

@@ -67,7 +67,7 @@ function sha256OfDigest(digest) {
   return m === null ? null : m[1].toLowerCase();
 }
 
-import { Age } from "@finbheara/domain/age";
+import { Age, DANCE_UP_YEARS, birthYearsMeet } from "@finbheara/domain/age";
 import { createIndex, indexSchema, personEncoder } from "@finbheara/domain/noun-index";
 import domainPkg from "@finbheara/domain/package.json";
 import { dancerName } from "@finbheara/domain/person";
@@ -609,6 +609,21 @@ class MajorsFinder2 {
 }
 
 var LINEAGE_FILE = "school-lineage.jsonl";
+function schoolLine(lineage, ids, year) {
+  const reached = new Set(ids);
+  const todo = [...ids];
+  for (let id = todo.pop();id !== undefined; id = todo.pop())
+    for (const [o, y] of lineage.get(id) ?? [])
+      if (!reached.has(o) && (year === null || y === null || y <= year)) {
+        reached.add(o);
+        todo.push(o);
+      }
+  return reached;
+}
+function initialsOnly2(name) {
+  const g = name.givenFields();
+  return g.length > 0 && g.every((f) => f.length === 1);
+}
 function nameOrderOf(s) {
   return s === "surname-first" || s === "given-first" || s === "unknown" ? s : undefined;
 }
@@ -811,6 +826,7 @@ function idChunks(ids) {
 class DancerResolver2 {
   rel;
   printIds = new Map;
+  rowIds = new Map;
   lineageOf;
   regions;
   constructor(rel) {
@@ -822,15 +838,17 @@ class DancerResolver2 {
         return null;
       await this.rel.fetch(LINEAGE_FILE);
       const out = new Map;
-      const join = (a, b) => {
-        const s = out.get(a) ?? new Set;
-        s.add(b);
-        out.set(a, s);
+      const join = (a, b, year) => {
+        const m = out.get(a) ?? new Map;
+        const was = m.get(b);
+        m.set(b, was === undefined ? year : was === null || year === null ? null : Math.min(was, year));
+        out.set(a, m);
       };
       for (const r of readJsonl(this.rel.path(LINEAGE_FILE)))
         if (r.id !== r.other) {
-          join(r.id, r.other);
-          join(r.other, r.id);
+          const year = typeof r.year === "number" ? r.year : null;
+          join(r.id, r.other, year);
+          join(r.other, r.id, year);
         }
       return out;
     })();
@@ -952,15 +970,7 @@ class DancerResolver2 {
         school = { arm: s.arm, ids: schoolIds };
       else {
         const asked = new Set(schoolIds);
-        const reached = new Set(schoolIds);
-        const todo = [...schoolIds];
-        for (let id = todo.pop();id !== undefined; id = todo.pop())
-          for (const o of lineage.get(id) ?? [])
-            if (!reached.has(o)) {
-              reached.add(o);
-              todo.push(o);
-            }
-        lineageIds = [...reached].filter((id) => !asked.has(id)).sort();
+        lineageIds = [...schoolLine(lineage, schoolIds, null)].filter((id) => !asked.has(id)).sort();
         school = { arm: s.arm, ids: schoolIds, lineage: lineageIds };
       }
     }
@@ -1034,6 +1044,55 @@ class DancerResolver2 {
           return true;
         return false;
       });
+    const year = askedYear(q, asOf);
+    let initials;
+    if (narrow && kept.length > 1 && schoolIds !== null && schoolIds.length > 0 && initialsOnly2(dancerName(q.name, q.order === "unknown" ? undefined : q.order))) {
+      const lineage = await this.lineage();
+      const line = lineage === null ? new Set(schoolIds) : schoolLine(lineage, schoolIds, year);
+      const band = age?.age?.birthYears() ?? null;
+      const slack = q.age !== undefined && !("yob" in q.age) ? DANCE_UP_YEARS : 0;
+      const open = [];
+      const held = [];
+      const refuted = [];
+      const bySchool = new Set;
+      const schoolFact = async (c) => {
+        const fact = await this.schoolRefutes(schoolsOf(db, c.dancer_id), line, year, q.school);
+        if (fact === null)
+          return false;
+        refuted.push({ dancer_id: c.dancer_id, why: "school", fact });
+        bySchool.add(c.dancer_id);
+        return true;
+      };
+      for (const c of kept)
+        if (!await schoolFact(c))
+          open.push(c);
+      for (const x of excluded) {
+        const c = x.candidate;
+        const own = { from: c.birth.lo, to: c.birth.hi };
+        if (x.why === "age" && band !== null && slack > 0 && birthYearsMeet(band, own, slack)) {
+          if (!await schoolFact(c))
+            held.push(c.dancer_id);
+          continue;
+        }
+        refuted.push({
+          dancer_id: c.dancer_id,
+          why: x.why,
+          fact: contradictionFact(x, age, slack)
+        });
+      }
+      initials = {
+        open: [...open.map((c) => c.dancer_id), ...held],
+        heldByDanceUp: held,
+        refuted,
+        year
+      };
+      if (open.length === 1 && held.length === 0) {
+        for (const c of kept)
+          if (bySchool.has(c.dancer_id))
+            excluded.push({ candidate: c, why: "school" });
+        kept = open;
+      }
+    }
     let preferred;
     if (kept.length > 1 && school !== undefined)
       for (const rank of [SCHOOL_RANK.same, SCHOOL_RANK.moved]) {
@@ -1060,6 +1119,17 @@ class DancerResolver2 {
         };
       }
     }
+    if (preferred === undefined && kept.length > 1 && initials !== undefined) {
+      const openIds = new Set(initials.open);
+      const hit = kept.filter((c) => openIds.has(c.dancer_id) && c.year_hi !== null && c.year_hi >= year - 1);
+      if (hit.length === 1) {
+        const c = hit[0];
+        preferred = {
+          dancer_id: c.dancer_id,
+          why: `the only candidate no hard fact refutes with a row in ${year - 1} or ${year}`
+        };
+      }
+    }
     return {
       tag: this.rel.tag,
       asked: q,
@@ -1071,7 +1141,8 @@ class DancerResolver2 {
       ...age !== undefined ? { age: age.answer } : {},
       ...population !== undefined ? { population } : {},
       ...oireachtas !== undefined ? { oireachtas } : {},
-      ...school !== undefined ? { school } : {}
+      ...school !== undefined ? { school } : {},
+      ...initials !== undefined ? { initials } : {}
     };
   }
   async readOireachtas(db, o, asOf) {
@@ -1124,6 +1195,31 @@ class DancerResolver2 {
     }
     return joined ? "lineage" : earlier ? "moved" : "none";
   }
+  async schoolRefutes(schools, line, year, asked) {
+    const rows = schools.filter((s) => s.year_lo === null || s.year_lo <= year);
+    if (rows.length === 0)
+      return null;
+    const seen = new Set;
+    for (const s of rows) {
+      const own = await this.schoolIdsOf(s);
+      if (own.length === 0 || own.some((id) => line.has(id)))
+        return null;
+      for (const id of own)
+        seen.add(id);
+    }
+    const last = latestSchool(rows, year);
+    return `every school row to ${year} reads ${[...seen].sort().join(", ")} (the latest ${last?.school_id ?? last?.print} in ${last?.year_hi}), none of them ${asked ?? "the asked school"} or a school its line joined by ${year}`;
+  }
+  async schoolIdsOf(s) {
+    const key = s.school_id ?? s.print;
+    let read = this.rowIds.get(key);
+    if (read === undefined) {
+      const got = (await this.rel.schools.resolve(key)).candidates.map((c) => c.school_id);
+      read = s.school_id === null ? got : [...new Set([s.school_id, ...got])];
+      this.rowIds.set(key, read);
+    }
+    return read;
+  }
   readAge(a, asOf) {
     const done = (age, note) => {
       const read = age?.isAge() ? age : null;
@@ -1232,6 +1328,26 @@ function ageEvidence(d, asked) {
     return "overlaps";
   return "contradicts";
 }
+function askedYear(q, asOf) {
+  if (asOf !== null)
+    return asOf;
+  const a = q.age;
+  if (a !== undefined && !("yob" in a) && typeof a.year === "number")
+    return a.year;
+  return new Date().getFullYear();
+}
+function contradictionFact(x, age, slack) {
+  const c = x.candidate;
+  if (x.why === "age") {
+    const w = age?.answer.birth;
+    return `born ${c.birth.lo ?? "?"}-${c.birth.hi ?? "?"}, outside ${age?.answer.read ?? "the asked age"} (born ${w?.from ?? "any"}-${w?.to ?? "any"})${slack > 0 ? ` even with ${slack} year's dance-up` : ""}`;
+  }
+  if (x.why === "population")
+    return `published in the other population's majors solo competitions only (girls ${c.population.girls}, boys ${c.population.boys})`;
+  if (x.why === "region")
+    return `danced the ${c.region?.region} regional in ${c.region?.year}, another regional that year`;
+  return "set aside by the school";
+}
 
 import { Age as Age2 } from "@finbheara/domain/age";
 import {
@@ -3413,4 +3529,4 @@ function releases2(opts = {}) {
   return new ReleaseManager2(opts);
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, NO_CALENDAR2, FeisFinder2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, nameOrderOf, DancerResolver2, readPopulation2, canonicalOf2, CompResolver2, StaffFinder2, SchoolResolver2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };
+export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, NO_CALENDAR2, FeisFinder2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, canonicalOf2, CompResolver2, StaffFinder2, SchoolResolver2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   nameOrderOf,
   openRelease2,
   releases2
-} from "./chunks/index-1sj5zr8k.js";
+} from "./chunks/index-hs72zekf.js";
 import"./chunks/index-hne1wadw.js";
 import"./chunks/index-hghdy980.js";
 

package/dist/index.js

@@ -12,6 +12,7 @@ import {
   FEIS_LOCAL_ID_FLOOR2,
   ResultFinder2,
   MajorsFinder2,
+  initialsOnly2,
   DancerResolver2,
   readPopulation2,
   canonicalOf2,
@@ -45,7 +46,7 @@ import {
   openCached2,
   ReleaseManager2,
   releases2
-} from "./chunks/index-1sj5zr8k.js";
+} from "./chunks/index-hs72zekf.js";
 import {
   cacheRoot2,
   repoOf2
@@ -94,6 +95,7 @@ export {
   httpsRemote2 as httpsRemote,
   indexKey2 as indexKey,
   indexPath2 as indexPath,
+  initialsOnly2 as initialsOnly,
   isCurrent2 as isCurrent,
   listIndexes2 as listIndexes,
   nameLevel2 as nameLevel,

package/dist/types/dancers.d.ts

@@ -1,7 +1,9 @@
+import { type PersonName } from "@finbheara/names/normalize";
 import { type NameLevel } from "./dancers-names.js";
 import type { IndexBuilder } from "./indexes.js";
 import type { Release } from "./release.js";
 import { FEIS_LOCAL_ID_FLOOR } from "./results.js";
+export declare function initialsOnly(name: PersonName): boolean;
 export { FEIS_LOCAL_ID_FLOOR };
 export type NameOrderAsked = "surname-first" | "given-first" | "unknown";
 export type AgeAsked = {
@@ -80,7 +82,12 @@ export interface DancerRegion {
 }
 export interface ExcludedCandidate {
     candidate: DancerCandidate;
-    why: "age" | "population" | "region";
+    why: "age" | "population" | "region" | "school";
+}
+export interface InitialsRefuted {
+    dancer_id: number;
+    why: "school" | "age" | "population" | "region";
+    fact: string;
 }
 export interface DancerAnswer {
     tag: string;
@@ -121,6 +128,12 @@ export interface DancerAnswer {
         lineage?: string[];
     };
     refused?: string;
+    initials?: {
+        open: number[];
+        heldByDanceUp: number[];
+        refuted: InitialsRefuted[];
+        year: number;
+    };
 }
 export interface DancerSearchQuery extends Omit<DancerQuery, "name"> {
     name?: string;
@@ -184,6 +197,7 @@ export interface DancerYear {
 export declare class DancerResolver {
     private readonly rel;
     private readonly printIds;
+    private readonly rowIds;
     private lineageOf;
     private regions;
     constructor(rel: Release);
@@ -208,6 +222,8 @@ export declare class DancerResolver {
     private answer;
     private readOireachtas;
     private schoolEvidence;
+    private schoolRefutes;
+    private schoolIdsOf;
     private readAge;
 }
 export declare function readPopulation(asked: string): NonNullable<DancerAnswer["population"]>;

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 export { type AssetPlan, DATABASES, type DatabaseName, type LandedFile, type Receipt, type ReleaseManifest, planAsset, } from "./assets.js";
 export { sha256File, unzstdTo } from "./bytes.js";
-export { type AgeAsked, type AgeEvidence, type DancerAnswer, type DancerBulkRecord, type DancerCandidate, type DancerQuery, type DancerRecord, DancerResolver, type DancerRegion, type DancerSchool, type DancerSearchQuery, type DancerYear, type ExcludedCandidate, FEIS_LOCAL_ID_FLOOR, type OireachtasAsked, type PopulationEvidence, type RegionEvidence, type SchoolEvidence, readPopulation, } from "./dancers.js";
+export { type AgeAsked, type AgeEvidence, type DancerAnswer, type DancerBulkRecord, type DancerCandidate, type DancerQuery, type DancerRecord, DancerResolver, type DancerRegion, type DancerSchool, type DancerSearchQuery, type DancerYear, type ExcludedCandidate, FEIS_LOCAL_ID_FLOOR, type InitialsRefuted, initialsOnly, type OireachtasAsked, type PopulationEvidence, type RegionEvidence, type SchoolEvidence, readPopulation, } from "./dancers.js";
 export { NAME_LEVELS, type NameLevel, nameLevel } from "./dancers-names.js";
 export { type Comp, type CompAnswer, type CompDance, type CompKind, type CompQuery, CompResolver, type CompSource, type FeisPlace, type SyllabusAnswer, type SyllabusForAnswer, type SyllabusSource, type TitleCheck, canonicalOf, } from "./comps.js";
 export { type ClientOptions, cacheRoot, repoOf } from "./config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Open a versioned release of an Irish dance results archive: download, verify, decompress and cache it by tag, keep the cache, and resolve feises and schools against it",
 	"keywords": ["irish-dance", "results", "release", "cache", "sqlite"],
 	"license": "MIT",
@@ -45,7 +45,7 @@
 	},
 	"dependencies": {
 		"@finbheara/domain": "0.50.0",
-		"@finbheara/names": "0.23.0",
+		"@finbheara/names": "0.24.0",
 		"hyparquet": "1.31.2"
 	},
 	"devDependencies": {