// Curated per-video tags — an operator-owned vocabulary that cuts ACROSS
// channels ("every stream where Eva is on mic", on any site, any channel).
//
// Three unrelated things in this repo are already called "tags":
//   1. `TranscriptSummary.tags` — yt-dlp keywords from metadata.info.json
//      (the search scope "tags", relabelled "Keywords" in the UI);
//   2. AI digest topic tags;
//   3. THIS — curated tags, carried on a record as `curatedTags`.
// The record field is therefore NEVER `tags`. See plans/FACTS.md.
//
// This module is PURE (no I/O) so it can be unit-tested and shared by the
// server-side store (common/lib/curatedTagsStore.ts), the index builder
// (common/controller/curatedTagsIndex.ts), the editor and the export viewer.
// Disk/merge/defaulting policy lives in the store; this file only knows how to
// coerce a config, layer a site over the corpus, evaluate rules and fold rule
// hits together with the operator's pins and suppressions.

// The file name, identical at every layer: `transcripts/tags.json`,
// `transcripts/sites/<id>/tags.json` and the published `/tags.json`.
export const TAGS_FILENAME = "tags.json";

// Tag ids are free-form but url/filename-safe and lowercase, so they can travel
// in a query param, a CLI argument and a JSON key without quoting.
export const TAG_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;

export const CURATED_TAGS_VERSION = 1;

// Which file a config came out of. The two layers differ in exactly one way —
// see coerceTagDef — and naming it beats a boolean at every call site.
export type TagLayer = "global" | "site";

export type CuratedTagRuleKind = "metadata" | "chat-author" | "caption";

const RULE_KINDS: readonly CuratedTagRuleKind[] = [
  "metadata",
  "chat-author",
  "caption",
];

export type CuratedTagRule = {
  // Stable within its tag; used in provenance (`rule:<ruleId>`) and to let a
  // site layer append rules without colliding with the corpus ones.
  id: string;
  kind: CuratedTagRuleKind;
  // A JS regex source, matched case-insensitively. What it is matched against
  // depends on `kind` — see evaluateCompiledRules.
  pattern: string;
  // Channel slugs this rule may fire on. Absent or empty = every channel.
  channels?: string[];
  // Channel slugs this rule may NEVER fire on, applied AFTER `channels`. A slug
  // in both lists is excluded: naming a channel to skip is the more specific
  // statement, and the shape this exists for — "every channel except that one"
  // — needs no allow-list at all. Absent or empty = exclude nothing.
  channelsExclude?: string[];
  // Inclusive upload-date bounds, compared digit-wise so both "20260101" and
  // "2026-01-01" work. null/absent = unbounded.
  dateFrom?: string | null;
  dateTo?: string | null;
  // Defaults true. A rule whose pattern does not compile is KEPT with
  // `enabled: false` and a `disabledReason` — never dropped, never thrown, so
  // the operator can see and fix their typo instead of losing the rule.
  enabled: boolean;
  disabledReason?: string;
};

export type CuratedTagDef = {
  id: string;
  // OPTIONAL, and the optionality is load-bearing at the SITE layer: an overlay
  // that only recolours a tag must carry no label, or mergeTagDefs would apply
  // one and rename the tag on that site. Absent means "whatever the layer below
  // says", and the display fallback everywhere is `label ?? id`.
  label?: string;
  // Optional grouping so a chip row can read "Eva: Collab · In chat · Discussed".
  group?: string;
  groupLabel?: string;
  description?: string;
  color?: string;
  // Sort key for chips and for the order of a record's `curatedTags`.
  order?: number;
  // Presentation only: hidden tags are dropped from a published /tags.json but
  // still ride on records (a site hides a chip; it does not erase a fact).
  hidden?: boolean;
  // The sites this tag EXISTS on (site ids). Absent or empty = every site.
  // Unlike `hidden`, this is not presentation: a scoped tag is never derived for
  // a video whose channel is not a member of one of these sites (its rules do
  // not fire there and its pins do not apply), and a site outside the list
  // drops it from its summaries and its /tags.json — so it is on no record,
  // chip or count of another site (the Eva tags: Anilyzer's only). Corpus layer
  // only: a site's own tags.json cannot widen or narrow it.
  sites?: string[];
  // Optional — a purely manual tag is legal.
  rules?: CuratedTagRule[];
};

