@finbheara/archive-client 0.33.0 → 0.35.0

package/README.md

@@ -100,6 +100,9 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `upcoming.feises` | `upcoming.feises`, and the `next` of `feises.series` (null with the reason without it) | 285 |
 | `upcoming.fields`, `upcoming.entrants` | `upcoming.fields`, `upcoming.entrants` (285 and 290 carry the tables empty) | 291 |
 | `upcoming.fields.instance` | the `feis_instance_id` `upcoming.fields` carries; absent, never refused, without it | 320 |
+| `calendar` | `calendar.get`, `calendar.list` | 320 |
+| `calendar.expected` | each calendar stage's `expected`; absent, never refused, without it | 320 |
+| `calendar.next` | `calendar.next` | 320 |
 | `tabs`, `panels` | `tabs.query`, `tabs.stream`; `panels.query` | 184 |
 | `feis-panels` | `feisPanels.query` | 260 |
 | `staff.adjudicators` | `staff.adjudicators` | 230 |
@@ -752,6 +755,53 @@ the corpus `entrants/` part: its rows are schools' counts (`level_counts`), with
 host with a registrant list publishes no such field. An unknown field or version answers no rows and says
 why. On a release without the tables each call refuses by name.
 
+## The feis calendar
+
+```ts
+const g = await rel.calendar.get("plf.2026");  // an instance, an event-year (`<event><year>`), a retired
+                                                // id, a capture (`fweb:PLF26`) or an occurrence id
+g.via;       // "instance" | "formerly" | "feis_id" | "occurrence_id" | null
+g.entries;   // [{ feis_instance_id, feis_brand_id, tier, name_printed, date_lo, date_hi, date_source,
+             //    occurrence_ids, feis_ids, stages: { announced, syllabus, entrants, run, results },
+             //    terminal, carried, formerly }]
+g.entries[0].stages.results.expected;
+             // { date, basis, n, platform } or null: "announced" | "brand" | "platform" |
+             //   "pooled" | "roster-window" | "unmeasured"
+const l = await rel.calendar.list({ stage: "entrants", state: "observed", from: "2026-11-01" });
+             // brand, tier, from, to, stage, state, terminal ("none": still ahead)
+const n = await rel.calendar.next({ brand: "plf" });
+             // [{ feis_brand_id, year, run_expected, run_expected_basis, run_expected_n,
+             //    from_instance_id, from_date }]: a series' next edition no listing names yet
+```
+
+ONE ROW PER FEIS INSTANCE, on the id its results carry: a feis-series instance (`<brand>.<year>`),
+announced, held or both, or a rated majors event-year. Each stage (`announced`, `syllabus`,
+`entrants`, `run`, `results`) is `{ state, date, cite }`: `observed` (a capture showed it, `date`
+the day it was first observed, null where no capture dates it, `cite` the capture), `pending` (the
+release holds captures of that kind for the instance's platform, so a later one may show it) or
+`not-captured` (it holds none). A day first observed never moves later from one release to the
+next: a stage an earlier release observed keeps its day, named in `carried` (`["row"]` for a row
+the cut no longer names, kept whole), and a retired id is listed in `formerly`. `terminal` is
+`results`, `withdrawn` (every field withdrawn), `passed-no-results` (its first day is before the
+cut's day), or null for a feis still ahead. Stage dates follow capture timing, not the feis's own
+order: only results after the run is a belief. `get` tries the instance id, then `formerly`, then
+a capture, then an occurrence id, and says which met (`via`). On a release without the table each
+call refuses by name.
+
+EXPECTED DAYS (`calendar.expected`): each stage carries `expected`, `{ date, basis, n, platform }`
+or null. `announced` is the listing's own first day; `brand` the series' edition the year before
+plus 364 days, `n` its held years; `platform` a platform's capture lag (the P90 of first results
+capture less last day) or list lead (the median of first day less first list capture), measured
+over the feiseanna run in the 180 days before the cut, `n` at least 10; `pooled` every platform's
+results lags together, for a feis whose hosts have no capture form (`platform` `all`) and, NAMED, in
+place of a platform measured on fewer than 10 (`platform` the host's); `roster-window` a majors event-year
+no capture dates; `unmeasured` no day. A stage still ahead always carries one; an observed stage
+carries the day its estimator gives it where one applies, so the misses can be read. The lags are
+capture's own scrape cadence, re-measured every release. `next` lists each series with two or more
+held years, the last the release's year or the one before, whose next edition is not on the
+calendar: its year and expected first day. It is never an instance: an id is minted only once a
+listing names the edition.
+
 ## Teachers and adjudicators
 
 ```ts
@@ -927,6 +977,10 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     idq upcoming [--release <spec>] [--state <s,...>] [--feis <id>] [--from <date>] [--to <date>]
     idq upcoming --entrants <field_id> [--version <capture id>]
     idq upcoming --feises [--state upcoming|no-results] [--brand <series>] [--from <date>] [--to <date>]
+    idq calendar [--release <spec>] <instance|feis id|occurrence id>
+    idq calendar [--brand <series>] [--tier <t>] [--from <date>] [--to <date>] [--stage <s>] [--state <s>]
+                 [--terminal results|withdrawn|passed-no-results|none]
+    idq calendar --next [--brand <series>]
     idq teacher [--release <spec>] <name|TD number>
     idq adjudicator [--release <spec>] <name|TD number>
     idq comp [--release <spec>] <feis> <code> [--year y] [--title t]

package/dist/chunks/{index-g8ab43kz.js → index-gt7yxxp8.js}

@@ -688,6 +688,60 @@ var FEATURES2 = [
     since: 320,
     calls: "upcoming.fields' `feis_instance_id` (absent, never null, without it)"
   },
+  {
+    feature: "calendar",
+    needs: [
+      "feis_instance_id",
+      "feis_brand_id",
+      "tier",
+      "name_printed",
+      "date_lo",
+      "date_hi",
+      "date_source",
+      "occurrence_ids",
+      "feis_ids",
+      "announced_state",
+      "announced_date",
+      "announced_cite",
+      "syllabus_state",
+      "syllabus_date",
+      "syllabus_cite",
+      "entrants_state",
+      "entrants_date",
+      "entrants_cite",
+      "run_state",
+      "run_date",
+      "run_cite",
+      "results_state",
+      "results_date",
+      "results_cite",
+      "terminal",
+      "carried",
+      "formerly"
+    ].map((c) => `results:feis_calendar.${c}`),
+    since: 320,
+    calls: "calendar.get, calendar.list"
+  },
+  {
+    feature: "calendar.expected",
+    needs: ["announced", "syllabus", "entrants", "run", "results"].flatMap((st) => ["", "_basis", "_n", "_platform"].map((x) => `results:feis_calendar.${st}_expected${x}`)),
+    since: 320,
+    calls: "each calendar stage's `expected` (absent, never refused, without it)"
+  },
+  {
+    feature: "calendar.next",
+    needs: [
+      "feis_brand_id",
+      "year",
+      "run_expected",
+      "run_expected_basis",
+      "run_expected_n",
+      "from_instance_id",
+      "from_date"
+    ].map((c) => `results:feis_series_next.${c}`),
+    since: 320,
+    calls: "calendar.next"
+  },
   {
     feature: "upcoming.entrants",
     needs: [
@@ -3825,6 +3879,155 @@ import {
 } from "fs";
 import { join as join3 } from "path";
 
+var CALENDAR_STAGES2 = [
+  "announced",
+  "syllabus",
+  "entrants",
+  "run",
+  "results"
+];
+var CALENDAR_STAGE_STATES2 = [
+  "observed",
+  "pending",
+  "not-captured"
+];
+var CALENDAR_TERMINALS2 = [
+  "results",
+  "withdrawn",
+  "passed-no-results"
+];
+var json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
+function expectedOf(r, s) {
+  const basis = r[`${s}_expected_basis`];
+  if (basis === null || basis === undefined)
+    return null;
+  const n = r[`${s}_expected_n`];
+  return {
+    date: r[`${s}_expected`] ?? null,
+    basis,
+    n: n === null || n === undefined ? null : Number(n),
+    platform: r[`${s}_expected_platform`] ?? null
+  };
+}
+function entryOf2(r, expected) {
+  const stages = Object.fromEntries(CALENDAR_STAGES2.map((s) => [
+    s,
+    {
+      state: r[`${s}_state`],
+      date: r[`${s}_date`] ?? null,
+      cite: r[`${s}_cite`] ?? null,
+      ...expected ? { expected: expectedOf(r, s) } : {}
+    }
+  ]));
+  return {
+    feis_instance_id: r.feis_instance_id,
+    feis_brand_id: r.feis_brand_id ?? null,
+    tier: r.tier,
+    name_printed: r.name_printed ?? null,
+    date_lo: r.date_lo ?? null,
+    date_hi: r.date_hi ?? null,
+    date_source: r.date_source ?? null,
+    occurrence_ids: json(r.occurrence_ids, []),
+    feis_ids: json(r.feis_ids, []),
+    stages,
+    terminal: r.terminal ?? null,
+    carried: json(r.carried, []),
+    formerly: json(r.formerly, [])
+  };
+}
+var holds = (col) => `EXISTS (SELECT 1 FROM json_each(${col}) WHERE value = ?)`;
+
+class CalendarFinder2 {
+  rel;
+  constructor(rel) {
+    this.rel = rel;
+  }
+  async db() {
+    await this.rel.fetch("results");
+    await this.rel.require("calendar");
+    return this.rel.db("results");
+  }
+  async expected() {
+    return (await this.rel.capability("calendar.expected")).state === "full";
+  }
+  async next(q = {}) {
+    await this.rel.fetch("results");
+    await this.rel.require("calendar.next");
+    const db = this.rel.db("results");
+    const rows = q.brand === undefined ? db.query("SELECT * FROM feis_series_next ORDER BY run_expected, feis_brand_id").all() : db.query("SELECT * FROM feis_series_next WHERE feis_brand_id = ? ORDER BY run_expected").all(q.brand);
+    return {
+      tag: this.rel.tag,
+      next: rows.map((r) => ({
+        feis_brand_id: r.feis_brand_id,
+        year: Number(r.year),
+        run_expected: r.run_expected,
+        run_expected_basis: "brand",
+        run_expected_n: Number(r.run_expected_n),
+        from_instance_id: r.from_instance_id,
+        from_date: r.from_date
+      }))
+    };
+  }
+  async get(id) {
+    const db = await this.db();
+    const ways = [
+      ["instance", "feis_instance_id = ?"],
+      ["formerly", holds("formerly")],
+      ["feis_id", holds("feis_ids")],
+      ["occurrence_id", holds("occurrence_ids")]
+    ];
+    for (const [via, where] of ways) {
+      const rows = db.query(`SELECT * FROM feis_calendar WHERE ${where} ORDER BY feis_instance_id`).all(id);
+      if (rows.length > 0) {
+        const e = await this.expected();
+        return { tag: this.rel.tag, asked: id, via, entries: rows.map((r) => entryOf2(r, e)) };
+      }
+    }
+    return {
+      tag: this.rel.tag,
+      asked: id,
+      via: null,
+      entries: [],
+      why: `the calendar names no instance, capture or occurrence "${id}"`
+    };
+  }
+  async list(q = {}) {
+    if (q.stage !== undefined && !CALENDAR_STAGES2.includes(q.stage))
+      throw new Error(`calendar.list: no stage "${q.stage}" (the stages are ${CALENDAR_STAGES2.join(", ")})`);
+    if (q.state !== undefined && !CALENDAR_STAGE_STATES2.includes(q.state))
+      throw new Error(`calendar.list: no state "${q.state}" (the states are ${CALENDAR_STAGE_STATES2.join(", ")})`);
+    if (q.terminal !== undefined && q.terminal !== "none" && !CALENDAR_TERMINALS2.includes(q.terminal))
+      throw new Error(`calendar.list: no terminal "${q.terminal}" (the terminals are ${CALENDAR_TERMINALS2.join(", ")}, none)`);
+    const db = await this.db();
+    const where = [];
+    const args = [];
+    const add = (sql, ...v) => {
+      where.push(sql);
+      args.push(...v);
+    };
+    if (q.brand !== undefined)
+      add("feis_brand_id = ?", q.brand);
+    if (q.tier !== undefined)
+      add("tier = ?", q.tier);
+    if (q.from !== undefined)
+      add("date_lo >= ?", q.from);
+    if (q.to !== undefined)
+      add("date_lo <= ?", q.to);
+    if (q.stage !== undefined)
+      add(`${q.stage}_state = ?`, q.state ?? "observed");
+    else if (q.state !== undefined)
+      add(`(${CALENDAR_STAGES2.map((s) => `${s}_state = ?`).join(" OR ")})`, ...CALENDAR_STAGES2.map(() => q.state));
+    if (q.terminal === "none")
+      add("terminal IS NULL");
+    else if (q.terminal !== undefined)
+      add("terminal = ?", q.terminal);
+    const sql = `SELECT * FROM feis_calendar${where.length > 0 ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY date_lo IS NULL, date_lo, feis_instance_id`;
+    const rows = db.query(sql).all(...args);
+    const e = await this.expected();
+    return { tag: this.rel.tag, entries: rows.map((r) => entryOf2(r, e)) };
+  }
+}
+
 import { Age as Age3 } from "@finbheara/domain/age";
 import { compTitle as compTitle3 } from "@finbheara/domain/title";
 function youngest2(answers) {
@@ -4125,7 +4328,7 @@ var FIELD_STATES2 = [
   "withdrawn"
 ];
 var DEPARTURE_REASONS2 = FIELD_STATES2.filter((s) => s !== "pending");
-var json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
+var json2 = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
 function fieldOf(r) {
   const countOnly = r.count_only === 1;
   return {
@@ -4154,19 +4357,19 @@ function fieldOf(r) {
       why: r.comp_why ?? null
     },
     state: r.state,
-    flags: json(r.flags, []),
-    results_competitions: json(r.results_competitions, []),
-    results_feis_ids: json(r.results_feis_ids, []),
-    held_out: json(r.held_out, []),
+    flags: json2(r.flags, []),
+    results_competitions: json2(r.results_competitions, []),
+    results_feis_ids: json2(r.results_feis_ids, []),
+    held_out: json2(r.held_out, []),
     merged_into: r.merged_into ?? null,
     version: r.version,
-    versions: json(r.versions, []),
+    versions: json2(r.versions, []),
     captured_date: r.captured_date,
     sha256: r.sha256,
-    limits: json(r.limits, []),
+    limits: json2(r.limits, []),
     entrants: r.entrants,
     stated_rows: r.stated_rows ?? null,
-    printed_total: json(r.printed_total, null)
+    printed_total: json2(r.printed_total, null)
   };
 }
 function entrantOf(r) {
@@ -4183,30 +4386,30 @@ function entrantOf(r) {
     school_printed: r.school_printed ?? null,
     school_id: r.school_id ?? null,
     school_rung: r.school_rung,
-    school_candidates: json(r.school_candidates, []),
-    competitions: json(r.competitions, []),
-    field_ids: json(r.field_ids, []),
-    level_counts: json(r.level_counts, null),
+    school_candidates: json2(r.school_candidates, []),
+    competitions: json2(r.competitions, []),
+    field_ids: json2(r.field_ids, []),
+    level_counts: json2(r.level_counts, null),
     yob: r.yob ?? null,
-    asked: json(r.asked, null),
+    asked: json2(r.asked, null),
     arm: r.arm ?? null,
-    candidates: json(r.candidates, []),
-    flags: json(r.flags, [])
+    candidates: json2(r.candidates, []),
+    flags: json2(r.flags, [])
   };
 }
 function feisOf(r) {
   return {
     occurrence_id: r.occurrence_id,
-    occurrence_ids: json(r.occurrence_ids, []),
+    occurrence_ids: json2(r.occurrence_ids, []),
     name_printed: r.name_printed,
     date_lo: r.date_lo,
     date_hi: r.date_hi ?? null,
     year: r.year,
-    hosts: json(r.hosts, []),
+    hosts: json2(r.hosts, []),
     feis_brand_id: r.feis_brand_id ?? null,
     feis_instance_id: r.feis_instance_id ?? null,
     series_basis: r.series_basis,
-    brand_candidates: json(r.brand_candidates, []),
+    brand_candidates: json2(r.brand_candidates, []),
     captured_id: r.captured_id,
     state: r.results_state
   };
@@ -4396,6 +4599,7 @@ class Release2 {
   teams;
   events;
   upcoming;
+  calendar;
   tabs;
   panels;
   feisPanels;
@@ -4422,6 +4626,7 @@ class Release2 {
     this.teams = new TeamFinder2(this);
     this.events = new EventFinder2(this);
     this.upcoming = new UpcomingFinder2(this);
+    this.calendar = new CalendarFinder2(this);
     this.tabs = new TabFinder2(this);
     this.panels = new PanelFinder2(this);
     this.feisPanels = new FeisPanelFinder2(this);
@@ -5145,4 +5350,4 @@ function staleWarning2(answered, latest, floor, tags = [], command = "idq") {
   return `answered from ${answered}. ${floorTag ?? `cut ${floor.cut}`} is required${why}: run \`${command} use ${floor.cut}\` to get it`;
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, TabFinder2, PanelFinder2, FeisPanelFinder2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, rosterOf2, NO_CALENDAR2, NO_UPCOMING2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, defaultRemote, FIELD_STATES2, DEPARTURE_REASONS2, UpcomingFinder2, resolveTag2, Release2, openRelease2, openCached2, DEFAULT_KEEP2, ReleaseManager2, releases2, LOCAL_DIR2, localRoot2, newerThan2, incomplete2, releaseVersion2, pickBuild2, buildTag2, lacks, openBuild2, sweepBuilds2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };
+export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, TabFinder2, PanelFinder2, FeisPanelFinder2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, rosterOf2, NO_CALENDAR2, NO_UPCOMING2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, CALENDAR_STAGES2, CALENDAR_STAGE_STATES2, CALENDAR_TERMINALS2, CalendarFinder2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, defaultRemote, FIELD_STATES2, DEPARTURE_REASONS2, UpcomingFinder2, resolveTag2, Release2, openRelease2, openCached2, DEFAULT_KEEP2, ReleaseManager2, releases2, LOCAL_DIR2, localRoot2, newerThan2, incomplete2, releaseVersion2, pickBuild2, buildTag2, lacks, openBuild2, sweepBuilds2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-g8ab43kz.js";
+} from "./chunks/index-gt7yxxp8.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
@@ -392,6 +392,25 @@ var VERBS = [
       "                                    held-out competitions)"
     ]
   },
