@plantnet/planttaxomatcher 0.1.3 → 0.2.0

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire } from "module";
 import { promises as fs4 } from "fs";
 import { parse as parsePath } from "path";
 import { confirm, password } from "@inquirer/prompts";
@@ -31,7 +32,9 @@ var evidenceTypeSchema = z2.enum([
   "local_fuzzy",
   "external_fuzzy",
   "team_history",
-  "llm"
+  "llm",
+  // Resolved via the OTHER backbone (WFO↔WCVP) then mapped back to the target.
+  "cross_backbone"
 ]);
 var gradeSchema = z2.enum(["A", "B", "C"]);
 var reviewStatusSchema = z2.enum(["not_required", "pending", "accepted", "rejected", "overridden"]);
@@ -59,8 +62,80 @@ var scoreBreakdownSchema = z2.object({
 });
 
 // ../shared/src/schemas/job.ts
+import { z as z4 } from "zod";
+
+// ../shared/src/schemas/plugins.ts
 import { z as z3 } from "zod";
-var jobStatusSchema = z3.enum([
+var verifierStateSchema = z3.enum(["pass", "fail", "error", "skipped"]);
+var verifierColumnKindSchema = z3.enum(["check", "badge", "link", "text"]);
+var verifierColumnSchema = z3.object({
+  /** Export column id, e.g. `verify_plantnet`. */
+  key: z3.string(),
+  /** Human-facing header. */
+  header: z3.string(),
+  kind: verifierColumnKindSchema
+});
+var pluginRunStatusSchema = z3.enum(["queued", "running", "completed", "failed", "cancelled"]);
+var pluginRunTriggerSchema = z3.enum(["auto", "manual"]);
+var pluginConfigOptionSchema = z3.object({
+  value: z3.string(),
+  label: z3.string()
+});
+var pluginConfigFieldSchema = z3.object({
+  key: z3.string(),
+  label: z3.string(),
+  type: z3.literal("select"),
+  options: z3.array(pluginConfigOptionSchema).min(1),
+  default: z3.string()
+});
+var pluginDescriptorSchema = z3.object({
+  id: z3.string(),
+  version: z3.string(),
+  title: z3.string(),
+  description: z3.string(),
+  /** Deployment can actually run it (key/env present). */
+  available: z3.boolean(),
+  columns: z3.array(verifierColumnSchema),
+  configFields: z3.array(pluginConfigFieldSchema)
+});
+var pluginRunRequestSchema = z3.object({
+  config: z3.record(z3.string(), z3.string()).default({})
+});
+var pluginRunSummarySchema = z3.object({
+  id: z3.string().uuid(),
+  jobId: z3.string().ulid(),
+  pluginId: z3.string(),
+  pluginVersion: z3.string(),
+  config: z3.record(z3.string(), z3.unknown()),
+  status: pluginRunStatusSchema,
+  trigger: pluginRunTriggerSchema,
+  totalUnits: z3.number().int().nonnegative(),
+  processedUnits: z3.number().int().nonnegative(),
+  passUnits: z3.number().int().nonnegative(),
+  errorUnits: z3.number().int().nonnegative(),
+  /** Label of the token that triggered a manual run; null for auto runs. */
+  triggeredBy: z3.string().nullable(),
+  /** `failed` run: why it stopped. `completed` run: why its errored rows
+   * couldn't be checked (most frequent reasons first). */
+  error: z3.string().nullable(),
+  createdAt: z3.string().datetime(),
+  startedAt: z3.string().datetime().nullable(),
+  completedAt: z3.string().datetime().nullable()
+});
+var pluginRunsResponseSchema = z3.object({
+  runs: z3.array(pluginRunSummarySchema)
+});
+var jobRowPluginResultSchema = z3.object({
+  pluginId: z3.string(),
+  state: verifierStateSchema,
+  label: z3.string().nullable(),
+  url: z3.string().nullable(),
+  /** Why this verdict — the error reason, or what a `fail` was checked against. */
+  detail: z3.string().nullable()
+});
+
+// ../shared/src/schemas/job.ts
+var jobStatusSchema = z4.enum([
   "queued",
   "parsing",
   "matching",
@@ -69,39 +144,87 @@ var jobStatusSchema = z3.enum([
   "completed",
   "failed"
 ]);
-var authorModeSchema = z3.enum(["ignore", "prefer", "strict"]);
-var reviewModeSchema = z3.enum(["off", "recommended", "strict"]);
-var jobConfigSchema = z3.object({
-  nameColumn: z3.string().min(1),
-  idColumn: z3.string().nullable().optional(),
-  familyColumn: z3.string().nullable().optional(),
-  genusColumn: z3.string().nullable().optional(),
-  rankColumn: z3.string().nullable().optional(),
-  authorColumn: z3.string().nullable().optional(),
-  sourceReferentialColumn: z3.string().nullable().optional(),
-  sourceIdColumn: z3.string().nullable().optional(),
+var authorModeSchema = z4.enum(["ignore", "prefer", "strict"]);
+var reviewModeSchema = z4.enum(["off", "recommended", "strict"]);
+var jobConfigSchema = z4.object({
+  nameColumn: z4.string().min(1),
+  idColumn: z4.string().nullable().optional(),
+  familyColumn: z4.string().nullable().optional(),
+  genusColumn: z4.string().nullable().optional(),
+  rankColumn: z4.string().nullable().optional(),
+  authorColumn: z4.string().nullable().optional(),
+  sourceReferentialColumn: z4.string().nullable().optional(),
+  sourceIdColumn: z4.string().nullable().optional(),
   authorMode: authorModeSchema.default("prefer"),
-  matchAuthors: z3.boolean().default(true),
-  parallelism: z3.number().int().min(1).max(10).default(4),
-  allowFuzzy: z3.boolean().default(true),
-  allowLlm: z3.boolean().default(false),
-  llmCostCapCents: z3.number().int().min(0).default(500),
+  matchAuthors: z4.boolean().default(true),
+  parallelism: z4.number().int().min(1).max(10).default(4),
+  allowFuzzy: z4.boolean().default(true),
+  allowLlm: z4.boolean().default(false),
+  llmCostCapCents: z4.number().int().min(0).default(500),
   reviewMode: reviewModeSchema.default("recommended"),
-  exportConfirmedOnly: z3.boolean().default(false),
+  exportConfirmedOnly: z4.boolean().default(false),
+  /**
+   * When false, this job's review decisions (accept + reject) do NOT feed the
+   * team's Layer 0.5 match-history cache — a one-off or experimental job can't
+   * teach (or poison) the shared cache. Default false (opt-in).
+   */
+  contributeToTeamCache: z4.boolean().default(false),
+  /**
+   * Roll infraspecific results up to the species: when an input resolves to an
+   * infraspecific accepted taxon (Variety / Subspecies / Form / …), replace it
+   * with its parent Species so every output row sits at species level.
+   *
+   * Default FALSE — the resolved rank is preserved as-is. Rolling up discards
+   * information the source data carried, so it is opt-in: turn it on only when
+   * the consuming system works at species level and you would otherwise have to
+   * flatten the export yourself.
+   */
+  speciesLevelAcceptedOnly: z4.boolean().default(false),
+  /**
+   * "The author isn't important." When the canonical name matches exactly one
+   * taxon but the input's author could not be CONFIRMED (flag
+   * `author-unconfirmed`), auto-accept the match instead of sending it to
+   * review. The taxon itself was never in doubt in that case — only whether
+   * the author string cites it the way WCVP does — so a dataset whose author
+   * column is unreliable (or absent from the source) can skip that queue.
+   *
+   * Default FALSE. This does NOT relax a genuine author CONFLICT
+   * (`author-mismatch`): a conflicting author may point at a different plant,
+   * so those still go to review. Every other review trigger (qualifiers,
+   * parse quality, force-review families, alternatives) is untouched.
+   */
+  acceptUnconfirmedAuthor: z4.boolean().default(false),
+  /**
+   * Which taxonomic backbone to match against. `wcvp` (default) runs the full
+   * cascade; `wfo` matches against the World Flora Online snapshot using the
+   * local layers (L1–L4). Stored on `jobs.referential`.
+   */
+  referential: z4.enum(["wcvp", "wfo"]).default("wcvp"),
+  /**
+   * Which snapshot version of the chosen backbone to match against. When
+   * omitted, the API resolves it at submit time: the team's configured default
+   * snapshot for this backbone (Admin → Backbone) when it is still installed,
+   * otherwise the most-recently-imported one. The job stores the resolved
+   * version on `jobs.referential_version` so re-runs are reproducible even if
+   * a newer snapshot lands later.
+   */
+  referentialVersion: z4.string().min(1).optional(),
   /**
-   * Keep the identified accepted name at species level: when an input
-   * resolves to an infraspecific accepted taxon (Variety / Subspecies /
-   * Form / …), collapse it up to its parent Species. Default true; set false
-   * to keep the exact infraspecific accepted taxon.
+   * WGSRPD Level-3 area code (e.g. 'MAS' = Massachusetts) the import is scoped
+   * to. When set, an ambiguous multi-candidate match is narrowed to the taxa
+   * that occur in this area — exactly one survivor resolves the match (Grade B,
+   * flagged `resolved-by-area:<code>`). null/omitted = no disambiguation.
    */
-  speciesLevelAcceptedOnly: z3.boolean().default(true),
+  area: z4.string().nullable().optional(),
   /**
-   * Which WCVP snapshot to match against. When omitted, the API picks the
-   * most-recently-imported snapshot at submit time. The job stores the
-   * resolved version on `jobs.referential_version` so re-runs are
-   * reproducible even if a newer snapshot lands later.
+   * Auto-run the Pl@ntNet verification plugin for this job at completion —
+   * tags each match with whether its accepted taxon aligns to a Pl@ntNet
+   * species. Defaults on; set false to skip the auto-run for this job (it can
+   * still be triggered manually from the Plugins menu). Only has an effect
+   * when the server has Pl@ntNet configured (key set + not globally disabled);
+   * otherwise it is a no-op regardless.
    */
-  referentialVersion: z3.string().min(1).optional(),
+  plantnet: z4.boolean().optional(),
   /**
    * Row filter: keep only rows whose `filterColumn` value equals
    * `filterValue` (trimmed, case-insensitive); all other rows are skipped at
@@ -109,306 +232,403 @@ var jobConfigSchema = z3.object({
    * apply. Lets a user match a subset of a mixed file (e.g. only
    * `kingdom = Plantae`).
    */
-  filterColumn: z3.string().nullable().optional(),
-  filterValue: z3.string().nullable().optional()
+  filterColumn: z4.string().nullable().optional(),
+  filterValue: z4.string().nullable().optional()
 });
-var wcvpSnapshotSummarySchema = z3.object({
-  version: z3.string(),
-  recordCount: z3.number().int().nonnegative(),
-  importedAt: z3.string().datetime(),
-  isLatest: z3.boolean()
-});
-var idTypeDetectionSchema = z3.object({
-  sampleSize: z3.number().int().nonnegative(),
-  counts: z3.record(z3.string(), z3.number().int().nonnegative()),
-  dominant: z3.string().nullable(),
-  dominantConfidence: z3.number().min(0).max(1),
-  minorityExamples: z3.array(
-    z3.object({
-      rowIndex: z3.number().int().nonnegative(),
-      value: z3.string(),
-      type: z3.string()
+var wcvpSnapshotSummarySchema = z4.object({
+  version: z4.string(),
+  recordCount: z4.number().int().nonnegative(),
+  importedAt: z4.string().datetime(),
+  /** Newest OFFICIAL snapshot (derived ones never count as latest). */
+  isLatest: z4.boolean(),
+  kind: z4.enum(["official", "derived"]),
+  baseVersion: z4.string().nullable(),
+  label: z4.string().nullable(),
+  ownerTeamId: z4.string().nullable()
+});
+var idTypeDetectionSchema = z4.object({
+  sampleSize: z4.number().int().nonnegative(),
+  counts: z4.record(z4.string(), z4.number().int().nonnegative()),
+  dominant: z4.string().nullable(),
+  dominantConfidence: z4.number().min(0).max(1),
+  minorityExamples: z4.array(
+    z4.object({
+      rowIndex: z4.number().int().nonnegative(),
+      value: z4.string(),
+      type: z4.string()
     })
   )
 });
-var publicAccessSchema = z3.enum(["none", "read", "review"]);
-var jobSummarySchema = z3.object({
-  id: z3.string().ulid(),
-  teamId: z3.string().uuid(),
-  userId: z3.string().uuid(),
+var publicAccessSchema = z4.enum(["none", "read", "review"]);
+var jobSummarySchema = z4.object({
+  id: z4.string().ulid(),
+  teamId: z4.string().uuid(),
+  userId: z4.string().uuid(),
   /** Optional user-supplied label. URL still uses `id`; null when unset. */
-  name: z3.string().nullable(),
-  /** Display name of the user who submitted the job (from their token's
-   * user). Null when unavailable (e.g. mutation responses). */
-  submittedBy: z3.string().nullable(),
+  name: z4.string().nullable(),
+  /** The job's author: the label of the token that submitted it (snapshotted
+   * at creation, so it survives the token being renamed or revoked). Null for
+   * jobs created before authorship was tracked. */
+  submittedBy: z4.string().nullable(),
   status: jobStatusSchema,
   /** 'none' = private. 'read'/'review' = anyone with the link, no sign-in. */
   publicAccess: publicAccessSchema,
-  referentialVersion: z3.string(),
-  idColumn: z3.string().nullable(),
+  referentialVersion: z4.string(),
+  idColumn: z4.string().nullable(),
   idTypeDetection: idTypeDetectionSchema.nullable(),
-  totalRows: z3.number().int().nonnegative(),
-  uniqueQueries: z3.number().int().nonnegative(),
-  processedRows: z3.number().int().nonnegative(),
-  matchedRows: z3.number().int().nonnegative(),
-  ambiguousRows: z3.number().int().nonnegative(),
-  errorRows: z3.number().int().nonnegative(),
-  needsReviewRows: z3.number().int().nonnegative(),
-  llmCostCents: z3.number().int().nonnegative(),
-  llmCostCapCents: z3.number().int().nonnegative(),
-  createdAt: z3.string().datetime(),
-  startedAt: z3.string().datetime().nullable(),
-  completedAt: z3.string().datetime().nullable(),
-  expiresAt: z3.string().datetime()
+  totalRows: z4.number().int().nonnegative(),
+  uniqueQueries: z4.number().int().nonnegative(),
+  processedRows: z4.number().int().nonnegative(),
+  matchedRows: z4.number().int().nonnegative(),
+  ambiguousRows: z4.number().int().nonnegative(),
+  errorRows: z4.number().int().nonnegative(),
+  needsReviewRows: z4.number().int().nonnegative(),
+  llmCostCents: z4.number().int().nonnegative(),
+  llmCostCapCents: z4.number().int().nonnegative(),
+  createdAt: z4.string().datetime(),
+  startedAt: z4.string().datetime().nullable(),
+  completedAt: z4.string().datetime().nullable(),
+  expiresAt: z4.string().datetime()
 });
-var jobPublicAccessUpdateSchema = z3.object({
+var jobPublicAccessUpdateSchema = z4.object({
   publicAccess: publicAccessSchema
 });
-var progressEventSchema = z3.object({
-  type: z3.enum(["progress", "status", "error", "completed"]),
-  jobId: z3.string().ulid(),
-  timestamp: z3.string().datetime(),
-  processedRows: z3.number().int().nonnegative().optional(),
-  totalRows: z3.number().int().nonnegative().optional(),
+var jobRenameSchema = z4.object({
+  name: z4.string().trim().min(1).max(200)
+});
+var progressEventSchema = z4.object({
+  type: z4.enum(["progress", "status", "error", "completed"]),
+  jobId: z4.string().ulid(),
+  timestamp: z4.string().datetime(),
+  processedRows: z4.number().int().nonnegative().optional(),
+  totalRows: z4.number().int().nonnegative().optional(),
   status: jobStatusSchema.optional(),
-  message: z3.string().optional()
+  message: z4.string().optional()
 });
-var taxonIdentifierRefSchema = z3.object({
-  namespace: z3.string(),
-  value: z3.string()
+var taxonIdentifierRefSchema = z4.object({
+  namespace: z4.string(),
+  value: z4.string()
 });
-var jobRowSummarySchema = z3.object({
-  id: z3.string().uuid(),
-  rowIndex: z3.number().int().nonnegative(),
-  inputName: z3.string().nullable(),
-  inputId: z3.string().nullable(),
-  inputFamily: z3.string().nullable(),
+var jobRowSummarySchema = z4.object({
+  id: z4.string().uuid(),
+  rowIndex: z4.number().int().nonnegative(),
+  inputName: z4.string().nullable(),
+  inputId: z4.string().nullable(),
+  inputFamily: z4.string().nullable(),
   matchStatus: matchStatusSchema.nullable(),
   grade: gradeSchema.nullable(),
-  evidenceType: z3.string().nullable(),
+  evidenceType: z4.string().nullable(),
   reviewStatus: reviewStatusSchema,
-  matchQueryId: z3.string().uuid().nullable(),
-  confidence: z3.number().nullable(),
-  layer: z3.string().nullable(),
-  flags: z3.array(z3.string()).nullable(),
-  candidateAcceptedName: z3.string().nullable(),
+  matchQueryId: z4.string().uuid().nullable(),
+  confidence: z4.number().nullable(),
+  layer: z4.string().nullable(),
+  flags: z4.array(z4.string()).nullable(),
+  candidateAcceptedName: z4.string().nullable(),
   /** Authorship of the accepted taxon (distinct from `candidateAuthorship`
    * which carries the matched-row author when the match resolves via a synonym). */
-  candidateAcceptedAuthorship: z3.string().nullable(),
-  candidateAcceptedIdentifiers: z3.array(taxonIdentifierRefSchema).nullable(),
-  candidateScientificName: z3.string().nullable(),
-  candidateAuthorship: z3.string().nullable(),
-  candidateFamily: z3.string().nullable(),
-  candidateReason: z3.string().nullable(),
-  candidateTargetUrl: z3.string().nullable()
-});
-var gradeCountsSchema = z3.object({
-  A: z3.number().int().nonnegative(),
-  B: z3.number().int().nonnegative(),
-  C: z3.number().int().nonnegative(),
-  ungraded: z3.number().int().nonnegative()
-});
-var statusCountsSchema = z3.object({
-  matched: z3.number().int().nonnegative(),
-  ambiguous: z3.number().int().nonnegative(),
-  no_match: z3.number().int().nonnegative(),
-  error: z3.number().int().nonnegative(),
-  skipped: z3.number().int().nonnegative(),
+  candidateAcceptedAuthorship: z4.string().nullable(),
+  candidateAcceptedIdentifiers: z4.array(taxonIdentifierRefSchema).nullable(),
+  candidateScientificName: z4.string().nullable(),
+  candidateAuthorship: z4.string().nullable(),
+  candidateFamily: z4.string().nullable(),
+  candidateReason: z4.string().nullable(),
+  candidateTargetUrl: z4.string().nullable(),
+  /** Post-job verification-plugin results for this row, one per plugin that
+   * has a completed run. Empty when no plugin has run. Sourced from
+   * `job_plugin_results` joined via the row's match query. */
+  plugins: z4.array(jobRowPluginResultSchema).default([])
+});
+var gradeCountsSchema = z4.object({
+  A: z4.number().int().nonnegative(),
+  B: z4.number().int().nonnegative(),
+  C: z4.number().int().nonnegative(),
+  ungraded: z4.number().int().nonnegative()
+});
+var statusCountsSchema = z4.object({
+  matched: z4.number().int().nonnegative(),
+  ambiguous: z4.number().int().nonnegative(),
+  no_match: z4.number().int().nonnegative(),
+  error: z4.number().int().nonnegative(),
+  skipped: z4.number().int().nonnegative(),
   /** Rows whose match query exists but hasn't been processed yet (mid-run).
    * Distinct from `skipped` (no query — empty/guarded input). Not part of the
    * outcome funnel; the SPA can show it as in-progress. */
-  pending: z3.number().int().nonnegative()
+  pending: z4.number().int().nonnegative()
 });
-var jobRowsPageSchema = z3.object({
-  rows: z3.array(jobRowSummarySchema),
+var layerCountsSchema = z4.record(z4.string(), z4.number().int().nonnegative());
+var jobRowsPageSchema = z4.object({
+  rows: z4.array(jobRowSummarySchema),
   /** Row count matching the CURRENT filter (not the whole job) — drives
    * pagination so page count adapts to active grade/status/search/conf filters. */
-  total: z3.number().int().nonnegative(),
-  offset: z3.number().int().nonnegative(),
-  limit: z3.number().int().positive(),
+  total: z4.number().int().nonnegative(),
+  offset: z4.number().int().nonnegative(),
+  limit: z4.number().int().positive(),
   /** Per-grade row counts for the whole job, independent of the current
    * filter. Used by the SPA to show "B (12)" next to each grade chip. */
   gradeCounts: gradeCountsSchema,
   /** Per-status row counts (matched / ambiguous / no_match / error /
    * skipped), same scope + purpose as `gradeCounts`. */
-  statusCounts: statusCountsSchema
-});
-var wcvpSearchHitSchema = z3.object({
-  taxonId: z3.string(),
-  scientificName: z3.string(),
-  canonicalName: z3.string(),
-  authorship: z3.string().nullable(),
-  rank: z3.string().nullable(),
-  taxonomicStatus: z3.string().nullable(),
-  family: z3.string().nullable(),
-  acceptedTaxonId: z3.string().nullable(),
-  acceptedName: z3.string().nullable(),
-  similarity: z3.number()
-});
-var wcvpSearchResponseSchema = z3.array(wcvpSearchHitSchema);
-var jobDiffRowSchema = z3.object({
-  rowId: z3.string().uuid(),
-  rowIndex: z3.number().int().nonnegative(),
-  inputName: z3.string().nullable(),
-  inputFamily: z3.string().nullable(),
-  matchedName: z3.string().nullable(),
-  matchedAuthorship: z3.string().nullable(),
-  matchedTaxonomicStatus: z3.string().nullable(),
-  acceptedName: z3.string().nullable(),
-  acceptedAuthorship: z3.string().nullable(),
-  acceptedFamily: z3.string().nullable(),
-  isSynonym: z3.boolean(),
-  familyChanged: z3.boolean(),
+  statusCounts: statusCountsSchema,
+  /** Per-layer row counts, keyed by evidence type. Same scope + purpose as
+   * `gradeCounts`; only layers present in the job appear. */
+  layerCounts: layerCountsSchema
+});
+var wcvpRankLevelSchema = z4.enum(["genus", "species", "infra"]);
+var wcvpSearchHitSchema = z4.object({
+  taxonId: z4.string(),
+  scientificName: z4.string(),
+  canonicalName: z4.string(),
+  authorship: z4.string().nullable(),
+  rank: z4.string().nullable(),
+  taxonomicStatus: z4.string().nullable(),
+  family: z4.string().nullable(),
+  acceptedTaxonId: z4.string().nullable(),
+  acceptedName: z4.string().nullable(),
+  similarity: z4.number()
+});
+var wcvpSearchResponseSchema = z4.array(wcvpSearchHitSchema);
+var speciesRollupStatusSchema = z4.enum([
+  "available",
+  "already-species",
+  "no-species-ancestor",
+  "no-selection",
+  "unknown-taxon"
+]);
+var speciesRollupTaxonSchema = z4.object({
+  taxonId: z4.string(),
+  scientificName: z4.string(),
+  canonicalName: z4.string(),
+  authorship: z4.string().nullable(),
+  rank: z4.string().nullable(),
+  family: z4.string().nullable()
+});
+var speciesRollupResponseSchema = z4.object({
+  status: speciesRollupStatusSchema,
+  /** The accepted taxon the row currently resolves to. */
+  current: speciesRollupTaxonSchema.nullable(),
+  /** Only set when `status` is `available`. */
+  target: speciesRollupTaxonSchema.nullable()
+});
+var jobDiffRowSchema = z4.object({
+  rowId: z4.string().uuid(),
+  rowIndex: z4.number().int().nonnegative(),
+  inputName: z4.string().nullable(),
+  inputFamily: z4.string().nullable(),
+  matchedName: z4.string().nullable(),
+  matchedAuthorship: z4.string().nullable(),
+  matchedTaxonomicStatus: z4.string().nullable(),
+  acceptedName: z4.string().nullable(),
+  acceptedAuthorship: z4.string().nullable(),
+  acceptedFamily: z4.string().nullable(),
+  isSynonym: z4.boolean(),
+  familyChanged: z4.boolean(),
   grade: gradeSchema.nullable(),
   reviewStatus: reviewStatusSchema,
-  targetUrl: z3.string().nullable()
+  targetUrl: z4.string().nullable()
 });
-var jobDiffPageSchema = z3.object({
-  rows: z3.array(jobDiffRowSchema),
-  total: z3.number().int().nonnegative()
+var jobDiffPageSchema = z4.object({
+  rows: z4.array(jobDiffRowSchema),
+  total: z4.number().int().nonnegative()
 });
-var reviewActionSchema = z3.enum(["accept", "reject"]);
-var reviewRequestSchema = z3.object({
+var reviewActionSchema = z4.enum(["accept", "reject"]);
+var reviewRequestSchema = z4.object({
   action: reviewActionSchema,
-  candidateId: z3.string().uuid()
+  // Optional so a row with no candidates can still be resolved as "no
+  // match" (reject with no candidate). Accept always needs one.
+  candidateId: z4.string().uuid().optional()
+}).refine((v) => v.action === "reject" || !!v.candidateId, {
+  message: "candidateId is required to accept a candidate",
+  path: ["candidateId"]
 });
-var bulkReviewRequestSchema = z3.object({
+var bulkReviewRequestSchema = z4.object({
   action: reviewActionSchema,
-  filter: z3.object({
+  filter: z4.object({
     grade: gradeSchema.optional(),
     matchStatus: matchStatusSchema.optional(),
-    family: z3.string().optional()
+    family: z4.string().optional(),
+    /** Restrict the bulk action to these specific match-query ids. The
+     * review queue's grouped/batch view computes a group's membership
+     * client-side (by issue category or author-equivalence pair) and
+     * sends the exact ids — flag/category logic that a coarse
+     * grade/family filter can't express. ANDed with any other filter;
+     * the server still restricts to currently-pending, owned queries. */
+    matchQueryIds: z4.array(z4.string().uuid()).max(5e4).optional()
   }).default({}),
-  dryRun: z3.boolean().default(false)
+  dryRun: z4.boolean().default(false)
 });
-var bulkReviewResponseSchema = z3.object({
+var bulkReviewResponseSchema = z4.object({
   action: reviewActionSchema,
-  matchedQueries: z3.number().int().nonnegative(),
-  dryRun: z3.boolean(),
-  appliedAt: z3.string().datetime().nullable()
+  matchedQueries: z4.number().int().nonnegative(),
+  dryRun: z4.boolean(),
+  appliedAt: z4.string().datetime().nullable()
 });
-var reviewResponseSchema = z3.object({
-  matchQueryId: z3.string().uuid(),
+var reviewResponseSchema = z4.object({
+  matchQueryId: z4.string().uuid(),
   action: reviewActionSchema,
-  candidateId: z3.string().uuid(),
+  // Null only for a "no match" reject (a row with no candidate). An accept
+  // always resolves to a candidate — the refine catches a server that
+  // returned an accept without one.
+  candidateId: z4.string().uuid().nullable(),
   reviewStatus: reviewStatusSchema,
-  reviewEventId: z3.string().uuid()
+  reviewEventId: z4.string().uuid()
+}).refine((v) => v.action !== "accept" || v.candidateId !== null, {
+  message: "an accept must resolve to a candidateId",
+  path: ["candidateId"]
 });
-var matchAttemptSummarySchema = z3.object({
-  id: z3.string().uuid(),
-  layer: z3.string(),
-  provider: z3.string(),
-  status: z3.string(),
-  durationMs: z3.number().int().nonnegative(),
+var matchAttemptSummarySchema = z4.object({
+  id: z4.string().uuid(),
+  layer: z4.string(),
+  provider: z4.string(),
+  status: z4.string(),
+  durationMs: z4.number().int().nonnegative(),
   // JSONB fields accept any shape. Note: `z.unknown()` infers as optional,
   // so consumers should guard for `undefined` even though we always send
   // them as part of the response.
-  query: z3.unknown(),
-  rawResponseSummary: z3.unknown().nullable(),
-  createdAt: z3.string().datetime()
+  query: z4.unknown(),
+  rawResponseSummary: z4.unknown().nullable(),
+  createdAt: z4.string().datetime()
 });
-var matchCandidateSummarySchema = z3.object({
-  id: z3.string().uuid(),
-  attemptId: z3.string().uuid(),
-  source: z3.string(),
-  sourceId: z3.string().nullable(),
-  scientificName: z3.string(),
-  canonicalName: z3.string(),
-  authorship: z3.string().nullable(),
-  rank: z3.string().nullable(),
-  taxonomicStatus: z3.string().nullable(),
-  acceptedName: z3.string().nullable(),
-  acceptedAuthorship: z3.string().nullable(),
-  acceptedIdentifiers: z3.array(taxonIdentifierRefSchema).nullable(),
-  identifiers: z3.array(taxonIdentifierRefSchema),
-  family: z3.string().nullable(),
-  confidence: z3.number().nullable(),
+var matchCandidateSummarySchema = z4.object({
+  id: z4.string().uuid(),
+  attemptId: z4.string().uuid(),
+  source: z4.string(),
+  sourceId: z4.string().nullable(),
+  scientificName: z4.string(),
+  canonicalName: z4.string(),
+  authorship: z4.string().nullable(),
+  rank: z4.string().nullable(),
+  taxonomicStatus: z4.string().nullable(),
+  acceptedName: z4.string().nullable(),
+  acceptedAuthorship: z4.string().nullable(),
+  acceptedIdentifiers: z4.array(taxonIdentifierRefSchema).nullable(),
+  identifiers: z4.array(taxonIdentifierRefSchema),
+  family: z4.string().nullable(),
+  confidence: z4.number().nullable(),
   grade: gradeSchema.nullable(),
-  reason: z3.string().nullable(),
-  flags: z3.array(z3.string()).nullable(),
-  state: z3.enum(["proposed", "accepted", "rejected", "overridden"]),
-  targetUrl: z3.string().nullable()
+  reason: z4.string().nullable(),
+  flags: z4.array(z4.string()).nullable(),
+  state: z4.enum(["proposed", "accepted", "rejected", "overridden"]),
+  targetUrl: z4.string().nullable()
 });
-var matchQueryDetailSchema = z3.object({
-  id: z3.string().uuid(),
-  jobId: z3.string().ulid(),
-  normalizedInput: z3.string(),
-  parsed: z3.unknown(),
+var matchQueryDetailSchema = z4.object({
+  id: z4.string().uuid(),
+  jobId: z4.string().ulid(),
+  normalizedInput: z4.string(),
+  parsed: z4.unknown(),
   matchStatus: matchStatusSchema.nullable(),
-  evidenceType: z3.string().nullable(),
+  evidenceType: z4.string().nullable(),
   grade: gradeSchema.nullable(),
-  confidence: z3.number().nullable(),
-  flags: z3.array(z3.string()).nullable(),
+  confidence: z4.number().nullable(),
+  flags: z4.array(z4.string()).nullable(),
   reviewStatus: reviewStatusSchema,
-  selectedCandidateId: z3.string().uuid().nullable()
+  selectedCandidateId: z4.string().uuid().nullable()
+});
+var otherVersionMatchSchema = z4.object({
+  version: z4.string(),
+  importedAt: z4.string(),
+  isLatest: z4.boolean(),
+  scientificName: z4.string(),
+  authorship: z4.string().nullable(),
+  taxonomicStatus: z4.string().nullable(),
+  acceptedName: z4.string().nullable()
 });
-var queryCandidatesResponseSchema = z3.object({
+var queryCandidatesResponseSchema = z4.object({
   query: matchQueryDetailSchema,
-  candidates: z3.array(matchCandidateSummarySchema),
-  attempts: z3.array(matchAttemptSummarySchema)
-});
-var reviewChatMessageSchema = z3.object({
-  role: z3.enum(["user", "assistant"]),
-  content: z3.string().min(1).max(4e3)
-});
-var reviewChatBodySchema = z3.object({
-  messages: z3.array(reviewChatMessageSchema).min(1).max(40)
-});
-var reviewChatResponseSchema = z3.object({
-  reply: z3.string(),
-  model: z3.string()
-});
-var replayableLayerSchema = z3.enum(["L1", "L2", "L3", "L4", "L5", "L6", "L7"]);
-var replayLayerBodySchema = z3.object({ layer: replayableLayerSchema });
-var replayCandidateSchema = z3.object({
-  scientificName: z3.string(),
-  canonicalName: z3.string(),
-  authorship: z3.string().nullable(),
-  rank: z3.string().nullable(),
-  taxonomicStatus: z3.string().nullable(),
-  acceptedName: z3.string().nullable(),
-  acceptedAuthorship: z3.string().nullable(),
-  family: z3.string().nullable(),
+  candidates: z4.array(matchCandidateSummarySchema),
+  attempts: z4.array(matchAttemptSummarySchema),
+  /** A newer/other backbone version that has this exact name (see schema). */
+  otherVersionMatch: otherVersionMatchSchema.nullable()
+});
+var reviewChatMessageSchema = z4.object({
+  role: z4.enum(["user", "assistant"]),
+  content: z4.string().min(1).max(4e3)
+});
+var reviewChatBodySchema = z4.object({
+  messages: z4.array(reviewChatMessageSchema).min(1).max(40),
+  /** Let the assistant also search the web (OpenRouter web plugin). Default on
+   * server-side when omitted; the client sends it explicitly from its toggle. */
+  webSearch: z4.boolean().optional(),
+  /** Per-chat model override (an OpenRouter id / alias). When omitted the
+   * team's configured heavy model is used. Length-capped defensively. */
+  model: z4.string().trim().min(1).max(200).optional()
+});
+var reviewChatResponseSchema = z4.object({
+  reply: z4.string(),
+  model: z4.string()
+});
+var reviewChatStreamEventSchema = z4.discriminatedUnion("type", [
+  /** A chunk of the model's visible answer. */
+  z4.object({ type: z4.literal("text"), delta: z4.string() }),
+  /** A chunk of the model's reasoning/thinking (when the model exposes it). */
+  z4.object({ type: z4.literal("reasoning"), delta: z4.string() }),
+  /** The model decided to call a tool, with the (JSON) arguments it chose. */
+  z4.object({ type: z4.literal("tool_call"), id: z4.string(), name: z4.string(), arguments: z4.string() }),
+  /** The result we fed back to the model after running that tool. `sql` is the
+   * statement the tool actually ran, shown to the reviewer for transparency —
+   * it is emitted on this event ONLY and never added to the model's context. */
+  z4.object({
+    type: z4.literal("tool_result"),
+    id: z4.string(),
+    name: z4.string(),
+    result: z4.string(),
+    sql: z4.string().optional()
+  }),
+  /** Terminal success — carries the model id that answered. */
+  z4.object({ type: z4.literal("done"), model: z4.string() }),
+  /** Terminal failure — a human-readable reason. */
+  z4.object({ type: z4.literal("error"), error: z4.string() })
+]);
+var replayableLayerSchema = z4.enum(["L1", "L2", "L3", "L4", "L5", "L6", "L7"]);
+var replayLayerBodySchema = z4.object({ layer: replayableLayerSchema });
+var replayCandidateSchema = z4.object({
+  scientificName: z4.string(),
+  canonicalName: z4.string(),
+  authorship: z4.string().nullable(),
+  rank: z4.string().nullable(),
+  taxonomicStatus: z4.string().nullable(),
+  acceptedName: z4.string().nullable(),
+  acceptedAuthorship: z4.string().nullable(),
+  family: z4.string().nullable(),
   /** WCVP taxon id of the matched row (null for unresolved external proposals). */
-  taxonId: z3.string().nullable(),
+  taxonId: z4.string().nullable(),
   /** WCVP taxon id of the resolved accepted taxon (null when unresolved). */
-  acceptedTaxonId: z3.string().nullable(),
-  confidence: z3.number().nullable(),
-  reason: z3.string().nullable(),
-  flags: z3.array(z3.string()),
-  targetUrl: z3.string().nullable(),
+  acceptedTaxonId: z4.string().nullable(),
+  confidence: z4.number().nullable(),
+  reason: z4.string().nullable(),
+  flags: z4.array(z4.string()),
+  targetUrl: z4.string().nullable(),
   /** Provider that proposed this candidate (e.g. tnrs, gbif, openrouter,
    * wcvp-local). */
-  provider: z3.string().nullable()
+  provider: z4.string().nullable()
 });
-var replayAttemptSchema = z3.object({
-  provider: z3.string(),
-  status: z3.string(),
-  durationMs: z3.number().int().nonnegative(),
-  summary: z3.unknown().nullable()
+var replayAttemptSchema = z4.object({
+  provider: z4.string(),
+  status: z4.string(),
+  durationMs: z4.number().int().nonnegative(),
+  summary: z4.unknown().nullable()
 });
-var replayLayerResultSchema = z3.object({
+var replayLayerResultSchema = z4.object({
   layer: replayableLayerSchema,
-  kind: z3.enum(["unique", "ambiguous", "miss"]),
-  reason: z3.string().nullable(),
+  kind: z4.enum(["unique", "ambiguous", "miss"]),
+  reason: z4.string().nullable(),
   /** Human-facing note when the layer couldn't run as-is (e.g. LLM not
    * configured, no external providers enabled). */
-  note: z3.string().nullable(),
-  providers: z3.array(z3.string()),
-  durationMs: z3.number().int().nonnegative(),
+  note: z4.string().nullable(),
+  providers: z4.array(z4.string()),
+  durationMs: z4.number().int().nonnegative(),
   /** What was actually submitted to the layer (post gnparser). */
-  query: z3.object({
-    canonical: z3.string(),
-    authorship: z3.string().nullable(),
-    inputId: z3.string().nullable()
+  query: z4.object({
+    canonical: z4.string(),
+    authorship: z4.string().nullable(),
+    inputId: z4.string().nullable()
   }),
-  candidates: z3.array(replayCandidateSchema),
-  attempts: z3.array(replayAttemptSchema)
+  candidates: z4.array(replayCandidateSchema),
+  attempts: z4.array(replayAttemptSchema)
 });
 
 // ../shared/src/schemas/auth.ts
-import { z as z4 } from "zod";
-var tokenScopeSchema = z4.enum([
+import { z as z5 } from "zod";
+var tokenScopeSchema = z5.enum([
   "submit:job",
   "read:job",
   "cancel:job",
@@ -420,77 +640,83 @@ var tokenScopeSchema = z4.enum([
   "admin:teams"
 ]);
 var ALL_TOKEN_SCOPES = tokenScopeSchema.options;
-var tokenStringSchema = z4.string().regex(/^ptm_[a-zA-Z0-9]{12}_[a-zA-Z0-9]{32}$/, "Malformed token");
-var meSchema = z4.object({
-  userId: z4.string().uuid(),
-  teamId: z4.string().uuid(),
-  displayName: z4.string(),
-  scopes: z4.array(tokenScopeSchema),
-  tokenLabel: z4.string().nullable()
+var tokenStringSchema = z5.string().regex(/^ptm_[a-zA-Z0-9]{12}_[a-zA-Z0-9]{32}$/, "Malformed token");
+var meSchema = z5.object({
+  userId: z5.string().uuid(),
+  teamId: z5.string().uuid(),
+  displayName: z5.string(),
+  scopes: z5.array(tokenScopeSchema),
+  tokenLabel: z5.string().nullable(),
+  /** DB id of the token that authenticated this request — matches a row's
+   * `id` in the admin token list, so the UI can highlight "this is you". */
+  tokenId: z5.string().uuid().nullable()
 });
-var tokenCreateBodySchema = z4.object({
-  label: z4.string().min(1).max(120),
-  scopes: z4.array(tokenScopeSchema).min(1),
-  expiresAt: z4.string().datetime().optional()
+var tokenCreateBodySchema = z5.object({
+  label: z5.string().min(1).max(120),
+  scopes: z5.array(tokenScopeSchema).min(1),
+  expiresAt: z5.string().datetime().optional()
 });
-var tokenSummarySchema = z4.object({
-  id: z4.string().uuid(),
-  tokenIdPrefix: z4.string(),
-  label: z4.string(),
-  displayName: z4.string(),
-  scopes: z4.array(tokenScopeSchema),
-  createdAt: z4.string().datetime(),
-  lastUsedAt: z4.string().datetime().nullable(),
-  expiresAt: z4.string().datetime().nullable()
+var tokenRenameSchema = z5.object({
+  label: z5.string().trim().min(1).max(120)
+});
+var tokenSummarySchema = z5.object({
+  id: z5.string().uuid(),
+  tokenIdPrefix: z5.string(),
+  label: z5.string(),
+  displayName: z5.string(),
+  scopes: z5.array(tokenScopeSchema),
+  createdAt: z5.string().datetime(),
+  lastUsedAt: z5.string().datetime().nullable(),
+  expiresAt: z5.string().datetime().nullable()
 });
 var tokenCreatedSchema = tokenSummarySchema.extend({
   tokenString: tokenStringSchema
 });
-var teamSummarySchema = z4.object({
-  id: z4.string().uuid(),
-  name: z4.string(),
-  createdAt: z4.string().datetime()
+var teamSummarySchema = z5.object({
+  id: z5.string().uuid(),
+  name: z5.string(),
+  createdAt: z5.string().datetime()
 });
-var teamCreateBodySchema = z4.object({
-  name: z4.string().min(1).max(120),
-  initialUserDisplayName: z4.string().min(1).max(120).default("Admin"),
-  initialToken: z4.object({
-    label: z4.string().min(1).max(120),
-    scopes: z4.array(tokenScopeSchema).min(1)
+var teamCreateBodySchema = z5.object({
+  name: z5.string().min(1).max(120),
+  initialUserDisplayName: z5.string().min(1).max(120).default("Admin"),
+  initialToken: z5.object({
+    label: z5.string().min(1).max(120),
+    scopes: z5.array(tokenScopeSchema).min(1)
   }).optional()
 });
 var teamCreatedSchema = teamSummarySchema.extend({
-  initialUser: z4.object({
-    id: z4.string().uuid(),
-    displayName: z4.string()
+  initialUser: z5.object({
+    id: z5.string().uuid(),
+    displayName: z5.string()
   }),
   initialToken: tokenCreatedSchema.nullable()
 });
-var setupStatusSchema = z4.object({
-  needsSetup: z4.boolean()
+var setupStatusSchema = z5.object({
+  needsSetup: z5.boolean()
 });
-var setupBodySchema = z4.object({
-  teamName: z4.string().min(1).max(120),
-  displayName: z4.string().min(1).max(120).default("Admin")
+var setupBodySchema = z5.object({
+  teamName: z5.string().min(1).max(120),
+  displayName: z5.string().min(1).max(120).default("Admin")
 });
-var setupResultSchema = z4.object({
+var setupResultSchema = z5.object({
   team: teamSummarySchema,
-  user: z4.object({ id: z4.string().uuid(), displayName: z4.string() }),
+  user: z5.object({ id: z5.string().uuid(), displayName: z5.string() }),
   tokenString: tokenStringSchema,
-  scopes: z4.array(tokenScopeSchema)
+  scopes: z5.array(tokenScopeSchema)
 });
-var teamLlmSettingsSchema = z4.object({
-  keyConfigured: z4.boolean(),
-  keyHint: z4.string().nullable(),
-  lightModel: z4.string(),
-  heavyModel: z4.string()
+var teamLlmSettingsSchema = z5.object({
+  keyConfigured: z5.boolean(),
+  keyHint: z5.string().nullable(),
+  lightModel: z5.string(),
+  heavyModel: z5.string()
 });
-var teamLlmUpdateSchema = z4.object({
-  openrouterApiKey: z4.string().max(400).nullable().optional(),
-  lightModel: z4.string().min(1).max(200).optional(),
-  heavyModel: z4.string().min(1).max(200).optional()
+var teamLlmUpdateSchema = z5.object({
+  openrouterApiKey: z5.string().max(400).nullable().optional(),
+  lightModel: z5.string().min(1).max(200).optional(),
+  heavyModel: z5.string().min(1).max(200).optional()
 });
-var wcvpImportStatusSchema = z4.enum([
+var wcvpImportStatusSchema = z5.enum([
   "queued",
   "downloading",
   "importing",
@@ -498,68 +724,68 @@ var wcvpImportStatusSchema = z4.enum([
   "failed",
   "cancelled"
 ]);
-var wcvpImportRunSchema = z4.object({
-  id: z4.string().uuid(),
-  version: z4.string(),
-  sourceUrl: z4.string(),
+var wcvpImportRunSchema = z5.object({
+  id: z5.string().uuid(),
+  version: z5.string(),
+  sourceUrl: z5.string(),
   status: wcvpImportStatusSchema,
-  forceOverwrite: z4.boolean(),
-  bytesDownloaded: z4.number().int().nonnegative(),
-  totalBytes: z4.number().int().nonnegative().nullable(),
-  insertedCount: z4.number().int().nonnegative(),
-  recordCount: z4.number().int().nonnegative().nullable(),
-  message: z4.string().nullable(),
-  createdAt: z4.string().datetime(),
-  startedAt: z4.string().datetime().nullable(),
-  completedAt: z4.string().datetime().nullable()
+  forceOverwrite: z5.boolean(),
+  bytesDownloaded: z5.number().int().nonnegative(),
+  totalBytes: z5.number().int().nonnegative().nullable(),
+  insertedCount: z5.number().int().nonnegative(),
+  recordCount: z5.number().int().nonnegative().nullable(),
+  message: z5.string().nullable(),
+  createdAt: z5.string().datetime(),
+  startedAt: z5.string().datetime().nullable(),
+  completedAt: z5.string().datetime().nullable()
 });
-var wcvpImportCreateBodySchema = z4.object({
-  version: z4.string().min(1).max(120),
+var wcvpImportCreateBodySchema = z5.object({
+  version: z5.string().min(1).max(120),
   /** Defaults to the Kew SFTP URL when omitted, so the admin doesn't have
    * to remember it for routine v13/v14 imports. */
-  url: z4.string().url().optional(),
-  force: z4.boolean().optional()
+  url: z5.string().url().optional(),
+  force: z5.boolean().optional()
 });
-var adminHealthErrorSchema = z4.object({
-  id: z4.string().uuid(),
-  action: z4.string(),
-  entityType: z4.string(),
-  entityId: z4.string().nullable(),
-  timestamp: z4.string().datetime(),
-  metadata: z4.unknown().nullable()
-});
-var adminHealthSchema = z4.object({
-  queueDepth: z4.object({
-    waiting: z4.number().int().nonnegative(),
-    active: z4.number().int().nonnegative(),
-    delayed: z4.number().int().nonnegative(),
-    completed: z4.number().int().nonnegative(),
-    failed: z4.number().int().nonnegative(),
-    paused: z4.number().int().nonnegative()
+var adminHealthErrorSchema = z5.object({
+  id: z5.string().uuid(),
+  action: z5.string(),
+  entityType: z5.string(),
+  entityId: z5.string().nullable(),
+  timestamp: z5.string().datetime(),
+  metadata: z5.unknown().nullable()
+});
+var adminHealthSchema = z5.object({
+  queueDepth: z5.object({
+    waiting: z5.number().int().nonnegative(),
+    active: z5.number().int().nonnegative(),
+    delayed: z5.number().int().nonnegative(),
+    completed: z5.number().int().nonnegative(),
+    failed: z5.number().int().nonnegative(),
+    paused: z5.number().int().nonnegative()
   }),
-  workerCount: z4.number().int().nonnegative(),
-  lastErrors: z4.array(adminHealthErrorSchema),
-  rateLimitBudget: z4.object({
-    max: z4.number().int().nonnegative(),
-    timeWindowSeconds: z4.number().int().nonnegative()
+  workerCount: z5.number().int().nonnegative(),
+  lastErrors: z5.array(adminHealthErrorSchema),
+  rateLimitBudget: z5.object({
+    max: z5.number().int().nonnegative(),
+    timeWindowSeconds: z5.number().int().nonnegative()
   }),
-  snapshotVersion: z4.string().nullable(),
-  snapshotImportedAt: z4.string().datetime().nullable(),
+  snapshotVersion: z5.string().nullable(),
+  snapshotImportedAt: z5.string().datetime().nullable(),
   /**
    * Number of cached accepted-name mappings (L0.5 match-history rows) for the
    * caller's team — the size of the team accepted-name cache.
    */
-  teamHistorySize: z4.number().int().nonnegative(),
+  teamHistorySize: z5.number().int().nonnegative(),
   /**
    * Overall (all-teams) tally of which cascade layer produced the winning
    * candidate, across every matched query. `layer` is the raw attempt layer
    * (`L1`…`L7`, `L0.5`, `OVERRIDE`); `count` is the number of matched queries
    * that layer resolved. Descending by count.
    */
-  layerUsage: z4.array(
-    z4.object({
-      layer: z4.string(),
-      count: z4.number().int().nonnegative()
+  layerUsage: z5.array(
+    z5.object({
+      layer: z5.string(),
+      count: z5.number().int().nonnegative()
     })
   ),
   /**
@@ -569,18 +795,239 @@ var adminHealthSchema = z4.object({
    * Lets the health page surface each external source's usage, hit/miss/error
    * breakdown, latency, and recency — so a misbehaving provider is visible.
    */
-  externalProviders: z4.array(
-    z4.object({
-      provider: z4.string(),
-      total: z4.number().int().nonnegative(),
-      hits: z4.number().int().nonnegative(),
-      misses: z4.number().int().nonnegative(),
-      errors: z4.number().int().nonnegative(),
-      avgDurationMs: z4.number().int().nonnegative(),
-      lastUsedAt: z4.string().datetime().nullable()
+  externalProviders: z5.array(
+    z5.object({
+      provider: z5.string(),
+      total: z5.number().int().nonnegative(),
+      hits: z5.number().int().nonnegative(),
+      misses: z5.number().int().nonnegative(),
+      errors: z5.number().int().nonnegative(),
+      avgDurationMs: z5.number().int().nonnegative(),
+      lastUsedAt: z5.string().datetime().nullable()
+    })
+  )
+});
+var matchHistoryEntrySchema = z5.object({
+  id: z5.string().uuid(),
+  /** The normalized input name this mapping is keyed on. */
+  normalizedInput: z5.string(),
+  acceptedName: z5.string(),
+  acceptedIdentifier: z5.object({ namespace: z5.string(), value: z5.string() }).nullable(),
+  /** Resolved from the backbone snapshot at read time (null when the stored
+   * identifier no longer resolves): authorship + family of the accepted taxon,
+   * its identifiers (backbone id, IPNI LSID, portal url) and the portal link. */
+  acceptedAuthorship: z5.string().nullable(),
+  family: z5.string().nullable(),
+  acceptedIdentifiers: z5.array(z5.object({ namespace: z5.string(), value: z5.string() })),
+  targetUrl: z5.string().nullable(),
+  targetReferential: z5.string(),
+  referentialVersion: z5.string(),
+  independentUserAcceptanceCount: z5.number().int().nonnegative(),
+  rejectionCount: z5.number().int().nonnegative(),
+  blacklisted: z5.boolean(),
+  needsReconfirmation: z5.boolean(),
+  /** Currently usable as a cache hit (not blacklisted, acceptances > rejections). */
+  active: z5.boolean(),
+  /** Auto-accept (Grade A): acceptances ≥ the team's promotion threshold. */
+  promoted: z5.boolean(),
+  /** Label of the token that last reviewed this mapping (falls back to the
+   * reviewer's display name for rows predating token tracking). */
+  lastReviewedBy: z5.string().nullable(),
+  firstSeenAt: z5.string().datetime(),
+  lastAcceptedAt: z5.string().datetime().nullable()
+});
+var teamCacheResponseSchema = z5.object({
+  /** Distinct-user acceptances needed to promote a hit to Grade A. */
+  promotionThreshold: z5.number().int().positive(),
+  /** Total entries in the team cache (before the limit). */
+  total: z5.number().int().nonnegative(),
+  entries: z5.array(matchHistoryEntrySchema)
+});
+
+// ../shared/src/schemas/backbone.ts
+import { z as z6 } from "zod";
+var backboneSchema = z6.enum(["wcvp", "wfo"]);
+var wfoImportStatusSchema = z6.enum([
+  "queued",
+  "downloading",
+  "importing",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+var wfoImportRunSchema = z6.object({
+  id: z6.string().uuid(),
+  version: z6.string(),
+  sourceUrl: z6.string(),
+  status: wfoImportStatusSchema,
+  forceOverwrite: z6.boolean(),
+  bytesDownloaded: z6.number().int().nonnegative(),
+  totalBytes: z6.number().int().nonnegative().nullable(),
+  insertedCount: z6.number().int().nonnegative(),
+  recordCount: z6.number().int().nonnegative().nullable(),
+  message: z6.string().nullable(),
+  createdAt: z6.string().datetime(),
+  startedAt: z6.string().datetime().nullable(),
+  completedAt: z6.string().datetime().nullable()
+});
+var wfoImportCreateBodySchema = z6.object({
+  version: z6.string().min(1).max(120),
+  /** Direct download URL (from the Zenodo version listing). Required for WFO
+   * since versions aren't derivable from the label like WCVP's Kew URLs. */
+  url: z6.string().url().optional(),
+  force: z6.boolean().optional()
+});
+var snapshotKindSchema = z6.enum(["official", "derived"]);
+var wfoSnapshotSummarySchema = z6.object({
+  version: z6.string(),
+  recordCount: z6.number().int().nonnegative(),
+  importedAt: z6.string().datetime(),
+  isLatest: z6.boolean(),
+  kind: snapshotKindSchema,
+  baseVersion: z6.string().nullable(),
+  label: z6.string().nullable(),
+  ownerTeamId: z6.string().nullable()
+});
+var wfoVersionSchema = z6.object({
+  /** Release label, e.g. "2025-12". */
+  version: z6.string(),
+  /** Zenodo record id for this version. */
+  recordId: z6.string(),
+  /** The plant-list archive filename inside the record. */
+  fileName: z6.string(),
+  /** Direct content download URL. */
+  url: z6.string().url(),
+  sizeBytes: z6.number().int().nonnegative().nullable(),
+  publishedAt: z6.string().nullable(),
+  isLatest: z6.boolean()
+});
+var wfoVersionListSchema = z6.array(wfoVersionSchema);
+var backboneKeySchema = z6.enum(["wcvp", "wfo"]);
+var backboneDefaultsSchema = z6.object({
+  wcvp: z6.string().nullable(),
+  wfo: z6.string().nullable()
+});
+var backboneDefaultUpdateSchema = z6.object({
+  backbone: backboneKeySchema,
+  version: z6.string().min(1).nullable()
+});
+var DERIVED_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,40}$/;
+var MAX_BASE_VERSION_LENGTH = 120;
+var MAX_SNAPSHOT_VERSION_LENGTH = MAX_BASE_VERSION_LENGTH + 1 + 41;
+var derivedUploadMetaSchema = z6.object({
+  baseVersion: z6.string().min(1).max(MAX_BASE_VERSION_LENGTH),
+  slug: z6.string().regex(DERIVED_SLUG_RE, "slug: lowercase letters, digits and dashes (2\u201341 chars)"),
+  label: z6.string().trim().min(1).max(120),
+  notes: z6.string().trim().max(2e3).optional()
+});
+var derivedUploadStatusSchema = z6.enum([
+  "staging",
+  "ready",
+  "invalid",
+  "importing",
+  "imported",
+  "failed",
+  "discarded"
+]);
+var derivedIssueSeveritySchema = z6.enum(["error", "warning"]);
+var derivedIssueSchema = z6.object({
+  code: z6.string(),
+  severity: derivedIssueSeveritySchema,
+  count: z6.number().int().nonnegative(),
+  /** Free-form detail for the UI (e.g. the offending vocabulary values). */
+  detail: z6.string().nullable(),
+  samples: z6.array(
+    z6.object({
+      taxonId: z6.string().nullable(),
+      name: z6.string().nullable(),
+      detail: z6.string().nullable(),
+      line: z6.number().int().nullable()
     })
   )
 });
+var derivedDiffFieldSchema = z6.enum([
+  "canonical_name",
+  "scientific_name",
+  "authorship",
+  "rank",
+  "taxonomic_status",
+  "accepted_name_usage_id",
+  "parent_name_usage_id",
+  "family"
+]);
+var DERIVED_DIFF_FIELDS = derivedDiffFieldSchema.options;
+var diffSampleSchema = z6.object({ taxonId: z6.string(), name: z6.string().nullable() });
+var changedSampleSchema = diffSampleSchema.extend({
+  changes: z6.array(
+    z6.object({ field: derivedDiffFieldSchema, before: z6.string().nullable(), after: z6.string().nullable() })
+  )
+});
+var derivedReportSchema = z6.object({
+  rowsRead: z6.number().int().nonnegative(),
+  rowsStaged: z6.number().int().nonnegative(),
+  rowsRejected: z6.number().int().nonnegative(),
+  baseRowCount: z6.number().int().nonnegative(),
+  errors: z6.number().int().nonnegative(),
+  warnings: z6.number().int().nonnegative(),
+  issues: z6.array(derivedIssueSchema),
+  diff: z6.object({
+    added: z6.object({ count: z6.number().int().nonnegative(), samples: z6.array(diffSampleSchema) }),
+    removed: z6.object({ count: z6.number().int().nonnegative(), samples: z6.array(diffSampleSchema) }),
+    changed: z6.object({
+      count: z6.number().int().nonnegative(),
+      byField: z6.record(z6.string(), z6.number().int().nonnegative()),
+      samples: z6.array(changedSampleSchema)
+    }),
+    unchanged: z6.number().int().nonnegative()
+  })
+});
+var derivedUploadSchema = z6.object({
+  id: z6.string().uuid(),
+  backbone: backboneSchema,
+  baseVersion: z6.string(),
+  slug: z6.string(),
+  label: z6.string(),
+  notes: z6.string().nullable(),
+  /** The snapshot version this upload installs as (`<base>+<slug>`). */
+  version: z6.string(),
+  originalFilename: z6.string().nullable(),
+  sha256: z6.string(),
+  sizeBytes: z6.number().int().nonnegative(),
+  status: derivedUploadStatusSchema,
+  rowsRead: z6.number().int().nonnegative(),
+  report: derivedReportSchema.nullable(),
+  message: z6.string().nullable(),
+  createdAt: z6.string().datetime(),
+  expiresAt: z6.string().datetime(),
+  importedVersion: z6.string().nullable()
+});
+var derivedConfirmBodySchema = z6.object({
+  /** Acknowledge warnings. Never overrides errors. */
+  force: z6.boolean().optional()
+});
+
+// ../shared/src/schemas/openrouter.ts
+import { z as z7 } from "zod";
+var openRouterModelSchema = z7.object({
+  /** Full model id, e.g. `anthropic/claude-opus-4.8` or the alias
+   *  `~anthropic/claude-haiku-latest`. Used verbatim as the OpenRouter model. */
+  id: z7.string(),
+  /** Human label from OpenRouter (falls back to the id). */
+  name: z7.string(),
+  /** Author slug (the part before `/`), with any leading `~` stripped. */
+  author: z7.string(),
+  /** Unix seconds the model was published; used to rank "latest". */
+  created: z7.number(),
+  /** Context window in tokens, when OpenRouter reports it. */
+  contextLength: z7.number().nullable(),
+  /** USD price per PROMPT token (input). Null when OpenRouter doesn't report a
+   * numeric price. 0 = free. */
+  promptPriceUsd: z7.number().nullable(),
+  /** USD price per COMPLETION token (output). */
+  completionPriceUsd: z7.number().nullable(),
+  /** An auto-updating `…-latest` pointer (e.g. `~anthropic/claude-haiku-latest`). */
+  isAlias: z7.boolean()
+});
 
 // ../shared/src/normalize.ts
 var NULL_SENTINELS = /* @__PURE__ */ new Set(["", "na", "n/a", "null", "-", "\u2014", "unknown", "undet", "undet."]);
@@ -708,21 +1155,21 @@ function detectIdTypeDistribution(samples, opts) {
 }
 
 // ../shared/src/column-map.ts
-import { z as z5 } from "zod";
-var columnMappingSchema = z5.object({
-  nameColumn: z5.string().nullable(),
-  idColumn: z5.string().nullable(),
-  familyColumn: z5.string().nullable(),
-  genusColumn: z5.string().nullable(),
-  rankColumn: z5.string().nullable(),
-  authorColumn: z5.string().nullable()
-});
-var detectColumnsBodySchema = z5.object({
-  headers: z5.array(z5.string().min(1)).min(1).max(200)
-});
-var detectColumnsResponseSchema = z5.object({
+import { z as z8 } from "zod";
+var columnMappingSchema = z8.object({
+  nameColumn: z8.string().nullable(),
+  idColumn: z8.string().nullable(),
+  familyColumn: z8.string().nullable(),
+  genusColumn: z8.string().nullable(),
+  rankColumn: z8.string().nullable(),
+  authorColumn: z8.string().nullable()
+});
+var detectColumnsBodySchema = z8.object({
+  headers: z8.array(z8.string().min(1)).min(1).max(200)
+});
+var detectColumnsResponseSchema = z8.object({
   mapping: columnMappingSchema,
-  usedLlm: z5.boolean()
+  usedLlm: z8.boolean()
 });
 
 // src/api-client.ts
@@ -775,7 +1222,7 @@ var apiClient = {
     const buf = await fs.readFile(filePath);
     const fd = new FormData();
     const lower = filePath.toLowerCase();
-    const mime = lower.endsWith(".json") ? "application/json" : "text/csv";
+    const mime = lower.endsWith(".json") ? "application/json" : lower.endsWith(".xlsx") || lower.endsWith(".xls") ? "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" : "text/csv";
     fd.set("file", new Blob([buf], { type: mime }), basename(filePath));
     fd.set("config", JSON.stringify(config));
     if (name && name.trim()) fd.set("name", name.trim());
@@ -793,6 +1240,7 @@ var apiClient = {
   async downloadJob(creds, id, opts) {
     const params = new URLSearchParams({ format: opts.format });
     if (opts.confirmedOnly) params.set("confirmedOnly", "true");
+    if (opts.dedupe) params.set("dedupe", "true");
     if (opts.bundle) params.set("bundle", "true");
     if (opts.delimiter) params.set("delimiter", opts.delimiter);
     if (opts.columns) params.set("columns", opts.columns);
@@ -1023,8 +1471,9 @@ function trunc(s, n) {
 }
 
 // src/index.ts
+var { version } = createRequire(import.meta.url)("../package.json");
 var program = new Command();
-program.name("planttaxomatcher").description("PlantTaxoMatcher CLI").version("0.1.1");
+program.name("planttaxomatcher").description("PlantTaxoMatcher CLI").version(version);
 program.command("login").description("Save a personal token + server URL").option(
   "--token <token>",
   "Personal token (ptm_...). Avoid on shared hosts: it is visible in shell history and the process list. Prefer --token-stdin or the PLANTTAXOMATCHER_TOKEN env var."
@@ -1036,17 +1485,15 @@ program.command("login").description("Save a personal token + server URL").optio
   "--insecure",
   "Allow sending the token over cleartext http to a non-loopback server (NOT recommended).",
   false
-).action(
-  async (opts) => {
-    assertServerTransport(opts.server, !!opts.insecure);
-    const token = await resolveLoginToken(opts);
-    if (!tokenStringSchema.safeParse(token).success) {
-      throw new Error("malformed token \u2014 expected ptm_<12 chars>_<32 chars>");
-    }
-    await writeCredentials({ token, server: opts.server });
-    console.log(kleur2.green("\u2713"), `Logged in to ${opts.server}`);
+).action(async (opts) => {
+  assertServerTransport(opts.server, !!opts.insecure);
+  const token = await resolveLoginToken(opts);
+  if (!tokenStringSchema.safeParse(token).success) {
+    throw new Error("malformed token \u2014 expected ptm_<12 chars>_<32 chars>");
   }
-);
+  await writeCredentials({ token, server: opts.server });
+  console.log(kleur2.green("\u2713"), `Logged in to ${opts.server}`);
+});
 program.command("logout").description("Clear saved credentials").action(async () => {
   await clearCredentials();
   console.log(kleur2.green("\u2713"), "Logged out");
@@ -1081,25 +1528,27 @@ program.command("submit <files...>").description(
   "--name <label>",
   "Job name override (single file only; ignored when multiple files match \u2014 the file name is used)"
 ).requiredOption("--name-column <name>", "Column holding the scientific name").option("--id-column <name>", "Column holding a known ID").option("--family-column <name>", "Column holding family").option("--genus-column <name>", "Column holding genus").option("--rank-column <name>", "Column holding rank").option("--author-column <name>", "Column holding authorship").option("--filter-column <name>", "Only process rows where this column matches --filter-value; others are skipped").option("--filter-value <value>", "Value the --filter-column must equal (trimmed, case-insensitive)").option("--author-mode <mode>", "ignore|prefer|strict", "prefer").option("--parallel <n>", "Per-job parallelism", "4").option("--review-mode <mode>", "off|recommended|strict", "recommended").option(
-  "--keep-infraspecific",
-  "Keep infraspecific accepted taxa (varieties, subspecies, forms) instead of collapsing them up to the species",
-  false
-).option("--allow-llm", "Allow Layer 7 LLM cascade (breaks ties between competing matches)", false).option("--llm-cap-cents <cents>", "Max LLM spend in cents", "500").option("--referential <version>", "WCVP snapshot version to match against (default: latest)").option("--no-watch", "Do not stream progress after submit").option(
-  "--dry-run",
-  "Preview locally (normalize first rows + detect ID type) and confirm before uploading",
+  "--species-level",
+  "Roll infraspecific accepted taxa (varieties, subspecies, forms) up to their species, so every output row sits at species level",
   false
 ).option(
-  "--dry-run-rows <n>",
-  "Number of rows to show in the dry-run preview table (default 10)",
-  "10"
-).action(async (files, opts) => {
+  "--ignore-author",
+  "Accept a unique canonical name match whose author couldn't be confirmed instead of sending it to review (an author that CONFLICTS with the matched taxon still reviews)",
+  false
+).option("--keep-infraspecific", "Deprecated \u2014 now the default; has no effect", false).option("--allow-llm", "Allow Layer 7 LLM cascade (breaks ties between competing matches)", false).option("--llm-cap-cents <cents>", "Max LLM spend in cents", "500").option(
+  "--referential <version>",
+  "WCVP snapshot version to match against (default: your team's configured default snapshot, else the newest import)"
+).option("--no-watch", "Do not stream progress after submit").option("--dry-run", "Preview locally (normalize first rows + detect ID type) and confirm before uploading", false).option("--dry-run-rows <n>", "Number of rows to show in the dry-run preview table (default 10)", "10").action(async (files, opts) => {
   const creds = await requireCredentials();
   const inputs = await expandInputs(files);
   if (inputs.length === 0) throw new Error("no input files");
   if (opts.name && inputs.length > 1) {
+    console.log(kleur2.yellow("!"), "--name ignored for multi-file submit; using each file name as the job name");
+  }
+  if (opts.keepInfraspecific) {
     console.log(
       kleur2.yellow("!"),
-      "--name ignored for multi-file submit; using each file name as the job name"
+      "--keep-infraspecific is deprecated and does nothing \u2014 infraspecific taxa are kept by default. Pass --species-level to roll them up to the species."
     );
   }
   if (inputs.length > 1) {
@@ -1145,9 +1594,12 @@ ${file}`));
     allowLlm: !!opts.allowLlm,
     llmCostCapCents: Number(opts.llmCapCents ?? 500),
     reviewMode: String(opts.reviewMode ?? "recommended"),
-    // UI/CLI opt-in inverts the config flag: by default we collapse an
-    // infraspecific accepted taxon up to its species.
-    speciesLevelAcceptedOnly: !opts.keepInfraspecific,
+    // Opt-in: by default an infraspecific accepted taxon is kept at the
+    // rank it resolved to, not rolled up to its species.
+    speciesLevelAcceptedOnly: !!opts.speciesLevel,
+    // Opt-in: an unconfirmed author still routes the match to review
+    // unless the caller declares the author unimportant.
+    acceptUnconfirmedAuthor: !!opts.ignoreAuthor,
     exportConfirmedOnly: false,
     forceReviewFamilies: [],
     ...opts.referential ? { referentialVersion: String(opts.referential) } : {}
@@ -1187,10 +1639,7 @@ program.command("cancel <jobId>").description("Cancel a job. Already-matched row
   const job = await apiClient.cancelJob(creds, jobId);
   console.log(kleur2.green("\u2713"), `cancelled: ${job.id} (status=${job.status})`);
 });
-program.command("download <jobId>").description("Download a job export (CSV, JSON, or NDJSON; optionally bundled with NOTICE.md)").option("--format <fmt>", "csv | xlsx | json | ndjson", "csv").option("--confirmed-only", "only matched rows that are accepted / not pending", false).option("--delimiter <sep>", "CSV separator: comma | semicolon | tab | pipe (csv format only)", "comma").option("--bundle", "wrap in a ZIP with NOTICE.md citing the WCVP snapshot + providers", false).option(
-  "--columns <list>",
-  "comma-separated result/upload column keys to KEEP (default: all). See --list-columns"
-).option(
+program.command("download <jobId>").description("Download a job export (CSV, JSON, or NDJSON; optionally bundled with NOTICE.md)").option("--format <fmt>", "csv | xlsx | json | ndjson", "csv").option("--confirmed-only", "only matched rows that are accepted / not pending", false).option("--dedupe", "collapse rows that resolved to the same accepted taxon to one line", false).option("--delimiter <sep>", "CSV separator: comma | semicolon | tab | pipe (csv format only)", "comma").option("--bundle", "wrap in a ZIP with NOTICE.md citing the WCVP snapshot + providers", false).option("--columns <list>", "comma-separated result/upload column keys to KEEP (default: all). See --list-columns").option(
   "--wcvp-extra <list>",
   "comma-separated extra WCVP fields to append as wcvp_<key> columns (e.g. ipni_id,powo_id). See --list-columns"
 ).option("--list-columns", "print the columns available for this job and exit", false).option("--output <path>", "write to this path; default is the server-provided filename in CWD").action(async (jobId, opts) => {
@@ -1212,6 +1661,7 @@ program.command("download <jobId>").description("Download a job export (CSV, JSO
     throw new Error(`--format must be csv, xlsx, json or ndjson (got ${String(format)})`);
   }
   const confirmedOnly = !!opts.confirmedOnly;
+  const dedupe = !!opts.dedupe;
   const bundle = !!opts.bundle;
   const delimiter = String(opts.delimiter ?? "comma");
   if (!["comma", "semicolon", "tab", "pipe"].includes(delimiter)) {
@@ -1220,6 +1670,7 @@ program.command("download <jobId>").description("Download a job export (CSV, JSO
   const { filename, body } = await apiClient.downloadJob(creds, jobId, {
     format,
     confirmedOnly,
+    dedupe,
     bundle,
     ...format === "csv" && delimiter !== "comma" ? { delimiter } : {},
     ...opts.columns ? { columns: String(opts.columns) } : {},
@@ -1269,9 +1720,7 @@ async function resolveLoginToken(opts) {
   const env = process.env.PLANTTAXOMATCHER_TOKEN;
   if (env && env.trim()) return env.trim();
   if (!process.stdin.isTTY) {
-    throw new Error(
-      "no token provided. Pass --token-stdin, set PLANTTAXOMATCHER_TOKEN, or run interactively."
-    );
+    throw new Error("no token provided. Pass --token-stdin, set PLANTTAXOMATCHER_TOKEN, or run interactively.");
   }
   const entered = await password({ message: "Personal token (ptm_...)", mask: true });
   return entered.trim();
@@ -1298,6 +1747,7 @@ async function expandInputs(patterns) {
 }
 async function streamJob(creds, jobId) {
   console.log(kleur2.cyan("\u2192"), `Streaming progress for ${jobId} \u2026`);
+  let lastLineWidth = 0;
   for await (const evt of apiClient.streamJob(creds, jobId)) {
     const t = String(evt.type ?? "");
     if (t === "heartbeat") continue;
@@ -1315,7 +1765,10 @@ async function streamJob(creds, jobId) {
     } else if (t === "progress") {
       const p = evt.processedQueries ?? evt.processedRows ?? 0;
       const total = evt.totalQueries ?? evt.totalRows ?? 0;
-      process.stdout.write(`\r  progress: ${p}/${total}        `);
+      const phase = p === 0 && typeof evt.phase === "string" ? ` (${evt.phase}\u2026)` : "";
+      const line = `  progress: ${p}/${total}${phase}`;
+      process.stdout.write(`\r${line.padEnd(lastLineWidth)}`);
+      lastLineWidth = line.length;
     } else if (t === "completed") {
       process.stdout.write("\n");
       console.log(kleur2.green("\u2713"), "completed");