// Where a pin or a suppression came from: `operator`, `agent:<label>`,
// `umtool:<project>` or `rule:<ruleId>`. Free text, recorded verbatim.
export type CuratedTagProvenance = {
  source: string;
  // ISO-8601.
  setAt: string;
};

export type CuratedTagAssignment = {
  // Tags pinned onto this video regardless of what the rules say.
  manual?: string[];
  // Tags a rule would have produced but the operator rejected. If a tag is in
  // BOTH lists, `manual` wins (a later pin beats an older suppression).
  suppressed?: string[];
  // Provenance per tag id, recorded for pins AND suppressions.
  sources?: Record<string, CuratedTagProvenance>;
};

export type CuratedTagsConfig = {
  version: number;
  tags: CuratedTagDef[];
  // Keyed by `assignmentKey(channelSlug, videoId)`.
  assignments: Record<string, CuratedTagAssignment>;
};

// The published, presentation-side document served at `/tags.json`. Counts are
// per site, computed at index time; compose drops hidden and zero-count tags,
// and writes no file at all when nothing survives (a 404 is a valid empty
// state, exactly like /duplicates.json).
export type PublishedTag = {
  id: string;
  label: string;
  group?: string;
  groupLabel?: string;
  color?: string;
  order?: number;
  count: number;
  // slug -> number of videos carrying this tag on that channel.
  channels: Record<string, number>;
};

export type PublishedTags = {
  version: number;
  tags: PublishedTag[];
};

// The one key shape for an assignment. Channel slug first so a prefix scan over
// the assignment keys is a per-channel scan.
export function assignmentKey(channelSlug: string, id: string): string {
  return `${channelSlug}/${id}`;
}

export function isTagId(v: unknown): v is string {
  return typeof v === "string" && TAG_ID_RE.test(v);
}

function normalizeTagId(v: unknown): string | null {
  if (typeof v !== "string") return null;
  const id = v.trim().toLowerCase();
  return TAG_ID_RE.test(id) ? id : null;
}

function trimmedString(v: unknown): string | undefined {
  if (typeof v !== "string") return undefined;
  const s = v.trim();
  return s === "" ? undefined : s;
}

function dateBound(v: unknown): string | null {
  const s = trimmedString(v);
  if (!s) return null;
  const digits = s.replace(/\D/g, "");
  return digits === "" ? null : digits;
}

// Compile once, here, so both sanitize (which disables a broken rule) and
// compileTagRules (which skips one) agree on what "compiles" means.
function tryCompile(pattern: string): { re: RegExp } | { error: string } {
  try {
    return { re: new RegExp(pattern, "i") };
  } catch (err) {
    return { error: err instanceof Error ? err.message : String(err) };
  }
}

// A rule's channel scope, either side of it. Shared so the allow-list and the
// exclude list can never drift into sanitizing differently.
function channelList(v: unknown): string[] {
  return Array.isArray(v)
    ? v
        .filter((c): c is string => typeof c === "string" && c.trim() !== "")
        .map((c) => c.trim())
    : [];
}

