@finbheara/archive-client 0.1.2 → 0.3.0

package/README.md

@@ -20,7 +20,7 @@ type declarations (`.d.ts`), so a TypeScript project needs Bun's types (`"types"
 `bunx idq <verb>`.
 
 The version is 0.x while the API settles: a minor bump may break, so pin a minor
-(`"@finbheara/archive-client": "0.1.x"`).
+(`"@finbheara/archive-client": "0.2.x"`).
 
 ## Configuration
 
@@ -67,6 +67,25 @@ rel.path("school-registry.jsonl");                                   // its cach
 rel.close();
 ```
 
+An older release that lacks what a call reads (a column, a table or a side file a newer release
+added) is REFUSED BY NAME, never read in part: the call throws, naming the feature, what the
+release lacks and the first cut that publishes it. What a release carries is read from its own
+schema and assets, never from its tag:
+
+```ts
+const c = await rel.capabilities();
+c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...], since: 260, calls }]
+```
+
+| feature | the calls | from cut |
+| --- | --- | --- |
+| `results.level` | `results.query`, `majors.results` | 215 |
+| `dancers` | `dancers.resolve`, `search`, `get` | 260 |
+| `schools` | `schools.resolve`, a dancer question with a school | 260 |
+| `staff` | `staff.teacher`, `staff.adjudicator` | 260 |
+| `majors.order` | `majors.competitions` | 260 |
+| `feises`, `comps` | `feises.find`, `feises.series`, `comps.*`, `registrations.resolve` | 265 |
+
 A spec is `pinned` (the default: the user-local pin, else the latest), `latest`, a cut number
 (`42`, or `42.1` for a fraction) or a tag (`archive-YYYY.MM.DD-N`).
 
@@ -182,10 +201,11 @@ const r = await rel.dancers.resolve({
   school: "Ardvarna Academy",                      // a print or an id, through rel.schools
   age: { band: "U10", year: 2026 },                // or { yob: 2016 }, or { comp: "<competition>" }
   asOf: "2026-10-17",                              // the school as of then
+  population: "girls",                             // or "boys": only a contradiction excludes
 });
 r.arm;         // "unique" | "ambiguous" | "none"
 r.candidates;  // [{ dancer_id, display, scope, score, evidence: { nameLevel, age, school }, prints, ... }]
-r.excluded;    // the candidates an age contradiction set aside (why: "age")
+r.excluded;    // the candidates a contradiction set aside (why: "age" | "population")
 r.preferred;   // NON-BINDING: { dancer_id, why } where the school singles one out; never moves arm
 r.unlinked;    // rows printing a matched name that the release linked to no dancer
 
@@ -202,8 +222,21 @@ meets the asked age (`Age.fitsIn`, `overlaps`): `fits`, `overlaps`, `contradicts
 `school` is how the dancer's schools meet the asked one: `same` (the latest school as of `asOf`),
 `moved` (an earlier one), `none`, `unresolved` (the print reached no school).
 
+`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
+the majors (tiers T1 to T3) in competitions whose published `gender` reads girls or boys
+(`@finbheara/domain`'s `populationIn`), whatever the competition's category (a solo championship
+often publishes none), counted on the candidate (`population: { girls, boys }`). The results hold
+individual dancers' rows only (a team is published apart), so every such row is a solo row. A feis
+competition is no evidence either way (below open a feis runs its competitions mixed and may merge
+its few boys into the girls' group), and a mixed competition reads `mixed`.
+
 NO SILENT GUESS. Only a contradiction sets a candidate aside: a birth window that shares no birth
-year with the asked age (listed in `excluded`). The school is evidence and order, never a reason
+year with the asked age, or a dancer the release publishes in the other population's gendered
+majors solo competitions and in none of the asked one's (listed in `excluded`, `why: "age"` or
+`"population"`, and a candidate contradicting both says `age`). A dancer published in both, or in
+neither, stays. A population word that names no one population (`mixed`) narrows nothing, and the
+answer says so (`r.population.note`). The school is evidence and order, never a reason
 to drop anyone: candidates whose latest school is the asked one come first, then those that ever
 danced for it, then the rest. A school row meets the asked school by its id, else by its print
 (one `rel.schools` resolves to the asked ids), so a latest print the release
@@ -216,6 +249,10 @@ A FEIS-LOCAL ID (`FEIS_LOCAL_ID_FLOOR`, 2^34, and up) is valid in its release on
 carrying one say `scope: "per-release"` (`dancer_scope` on a row), so a caller never stores one
 across releases. Every answer carries the release tag.
 
+A MAJORS ID (under the floor) is kept across releases on a best-effort basis only: a merge
+retires one, a split mints one, and a renumbered source page can hand one to another dancer. A
+caller that joins ids across releases checks the name and the rows it expects.
+
 ## Results and the majors
 
 ```ts
@@ -251,6 +288,8 @@ c.source;     // "syllabus" | "prior-year" | "title"
 c.kind;       // "championship" | "grade" | "unrated"
 c.level;      // "OC" (FF, BG, AB, NV, PW, PC, OC), c.feis_level 700
 c.age;        // "U10", c.population "mixed", c.canonical "710OC", c.title, c.competition
+c.age_source; // "printed" | "title" | "code" | "merged" | null, c.age_printed "U10" as printed
+c.second;     // true for a second chance or a supplementary comp beside the main one
 c.from;       // { feis_ids: ["fweb:ABC25"], year: 2025 } where an earlier year answered
 c.check;      // "unchecked", or what the caller's `title` says about the earlier comp
 c.syllabus_source;  // "results": what the syllabus the answer read is read from
