@finbheara/archive-client 0.15.1 → 0.16.1

package/README.md

@@ -184,8 +184,8 @@ s.next;       // the next scheduled instance where the release knows one, else n
 ```
 
 A series is asked by any id of it (a feis, instance or brand id, a retired one followed), by a
-host code with or without its year (held codes `<stem><yy>` whose two digits are their own year),
-or by a name (a glob, or a plain word read as `*word*`). Two series answer `ambiguous` with both.
+host code with or without its year (held codes `<stem><yy>` whose two digits are their own year,
+never a host id of digits alone, which is a sequence number), or by a name (a glob, or a plain word read as `*word*`). Two series answer `ambiguous` with both.
 A release holds a feis-year once its results are captured and carries no calendar, so `next` is
 `null` today, with the reason.
 
@@ -212,6 +212,26 @@ rows were published under and their rows, so it agrees with each print lookup of
 
 Every answer carries the release tag it came from.
 
+### How two schools are linked
+
+```ts
+const l = await rel.schools.links("ostrel-academy", "wyvern-academy", { year: 2026 });
+l.arm;          // "self" | "linked" | "none"
+l.candidates;   // [{ hops, steps: [{ at, next, link: { from, to, shape, year }, flags }], flags, confidence }]
+
+const line = await rel.schools.line("ostrel-academy");
+line.candidates; // every school on its line, nearest first, each with its paths
+```
+
+The release's school lineage (a rename, an absorption, a merger, a split, or a `related` link of
+unknown type, each dated where a year is known) read by `@finbheara/domain/school-graph`: every
+simple path between two schools, each with its flags (`relatedHops`, `maxYearGap`, `datedAfter`,
+`undated`, `provisional`, `redirected` and the rest), never a yes or a no. Pass a `policy`, your
+reading over those flags, and the answer carries its verdict (`l.policy.passes`), exact however
+many paths are listed. A retired id is followed to the live one. The release publishes no decision
+behind an edge, so a path carries no `confidence` here. A release that publishes no lineage
+refuses both calls by name.
+
 ## Dancers
 
 ```ts
@@ -265,7 +285,9 @@ joins: every school reached through any number of edges, in either direction (th
 split are joined through their predecessor, the schools of a merger through their successor). An
 earlier row at a joined school alone is no match. `r.school.lineage` lists the ids joined to the
 asked ones. A release that publishes no lineage (feature `schools.lineage`) joins
-nothing and its answer carries no `lineage`, never refused.
+nothing and its answer carries no `lineage`, never refused. The line is read on the same school
+graph as `rel.schools.line` (`@finbheara/domain/school-graph`): untimed, every path, and as of a
+year, every path none of whose steps is dated after it (`LINE_AS_OF`).
 
 `population` is how the dancer's published majors population meets the asked one: `same`,
 `contradicts`, `both`, `unknown`, `unasked`. A dancer's population is read only from its rows at
@@ -562,7 +584,8 @@ held feis-year is still read from that feis-year's own competitions.
 A feis the release holds names itself, its year and its series. A series instance or brand id
 names the series. A feis id the release does not hold is placed in a series by its host code
 (`<token>:<stem><yy>` where the held codes of that stem carry their own year), and a stem two
-series share answers `ambiguous`. A held feis-year never falls back to an earlier year, and two
+series share answers `ambiguous`. A host id of digits alone (`qf:926`, `fw:1001`) is a sequence
+number and carries no stem: unheld, it is placed nowhere. A held feis-year never falls back to an earlier year, and two
 competitions printing one code are never folded into one.
 
 `kind` and `level` are read off the release's published rung (`feis_level`: 100 first feis to

package/dist/chunks/{index-9r4rw6xq.js → index-hbb1dnnh.js}

@@ -71,6 +71,7 @@ import { Age, DANCE_UP_YEARS, birthYearsMeet } from "@finbheara/domain/age";
 import { createIndex as createIndex2, indexSchema as indexSchema2, personEncoder } from "@finbheara/domain/noun-index";
 import domainPkg from "@finbheara/domain/package.json";
 import { dancerName } from "@finbheara/domain/person";