function coerceRule(raw: unknown, index: number): CuratedTagRule | null {
  if (!raw || typeof raw !== "object") return null;
  const r = raw as Record<string, unknown>;
  const kind = RULE_KINDS.find((k) => k === r.kind);
  if (!kind) return null;
  const pattern = typeof r.pattern === "string" ? r.pattern : "";
  // A rule with no pattern cannot mean anything; drop it.
  if (pattern.trim() === "") return null;
  const id = trimmedString(r.id) ?? `r${index + 1}`;
  const channels = channelList(r.channels);
  const channelsExclude = channelList(r.channelsExclude);
  const dateFrom = dateBound(r.dateFrom);
  const dateTo = dateBound(r.dateTo);
  const rule: CuratedTagRule = {
    id,
    kind,
    pattern,
    enabled: r.enabled !== false, // default true
    ...(channels.length > 0 ? { channels } : {}),
    ...(channelsExclude.length > 0 ? { channelsExclude } : {}),
    ...(dateFrom ? { dateFrom } : {}),
    ...(dateTo ? { dateTo } : {}),
  };
  const compiled = tryCompile(pattern);
  if ("error" in compiled) {
    // Kept, disabled, with the reason — the operator's typo stays visible.
    rule.enabled = false;
    rule.disabledReason = `pattern does not compile: ${compiled.error}`;
  }
  return rule;
}

function coerceTagDef(raw: unknown, layer: TagLayer): CuratedTagDef | null {
  if (!raw || typeof raw !== "object") return null;
  const r = raw as Record<string, unknown>;
  const id = normalizeTagId(r.id);
  if (!id) return null;
  // The one field the two layers treat differently. A corpus definition is the
  // thing being named, so it always ends up with a label (the id, if nobody
  // wrote one). A site row is an OVERLAY: a missing label means "do not
  // override", and inventing one here would rename the tag on that site, since
  // mergeTagDefs applies every field the overlay carries.
  const label = trimmedString(r.label) ?? (layer === "site" ? undefined : id);
  // THE SECOND FIELD THE LAYERS TREAT DIFFERENTLY: a site layer carries no
  // rules at all, and one written there is dropped — on read AND on write, so
  // it can never reach a file, a merge or a published def.
  //
  // A rule is evaluated once at index time, over records SHARED by every site
  // that carries the channel. There is no per-site record for a per-site hit to
  // live in, so a site rule could only ever LOOK like it worked. Dropping it in
  // the coercion is the one place that covers every writer. Rules bind from
  // transcripts/tags.json alone; promote one there to make it fire.
  const rules =
    layer === "site" || !Array.isArray(r.rules)
      ? []
      : r.rules
          .map((rule, i) => coerceRule(rule, i))
          .filter((rule): rule is CuratedTagRule => rule !== null);
  const order =
    typeof r.order === "number" && Number.isFinite(r.order)
      ? r.order
      : undefined;
  // Corpus layer only (see the field): a site row's `sites` is dropped.
  const sites = layer === "site" ? [] : siteIdList(r.sites);
  return {
    id,
    ...(label !== undefined ? { label } : {}),
    ...(trimmedString(r.group) ? { group: trimmedString(r.group) } : {}),
    ...(trimmedString(r.groupLabel)
      ? { groupLabel: trimmedString(r.groupLabel) }
      : {}),
    ...(trimmedString(r.description)
      ? { description: trimmedString(r.description) }
      : {}),
    ...(trimmedString(r.color) ? { color: trimmedString(r.color) } : {}),
    ...(order !== undefined ? { order } : {}),
    ...(r.hidden === true ? { hidden: true } : {}),
    ...(sites.length > 0 ? { sites } : {}),
    ...(rules.length > 0 ? { rules } : {}),
  };
}

// lib/siteSchema.ts SITE_ID_RE, repeated: this module imports nothing.
const SITE_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;

// A list of site ids: trimmed, lowercased, valid, deduplicated, sorted.
function siteIdList(v: unknown): string[] {
  if (!Array.isArray(v)) return [];
  const out = new Set<string>();
  for (const item of v) {
    if (typeof item !== "string") continue;
    const id = item.trim().toLowerCase();
    if (SITE_ID_PATTERN.test(id)) out.add(id);
  }
  return [...out].sort();
}

// ─── Site scope (a tag that exists on some sites only) ───