@@ -293,6 +332,21 @@ QuickFeis numbers its own and-over championships (`15 & over` prelim `616PC`, `1
 `719OC`). An and-over code is then the same string as an `Under N + 1` one, and `age` (`O18`)
 tells them apart. An adult band, a range and a grade render none.
 
+`age` is the release's reading, and `age_source` says where it was read. A `merged` comp (a
+platform's comps merged into one, `710OCM` with no `710OC` beside it) prints one member's band,
+so its `age` is the union of its members' (`U12` for `710OCM - U10 Open Champion` where the next
+open the feis prints is `713OCM`), and `age_printed` keeps the platform's own field (`U10`). A
+joined code at the bottom of its series stays open below (`710OC/711OC` with no open under 10
+beside it is `U11/11yr`, every age under 11), as a younger dancer dances up into it.
+
+`population` is the sex the release states, else a population word in the title, else the
+code's sex suffix read with every code its feis printed (`codePopulation` from
+`@finbheara/domain/title`: `720OCB` beside `720OCG` is boys and girls, `512M` beside `512` is
+boys, a lone `713OCM` says nothing), else the release's `mixed` for a grade or a preliminary
+championship. `second` is read from the words of the title and the platform's level and dance
+fields (`secondIn`: `2nd Chance`, `2nd Chc`, `Second Chance`, `Supplementary Prelim`, `2nd Open
+Champ`), and never from a code's digit, which marks a round's half at some hosts (`610PC2H`).
+
 ## Registrations
 
 ```ts
@@ -301,10 +355,13 @@ const rows = await rel.registrations.resolve([
 ]);
 rows[0].comps;    // one competition answer per code
 rows[0].age;      // { band: "U10", year: 2026, code: "610", from: "comp" }: the band the dancer is asked at
+rows[0].population; // { asked: "girls", from: "comp", codes: ["610"] }: who the dancer is asked as
 rows[0].dancer;   // the dancer resolver's answer
 ```
 
-Each code is resolved as above. The dancer is asked at the YOUNGEST band the row's competitions
+Each code is resolved as above. The dancer is asked at the row's own `population` where it gives
+one, else at the one population its unique comps read (`from: "comp"`, with the codes). Comps
+reading both populations give none, with the reason. The dancer is asked at the YOUNGEST band the row's competitions
 read (the lowest ceiling, then the highest floor): a dancer may dance up into an older band and
 never down, so the youngest bounds the dancer. Every band a row read is listed (`bands`) where
 there are several. Where no comp answers with a band (a syllabus read from results that lacks the
@@ -323,6 +380,7 @@ and the competitions still resolve.
     idq add <dir> --tag <tag>
     idq index [--release <spec>] [<name>...] [--force]
     idq verify [--release <spec>]
+    idq capabilities [--release <spec>]
     idq prune [--keep N] [--dry-run]
     idq rm <tag> [--dry-run]
     idq drop-indexes [<tag>] [--dry-run]
@@ -331,7 +389,8 @@ and the competitions still resolve.
     idq school [--release <spec>] <print|school_id> [--region <code>]
     idq dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>
                [--order surname-first|given-first] [--school <print|id>]
-               [--yob <y> | --band <band> [--year <y>] | --comp <competition>] [--as-of <date>] [--rows]
+               [--yob <y> | --band <band> [--year <y>] | --comp <competition>] [--as-of <date>]
+               [--population girls|boys] [--rows]
     idq results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <c>] [--school <s>] [--year <y>] [--limit <n>]
     idq majors [--release <spec>] [--event <e>] [--year <y>] [--comp <c>] [--dancer <id>] [--rows]
     idq teacher [--release <spec>] <name|TD number>
@@ -348,7 +407,7 @@ and the competitions still resolve.
 
 `resolve` speaks JSON lines: one answer per line out, and with no positional question the
 questions are JSON lines on stdin, one per line (`{feis, code, year?, title?}`,
-`{name, school?, age?}`, `{name, school?, codes, feis, year?}`). A line that is no JSON object,
+`{name, school?, age?, population?}`, `{name, school?, codes, feis, year?, population?}`). A line that is no JSON object,
 or no question of its kind, answers `{tag, line, error}` and the other lines still answer. The
 exit is non-zero where any line erred. A dancer's age may be given as a comp
 (`{"comp": "<feis>/<code>"}`, or `--comp` on the command line): `rel.registrations.dancer` reads

package/dist/chunks/{index-zr8tfjk0.js → index-kp811fb0.js}

@@ -71,6 +71,7 @@ import { Age } 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";
+import { populationIn, populationRelation } from "@finbheara/domain/title";
 import {
   foldNameKey,
   surnameBlock
@@ -160,6 +161,7 @@ class ResultFinder2 {
   }
   async query(q) {
     await this.rel.fetch("results");
+    await this.rel.require("results.level");
     return queryResults(this.rel, "results", q);
   }
 }
@@ -188,6 +190,7 @@ class MajorsFinder2 {
   }
   async competitions(q) {
     const db = await this.db();
+    await this.rel.require("majors.order");
     const args = [q.event];
     let year = "";
     if (q.year !== undefined) {
@@ -207,6 +210,7 @@ class MajorsFinder2 {
   }
   async results(q) {
     await this.db();
+    await this.rel.require("results.level");
     return queryResults(this.rel, "majors", q);
   }
 }
@@ -223,7 +227,7 @@ var PERSON = { table: "person", value: "id", valueType: "INTEGER PRIMARY KEY" };
 var ASKED = ["surname_key", "nn4", "blk_surname"];
 var dancersIndex = {
   name: "dancers",
-  version: "1",
+  version: "2",
   inputs: ["results"],
   keyParts: () => [...PACKAGE_KEY_PARTS],
   says: "every published dancer print at the names package's keys, its dancers, schools and years",
@@ -233,6 +237,7 @@ var dancersIndex = {
     out.run("CREATE TABLE print_dancer(person INTEGER NOT NULL, dancer_id INTEGER, rows INTEGER NOT NULL, year_lo INTEGER, year_hi INTEGER)");
     out.run("CREATE TABLE dancer(dancer_id INTEGER PRIMARY KEY, display TEXT NOT NULL, names_printed TEXT NOT NULL, genders TEXT NOT NULL, appearances INTEGER NOT NULL, kind TEXT, birth_lo INTEGER, birth_hi INTEGER, birth_source TEXT NOT NULL, birth_conflict INTEGER NOT NULL, rows INTEGER NOT NULL, year_lo INTEGER, year_hi INTEGER)");
     out.run("CREATE TABLE dancer_school(dancer_id INTEGER NOT NULL, school_id TEXT, print TEXT NOT NULL, rows INTEGER NOT NULL, year_lo INTEGER, year_hi INTEGER)");
+    out.run("CREATE TABLE dancer_population(dancer_id INTEGER NOT NULL, population TEXT NOT NULL, rows INTEGER NOT NULL, PRIMARY KEY(dancer_id, population)) WITHOUT ROWID");
     const src = rel.db("results");
     const groups = src.query(`SELECT r.name_printed AS p, r.name_order_resolved AS o, r.dancer_id AS d,
 				        r.school_printed AS sp, r.school_id AS s,
@@ -298,6 +303,15 @@ var dancersIndex = {
       const t = dt.get(d.dancer_id);
       putD.run(d.dancer_id, d.display, d.names_printed, d.genders, d.appearances, d.scope, d.birth_lo, d.birth_hi, d.birth_source, d.birth_conflict, t?.rows ?? 0, t?.lo ?? null, t?.hi ?? null);
     }
+    const putPop = out.prepare("INSERT INTO dancer_population VALUES (?, ?, ?) ON CONFLICT(dancer_id, population) DO UPDATE SET rows = rows + excluded.rows");
+    for (const r of src.query(`SELECT r.dancer_id AS d, c.gender AS g, count(*) AS n
+				 FROM results r JOIN competitions c ON c.file = r.file AND c.line = r.competition_line
+				 WHERE r.dancer_id IS NOT NULL AND c.tier IN ('T1', 'T2', 'T3') AND c.gender IS NOT NULL
+				 GROUP BY 1, 2`).all()) {
+      const pop = populationIn(r.g);
+      if (pop === "girls" || pop === "boys")
+        putPop.run(r.d, pop, r.n);
+    }
     for (const s of schema.indexes)
       if (ASKED.some((c) => s.endsWith(`(${c})`)))
         out.run(s);
@@ -337,6 +351,13 @@ var SCHOOL_RANK = {
   unresolved: 2,
   unasked: 2
 };
+var POPULATION_WEIGHT = {
+  same: 1,
+  both: 0,
+  unknown: 0,
+  unasked: 0,
+  contradicts: -10
+};
 var SCHOOL_WEIGHT = {
   same: 2,
   moved: 1,
@@ -418,6 +439,7 @@ class DancerResolver2 {
       year_lo: d.year_lo,
       year_hi: d.year_hi,
       birth: birthOf(d),
+      population: populationOf(db, dancerId),
       prints,
       schools: schoolsOf(db, dancerId)
     };
@@ -425,6 +447,7 @@ class DancerResolver2 {
   async answer(db, q, hits, narrow = true) {
     const asOf = yearOf(q.asOf);
     const age = q.age === undefined ? undefined : this.readAge(q.age, asOf);
+    const population = q.population === undefined ? undefined : readPopulation2(q.population);
     let schoolIds = null;
     let school;
     if (q.school !== undefined) {
@@ -455,19 +478,22 @@ class DancerResolver2 {
       const schools = schoolsOf(db, id);
       const latest = latestSchool(schools, asOf);
       const ageEv = ageEvidence(d, age?.age ?? null);
+      const pop = populationOf(db, id);
+      const popEv = populationEvidence(pop, population?.read ?? null);
       const schoolEv = schoolIds === null ? "unasked" : schoolIds.length === 0 ? "unresolved" : await this.schoolEvidence(schools, schoolIds, asOf);
       all.push({
         dancer_id: id,
         display: d.display,
         scope: id >= FEIS_LOCAL_ID_FLOOR2 ? "per-release" : "stable",
         kind: d.kind,
-        score: NAME_WEIGHT[e.level] + AGE_WEIGHT[ageEv] + SCHOOL_WEIGHT[schoolEv],
-        evidence: { nameLevel: e.level, age: ageEv, school: schoolEv },
+        score: NAME_WEIGHT[e.level] + AGE_WEIGHT[ageEv] + SCHOOL_WEIGHT[schoolEv] + POPULATION_WEIGHT[popEv],
+        evidence: { nameLevel: e.level, age: ageEv, school: schoolEv, population: popEv },
         prints: e.prints.sort((a, b) => b.rows - a.rows || (a.print < b.print ? -1 : 1)),
         rows: d.rows,
         year_lo: d.year_lo,
         year_hi: d.year_hi,
         birth: birthOf(d),
+        population: pop,
         school: latest
       });
     }
@@ -476,9 +502,12 @@ class DancerResolver2 {
     let kept = all;
     if (narrow)
       kept = all.filter((c) => {
-        if (c.evidence.age !== "contradicts")
+        if (c.evidence.age === "contradicts")
+          excluded.push({ candidate: c, why: "age" });
+        else if (c.evidence.population === "contradicts")
+          excluded.push({ candidate: c, why: "population" });
+        else
           return true;
-        excluded.push({ candidate: c, why: "age" });
         return false;
       });
     let preferred;
@@ -503,6 +532,7 @@ class DancerResolver2 {
       ...preferred !== undefined ? { preferred } : {},
       unlinked: [...unlinked].map(([print, rows]) => ({ print, rows })).sort((a, b) => b.rows - a.rows || (a.print < b.print ? -1 : 1)),
       ...age !== undefined ? { age: age.answer } : {},
+      ...population !== undefined ? { population } : {},
       ...school !== undefined ? { school } : {}
     };
   }
@@ -580,6 +610,34 @@ function latestSchool(schools, asOf) {
   }
   return best;
 }
+function populationOf(db, dancerId) {
+  const out = { girls: 0, boys: 0 };
+  for (const r of db.query("SELECT population, rows FROM dancer_population WHERE dancer_id = ?").all(dancerId))
+    if (r.population === "girls" || r.population === "boys")
+      out[r.population] = r.rows;
+  return out;
+}
+function readPopulation2(asked) {
+  const w = asked.trim().toLowerCase();
+  const read = w === "girls" || w === "boys" ? w : populationIn(w);
+  if (read === "girls" || read === "boys")
+    return { asked, read };
+  return {
+    asked,
+    read: null,
+    note: read === "mixed" ? `"${asked}" reads as mixed: it names no one population, so it narrows nothing` : `"${asked}" reads as no population (girls or boys): it narrows nothing`
+  };
+}
+function populationEvidence(own, asked) {
+  if (asked === null)
+    return "unasked";
+  if (own.girls > 0 && own.boys > 0)
+    return "both";
+  const mine = own.girls > 0 ? "girls" : own.boys > 0 ? "boys" : "";
+  if (mine === "")
+    return "unknown";
+  return populationRelation(asked, mine) === "disjoint" ? "contradicts" : "same";
+}
 function ageEvidence(d, asked) {
   if (asked === null)
     return "unasked";
@@ -597,9 +655,11 @@ function ageEvidence(d, asked) {
 
 import { Age as Age2 } from "@finbheara/domain/age";
 import {
+  codePopulation,
   compTitle,
   matchTitle,
-  populationIn,
+  populationIn as populationIn2,
+  secondIn,
   titleRelation
 } from "@finbheara/domain/title";
 var LEVEL = Object.freeze({
@@ -616,17 +676,25 @@ CREATE TABLE comp(
   competition TEXT PRIMARY KEY, feis_id TEXT NOT NULL, brand_id TEXT, year INTEGER,
   code TEXT NOT NULL, code_fold TEXT NOT NULL, title TEXT, age TEXT, gender TEXT,
   feis_level INTEGER, round TEXT, platform TEXT NOT NULL, captures INTEGER NOT NULL,
-  file TEXT NOT NULL, line INTEGER NOT NULL
+  file TEXT NOT NULL, line INTEGER NOT NULL, age_source TEXT, age_printed TEXT,
+  gender_source TEXT, level_printed TEXT, dance_printed TEXT
 );
 `;
 var INDEXES = [
   "CREATE INDEX comp_feis_code ON comp(feis_id, code_fold)",
   "CREATE INDEX comp_brand_year ON comp(brand_id, year)"
 ];
+var OPTIONAL = [
+  "age_source",
+  "age_printed",
+  "gender_source",
+  "level_printed",
+  "dance_printed"
+];
 var fold = (code) => code.trim().toLowerCase();
 var compsIndex = {
   name: "comps",
-  version: "1",
+  version: "2",
   inputs: ["results"],
   says: "every competition by its feis and its own code, with its series and year",
   build(rel, out) {
@@ -639,19 +707,23 @@ var compsIndex = {
     const captures = new Map;
     for (const r of src.query("SELECT competition, count(*) AS n FROM competitions GROUP BY competition").all())
       captures.set(r.competition, r.n);
-    const put = out.prepare("INSERT OR IGNORE INTO comp VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
-    for (const c of src.query("SELECT competition, event, year, comp_no, title, age, gender, feis_level, round, source, file, line FROM competitions WHERE comp_no IS NOT NULL AND trim(comp_no) != '' ORDER BY file, line").iterate()) {
+    const put = out.prepare("INSERT OR IGNORE INTO comp VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const has = new Set(src.query("PRAGMA table_info(competitions)").all().map((r) => r.name));
+    const opt = (col) => has.has(col) ? col : `NULL AS ${col}`;
+    for (const c of src.query(`SELECT competition, event, year, comp_no, title, age, gender, feis_level, round, source, file, line, ${OPTIONAL.map(opt).join(", ")} FROM competitions WHERE comp_no IS NOT NULL AND trim(comp_no) != '' ORDER BY file, line`).iterate()) {
       const f = brand.get(c.event);
-      put.run(c.competition, c.event, f?.brand ?? null, c.year ?? f?.year ?? null, c.comp_no.trim(), fold(c.comp_no), c.title, c.age, c.gender, c.feis_level, c.round, c.source, captures.get(c.competition) ?? 1, c.file, c.line);
+      put.run(c.competition, c.event, f?.brand ?? null, c.year ?? f?.year ?? null, c.comp_no.trim(), fold(c.comp_no), c.title, c.age, c.gender, c.feis_level, c.round, c.source, captures.get(c.competition) ?? 1, c.file, c.line, c.age_source, c.age_printed, c.gender_source, c.level_printed, c.dance_printed);
     }
     for (const s of INDEXES)
       out.run(s);
   }
 };
-function compOf(r) {
+function compOf(r, codes = []) {
   const lv = r.feis_level;
   const kind = lv === null ? "unrated" : lv >= 600 ? "championship" : "grade";
-  const pop = populationIn(r.gender ?? "") || populationIn(r.title ?? "");
+  const stated = r.gender_source === "level" ? "" : populationIn2(r.gender ?? "");
+  const pop = stated || populationIn2(r.title ?? "") || (r.platform === "ifeis" && codes.length > 0 ? codePopulation(r.code, codes) : "") || populationIn2(r.gender ?? "");
+  const second = [r.title, r.level_printed, r.dance_printed].some((t) => t != null && secondIn(t));
   const round = r.round ?? (r.title === null ? null : compTitle(r.title).round?.toString() ?? null);
   return {
     competition: r.competition,
@@ -663,7 +735,10 @@ function compOf(r) {
     feis_level: lv,
     level: lv === null ? null : LEVEL[lv] ?? null,
     age: r.age,
+    age_source: r.age_source ?? null,
+    age_printed: r.age_printed ?? null,
     population: pop === "" ? null : pop,
+    second,
     round,
     canonical: canonicalOf2(lv, r.age),
     platform: r.platform,
@@ -770,7 +845,12 @@ class CompResolver2 {
     const marks = feisIds.map(() => "?").join(", ");
     const sql = `SELECT * FROM comp WHERE feis_id IN (${marks})${code !== undefined ? " AND code_fold = ?" : ""} ORDER BY file, line`;
     const args = code !== undefined ? [...feisIds, fold(code)] : [...feisIds];
-    return db.query(sql).all(...args).map(compOf);
+    const rows = db.query(sql).all(...args);
+    const all = code === undefined ? rows : db.query(`SELECT feis_id, code FROM comp WHERE feis_id IN (${marks})`).all(...feisIds);
+    const codes = new Map;
+    for (const r of all)
+      codes.set(r.feis_id, [...codes.get(r.feis_id) ?? [], r.code]);
+    return rows.map((r) => compOf(r, codes.get(r.feis_id) ?? []));
   }
   async idsOf(brand, year) {
     return (await this.ofSeries("", brand, year, "series")).feis_ids;
@@ -1724,13 +1804,31 @@ class RegistrationResolver2 {
         from: "comp"
       } : byTitle !== undefined ? { band: byTitle.age, year: byTitle.year, code: byTitle.code, from: "title" } : null;
       const bands = [...new Set((first !== undefined ? read : printed).map((c) => c.age))];
+      let population = null;
+      if (row.population !== undefined)
+        population = { asked: row.population, from: "row" };
+      else {
+        const gendered = comps.flatMap((c, i) => c.arm === "unique" && (c.population === "girls" || c.population === "boys") ? [{ pop: c.population, code: row.codes[i] }] : []);
+        const pops = [...new Set(gendered.map((g) => g.pop))];
+        if (pops.length === 1)
+          population = {
+            asked: pops[0],
+            from: "comp",
+            codes: gendered.map((g) => g.code)
+          };
+        else if (pops.length > 1)
+          population = {
+            why: `the row's comps read both populations (${gendered.map((g) => `${g.code}: ${g.pop}`).join(", ")}): none asked`
+          };
+      }
       const order = nameOrderOf(row.order);
       const asked = {
         name: row.name,
         ...order !== undefined ? { order } : {},
         ...row.school !== undefined ? { school: row.school } : {},
         ...age !== null ? { age: { band: age.band, year: age.year } } : {},
-        ...row.asOf !== undefined ? { asOf: row.asOf } : {}
+        ...row.asOf !== undefined ? { asOf: row.asOf } : {},
+        ...population !== null && "asked" in population ? { population: population.asked } : {}
       };
       const { dancer } = await this.dancer(asked);
       out.push({
@@ -1739,6 +1837,7 @@ class RegistrationResolver2 {
         comps,
         age,
         ...bands.length > 1 ? { bands } : {},
+        population,
         dancer,
         asked
       });
@@ -1903,6 +2002,88 @@ function defaultRemote() {
   return installed ?? fallbackRemote2(ghRemote2, httpsRemote2());
 }
 
+function columnsOf2(db, table) {
+  return new Set(db.query("SELECT name FROM pragma_table_info(?)").all(table).map((r) => r.name));
+}
+var FEATURES2 = [
+  {
+    feature: "results.level",
+    needs: ["results:competitions.feis_level"],
+    since: 215,
+    calls: "results.query, majors.results"
+  },
+  {
+    feature: "majors.order",
+    needs: ["majors:competitions.seq"],
+    since: 260,
+    calls: "majors.competitions"
+  },
+  {
+    feature: "dancers",
+    needs: ["results:results.name_order_resolved"],
+    since: 260,
+    calls: "dancers.resolve, dancers.search, dancers.get (the dancers index)"
+  },
+  {
+    feature: "schools",
+    needs: ["school-registry.jsonl", "school-redirects.jsonl"],
+    since: 260,
+    calls: "schools.resolve, a dancer question with a school (the schools index)"
+  },
+  {
+    feature: "feises",
+    needs: [
+      "results:feises.date_lo",
+      "results:feises.date_hi",
+      "results:feises.feis_instance_id",
+      "results:feises.feis_brand_id",
+      "results:competitions.feis_region",
+      "feis-redirects.jsonl"
+    ],
+    since: 265,
+    calls: "feises.find, feises.series, and comps and registrations through them (the feises index)"
+  },
+  {
+    feature: "comps",
+    needs: [
+      "results:competitions.feis_level",
+      "results:competitions.round",
+      "results:feises.feis_brand_id"
+    ],
+    since: 265,
+    calls: "comps.resolve, comps.syllabus, comps.syllabusFor, registrations.resolve (the comps index)"
+  },
+  {
+    feature: "staff",
+    needs: [
+      "results:adjudicators",
+      "results:feis_panels",
+      "school-staff.jsonl",
+      "school-teachers.jsonl",
+      "school-registry.jsonl"
+    ],
+    since: 260,
+    calls: "staff.teacher, staff.adjudicator (the staff index)"
+  }
+];
+async function hasNeed(probe, n) {
+  const m = /^(results|majors):([A-Za-z_]+)(?:\.([A-Za-z_]+))?$/.exec(n);
+  if (m === null)
+    return probe.publishes(n);
+  const cols = columnsOf2(await probe.db(m[1]), m[2]);
+  return m[3] === undefined ? cols.size > 0 : cols.has(m[3]);
+}
+async function capabilityOf2(probe, f) {
+  const missing = [];
+  for (const n of f.needs)
+    if (!await hasNeed(probe, n))
+      missing.push(n);
+  return { ...f, state: missing.length === 0 ? "full" : "missing", missing };
+}
+function needsRelease2(tag, c) {
+  return new Error(`archive-client: ${tag} is too old for ${c.feature} (${c.calls}): it lacks ${c.missing.join(", ")}. Open a release of cut ${c.since} or later`);
+}
+
 function tagDir(root, tag) {
   if (parseArchiveTag2(tag) === null)
     throw new Error(`archive-client: "${tag}" is not a release tag (archive-YYYY.MM.DD[-N[.k]])`);
@@ -1999,9 +2180,62 @@ class Release2 {
       out.push(await this.fetchOne(a));
     return out;
   }
+  async publishes(asset) {
+    const plan = this.plan(asset);
+    const r = this.receipt();
+    if (r.files[plan.local] !== undefined)
+      return true;
+    if (r.source.startsWith("local:"))
+      return this.has(asset);
+    if (r.published !== undefined)
+      return r.published.some((n) => plan.published.includes(n));
+    let listed;
+    try {
+      listed = await this.listed();
+    } catch (e) {
+      throw new Error(`archive-client: cannot tell whether ${this.tag} publishes ${asset}: its cache records no asset listing and the host did not answer (${String(e)}). Open it once with the network`);
+    }
+    return listed.some((a) => plan.published.includes(a.name));
+  }
+  probe = {
+    db: async (name) => {
+      await this.fetch(name);
+      return this.db(name);
+    },
+    publishes: (asset) => this.publishes(asset)
+  };
+  checked = new Map;
+  async capability(feature) {
+    let c = this.checked.get(feature);
+    if (c === undefined) {
+      const f = FEATURES2.find((x) => x.feature === feature);
+      if (f === undefined)
+        throw new Error(`archive-client: no feature "${feature}"`);
+      c = await capabilityOf2(this.probe, f);
+      this.checked.set(feature, c);
+    }
+    return c;
+  }
+  async capabilities() {
+    const features = [];
+    for (const f of FEATURES2)
+      features.push(await this.capability(f.feature));
+    return { tag: this.tag, features };
+  }
+  async require(feature) {
+    const c = await this.capability(feature);
+    if (c.state === "missing")
+      throw needsRelease2(this.tag, c);
+  }
   async listed() {
-    if (this.remoteAssets === null)
+    if (this.remoteAssets === null) {
       this.remoteAssets = await (this.opts.remote ?? defaultRemote()).assets(requireRepo2(this.opts), this.tag);
+      if (existsSync4(this.dir)) {
+        const r = this.receipt();
+        r.published = this.remoteAssets.map((a) => a.name).sort();
+        writeJsonAtomic2(receiptPath(this.dir), r);
+      }
+    }
     return this.remoteAssets;
   }
   async fetchOne(asset) {
@@ -2062,6 +2296,8 @@ class Release2 {
     const b = this.builders().find((x) => x.name === name);
     if (b === undefined)
       throw new Error(`archive-client: no index "${name}" (known: ${this.builders().map((x) => x.name).join(", ")})`);
+    if (FEATURES2.some((f) => f.feature === b.name))
+      await this.require(b.name);
     await this.fetch(...b.inputs);
     return buildIndex2(this, b, { force: o.force ?? false, log: this.opts.log });
   }
@@ -2142,7 +2378,8 @@ async function openRelease2(spec = "pinned", opts = {}) {
     writeJsonAtomic2(receiptPath(dir), {
       tag,
       source: repo,
-      files: { "MANIFEST.json": landed }
+      files: { "MANIFEST.json": landed },
+      published: listed.map((a) => a.name).sort()
     });
     dropIfEmpty(part);
   }
@@ -2354,4 +2591,4 @@ function releases2(opts = {}) {
   return new ReleaseManager2(opts);
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, nameOrderOf, DancerResolver2, canonicalOf2, CompResolver2, NO_CALENDAR2, FeisFinder2, StaffFinder2, SchoolResolver2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };
+export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, nameOrderOf, DancerResolver2, readPopulation2, canonicalOf2, CompResolver2, NO_CALENDAR2, FeisFinder2, StaffFinder2, SchoolResolver2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, 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-zr8tfjk0.js";
+} from "./chunks/index-kp811fb0.js";
 import"./chunks/index-hne1wadw.js";
 import"./chunks/index-hghdy980.js";
 
@@ -23,6 +23,9 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
   index [--release <spec>] [<name>...] [--force]
                                     build the per-tag indexes (default: every one)
   verify [--release <spec>]         re-hash every cached file against its receipt
+  capabilities [--release <spec>]   what the release carries of what the client reads, from
+                                    its own schema: each feature full or missing (its calls
+                                    refuse, naming the first cut that publishes it)
   prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default 1)
                                     and the pinned one
   rm <tag> [--dry-run]              remove one cached release (not the pinned one)
@@ -37,8 +40,9 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
   dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>
          [--order surname-first|given-first] [--school <print|id>]
          [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]
-         [--rows]                   the dancers a name reaches, each with its evidence
-                                    (name level, age, school) and the arm; the results of
+         [--population girls|boys] [--rows]
+                                    the dancers a name reaches, each with its evidence
+                                    (name level, age, school, population) and the arm; the results of
                                     the one dancer where one answers (or --rows for each)
   results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]
           [--school <print|id>] [--year <y>] [--limit <n>]
@@ -61,12 +65,13 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
                                     else the newest, saying which and what it is read from
   resolve comp [<feis> <code>] [--year <y>] [--title <t>]
   resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]
-                 [--order <o>] [--as-of <date>]
+                 [--order <o>] [--as-of <date>] [--population girls|boys]
   resolve registrations
                                     JSONL out, one answer per line; with no positional the
                                     questions are JSONL on stdin, one per line (a comp:
-                                    {feis, code, year?, title?}, a dancer: {name, school?, age?},
-                                    a registration: {name, school?, codes[], feis, year?})
+                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,
+                                    population?}, a registration: {name, school?, codes[], feis,
+                                    year?, population?})
 
   <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)`;
 var VALUE = new Set([
@@ -90,6 +95,7 @@ var VALUE = new Set([
   "--band",
   "--comp",
   "--as-of",
+  "--population",
   "--dancer",
   "--feis",
   "--limit",
@@ -137,8 +143,8 @@ function printCached(c, say) {
 }
 var span = (lo, hi) => lo === null ? "-" : lo === hi ? `${lo}` : `${lo}-${hi ?? "?"}`;
 function printCandidate(c, say, pad = "  ") {
-  say(`${pad}${c.dancer_id}  ${c.display}${c.scope === "per-release" ? "  [per-release id]" : ""}  score ${c.score}  name ${c.evidence.nameLevel}  age ${c.evidence.age}  school ${c.evidence.school}`);
-  say(`${pad}    ${c.rows} rows ${span(c.year_lo, c.year_hi)}  born ${span(c.birth.lo, c.birth.hi)} (${c.birth.source})  school ${c.school === null ? "-" : `${c.school.school_id ?? "(no id)"} "${c.school.print}" ${span(c.school.year_lo, c.school.year_hi)}`}`);
+  say(`${pad}${c.dancer_id}  ${c.display}${c.scope === "per-release" ? "  [per-release id]" : ""}  score ${c.score}  name ${c.evidence.nameLevel}  age ${c.evidence.age}  school ${c.evidence.school}  population ${c.evidence.population}`);
+  say(`${pad}    ${c.rows} rows ${span(c.year_lo, c.year_hi)}  born ${span(c.birth.lo, c.birth.hi)} (${c.birth.source})  majors girls ${c.population.girls} boys ${c.population.boys}  school ${c.school === null ? "-" : `${c.school.school_id ?? "(no id)"} "${c.school.print}" ${span(c.school.year_lo, c.school.year_hi)}`}`);
   say(`${pad}    prints ${c.prints.slice(0, 5).map((p) => `"${p.print}" (${p.rows}, ${p.level})`).join(", ")}${c.prints.length > 5 ? `, +${c.prints.length - 5} more` : ""}`);
 }
 function printDancers(a, say) {
@@ -147,6 +153,8 @@ function printDancers(a, say) {
     say(`  age asked: ${a.age.read ?? "(unread)"}${a.age.birth !== null ? ` born ${a.age.birth.from ?? "?"}-${a.age.birth.to ?? "?"}` : ""}${a.age.note !== undefined ? `  (${a.age.note})` : ""}`);
   if (a.school !== undefined)
     say(`  school asked: ${a.school.arm} ${a.school.ids.join(", ") || "-"}`);
+  if (a.population !== undefined)
+    say(`  population asked: ${a.population.read ?? "(unread)"}${a.population.note !== undefined ? `  (${a.population.note})` : ""}`);
   for (const c of a.candidates)
     printCandidate(c, say);
   if (a.preferred !== undefined)
@@ -277,7 +285,8 @@ async function resolveVerb(rel, what, args, p, say, stdin) {
               ...nameOrderOf(p.flags.get("--order")) !== undefined ? { order: nameOrderOf(p.flags.get("--order")) } : {},
               ...p.flags.has("--school") ? { school: p.flags.get("--school") } : {},
               ...age !== undefined ? { age } : {},
-              ...p.flags.has("--as-of") ? { asOf: p.flags.get("--as-of") } : {}
+              ...p.flags.has("--as-of") ? { asOf: p.flags.get("--as-of") } : {},
+              ...p.flags.has("--population") ? { population: p.flags.get("--population") } : {}
             }
           }
         ];
@@ -404,6 +413,20 @@ async function main(argv, io = {}) {
         });
         return 0;
       }
+      case "capabilities": {
+        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        try {
+          const c = await rel.capabilities();
+          out(c, () => {
+            say(`${c.tag}: what it carries of what the client reads`);
+            for (const f of c.features)
+              say(`  ${f.state.padEnd(8)} ${f.feature}${f.state === "full" ? "" : `  lacks ${f.missing.join(", ")}: a release of cut ${f.since} or later answers ${f.calls}`}`);
+          });
+          return 0;
+        } finally {
+          rel.close();
+        }
+      }
       case "verify": {
         const tag = (await m.fetch(spec, { assets: [] })).tag;
         const bad = await m.verify(tag);
@@ -522,6 +545,7 @@ async function main(argv, io = {}) {
             ...p.flags.has("--school") ? { school: p.flags.get("--school") } : {},
             ...age !== undefined ? { age } : {},
             ...p.flags.has("--as-of") ? { asOf: p.flags.get("--as-of") } : {},
+            ...p.flags.has("--population") ? { population: p.flags.get("--population") } : {},
             ...p.flags.has("--limit") ? { limit: Number(p.flags.get("--limit")) } : {}
           };
           const surname = p.flags.get("--surname");
@@ -666,7 +690,7 @@ async function main(argv, io = {}) {
         out(a, () => {
           say(`${a.feis.asked}  ${a.year ?? "?"}  ${a.held ? `held: ${a.feis.feis_ids.join(", ")}` : "not held"}  series ${a.feis.brand_id ?? "-"} (years ${a.years.join(", ") || "-"})  in ${a.tag}`);
           for (const c of a.entries)
-            say(`  ${c.code}  ${c.kind}  ${c.level ?? "-"}  ${c.age ?? "-"}  ${c.population ?? "-"}  "${c.title ?? ""}"`);
+            say(`  ${c.code}  ${c.kind}  ${c.level ?? "-"}  ${c.age ?? "-"}  ${c.population ?? "-"}${c.second ? "  second" : ""}  "${c.title ?? ""}"`);
           say(`${a.entries.length} comp(s)`);
         });
         rel.close();

package/dist/index.js

@@ -10,6 +10,7 @@ import {
   ResultFinder2,
   MajorsFinder2,
   DancerResolver2,
+  readPopulation2,
   canonicalOf2,
   CompResolver2,
   NO_CALENDAR2,
@@ -30,13 +31,17 @@ import {
   httpsRemote2,
   fallbackRemote2,
   setRemote2,
+  columnsOf2,
+  FEATURES2,
+  capabilityOf2,
+  needsRelease2,
   resolveTag2,
   Release2,
   openRelease2,
   openCached2,
   ReleaseManager2,
   releases2
-} from "./chunks/index-zr8tfjk0.js";
+} from "./chunks/index-kp811fb0.js";
 import {
   cacheRoot2,
   repoOf2
@@ -55,6 +60,7 @@ export {
   CompResolver2 as CompResolver,
   DATABASES2 as DATABASES,
   DancerResolver2 as DancerResolver,
+  FEATURES2 as FEATURES,
   FEIS_LOCAL_ID_FLOOR2 as FEIS_LOCAL_ID_FLOOR,
   FeisFinder2 as FeisFinder,
   MajorsFinder2 as MajorsFinder,
@@ -69,6 +75,8 @@ export {
   buildIndex2 as buildIndex,
   cacheRoot2 as cacheRoot,
   canonicalOf2 as canonicalOf,
+  capabilityOf2 as capabilityOf,
+  columnsOf2 as columnsOf,
   compareTagsNewestFirst2 as compareTagsNewestFirst,
   cutOf2 as cutOf,
   dancerResolverOf2 as dancerResolverOf,
@@ -81,6 +89,7 @@ export {
   isCurrent2 as isCurrent,
   listIndexes2 as listIndexes,
   nameLevel2 as nameLevel,
+  needsRelease2 as needsRelease,
   openCached2 as openCached,
   openRelease2 as openRelease,
   parseArchiveTag2 as parseArchiveTag,
@@ -88,6 +97,7 @@ export {
   pickTag2 as pickTag,
   planAsset2 as planAsset,
   readPin2 as readPin,
+  readPopulation2 as readPopulation,
   releases2 as releases,
   renderArchiveTag2 as renderArchiveTag,
   repoOf2 as repoOf,

package/dist/types/assets.d.ts

@@ -37,4 +37,5 @@ export interface Receipt {
     tag: string;
     source: string;
     files: Record<string, LandedFile>;
+    published?: string[];
 }

package/dist/types/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import type { OpenOptions } from "./release.js";
-export declare const USAGE = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]\n\n  config repo <owner/name>          set the user-local repository the releases come from\n  list [--remote]                   the cached releases (size, files, indexes, the pin), and\n                                    with --remote the published tags\n  fetch [--release <spec>] [--assets results,majors,<file>...]\n                                    download, verify and cache a release (default: results)\n  pin <spec>                        the user-local pin: what a bare open (spec \"pinned\") opens\n  unpin                             remove the pin (a bare open is then \"latest\")\n  current                           the pin, and whether it is cached\n  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)\n                                    to the cache under its tag\n  index [--release <spec>] [<name>...] [--force]\n                                    build the per-tag indexes (default: every one)\n  verify [--release <spec>]         re-hash every cached file against its receipt\n  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default 1)\n                                    and the pinned one\n  rm <tag> [--dry-run]              remove one cached release (not the pinned one)\n  drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)\n  feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]\n                                    the feises a query names\n  series [--release <spec>] <name|host code|feis id>\n                                    the series a name, a host code (fweb:ABC) or any feis id\n                                    names: its years, hosts, codes and next instance\n  school [--release <spec>] <print|school_id> [--region <code>]\n                                    a school print or id to the published schools\n  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>\n         [--order surname-first|given-first] [--school <print|id>]\n         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]\n         [--rows]                   the dancers a name reaches, each with its evidence\n                                    (name level, age, school) and the arm; the results of\n                                    the one dancer where one answers (or --rows for each)\n  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]\n          [--school <print|id>] [--year <y>] [--limit <n>]\n                                    the published result rows, prints and ids\n  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]\n                                    the majors: every event and its years; an event's\n                                    competitions; a competition's, an event's or a dancer's rows\n  teacher [--release <spec>] <name|TD number>\n                                    the staff lists' people: where they taught, the register,\n                                    where they sat\n  adjudicator [--release <spec>] <name|TD number>\n                                    the register's and the panels' people: the same answer\n  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]\n                                    a feis's own comp code to the comp it names, through that\n                                    feis's syllabus (or the prior year's)\n  syllabus [--release <spec>] <feis> [year]\n                                    one feis-year's comps, in printed order\n  syllabus [--release <spec>] --for <series> [year]\n                                    a series' syllabus for a year: that year's where held,\n                                    else the newest, saying which and what it is read from\n  resolve comp [<feis> <code>] [--year <y>] [--title <t>]\n  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]\n                 [--order <o>] [--as-of <date>]\n  resolve registrations\n                                    JSONL out, one answer per line; with no positional the\n                                    questions are JSONL on stdin, one per line (a comp:\n                                    {feis, code, year?, title?}, a dancer: {name, school?, age?},\n                                    a registration: {name, school?, codes[], feis, year?})\n\n  <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)";
+export declare const USAGE = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]\n\n  config repo <owner/name>          set the user-local repository the releases come from\n  list [--remote]                   the cached releases (size, files, indexes, the pin), and\n                                    with --remote the published tags\n  fetch [--release <spec>] [--assets results,majors,<file>...]\n                                    download, verify and cache a release (default: results)\n  pin <spec>                        the user-local pin: what a bare open (spec \"pinned\") opens\n  unpin                             remove the pin (a bare open is then \"latest\")\n  current                           the pin, and whether it is cached\n  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)\n                                    to the cache under its tag\n  index [--release <spec>] [<name>...] [--force]\n                                    build the per-tag indexes (default: every one)\n  verify [--release <spec>]         re-hash every cached file against its receipt\n  capabilities [--release <spec>]   what the release carries of what the client reads, from\n                                    its own schema: each feature full or missing (its calls\n                                    refuse, naming the first cut that publishes it)\n  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default 1)\n                                    and the pinned one\n  rm <tag> [--dry-run]              remove one cached release (not the pinned one)\n  drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)\n  feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]\n                                    the feises a query names\n  series [--release <spec>] <name|host code|feis id>\n                                    the series a name, a host code (fweb:ABC) or any feis id\n                                    names: its years, hosts, codes and next instance\n  school [--release <spec>] <print|school_id> [--region <code>]\n                                    a school print or id to the published schools\n  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>\n         [--order surname-first|given-first] [--school <print|id>]\n         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]\n         [--population girls|boys] [--rows]\n                                    the dancers a name reaches, each with its evidence\n                                    (name level, age, school, population) and the arm; the results of\n                                    the one dancer where one answers (or --rows for each)\n  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]\n          [--school <print|id>] [--year <y>] [--limit <n>]\n                                    the published result rows, prints and ids\n  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]\n                                    the majors: every event and its years; an event's\n                                    competitions; a competition's, an event's or a dancer's rows\n  teacher [--release <spec>] <name|TD number>\n                                    the staff lists' people: where they taught, the register,\n                                    where they sat\n  adjudicator [--release <spec>] <name|TD number>\n                                    the register's and the panels' people: the same answer\n  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]\n                                    a feis's own comp code to the comp it names, through that\n                                    feis's syllabus (or the prior year's)\n  syllabus [--release <spec>] <feis> [year]\n                                    one feis-year's comps, in printed order\n  syllabus [--release <spec>] --for <series> [year]\n                                    a series' syllabus for a year: that year's where held,\n                                    else the newest, saying which and what it is read from\n  resolve comp [<feis> <code>] [--year <y>] [--title <t>]\n  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]\n                 [--order <o>] [--as-of <date>] [--population girls|boys]\n  resolve registrations\n                                    JSONL out, one answer per line; with no positional the\n                                    questions are JSONL on stdin, one per line (a comp:\n                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,\n                                    population?}, a registration: {name, school?, codes[], feis,\n                                    year?, population?})\n\n  <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)";
 export interface Parsed {
     positional: string[];
     flags: Map<string, string>;

package/dist/types/comps.d.ts

@@ -15,7 +15,10 @@ export interface Comp {
     feis_level: number | null;
     level: string | null;
     age: string | null;
+    age_source: string | null;
+    age_printed: string | null;
     population: Population | null;
+    second: boolean;
     round: string | null;
     canonical: string | null;
     platform: string;
@@ -107,8 +110,13 @@ interface CompRow {
     round: string | null;
     platform: string;
     captures: number;
+    age_source?: string | null;
+    age_printed?: string | null;
+    gender_source?: string | null;
+    level_printed?: string | null;
+    dance_printed?: string | null;
 }
-export declare function compOf(r: CompRow): Comp;
+export declare function compOf(r: CompRow, codes?: readonly string[]): Comp;
 export declare function canonicalOf(level: number | null, age: string | null): string | null;
 export declare class CompResolver {
     private readonly rel;

package/dist/types/dancers.d.ts

@@ -20,8 +20,10 @@ export interface DancerQuery {
     school?: string;
     age?: AgeAsked;
     asOf?: string;
+    population?: string;
 }
 export type AgeEvidence = "fits" | "overlaps" | "contradicts" | "unknown" | "unasked";
+export type PopulationEvidence = "same" | "contradicts" | "both" | "unknown" | "unasked";
 export type SchoolEvidence = "same" | "moved" | "none" | "unresolved" | "unasked";
 export interface DancerSchool {
     school_id: string | null;
@@ -40,6 +42,7 @@ export interface DancerCandidate {
         nameLevel: NameLevel;
         age: AgeEvidence;
         school: SchoolEvidence;
+        population: PopulationEvidence;
     };
     prints: {
         print: string;
@@ -55,11 +58,15 @@ export interface DancerCandidate {
         source: string;
         conflict: boolean;
     };
+    population: {
+        girls: number;
+        boys: number;
+    };
     school: DancerSchool | null;
 }
 export interface ExcludedCandidate {
     candidate: DancerCandidate;
-    why: "age";
+    why: "age" | "population";
 }
 export interface DancerAnswer {
     tag: string;
@@ -83,6 +90,11 @@ export interface DancerAnswer {
         } | null;
         note?: string;
     };
+    population?: {
+        asked: string;
+        read: "girls" | "boys" | null;
+        note?: string;
+    };
     school?: {
         arm: string;
         ids: string[];
@@ -113,6 +125,10 @@ export interface DancerRecord {
         source: string;
         conflict: boolean;
     };
+    population: {
+        girls: number;
+        boys: number;
+    };
     prints: {
         print: string;
         rows: number;
@@ -136,3 +152,4 @@ export declare class DancerResolver {
     private schoolEvidence;
     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 DancerCandidate, type DancerQuery, type DancerRecord, DancerResolver, type DancerSchool, type DancerSearchQuery, type ExcludedCandidate, FEIS_LOCAL_ID_FLOOR, type SchoolEvidence, } from "./dancers.js";
+export { type AgeAsked, type AgeEvidence, type DancerAnswer, type DancerCandidate, type DancerQuery, type DancerRecord, DancerResolver, type DancerSchool, type DancerSearchQuery, type ExcludedCandidate, FEIS_LOCAL_ID_FLOOR, type PopulationEvidence, type SchoolEvidence, readPopulation, } from "./dancers.js";
 export { NAME_LEVELS, type NameLevel, nameLevel } from "./dancers-names.js";
 export { type Comp, type CompAnswer, 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";
@@ -14,4 +14,5 @@ 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, } from "./schools.js";
+export { type Capability, FEATURES, type Feature, type SchemaProbe, capabilityOf, columnsOf, needsRelease, } from "./schema.js";
 export { ARCHIVE_TAG, type ArchiveTag, type ReleaseSpec, compareTagsNewestFirst, cutOf, parseArchiveTag, parseReleaseSpec, pickTag, renderArchiveTag, } from "./tag.js";

package/dist/types/registrations.d.ts

@@ -10,6 +10,7 @@ export interface RegistrationRow {
     year?: number;
     titles?: Readonly<Record<string, string>>;
     asOf?: string;
+    population?: string;
     [k: string]: unknown;
 }
 export type DancerQueryLike = DancerQuery;
@@ -36,6 +37,13 @@ export interface ResolvedRegistration {
         from: "comp" | "title";
     } | null;
     bands?: string[];
+    population: {
+        asked: string;
+        from: "row" | "comp";
+        codes?: string[];
+    } | {
+        why: string;
+    } | null;
     dancer: DancerAnswer | DancerAnswerLike | DancerUnavailable;
     asked?: DancerQueryLike;
 }

package/dist/types/release.d.ts

@@ -9,6 +9,7 @@ import { StaffFinder } from "./people.js";
 import { type DancerResolverLike, RegistrationResolver } from "./registrations.js";
 import { type Remote } from "./remote.js";
 import { MajorsFinder, ResultFinder } from "./results.js";
+import { type Capability } from "./schema.js";
 import { type SchoolReaderChoice, SchoolResolver } from "./schools.js";
 import { type ReleaseSpec } from "./tag.js";
 export interface OpenOptions extends ClientOptions {
@@ -49,6 +50,15 @@ export declare class Release {
     has(asset: string): boolean;
     path(asset: string): string;
     fetch(...assets: string[]): Promise<LandedFile[]>;
+    publishes(asset: string): Promise<boolean>;
+    private readonly probe;
+    private readonly checked;
+    capability(feature: string): Promise<Capability>;
+    capabilities(): Promise<{
+        tag: string;
+        features: Capability[];
+    }>;
+    require(feature: string): Promise<void>;
     private listed;
     private fetchOne;
     private record;

package/dist/types/schema.d.ts

@@ -0,0 +1,20 @@
+import type { Database } from "bun:sqlite";
+export declare function columnsOf(db: Database, table: string): Set<string>;
+export interface Feature {
+    feature: string;
+    needs: readonly string[];
+    since: number;
+    calls: string;
+}
+export declare const FEATURES: readonly Feature[];
+export interface Capability extends Feature {
+    state: "full" | "missing";
+    missing: string[];
+}
+export interface SchemaProbe {
+    db(name: string): Promise<Database>;
+    publishes(asset: string): Promise<boolean>;
+}
+export declare function hasNeed(probe: SchemaProbe, n: string): Promise<boolean>;
+export declare function capabilityOf(probe: SchemaProbe, f: Feature): Promise<Capability>;
+export declare function needsRelease(tag: string, c: Capability): Error;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.1.2",
+	"version": "0.3.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",
@@ -44,7 +44,7 @@
 		"prepublishOnly": "bun scripts/build.ts && bun ../../tools/checks/archive-client-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/domain": "0.48.0",
+		"@finbheara/domain": "0.49.0",
 		"@finbheara/names": "0.22.0"
 	},
 	"devDependencies": {