+import { schoolGraph as schoolGraph2 } from "@finbheara/domain/school-graph";
 import {
   compTitle,
   populationIn,
@@ -244,6 +245,8 @@ class FeisFinder2 {
     return { tag: this.rel.tag, feises, ...redirected !== undefined ? { redirected } : {} };
   }
   async codeStem(token, stem) {
+    if (/^\d+$/.test(stem))
+      return [];
     const db = await this.rel.indexDb("feises");
     const like = db.query("SELECT host_id, year, brand_id FROM feis WHERE token = ? AND host_id LIKE ? ESCAPE '\\' COLLATE NOCASE").all(token, `${stem.replace(/[\\%_]/g, (c) => `\\${c}`)}__`);
     const fits = like.filter((f) => {
@@ -632,6 +635,40 @@ class MajorsFinder2 {
   }
 }
 
+import {
+  schoolGraph
+} from "@finbheara/domain/school-graph";
+var LINEAGE_FILE2 = "school-lineage.jsonl";
+var REDIRECTS_FILE = "school-redirects.jsonl";
+function linksOfLineage2(lines) {
+  const seen = new Map;
+  for (const r of lines) {
+    if (r.id === r.other)
+      continue;
+    const [from, to] = r.direction === "succeeds" ? [r.other, r.id] : [r.id, r.other];
+    const year = typeof r.year === "number" ? r.year : null;
+    const k = `${from}\x00${to}\x00${r.shape}\x00${year}`;
+    const was = seen.get(k);
+    if (was === undefined)
+      seen.set(k, { from, to, shape: r.shape, year, provisional: r.provisional === true });
+    else if (r.provisional === true)
+      was.provisional = true;
+  }
+  return [...seen.values()];
+}
+async function releaseSchoolGraph2(rel) {
+  await rel.require("schools.lineage");
+  await rel.fetch(LINEAGE_FILE2);
+  const links = linksOfLineage2(readJsonl(rel.path(LINEAGE_FILE2)));
+  const redirects = new Map;
+  if (await rel.publishes(REDIRECTS_FILE)) {
+    await rel.fetch(REDIRECTS_FILE);
+    for (const r of readJsonl(rel.path(REDIRECTS_FILE)))
+      redirects.set(r.old_id, r.new_id);
+  }
+  return schoolGraph({ links, redirect: (id) => redirects.get(id) ?? null });
+}
+
 import { createIndex, indexSchema } from "@finbheara/domain/noun-index";
 import {
   DEFAULT_SCHOOL_NAME_READER,
@@ -697,9 +734,18 @@ var schoolsIndex = {
 
 class SchoolResolver2 {
   rel;
+  graph;
   constructor(rel) {
     this.rel = rel;
   }
+  async links(a, b, q = {}) {
+    this.graph ??= releaseSchoolGraph2(this.rel);
+    return { tag: this.rel.tag, ...(await this.graph).links(a.trim(), b.trim(), q) };
+  }
+  async line(a, q = {}) {
+    this.graph ??= releaseSchoolGraph2(this.rel);
+    return { tag: this.rel.tag, ...(await this.graph).line(a.trim(), q) };
+  }
   async resolve(asked, q = {}) {
     const db = await this.rel.indexDb("schools");
     const reg = db.query("SELECT display, regions, places, spanish FROM registry WHERE school_id = ?");
@@ -815,16 +861,12 @@ class SchoolResolver2 {
   }
 }
 
-var LINEAGE_FILE = "school-lineage.jsonl";
+var LINE_AS_OF = { name: "line-as-of", keep: (s) => !s.flags.datedAfter };
 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);
-      }
+  for (const id of ids)
+    for (const x of lineage.within(id, LINE_AS_OF, year))
+      reached.add(x);
   return reached;
 }
 function initialsOnly2(name) {
@@ -1051,21 +1093,10 @@ class DancerResolver2 {
     this.lineageOf ??= (async () => {
       if ((await this.rel.capability("schools.lineage")).state !== "full")
         return null;
-      await this.rel.fetch(LINEAGE_FILE);
-      const out = new Map;
-      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) {
-          const year = typeof r.year === "number" ? r.year : null;
-          join(r.id, r.other, year);
-          join(r.other, r.id, year);
-        }
-      return out;
+      await this.rel.fetch(LINEAGE_FILE2);
+      return schoolGraph2({
+        links: linksOfLineage2(readJsonl(this.rel.path(LINEAGE_FILE2)))
+      });
     })();
     return this.lineageOf;
   }
@@ -1888,7 +1919,7 @@ class CompResolver2 {
         return this.ofSeries(asked, only, y, "series");
     }
     const m = /^([^:]+):(.*?)(\d{2})$/.exec(asked);
-    if (m !== null) {
+    if (m !== null && !/^\d+$/.test(`${m[2]}${m[3]}`)) {
       const [, token, stem, yy] = m;
       const brands = await this.rel.feises.codeStem(token, stem);
       const y = year ?? 2000 + Number(yy);
@@ -3069,7 +3100,7 @@ var FEATURES2 = [
     feature: "schools.lineage",
     needs: ["school-lineage.jsonl"],
     since: 184,
-    calls: "the `lineage` school evidence of dancers.resolve and dancers.search: no school is joined by lineage, never refused, on a release without it"
+    calls: "schools.links and schools.line (refused on a release without it), and the `lineage` school evidence of dancers.resolve and dancers.search: no school is joined by lineage, never refused, on a release without it"
   },
   {
     feature: "results.stream",
@@ -3783,4 +3814,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, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, canonicalOf2, CompResolver2, StaffFinder2, 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, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, canonicalOf2, CompResolver2, StaffFinder2, 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-9r4rw6xq.js";
+} from "./chunks/index-hbb1dnnh.js";
 import"./chunks/index-hne1wadw.js";
 import"./chunks/index-hghdy980.js";
 

package/dist/index.js

@@ -12,6 +12,9 @@ import {
   FEIS_LOCAL_ID_FLOOR2,
   ResultFinder2,
   MajorsFinder2,
+  LINEAGE_FILE2,
+  linksOfLineage2,
+  releaseSchoolGraph2,
   readsSpanishNames2,
   SchoolResolver2,
   initialsOnly2,
@@ -47,7 +50,7 @@ import {
   openCached2,
   ReleaseManager2,
   releases2
-} from "./chunks/index-9r4rw6xq.js";
+} from "./chunks/index-hbb1dnnh.js";
 import {
   cacheRoot2,
   repoOf2
@@ -70,6 +73,7 @@ export {
   FEATURES2 as FEATURES,
   FEIS_LOCAL_ID_FLOOR2 as FEIS_LOCAL_ID_FLOOR,
   FeisFinder2 as FeisFinder,
+  LINEAGE_FILE2 as LINEAGE_FILE,
   MajorsFinder2 as MajorsFinder,
   NAME_LEVELS2 as NAME_LEVELS,
   NO_CALENDAR2 as NO_CALENDAR,
@@ -98,6 +102,7 @@ export {
   indexPath2 as indexPath,
   initialsOnly2 as initialsOnly,
   isCurrent2 as isCurrent,
+  linksOfLineage2 as linksOfLineage,
   listIndexes2 as listIndexes,
   nameLevel2 as nameLevel,
   needsRelease2 as needsRelease,
@@ -110,6 +115,7 @@ export {
   readPin2 as readPin,
   readPopulation2 as readPopulation,
   readsSpanishNames2 as readsSpanishNames,
+  releaseSchoolGraph2 as releaseSchoolGraph,
   releases2 as releases,
   renderArchiveTag2 as renderArchiveTag,
   repoOf2 as repoOf,

package/dist/types/dancers.d.ts

@@ -1,8 +1,12 @@
+import { type SchoolGraph, type StepPolicy } from "@finbheara/domain/school-graph";
 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 type Lineage = SchoolGraph;
+export declare const LINE_AS_OF: StepPolicy;
+export declare function schoolLine(lineage: Lineage, ids: readonly string[], year: number | null): Set<string>;
 export declare function initialsOnly(name: PersonName): boolean;
 export { FEIS_LOCAL_ID_FLOOR };
 export type NameOrderAsked = "surname-first" | "given-first" | "unknown";

package/dist/types/index.d.ts

@@ -14,6 +14,8 @@ export { type OpenOptions, Release, openCached, openRelease, resolveTag, } from
 export { type MajorCompetition, type MajorEvent, MajorsFinder, type ResultAnswer, ResultFinder, type ResultQuery, type ResultRow, } from "./results.js";
 export { type DancerAnswerLike, type DancerQueryLike, type DancerResolverLike, type DancerUnavailable, type RegistrationRow, type ResolvedDancer, RegistrationResolver, type ResolvedRegistration, dancerResolverOf, youngest, } from "./registrations.js";
 export { type SchoolAnswer, type SchoolCandidate, type SchoolQuery, SchoolResolver, type SchoolRung, readsSpanishNames, type SpanishNames, } from "./schools.js";
+export { LINEAGE_FILE, type SchoolLineAnswer, type SchoolLinksAnswer, linksOfLineage, releaseSchoolGraph, } from "./school-links.js";
+export type { LineCandidate, LinkPath, LinkPolicy, LinkQuery, LinkStep, PathFlags, SchoolLink, StepFlags, StepPolicy, } from "@finbheara/domain/school-graph";
 export { type Capability, FEATURES, type Feature, type SchemaProbe, capabilityOf, columnsOf, needsRelease, } from "./schema.js";
 export { type EntryRow, type StreamQuery, type StreamRow, type StreamScope, entryRank, } from "./stream.js";
 export { EventFinder, type EventYear, type EventYearQuery, type ResultRoster, type RosterMember, type RosterTeam, TeamFinder, type TeamResult, } from "./teams.js";

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

@@ -0,0 +1,20 @@
+import { type LineAnswer, type LinkAnswer, type LinkQuery, type SchoolGraph, type SchoolLink } from "@finbheara/domain/school-graph";
+import type { Release } from "./release.js";
+export declare const LINEAGE_FILE = "school-lineage.jsonl";
+export interface LineageLine {
+    id: string;
+    direction: "precedes" | "succeeds";
+    other: string;
+    shape: string;
+    year?: number | null;
+    provisional?: boolean;
+}
+export declare function linksOfLineage(lines: Iterable<LineageLine>): SchoolLink[];
+export declare function releaseSchoolGraph(rel: Release): Promise<SchoolGraph>;
+export type SchoolLinksAnswer = LinkAnswer & {
+    tag: string;
+};
+export type SchoolLineAnswer = LineAnswer & {
+    tag: string;
+};
+export type { LinkQuery };

package/dist/types/schools.d.ts

@@ -1,6 +1,7 @@
 import { type SchoolNameParser } from "@finbheara/domain/school";
 import type { IndexBuilder } from "./indexes.js";
 import type { Release } from "./release.js";
+import { type LinkQuery, type SchoolLineAnswer, type SchoolLinksAnswer } from "./school-links.js";
 export type SchoolRung = "id" | "redirect" | "print" | "sn3" | "realWords";
 export interface SchoolCandidate {
     school_id: string;
@@ -52,6 +53,9 @@ export declare const GENERIC_SCHOOL_READER: SchoolReaderChoice;
 export declare const schoolsIndex: IndexBuilder;
 export declare class SchoolResolver {
     private readonly rel;
+    private graph;
     constructor(rel: Release);
+    links(a: string, b: string, q?: LinkQuery): Promise<SchoolLinksAnswer>;
+    line(a: string, q?: LinkQuery): Promise<SchoolLineAnswer>;
     resolve(asked: string, q?: SchoolQuery): Promise<SchoolAnswer>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.15.1",
+	"version": "0.16.1",
 	"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",
@@ -44,8 +44,8 @@
 		"prepublishOnly": "bun scripts/build.ts && bun ../../tools/checks/archive-client-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/domain": "0.54.1",
-		"@finbheara/names": "0.27.1",
+		"@finbheara/domain": "0.56.0",
+		"@finbheara/names": "0.28.0",
 		"hyparquet": "1.31.2"
 	},
 	"devDependencies": {