// tag id -> the channel slugs it may be derived for: the members of the sites
// its def names. Only scoped tags have an entry; a tag with no entry exists
// everywhere. A scoped tag whose sites carry no channel gets an EMPTY set — it
// is derived for nothing — never "no entry".
export function tagChannelScope(
  defs: readonly CuratedTagDef[],
  members: Readonly<Record<string, readonly string[]>>,
): Map<string, Set<string>> {
  const out = new Map<string, Set<string>>();
  for (const def of defs) {
    if (!def.sites || def.sites.length === 0) continue;
    const slugs = new Set<string>();
    for (const siteId of def.sites) for (const slug of members[siteId] ?? []) slugs.add(slug);
    out.set(def.id, slugs);
  }
  return out;
}

// A video's tags with every scoped tag its channel is outside of removed.
export function scopeTagsToChannel(
  tags: string[],
  channelSlug: string,
  scope: ReadonlyMap<string, ReadonlySet<string>>,
): string[] {
  if (scope.size === 0 || tags.length === 0) return tags;
  return tags.filter((id) => scope.get(id)?.has(channelSlug) ?? true);
}

// A record's tags as one SITE publishes them: a tag scoped to other sites is
// dropped. (Derivation already keeps a scoped tag off every channel outside
// its sites; this covers a channel that is a member of an allowed site AND of
// this one.) Returns the same array when nothing is dropped.
export function tagsForSite(
  tags: string[] | undefined,
  siteId: string,
  defs: readonly CuratedTagDef[],
): string[] | undefined {
  if (!tags || tags.length === 0) return tags;
  let out: string[] | null = null;
  for (const [i, id] of tags.entries()) {
    const sites = defs.find((d) => d.id === id)?.sites;
    const keep = !sites || sites.length === 0 || sites.includes(siteId);
    if (!keep && out === null) out = tags.slice(0, i);
    else if (keep && out !== null) out.push(id);
  }
  return out ?? tags;
}

function coerceAssignment(raw: unknown): CuratedTagAssignment | null {
  if (!raw || typeof raw !== "object") return null;
  const r = raw as Record<string, unknown>;
  const list = (v: unknown): string[] => {
    if (!Array.isArray(v)) return [];
    const out: string[] = [];
    for (const item of v) {
      const id = normalizeTagId(item);
      if (id && !out.includes(id)) out.push(id);
    }
    return out;
  };
  const manual = list(r.manual);
  const suppressed = list(r.suppressed);
  // An assignment that pins and suppresses nothing carries no fact.
  if (manual.length === 0 && suppressed.length === 0) return null;
  const sources: Record<string, CuratedTagProvenance> = {};
  if (r.sources && typeof r.sources === "object") {
    for (const [key, value] of Object.entries(
      r.sources as Record<string, unknown>,
    )) {
      const tagId = normalizeTagId(key);
      if (!tagId) continue;
      if (!manual.includes(tagId) && !suppressed.includes(tagId)) continue;
      if (!value || typeof value !== "object") continue;
      const v = value as Record<string, unknown>;
      const source = trimmedString(v.source);
      const setAt = trimmedString(v.setAt);
      if (!source || !setAt) continue;
      sources[tagId] = { source, setAt };
    }
  }
  return {
    ...(manual.length > 0 ? { manual } : {}),
    ...(suppressed.length > 0 ? { suppressed } : {}),
    ...(Object.keys(sources).length > 0 ? { sources } : {}),
  };
}