+  {
+    verb: "calendar",
+    value: ["--release", "--brand", "--tier", "--from", "--to", "--stage", "--state", "--terminal"],
+    bool: ["--next"],
+    usage: [
+      "  calendar [--release <spec>] <instance|feis id|occurrence id>",
+      "                                    one feis instance's stages: announced, syllabus, entrants,",
+      "                                    run and results, each observed, pending or not-captured,",
+      "                                    the day first observed and the capture that observed it",
+      "  calendar [--brand <series>] [--tier T1..T4] [--from <date>] [--to <date>]",
+      "           [--stage announced|syllabus|entrants|run|results] [--state observed|pending|not-captured]",
+      "           [--terminal results|withdrawn|passed-no-results|none]",
+      "                                    the instances a query names, by first day; each stage's",
+      "                                    expected day with its basis and n where the release has them",
+      "  calendar --next [--brand <series>]",
+      "                                    each series' next edition no listing names yet: its year",
+      "                                    and expected first day from the year before (basis brand)"
+    ]
+  },
   {
     verb: "teacher",
     value: ["--release"],
@@ -508,6 +527,7 @@ function parseArgs(argv) {
   return { positional, flags, bools };
 }
 var mb = (n) => `${(n / 1e6).toFixed(1)} MB`;
+var expectedText = (e) => e === null || e === undefined ? "" : `  expected ${e.date ?? "-"} (${e.basis}${e.platform !== null ? ` ${e.platform}` : ""}${e.n !== null ? `, n ${e.n}` : ""})`;
 function printPlan(p, say) {
   for (const k of p.keep)
     say(`keep    ${k.tag} (${k.why})`);
@@ -799,6 +819,7 @@ var ANSWERING = new Set([
   "teams",
   "events",
   "upcoming",
+  "calendar",
   "teacher",
   "adjudicator",
   "comp",
@@ -1533,6 +1554,52 @@ async function main(argv, io = {}) {
           rel.close();
         }
       }
+      case "calendar": {
+        const rel = await open(spec, { ...opts, assets: [] });
+        try {
+          const line = (e) => `  ${e.date_lo ?? "?"}  ${e.feis_instance_id}  ${e.tier}  ${["announced", "syllabus", "entrants", "run", "results"].map((s) => `${s}:${e.stages[s].state === "observed" ? e.stages[s].date ?? "seen" : e.stages[s].state}`).join(" ")}  [${e.terminal ?? "ahead"}]${e.name_printed !== null ? `  "${e.name_printed}"` : ""}`;
+          if (p.bools.has("--next")) {
+            const brand = p.flags.get("--brand");
+            const a = await rel.calendar.next(brand === undefined ? {} : { brand });
+            out(a, () => {
+              for (const n of a.next)
+                say(`  ${n.run_expected}  ${n.feis_brand_id}  ${n.year}  brand n ${n.run_expected_n}  from ${n.from_instance_id} (${n.from_date})`);
+              say(`${a.next.length} next edition(s) in ${a.tag}`);
+            });
+            return a.next.length === 0 ? 1 : 0;
+          }
+          if (rest.length > 0) {
+            const a = await rel.calendar.get(rest.join(" "));
+            out(a, () => {
+              for (const e of a.entries) {
+                say(line(e));
+                for (const s of ["announced", "syllabus", "entrants", "run", "results"])
+                  say(`      ${s}  ${e.stages[s].state}  ${e.stages[s].date ?? "-"}  ${e.stages[s].cite ?? "-"}${e.carried.includes(s) ? "  (carried)" : ""}${expectedText(e.stages[s].expected)}`);
+              }
+              say(`${a.entries.length} instance(s) for "${a.asked}"${a.via !== null ? ` by ${a.via}` : ""}${a.why !== undefined ? ` (${a.why})` : ""} in ${a.tag}`);
+            });
+            return a.entries.length === 0 ? 1 : 0;
+          }
+          const v = (f) => p.flags.get(f);
+          const a = await rel.calendar.list({
+            ...v("--brand") !== undefined ? { brand: v("--brand") } : {},
+            ...v("--tier") !== undefined ? { tier: v("--tier") } : {},
+            ...v("--from") !== undefined ? { from: v("--from") } : {},
+            ...v("--to") !== undefined ? { to: v("--to") } : {},
+            ...v("--stage") !== undefined ? { stage: v("--stage") } : {},
+            ...v("--state") !== undefined ? { state: v("--state") } : {},
+            ...v("--terminal") !== undefined ? { terminal: v("--terminal") } : {}
+          });
+          out(a, () => {
+            for (const e of a.entries)
+              say(line(e));
+            say(`${a.entries.length} instance(s) in ${a.tag}`);
+          });
+          return a.entries.length === 0 ? 1 : 0;
+        } finally {
+          rel.close();
+        }
+      }
       case "teacher":
       case "adjudicator": {
         if (rest.length === 0) {

package/dist/index.js

@@ -44,6 +44,10 @@ import {
   ensureIndex2,
   listIndexes2,
   readPin2,
+  CALENDAR_STAGES2,
+  CALENDAR_STAGE_STATES2,
+  CALENDAR_TERMINALS2,
+  CalendarFinder2,
   youngest2,
   dancerResolverOf2,
   RegistrationResolver2,
@@ -76,7 +80,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-g8ab43kz.js";
+} from "./chunks/index-gt7yxxp8.js";
 import {
   cacheRoot2,
   repoOf2
@@ -93,6 +97,10 @@ import {
 export {
   ADVANCEMENT_DANCES2 as ADVANCEMENT_DANCES,
   ARCHIVE_TAG2 as ARCHIVE_TAG,
+  CALENDAR_STAGES2 as CALENDAR_STAGES,
+  CALENDAR_STAGE_STATES2 as CALENDAR_STAGE_STATES,
+  CALENDAR_TERMINALS2 as CALENDAR_TERMINALS,
+  CalendarFinder2 as CalendarFinder,
   CompResolver2 as CompResolver,
   DATABASES2 as DATABASES,
   DEFAULT_KEEP2 as DEFAULT_KEEP,

package/dist/types/calendar.d.ts

@@ -0,0 +1,79 @@
+import type { Release } from "./release.js";
+export type CalendarStage = "announced" | "syllabus" | "entrants" | "run" | "results";
+export declare const CALENDAR_STAGES: readonly CalendarStage[];
+export type CalendarStageState = "observed" | "pending" | "not-captured";
+export declare const CALENDAR_STAGE_STATES: readonly CalendarStageState[];
+export type CalendarTerminal = "results" | "withdrawn" | "passed-no-results";
+export declare const CALENDAR_TERMINALS: readonly CalendarTerminal[];
+export type CalendarExpectedBasis = "announced" | "brand" | "platform" | "pooled" | "roster-window" | "unmeasured";
+export interface CalendarExpected {
+    date: string | null;
+    basis: CalendarExpectedBasis;
+    n: number | null;
+    platform: string | null;
+}
+export interface CalendarStageValue {
+    state: CalendarStageState;
+    date: string | null;
+    cite: string | null;
+    expected?: CalendarExpected | null;
+}
+export interface CalendarEntry {
+    feis_instance_id: string;
+    feis_brand_id: string | null;
+    tier: string;
+    name_printed: string | null;
+    date_lo: string | null;
+    date_hi: string | null;
+    date_source: "run" | "announced" | null;
+    occurrence_ids: string[];
+    feis_ids: string[];
+    stages: Record<CalendarStage, CalendarStageValue>;
+    terminal: CalendarTerminal | null;
+    carried: string[];
+    formerly: string[];
+}
+export interface CalendarQuery {
+    brand?: string;
+    tier?: string;
+    from?: string;
+    to?: string;
+    stage?: CalendarStage;
+    state?: CalendarStageState;
+    terminal?: CalendarTerminal | "none";
+}
+export interface CalendarAnswer {
+    tag: string;
+    entries: CalendarEntry[];
+}
+export interface CalendarNext {
+    feis_brand_id: string;
+    year: number;
+    run_expected: string;
+    run_expected_basis: "brand";
+    run_expected_n: number;
+    from_instance_id: string;
+    from_date: string;
+}
+export interface CalendarNextAnswer {
+    tag: string;
+    next: CalendarNext[];
+}
+export interface CalendarGetAnswer {
+    tag: string;
+    asked: string;
+    via: "instance" | "formerly" | "feis_id" | "occurrence_id" | null;
+    entries: CalendarEntry[];
+    why?: string;
+}
+export declare class CalendarFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    private db;
+    private expected;
+    next(q?: {
+        brand?: string;
+    }): Promise<CalendarNextAnswer>;
+    get(id: string): Promise<CalendarGetAnswer>;
+    list(q?: CalendarQuery): Promise<CalendarAnswer>;
+}

package/dist/types/index.d.ts

@@ -26,4 +26,5 @@ export { type EntryRow, type StreamCompetition, type StreamQuery, type StreamRow
 export { type FeisPanelSeat, FeisPanelFinder, PanelFinder, type PanelSeat, type RegisterRow, type TabAnswer, TabFinder, type TabQuery, type TabRow, type TabStreamQuery, } from "./tabs.js";
 export { EventFinder, type EventYear, type EventYearQuery, type ResultRoster, type RosterMember, type RosterTeam, TeamFinder, type TeamResult, } from "./teams.js";
 export { type EntrantCandidate, FIELD_STATES, type FieldComp, DEPARTURE_REASONS, type DepartureReason, type FieldState, type HeldOut, type UpcomingDeparture, type UpcomingDepartureAnswer, type UpcomingDepartureQuery, type UpcomingEntrant, type UpcomingEntrantAnswer, type UpcomingEntrantQuery, type UpcomingFeis, type UpcomingFeisAnswer, type UpcomingFeisQuery, type UpcomingFeisState, type UpcomingField, type UpcomingFieldAnswer, type UpcomingFieldQuery, UpcomingFinder, type UpcomingHost, } from "./upcoming.js";
+export { CALENDAR_STAGES, CALENDAR_STAGE_STATES, CALENDAR_TERMINALS, type CalendarAnswer, type CalendarEntry, type CalendarExpected, type CalendarExpectedBasis, type CalendarNext, type CalendarNextAnswer, CalendarFinder, type CalendarGetAnswer, type CalendarQuery, type CalendarStage, type CalendarStageState, type CalendarStageValue, type CalendarTerminal, } from "./calendar.js";
 export { ARCHIVE_TAG, type ArchiveTag, type ReleaseSpec, compareTagsNewestFirst, cutOf, parseArchiveTag, parseReleaseSpec, pickTag, renderArchiveTag, } from "./tag.js";

package/dist/types/release.d.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
 import { type AssetPlan, type LandedFile, type Receipt, type ReleaseManifest } from "./assets.js";
+import { CalendarFinder } from "./calendar.js";
 import { CompResolver } from "./comps.js";
 import { type ClientOptions } from "./config.js";
 import { DancerResolver } from "./dancers.js";
@@ -47,6 +48,7 @@ export declare class Release {
     readonly teams: TeamFinder;
     readonly events: EventFinder;
     readonly upcoming: UpcomingFinder;
+    readonly calendar: CalendarFinder;
     readonly tabs: TabFinder;
     readonly panels: PanelFinder;
     readonly feisPanels: FeisPanelFinder;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.33.0",
+	"version": "0.35.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",