@finbheara/archive-client 0.34.0 → 0.36.0

package/README.md

@@ -101,6 +101,9 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `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 |
+| `calendar.missing` | `calendar.missing` | 320 |
 | `tabs`, `panels` | `tabs.query`, `tabs.stream`; `panels.query` | 184 |
 | `feis-panels` | `feisPanels.query` | 260 |
 | `staff.adjudicators` | `staff.adjudicators` | 230 |
@@ -762,8 +765,18 @@ 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
+const m = await rel.calendar.missing({ stage: "results", kind: "platform-host" });
+             // stage, platform, tier, kind; { items: [{ item_id, stage, feis_instance_id, kind,
+             //   platform, expected, expected_basis, expected_n, grace_days, due, overdue_days,
+             //   hosts: [{ source, feis_id, url }], ... }], deferred }
 ```
 
 ONE ROW PER FEIS INSTANCE, on the id its results carry: a feis-series instance (`<brand>.<year>`),
@@ -780,6 +793,32 @@ order: only results after the run is a belief. `get` tries the instance id, 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.
+
+THE MISSING STAGES (`calendar.missing`): a `results` or `entrants` stage no capture has shown whose
+expected day plus its platform's GRACE is before the release's day, the run inside the 365 days
+before it. The grace is the platform's largest gap between two days it was captured on, over the
+180 days before the release, at least 7 days: an item waits out the platform's slowest scrape
+before it counts; a day on the pooled lag (basis `pooled`), or a platform with no gap of its own,
+waits the pooled grace. A stage whose basis is `unmeasured` is never missing. An item is a calendar
+instance, or a feis-index listing no instance holds (`feis_instance_id` null, `item_id` its first
+occurrence id). `kind` is `platform-host` (a capture platform lists it, so a scrape of it should
+bring it) or `listing-only` (only a calendar listing names it, no capture platform, and its results
+may be published nowhere capture reads). A stage a capture's not-found record defers is not listed:
+`deferred` counts those. A worklist, never an error.
+
 ## Teachers and adjudicators
 
 ```ts
@@ -958,6 +997,9 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     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 calendar --missing [--stage results|entrants] [--platform <p>] [--tier <t>]
+                 [--kind platform-host|listing-only]
     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-cwhyrcyx.js → index-c08q1b0d.js}

@@ -722,6 +722,53 @@ var FEATURES2 = [
     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: "calendar.missing",
+    needs: [
+      "item_id",
+      "stage",
+      "feis_instance_id",
+      "feis_brand_id",
+      "tier",
+      "name_printed",
+      "date_lo",
+      "date_hi",
+      "occurrence_ids",
+      "feis_ids",
+      "kind",
+      "platform",
+      "expected",
+      "expected_basis",
+      "expected_n",
+      "grace_days",
+      "due",
+      "overdue_days",
+      "hosts",
+      "deferred"
+    ].map((c) => `results:feis_calendar_missing.${c}`),
+    since: 320,
+    calls: "calendar.missing"
+  },
   {
     feature: "upcoming.entrants",
     needs: [
@@ -3877,13 +3924,26 @@ var CALENDAR_TERMINALS2 = [
   "passed-no-results"
 ];
 var json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
-function entryOf2(r) {
+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
+      cite: r[`${s}_cite`] ?? null,
+      ...expected ? { expected: expectedOf(r, s) } : {}
     }
   ]));
   return {
@@ -3914,6 +3974,73 @@ class CalendarFinder2 {
     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 missing(q = {}) {
+    await this.rel.fetch("results");
+    await this.rel.require("calendar.missing");
+    const db = this.rel.db("results");
+    const where = [];
+    const args = [];
+    for (const [col, v] of [
+      ["stage", q.stage],
+      ["platform", q.platform],
+      ["tier", q.tier],
+      ["kind", q.kind]
+    ])
+      if (v !== undefined) {
+        where.push(`${col} = ?`);
+        args.push(v);
+      }
+    const rows = db.query(`SELECT * FROM feis_calendar_missing${where.length === 0 ? "" : ` WHERE ${where.join(" AND ")}`}
+				 ORDER BY CASE stage WHEN 'results' THEN 0 ELSE 1 END,
+				          CASE kind WHEN 'platform-host' THEN 0 ELSE 1 END, platform, due, item_id`).all(...args);
+    const live = rows.filter((r) => r.deferred === null || r.deferred === undefined);
+    return {
+      tag: this.rel.tag,
+      items: live.map((r) => ({
+        item_id: r.item_id,
+        stage: r.stage,
+        feis_instance_id: r.feis_instance_id ?? null,
+        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,
+        occurrence_ids: json(r.occurrence_ids, []),
+        feis_ids: json(r.feis_ids, []),
+        kind: r.kind,
+        platform: r.platform,
+        expected: r.expected,
+        expected_basis: r.expected_basis,
+        expected_n: r.expected_n === null || r.expected_n === undefined ? null : Number(r.expected_n),
+        grace_days: Number(r.grace_days),
+        due: r.due,
+        overdue_days: Number(r.overdue_days),
+        hosts: json(r.hosts, [])
+      })),
+      deferred: rows.length - live.length
+    };
+  }
   async get(id) {
     const db = await this.db();
     const ways = [
@@ -3924,8 +4051,10 @@ class CalendarFinder2 {
     ];
     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)
-        return { tag: this.rel.tag, asked: id, via, entries: rows.map(entryOf2) };
+      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,
@@ -3967,7 +4096,8 @@ class CalendarFinder2 {
       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);
-    return { tag: this.rel.tag, entries: rows.map(entryOf2) };
+    const e = await this.expected();
+    return { tag: this.rel.tag, entries: rows.map((r) => entryOf2(r, e)) };
   }
 }
 

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-cwhyrcyx.js";
+} from "./chunks/index-c08q1b0d.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
@@ -394,8 +394,19 @@ var VERBS = [
   },
   {
     verb: "calendar",
-    value: ["--release", "--brand", "--tier", "--from", "--to", "--stage", "--state", "--terminal"],
-    bool: [],
+    value: [
+      "--release",
+      "--brand",
+      "--tier",
+      "--from",
+      "--to",
+      "--stage",
+      "--state",
+      "--terminal",
+      "--platform",
+      "--kind"
+    ],
+    bool: ["--next", "--missing"],
     usage: [
       "  calendar [--release <spec>] <instance|feis id|occurrence id>",
       "                                    one feis instance's stages: announced, syllabus, entrants,",
@@ -404,7 +415,16 @@ var VERBS = [
       "  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"
+      "                                    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)",
+      "  calendar --missing [--stage results|entrants] [--platform <p>] [--tier T1..T4]",
+      "           [--kind platform-host|listing-only]",
+      "                                    the stages past their expected day plus the platform's",
+      "                                    grace, the run in the last 365 days: hosts, urls, expected",
+      "                                    day, grace and days overdue; the deferred counted apart"
     ]
   },
   {
@@ -523,6 +543,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})`);
@@ -1553,13 +1574,44 @@ async function main(argv, io = {}) {
         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("--missing")) {
+            const stage = p.flags.get("--stage");
+            const platform = p.flags.get("--platform");
+            const tier = p.flags.get("--tier");
+            const kind = p.flags.get("--kind");
+            const a = await rel.calendar.missing({
+              ...stage !== undefined ? { stage } : {},
+              ...platform !== undefined ? { platform } : {},
+              ...tier !== undefined ? { tier } : {},
+              ...kind !== undefined ? { kind } : {}
+            });
+            out(a, () => {
+              for (const m of a.items) {
+                say(`  ${m.due}  ${m.item_id}  ${m.stage}  ${m.kind}  ${m.platform}  run ${m.date_lo ?? "?"}  expected ${m.expected} (${m.expected_basis}, n ${m.expected_n ?? "-"}) + ${m.grace_days} grace  ${m.overdue_days} days overdue${m.name_printed !== null ? `  "${m.name_printed}"` : ""}`);
+                for (const h of m.hosts)
+                  say(`      ${h.source}  ${h.feis_id ?? "-"}  ${h.url ?? "-"}`);
+              }
+              say(`${a.items.length} missing, ${a.deferred} deferred, in ${a.tag}`);
+            });
+            return a.items.length === 0 ? 1 : 0;
+          }
+          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)" : ""}`);
+                  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}`);
             });

package/dist/index.js

@@ -80,7 +80,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-cwhyrcyx.js";
+} from "./chunks/index-c08q1b0d.js";
 import {
   cacheRoot2,
   repoOf2

package/dist/types/calendar.d.ts

@@ -5,10 +5,18 @@ 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;
@@ -38,6 +46,58 @@ 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 type CalendarMissingStage = "results" | "entrants";
+export type CalendarMissingKind = "platform-host" | "listing-only";
+export interface CalendarMissingHost {
+    source: string;
+    feis_id: string | null;
+    url: string | null;
+}
+export interface CalendarMissing {
+    item_id: string;
+    stage: CalendarMissingStage;
+    feis_instance_id: string | null;
+    feis_brand_id: string | null;
+    tier: string;
+    name_printed: string | null;
+    date_lo: string | null;
+    date_hi: string | null;
+    occurrence_ids: string[];
+    feis_ids: string[];
+    kind: CalendarMissingKind;
+    platform: string;
+    expected: string;
+    expected_basis: CalendarExpectedBasis;
+    expected_n: number | null;
+    grace_days: number;
+    due: string;
+    overdue_days: number;
+    hosts: CalendarMissingHost[];
+}
+export interface CalendarMissingQuery {
+    stage?: CalendarMissingStage;
+    platform?: string;
+    tier?: string;
+    kind?: CalendarMissingKind;
+}
+export interface CalendarMissingAnswer {
+    tag: string;
+    items: CalendarMissing[];
+    deferred: number;
+}
 export interface CalendarGetAnswer {
     tag: string;
     asked: string;
@@ -49,6 +109,11 @@ export declare class CalendarFinder {
     private readonly rel;
     constructor(rel: Release);
     private db;
+    private expected;
+    next(q?: {
+        brand?: string;
+    }): Promise<CalendarNextAnswer>;
+    missing(q?: CalendarMissingQuery): Promise<CalendarMissingAnswer>;
     get(id: string): Promise<CalendarGetAnswer>;
     list(q?: CalendarQuery): Promise<CalendarAnswer>;
 }

package/dist/types/index.d.ts

@@ -26,5 +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, CalendarFinder, type CalendarGetAnswer, type CalendarQuery, type CalendarStage, type CalendarStageState, type CalendarStageValue, type CalendarTerminal, } from "./calendar.js";
+export { CALENDAR_STAGES, CALENDAR_STAGE_STATES, CALENDAR_TERMINALS, type CalendarAnswer, type CalendarEntry, type CalendarExpected, type CalendarExpectedBasis, type CalendarMissing, type CalendarMissingAnswer, type CalendarMissingHost, type CalendarMissingKind, type CalendarMissingQuery, type CalendarMissingStage, 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/package.json

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