// Coerce a parsed JSON value into a valid CuratedTagsConfig, dropping malformed
// entries. Tolerant like coerceAliasConfig (common/lib/searchAliases.ts): it
// NEVER throws, and missing/invalid input yields an empty config. The one
// deliberate exception to "drop what is malformed" is a rule whose regex does
// not compile: that rule is kept, disabled, with a reason.
//
// `layer` decides how a missing presentation field is read: at "global" a
// definition without a label is named after its id, at "site" it stays unnamed
// so the merge below leaves the corpus wording alone. Callers that hold a
// site file — readSiteTags/writeSiteTags, the site overlay action — must pass
// it in BOTH directions, because the file is sanitized on write and on read.
export function sanitizeTagsConfig(
  raw: unknown,
  opts: { layer?: TagLayer } = {},
): CuratedTagsConfig {
  const layer: TagLayer = opts.layer ?? "global";
  const empty: CuratedTagsConfig = {
    version: CURATED_TAGS_VERSION,
    tags: [],
    assignments: {},
  };
  if (!raw || typeof raw !== "object") return empty;
  const r = raw as Record<string, unknown>;
  const version =
    typeof r.version === "number" && Number.isFinite(r.version)
      ? r.version
      : CURATED_TAGS_VERSION;

  const tags: CuratedTagDef[] = [];
  const seen = new Set<string>();
  if (Array.isArray(r.tags)) {
    for (const entry of r.tags) {
      const def = coerceTagDef(entry, layer);
      if (!def) continue;
      if (seen.has(def.id)) continue; // first definition of an id wins
      seen.add(def.id);
      tags.push(def);
    }
  }

  const assignments: Record<string, CuratedTagAssignment> = {};
  if (r.assignments && typeof r.assignments === "object") {
    for (const [key, value] of Object.entries(
      r.assignments as Record<string, unknown>,
    )) {
      // `<channelSlug>/<videoId>` — exactly one slash, both halves non-empty.
      // Video ids are case-sensitive, so keys are NOT lowercased.
      const parts = key.split("/");
      if (parts.length !== 2 || !parts[0].trim() || !parts[1].trim()) continue;
      const assignment = coerceAssignment(value);
      if (!assignment) continue;
      assignments[key] = assignment;
    }
  }

  return { version, tags, assignments };
}

// Layer a site's tags.json over the corpus one.
//
// For an id the corpus already defines, the site entry is a FIELD-WISE OVERLAY
// of label/groupLabel/color/order/hidden — presentation, and nothing else. It
// can never delete a corpus rule, and it cannot add one: coerceTagDef drops
// rules from a site layer entirely (see there for why a per-site rule cannot
// tag anything), so there is nothing here to append. Assignments do not live at
// the site layer at all — an assignment is a fact about a video, not a
// presentation choice. A site id the corpus does not define becomes a full
// site-only tag, rule-less like every other site row.
//
// Deliberately NOT mergeAliases' wholesale replacement: aliases are suggestions,
// tags are a shared vocabulary that a site may dress up but not gut.
export function mergeTagDefs(
  global: CuratedTagDef[],
  site: CuratedTagDef[],
): CuratedTagDef[] {
  const out: CuratedTagDef[] = global.map((def) => ({ ...def }));
  const byId = new Map<string, CuratedTagDef>();
  for (const def of out) byId.set(def.id, def);
  for (const overlay of site) {
    const base = byId.get(overlay.id);
    if (!base) {
      const copy = { ...overlay };
      out.push(copy);
      byId.set(copy.id, copy);
      continue;
    }
    if (overlay.label !== undefined) base.label = overlay.label;
    if (overlay.groupLabel !== undefined) base.groupLabel = overlay.groupLabel;
    if (overlay.color !== undefined) base.color = overlay.color;
    if (overlay.order !== undefined) base.order = overlay.order;
    if (overlay.hidden !== undefined) base.hidden = overlay.hidden;
    // No rule branch: a sanitized site def has none, and the corpus rules on
    // `base` are left exactly as the corpus wrote them.
  }
  return out;
}

// (rule hits ∪ manual pins) − suppressions, with a pin beating a suppression of
// the same tag, sorted by def `order` then id so a record's `curatedTags` array
// is stable across builds.
//
// A tag id with no definition (a def deleted after the pin was made) is KEPT —
// losing an operator's fact silently would be worse — and sorts last by id. It
// simply never appears in a published /tags.json, which is built from defs.
export function effectiveTagsFor(
  ruleHits: string[],
  assignment: CuratedTagAssignment | undefined,
  defs: CuratedTagDef[],
): string[] {
  const manual = assignment?.manual ?? [];
  const suppressed = new Set(assignment?.suppressed ?? []);
  const out = new Set<string>();
  for (const id of ruleHits) {
    if (!suppressed.has(id)) out.add(id);
  }
  for (const id of manual) out.add(id); // a pin beats a suppression
  if (out.size === 0) return [];

  const rank = new Map<string, number>();
  defs.forEach((def, i) => {
    if (!rank.has(def.id)) rank.set(def.id, def.order ?? i);
  });
  const known = (id: string) => rank.has(id);
  return Array.from(out).sort((a, b) => {
    if (known(a) !== known(b)) return known(a) ? -1 : 1;
    if (known(a) && known(b)) {
      const ra = rank.get(a)!;
      const rb = rank.get(b)!;
      if (ra !== rb) return ra - rb;
    }
    return a < b ? -1 : a > b ? 1 : 0;
  });
}

// ─── Rule evaluation ───

export type TagRuleInput = {
  channelSlug: string;
  id: string;
  title?: string;
  description?: string;
  // yt-dlp keywords (TranscriptSummary.tags) — part of the `metadata` haystack.
  tags?: string[];
  uploadDate?: string;
  // Caption cues, for `caption` rules. Only `text` is read.
  captionCues?: readonly { text: string }[];
  // Live-chat cues, for `chat-author` rules. Only `text` is read; the author is
  // the `<author>: ` prefix (see chatAuthorOf).
  chatCues?: readonly { text: string }[];
};

export type CompiledTagRule = {
  tagId: string;
  ruleId: string;
  kind: CuratedTagRuleKind;
  re: RegExp;
  // null = every channel.
  channels: Set<string> | null;
  // null = exclude nothing. Applied after `channels` — see ruleApplies.
  channelsExclude: Set<string> | null;
  dateFrom: string | null;
  dateTo: string | null;
};

// Rules pre-split by kind so a per-video evaluation never re-partitions them.
export type CompiledTagRules = {
  metadata: CompiledTagRule[];
  chatAuthor: CompiledTagRule[];
  caption: CompiledTagRule[];
  // True when there is nothing to evaluate at all — the common case for an
  // untagged corpus, and the caller's cue to skip cue reads entirely.
  isEmpty: boolean;
};

export const EMPTY_COMPILED_TAG_RULES: CompiledTagRules = {
  metadata: [],
  chatAuthor: [],
  caption: [],
  isEmpty: true,
};

// Compile every enabled rule ONCE — the index build compiles per build, not per
// video, and then calls evaluateCompiledRules for each of tens of thousands of
// records. A rule that does not compile is skipped (sanitizeTagsConfig has
// already disabled it with a reason).
export function compileTagRules(defs: CuratedTagDef[]): CompiledTagRules {
  const metadata: CompiledTagRule[] = [];
  const chatAuthor: CompiledTagRule[] = [];
  const caption: CompiledTagRule[] = [];
  for (const def of defs) {
    for (const rule of def.rules ?? []) {
      if (rule.enabled === false) continue;
      const compiled = tryCompile(rule.pattern);
      if ("error" in compiled) continue;
      const entry: CompiledTagRule = {
        tagId: def.id,
        ruleId: rule.id,
        kind: rule.kind,
        re: compiled.re,
        channels:
          rule.channels && rule.channels.length > 0
            ? new Set(rule.channels)
            : null,
        channelsExclude:
          rule.channelsExclude && rule.channelsExclude.length > 0
            ? new Set(rule.channelsExclude)
            : null,
        dateFrom: dateBound(rule.dateFrom),
        dateTo: dateBound(rule.dateTo),
      };
      if (rule.kind === "metadata") metadata.push(entry);
      else if (rule.kind === "chat-author") chatAuthor.push(entry);
      else caption.push(entry);
    }
  }
  return {
    metadata,
    chatAuthor,
    caption,
    isEmpty:
      metadata.length === 0 && chatAuthor.length === 0 && caption.length === 0,
  };
}

// Channel scope and date range are cheap string work and are applied BEFORE any
// regex runs — the whole point of scoping a rule to one channel is not paying
// for it on the other twenty-nine.
// Exported because the index build asks the same question one step earlier — to
// decide whether a video's cues are worth decoding AT ALL
// (curatedTagsIndex.ts). A second copy of this predicate could disagree with
// the evaluation it is supposed to be predicting.
export function ruleApplies(
  rule: CompiledTagRule,
  input: { channelSlug: string; uploadDate?: string },
): boolean {
  if (rule.channels && !rule.channels.has(input.channelSlug)) return false;
  // The exclude wins over the allow-list on purpose: a slug in both is
  // excluded, so "this whole group, minus the one that floods it" is one rule
  // rather than an allow-list the operator has to keep in sync by hand.
  if (rule.channelsExclude && rule.channelsExclude.has(input.channelSlug)) {
    return false;
  }
  if (rule.dateFrom || rule.dateTo) {
    const date = (input.uploadDate ?? "").replace(/\D/g, "");
    if (!date) return false;
    if (rule.dateFrom && date < rule.dateFrom) return false;
    if (rule.dateTo && date > rule.dateTo) return false;
  }
  return true;
}

// The author of a live-chat cue. `common/lib/liveChat.ts` formats every cue as
// `${author}: ${message}` (and emits the bare message when the renderer carries
// no author), so the prefix up to the first ": " IS the contract — there is no
// `author` field on `Cue`. A cue with no such prefix has no author and can
// never match a chat-author rule.
export function chatAuthorOf(text: string): string | null {
  const at = text.indexOf(": ");
  if (at <= 0) return null;
  return text.slice(0, at);
}

// Tag ids whose rules match, sorted and deduped. Does not consult assignments —
// that is effectiveTagsFor's job.
export function evaluateCompiledRules(
  input: TagRuleInput,
  compiled: CompiledTagRules,
): string[] {
  if (compiled.isEmpty) return [];
  const hits = new Set<string>();

  const metaRules = compiled.metadata.filter((r) => ruleApplies(r, input));
  if (metaRules.length > 0) {
    const haystack = [
      input.title ?? "",
      input.description ?? "",
      (input.tags ?? []).join(" "),
    ].join("\n");
    for (const rule of metaRules) {
      if (hits.has(rule.tagId)) continue;
      if (rule.re.test(haystack)) hits.add(rule.tagId);
    }
  }

  // One pass over the cues for all rules of a kind, dropping each rule as soon
  // as it fires (first hit short-circuits — a tag is on a video or it is not,
  // and nothing counts hits).
  const scanCues = (
    rules: CompiledTagRule[],
    cues: readonly { text: string }[] | undefined,
    project: (text: string) => string | null,
  ) => {
    if (!cues || cues.length === 0) return;
    let pending = rules.filter(
      (r) => ruleApplies(r, input) && !hits.has(r.tagId),
    );
    if (pending.length === 0) return;
    for (const cue of cues) {
      const subject = project(cue.text ?? "");
      if (subject === null || subject === "") continue;
      let fired = false;
      for (const rule of pending) {
        if (rule.re.test(subject)) {
          hits.add(rule.tagId);
          fired = true;
        }
      }
      if (fired) {
        pending = pending.filter((r) => !hits.has(r.tagId));
        if (pending.length === 0) return;
      }
    }
  };

  scanCues(compiled.chatAuthor, input.chatCues, chatAuthorOf);
  scanCues(compiled.caption, input.captionCues, (text) => text);

  return Array.from(hits).sort();
}

// Convenience for callers with only a handful of videos (the editor's rule
// preview, tests). The index build must use compileTagRules once per build and
// call evaluateCompiledRules per video instead.
export function evaluateTagRules(
  input: TagRuleInput,
  defs: CuratedTagDef[],
): string[] {
  return evaluateCompiledRules(input, compileTagRules(defs));
}