@pythia-software/query-table-core 0.9.6 → 0.9.7

package/dist/index.js

@@ -451,16 +451,29 @@ var METRIC_OPTION_SPECS = {
     expressionY: "string",
     scope: ["allMatching", "shownRows"],
     groupLimit: "integer",
-    minCount: "positiveInteger",
+    minCount: "minCount",
     share: ["total", "group0"]
   },
+  minCount: {
+    min: "positiveInteger",
+    distinct: "string",
+    sum: "string"
+  },
   window: {
     reduce: ["total", "mean"],
     partial: ["omit", "include"]
   },
   dateGrouping: {
     field: "string",
-    interval: ["hour", "day", "week", "month", "year"],
+    interval: [
+      "hour",
+      "day",
+      "week",
+      "month",
+      "year",
+      "hourOfDay",
+      "dayOfWeek"
+    ],
     timeZone: "string",
     includeEmpty: "boolean",
     range: ["query", "observed", "custom"],
@@ -468,6 +481,10 @@ var METRIC_OPTION_SPECS = {
     end: "string",
     partialIntervals: ["include", "exclude"]
   },
+  occurrence: {
+    interval: ["hour", "day"],
+    includeEmpty: "boolean"
+  },
   display: {
     kind: [
       "auto",
@@ -548,6 +565,14 @@ function normalizeMetricOptions(raw) {
     for (const [key, spec] of Object.entries(specs)) {
       const v = input[key];
       if (v === void 0) continue;
+      if (spec === "minCount") {
+        const m = record2(v) ? copy(v, METRIC_OPTION_SPECS.minCount) : v;
+        const named = (x) => x === void 0 || typeof x === "string" && !!x && x.length <= 256;
+        if (record2(m) ? m.min !== void 0 && m.distinct === void 0 !== (m.sum === void 0) && named(m.distinct) && named(m.sum) : typeof m === "number" && Number.isSafeInteger(m) && m >= 1 && m <= 1e6)
+          result[key] = m;
+        else diagnostics.push(`Invalid metric ${key}.`);
+        continue;
+      }
       if (spec === "string" ? typeof v === "string" && v.length <= 1e4 : spec === "number" ? typeof v === "number" && Number.isFinite(v) : spec === "boolean" ? typeof v === "boolean" : spec === "integer" || spec === "positiveInteger" ? typeof v === "number" && Number.isSafeInteger(v) && v >= (spec === "positiveInteger" ? 1 : 0) && v <= 1e6 : typeof v === "string" && spec.includes(v))
         result[key] = v;
       else diagnostics.push(`Invalid metric ${key}.`);
@@ -573,6 +598,14 @@ function normalizeMetricOptions(raw) {
       const d = copy(raw.dateGrouping, METRIC_OPTION_SPECS.dateGrouping);
       if (typeof d.field !== "string" || !d.field || d.field.length > 256 || !d.interval || typeof d.includeEmpty !== "boolean" || !d.range)
         diagnostics.push("Invalid metric date grouping.");
+      const occurrence = raw.dateGrouping.occurrence;
+      if (record2(occurrence)) {
+        const o = copy(occurrence, METRIC_OPTION_SPECS.occurrence);
+        if (!o.interval || typeof o.includeEmpty !== "boolean")
+          diagnostics.push("Invalid metric date grouping occurrence.");
+        d.occurrence = o;
+      } else if (occurrence !== void 0)
+        diagnostics.push("Invalid metric date grouping occurrence.");
       out.dateGrouping = d;
     } else diagnostics.push("Invalid metric date grouping.");
   }
@@ -634,14 +667,472 @@ function normalizeMetricOptions(raw) {
   return out;
 }
 
+// src/relativeTime.ts
+var UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 };
+var MAX_RELATIVE_TIME_MS = 864e13;
+function parseRelativeDuration(value) {
+  const valid = /^[+-](?:[0-9]+(?:ms|s|m|h|d|w))+$/.exec(value);
+  if (!valid || valid[0] !== value) return null;
+  const body = value.slice(1);
+  const components = /([0-9]+)(ms|s|m|h|d|w)/g;
+  let total = 0;
+  for (const match of body.matchAll(components)) {
+    const amount = Number(match[1]);
+    const unit = UNIT_MS[match[2]];
+    if (!Number.isSafeInteger(amount) || amount > Math.floor((MAX_RELATIVE_TIME_MS - total) / unit)) return null;
+    total += amount * unit;
+  }
+  return value[0] === "-" && total !== 0 ? -total : total;
+}
+function evaluationTime(options2) {
+  const now = options2.now ?? Date.now();
+  if (!Number.isSafeInteger(now) || Math.abs(now) > MAX_RELATIVE_TIME_MS) throw new Error("Invalid query evaluation time");
+  return now;
+}
+function relativeTimestamp(now, offsetMs) {
+  const result = now + offsetMs;
+  if (!Number.isSafeInteger(result) || Math.abs(result) > MAX_RELATIVE_TIME_MS) throw new Error("Relative time exceeds datetime limits");
+  return result;
+}
+
+// src/ops.ts
+var NULLITY = ["is_null", "is_not_null"];
+var COMPLEMENT_OP = {
+  "=": "!=",
+  "!=": "=",
+  ">": "<=",
+  "<=": ">",
+  ">=": "<",
+  "<": ">=",
+  is_null: "is_not_null",
+  is_not_null: "is_null",
+  matches_regex: "not_matches_regex",
+  not_matches_regex: "matches_regex"
+};
+function negateClause(clause, allowedOps) {
+  if (clause.value === "0" && !clause.negated) {
+    const zeroComplement = clause.op === "length_gt" ? "length_eq" : clause.op === "length_eq" ? "length_gt" : null;
+    if (zeroComplement && (!allowedOps || allowedOps.includes(zeroComplement))) {
+      return { field: clause.field, op: zeroComplement, value: "0" };
+    }
+  }
+  const complement = COMPLEMENT_OP[clause.op];
+  if (complement && (!allowedOps || allowedOps.includes(complement))) {
+    const next2 = { field: clause.field, op: complement, value: clause.value };
+    return next2;
+  }
+  const next = { field: clause.field, op: clause.op, value: clause.value };
+  if (!clause.negated) next.negated = true;
+  return next;
+}
+function isNegativePredicate(clause) {
+  return Boolean(clause.negated) || clause.op === "!=" || clause.op === "not_matches_regex" || clause.op === "is_not_null";
+}
+var POSITIVE_OP_ORDER = ["=", ">", ">=", "contains", "starts_with", "ends_with", "length_gt", "length_lt", "length_eq", "matches_regex", "includes"];
+function opPairsForField(field) {
+  const ops = opsForField(field);
+  const allow = new Set(ops);
+  const pairs = [];
+  for (const op of POSITIVE_OP_ORDER) {
+    if (!allow.has(op)) continue;
+    const neg = negateClause({ field: "", op, value: "" }, ops);
+    pairs.push({ keep: { op, negated: false }, exclude: { op: neg.op, negated: Boolean(neg.negated) } });
+  }
+  if (allow.has("is_null") || allow.has("is_not_null")) {
+    pairs.push({ keep: { op: "is_null", negated: false }, exclude: { op: "is_not_null", negated: false } });
+  }
+  return pairs;
+}
+var OPS_BY_TYPE = {
+  text: [
+    "=",
+    "!=",
+    "contains",
+    "starts_with",
+    "ends_with",
+    "matches_regex",
+    "not_matches_regex",
+    "length_gt",
+    "length_lt",
+    "length_eq",
+    ...NULLITY
+  ],
+  enum: ["=", "!=", ...NULLITY],
+  number: ["=", "!=", ">", ">=", "<", "<=", ...NULLITY],
+  datetime: ["=", "!=", ">", ">=", "<", "<=", ...NULLITY],
+  bool: ["=", "!=", ...NULLITY],
+  textarray: ["includes", ...NULLITY]
+};
+var NULLARY_OPS = new Set(NULLITY);
+function opsForField(field) {
+  return field.filter?.ops ?? OPS_BY_TYPE[field.type];
+}
+function opAllowedForType(type, op) {
+  return OPS_BY_TYPE[type].includes(op);
+}
+function coerceValue(type, raw, now) {
+  switch (type) {
+    case "number": {
+      const n = Number(raw);
+      if (raw.trim() === "" || Number.isNaN(n)) throw new Error(`not a number: ${JSON.stringify(raw)}`);
+      return n;
+    }
+    case "bool": {
+      const v = raw.toLowerCase();
+      if (v === "true" || v === "1" || v === "t") return true;
+      if (v === "false" || v === "0" || v === "f") return false;
+      throw new Error(`not a bool: ${JSON.stringify(raw)}`);
+    }
+    case "datetime": {
+      if (raw.startsWith("+") || raw.startsWith("-")) {
+        const offset = parseRelativeDuration(raw);
+        if (offset === null) throw new Error(`not a signed duration: ${JSON.stringify(raw)}`);
+        return relativeTimestamp(now ?? Date.now(), offset);
+      }
+      const ms = Date.parse(raw);
+      if (Number.isNaN(ms)) throw new Error(`not a datetime: ${JSON.stringify(raw)}`);
+      return ms;
+    }
+    default:
+      return raw;
+  }
+}
+
+// src/metricDates.ts
+import { Temporal } from "temporal-polyfill";
+var METRIC_DATE_INTERVALS = [
+  "hour",
+  "day",
+  "week",
+  "month",
+  "year",
+  "hourOfDay",
+  "dayOfWeek"
+];
+var METRIC_CYCLE_INTERVALS = ["hourOfDay", "dayOfWeek"];
+function isMetricCycle(interval) {
+  return interval === "hourOfDay" || interval === "dayOfWeek";
+}
+function metricCycleSlots(interval) {
+  return interval === "hourOfDay" ? Array.from({ length: 24 }, (_, i) => i) : [1, 2, 3, 4, 5, 6, 7];
+}
+function metricCalendarUnit(interval) {
+  return interval === "hourOfDay" ? "hour" : interval === "dayOfWeek" ? "day" : interval;
+}
+function metricCycleSlot(time, interval, timeZone = "UTC") {
+  if (timeZone === "UTC") {
+    const date = new Date(time);
+    return interval === "hourOfDay" ? date.getUTCHours() : (date.getUTCDay() + 6) % 7 + 1;
+  }
+  const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
+  return interval === "hourOfDay" ? zoned.hour : zoned.dayOfWeek;
+}
+function metricDateTime(value, timeZone = "UTC") {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2}))?$/.test(
+    value
+  ))
+    throw Error(
+      "Date grouping requires ISO dates or timestamps with a timezone."
+    );
+  const time = Date.parse(value), month = Number(value.slice(5, 7)), day = Number(value.slice(8, 10));
+  const calendar = /* @__PURE__ */ new Date(0);
+  calendar.setUTCFullYear(Number(value.slice(0, 4)), month, 0);
+  if (!Number.isFinite(time) || month < 1 || month > 12 || day < 1 || day > calendar.getUTCDate())
+    throw Error("Invalid date grouping value.");
+  return value.length === 10 && timeZone !== "UTC" ? Temporal.PlainDate.from(value).toZonedDateTime(timeZone).epochMilliseconds : time;
+}
+function metricOffsetTransition(start, end, timeZone) {
+  if (end <= start) return void 0;
+  const offset = (time) => Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone).offsetNanoseconds;
+  const before = offset(start);
+  if (before === offset(end)) return void 0;
+  while (end - start > 1) {
+    const middle = Math.floor((start + end) / 2);
+    if (offset(middle) === before) start = middle;
+    else end = middle;
+  }
+  return end;
+}
+function metricDateFloor(time, cycleOrInterval, timeZone = "UTC") {
+  const interval = metricCalendarUnit(cycleOrInterval);
+  if (timeZone !== "UTC") {
+    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
+    if (interval === "hour") {
+      const floor = time - zoned.minute * 6e4 - zoned.second * 1e3 - zoned.millisecond;
+      return metricOffsetTransition(floor, time, timeZone) ?? floor;
+    }
+    let date2 = zoned.toPlainDate();
+    if (interval === "week") date2 = date2.subtract({ days: date2.dayOfWeek - 1 });
+    if (interval === "month" || interval === "year")
+      date2 = date2.with({ day: 1 });
+    if (interval === "year") date2 = date2.with({ month: 1 });
+    return date2.toZonedDateTime(timeZone).epochMilliseconds;
+  }
+  const date = new Date(time);
+  date.setUTCMinutes(0, 0, 0);
+  if (interval !== "hour") date.setUTCHours(0);
+  if (interval === "week")
+    date.setUTCDate(date.getUTCDate() - (date.getUTCDay() + 6) % 7);
+  if (interval === "month" || interval === "year") date.setUTCDate(1);
+  if (interval === "year") date.setUTCMonth(0);
+  return date.getTime();
+}
+function metricDateNext(time, cycleOrInterval, timeZone = "UTC") {
+  const interval = metricCalendarUnit(cycleOrInterval);
+  if (timeZone !== "UTC") {
+    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
+    if (interval === "hour") {
+      const target = zoned.toPlainDateTime().with({
+        minute: 0,
+        second: 0,
+        millisecond: 0,
+        microsecond: 0,
+        nanosecond: 0
+      }).add({ hours: 1 });
+      let next = target.toZonedDateTime(timeZone).epochMilliseconds;
+      if (next <= time)
+        next = target.toZonedDateTime(timeZone, {
+          disambiguation: "later"
+        }).epochMilliseconds;
+      return metricOffsetTransition(time, next, timeZone) ?? next;
+    }
+    let date2 = zoned.toPlainDate();
+    if (interval === "month") date2 = date2.with({ day: 1 }).add({ months: 1 });
+    else if (interval === "year")
+      date2 = date2.with({ month: 1, day: 1 }).add({ years: 1 });
+    else if (interval === "week")
+      date2 = date2.subtract({ days: date2.dayOfWeek - 1 }).add({ weeks: 1 });
+    else date2 = date2.add({ days: 1 });
+    return date2.toZonedDateTime(timeZone).epochMilliseconds;
+  }
+  const date = new Date(time);
+  if (interval === "hour") date.setUTCHours(date.getUTCHours() + 1);
+  else if (interval === "month") date.setUTCMonth(date.getUTCMonth() + 1);
+  else if (interval === "year") date.setUTCFullYear(date.getUTCFullYear() + 1);
+  else date.setUTCDate(date.getUTCDate() + (interval === "week" ? 7 : 1));
+  return date.getTime();
+}
+function metricCustomEndTime(value, timeZone = "UTC") {
+  const time = metricDateTime(value, timeZone);
+  return value.length === 10 ? metricDateNext(time, "day", timeZone) - 1 : time;
+}
+function isGroupingTimeZone(value) {
+  if (typeof value !== "string" || !value || value.length > 80 || /^[+-]/.test(value))
+    return false;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function validateDateGrouping(config) {
+  if (typeof config.field !== "string" || !config.field || config.field.length > 256 || !METRIC_DATE_INTERVALS.includes(config.interval) || typeof config.includeEmpty !== "boolean" || !["query", "observed", "custom"].includes(config.range) || config.partialIntervals !== void 0 && !["include", "exclude"].includes(config.partialIntervals))
+    throw Error("Invalid date grouping definition.");
+  if (config.timeZone !== void 0 && !isGroupingTimeZone(config.timeZone))
+    throw Error(
+      "Use a valid IANA grouping timezone, such as America/Denver or UTC."
+    );
+  if (config.occurrence !== void 0) {
+    const o = config.occurrence;
+    if (!o || typeof o !== "object" || Array.isArray(o) || !["hour", "day"].includes(o.interval) || typeof o.includeEmpty !== "boolean")
+      throw Error("Invalid date grouping occurrence.");
+    if (!isMetricCycle(config.interval))
+      throw Error(
+        "Occurrences summarise an hour-of-day or day-of-week slot; calendar intervals are already one occurrence each."
+      );
+    if (config.interval === "hourOfDay" && o.interval !== "hour")
+      throw Error("An hour-of-day slot occurs once per hour: use hourly occurrences.");
+    if (config.partialIntervals === "include")
+      throw Error(
+        "Occurrences are always whole: a partial day or hour would bias the typical value. Leave out partialIntervals."
+      );
+  }
+  if (config.range === "custom" && (isMetricCycle(config.interval) ? config.occurrence?.includeEmpty : config.includeEmpty)) {
+    const start = metricDateTime(config.start ?? "", config.timeZone), end = metricCustomEndTime(config.end ?? "", config.timeZone);
+    if (end < start)
+      throw Error("The end date must be on or after the start date.");
+  }
+}
+function metricDateRange(config, query, observed, now, canonical) {
+  let min = Infinity, max = -Infinity;
+  for (const time of observed) {
+    min = Math.min(min, time);
+    max = Math.max(max, time);
+  }
+  if (config.range === "observed")
+    return observed.length ? [min, max] : void 0;
+  if (config.range === "custom") {
+    const start2 = metricDateFloor(
+      metricDateTime(config.start ?? "", config.timeZone),
+      config.interval,
+      config.timeZone
+    );
+    const end2 = metricDateFloor(
+      metricCustomEndTime(config.end ?? "", config.timeZone),
+      config.interval,
+      config.timeZone
+    );
+    if (observed.length && (start2 > min || end2 < max))
+      throw Error(
+        "Custom date bounds must include all observed buckets. Narrow the query filters to exclude data."
+      );
+    return [start2, end2];
+  }
+  let start = -Infinity, end = Infinity;
+  for (const term of query.where) {
+    if (isWhereGroup(term) || term.negated || canonical(term.field) !== canonical(config.field))
+      continue;
+    if (!["=", ">", ">=", "<", "<="].includes(term.op)) continue;
+    const time = Number(coerceValue("datetime", term.value, now));
+    if (term.op === ">" || term.op === ">=" || term.op === "=")
+      start = Math.max(start, time + (term.op === ">" ? 1 : 0));
+    if (term.op === "<" || term.op === "<=" || term.op === "=")
+      end = Math.min(end, time - (term.op === "<" ? 1 : 0));
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    const missing = [
+      ...Number.isFinite(start) ? [] : ["a lower bound (>= or >)"],
+      ...Number.isFinite(end) ? [] : ["an upper bound (<= or <)"]
+    ].join(" and ");
+    throw Error(
+      `Include empty dates with range "query" needs a bounded date filter on ${config.field}: add ${missing} as top-level filters (bounds inside OR groups do not count). Otherwise use range "observed" to fill from the first to the last observed date, or range "custom" with start and end.`
+    );
+  }
+  if (end < start) return void 0;
+  return [
+    metricDateFloor(start, config.interval, config.timeZone),
+    metricDateFloor(end, config.interval, config.timeZone)
+  ];
+}
+
+// src/groupKeys.ts
+var GROUP_KEY_INTERVALS = ["hour", "day", "week", "month", "year"];
+function isCalendarGroupKey(key) {
+  return typeof key === "object" && key !== null;
+}
+function groupKeyField(key) {
+  return isCalendarGroupKey(key) ? key.field : key;
+}
+function groupKeyFields(keys) {
+  return keys.map(groupKeyField);
+}
+function calendarGroupKey(keys, field) {
+  return keys.find((key) => isCalendarGroupKey(key) && key.field === field);
+}
+function calendarKeyReader(key) {
+  let start = Infinity, end = -Infinity, iso = "";
+  return (value) => {
+    if (value == null) return null;
+    const input = value instanceof Date ? value.toISOString() : value;
+    if (typeof input !== "string")
+      throw Error(`Calendar group key ${key.field} needs ISO dates or timestamps with a timezone.`);
+    const time = metricDateTime(input, key.timeZone);
+    if (time < start || time >= end) {
+      start = metricDateFloor(time, key.interval, key.timeZone);
+      end = metricDateNext(start, key.interval, key.timeZone);
+      iso = new Date(start).toISOString();
+    }
+    return iso;
+  };
+}
+function datetimeValue(value) {
+  const time = value instanceof Date ? value.getTime() : typeof value === "number" ? value : typeof value === "string" && value !== "" ? Date.parse(value) : NaN;
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+function keyClause(field, value) {
+  if (!field || field.type === "textarray" || !isFilterable(field)) return null;
+  if (value == null) return { field: field.name, op: "is_null", value: "" };
+  if (field.type === "datetime") {
+    const iso = datetimeValue(value);
+    return iso === null ? null : { field: field.name, op: "=", value: iso };
+  }
+  if (typeof value === "number" ? !Number.isFinite(value) : typeof value !== "string" && typeof value !== "boolean")
+    return null;
+  return { field: field.name, op: "=", value: String(value) };
+}
+function calendarKeyClauses(field, key, value) {
+  if (!field || field.type !== "datetime" || !isFilterable(field)) return null;
+  if (value == null) return [{ field: field.name, op: "is_null", value: "" }];
+  const iso = datetimeValue(value);
+  if (iso === null) return null;
+  const start = Date.parse(iso), end = metricDateNext(start, key.interval, key.timeZone);
+  if (!Number.isFinite(end) || end <= start) return null;
+  return [
+    { field: field.name, op: ">=", value: iso },
+    { field: field.name, op: "<", value: new Date(end).toISOString() }
+  ];
+}
+function groupKeyTerms(keys, group, schema) {
+  const terms = [];
+  for (const key of keys) {
+    const name = groupKeyField(key);
+    const field = resolveField(schema, name);
+    if (isCalendarGroupKey(key)) {
+      const range = calendarKeyClauses(field, key, group[name]);
+      if (!range) return null;
+      terms.push(...range);
+      continue;
+    }
+    const term = keyClause(field, group[name]);
+    if (!term) return null;
+    terms.push(term);
+  }
+  return terms;
+}
+
 // src/query.ts
+function isWhereConjunction(branch) {
+  return branch != null && Array.isArray(branch.all);
+}
 function isOrGroup(term) {
+  const any = term.any;
+  return Array.isArray(any) && !any.some((member) => isWhereConjunction(member));
+}
+function isOrOfAndsGroup(term) {
+  const any = term.any;
+  return Array.isArray(any) && any.some(isWhereConjunction);
+}
+function isWhereGroup(term) {
   return Array.isArray(term.any);
 }
 function predicatesOf(term) {
-  return isOrGroup(term) ? term.any : [term];
+  if (!isWhereGroup(term)) return [term];
+  return term.any.flatMap((member) => isWhereConjunction(member) ? member.all : [member]);
+}
+function branchesOf(term) {
+  if (!isWhereGroup(term)) return [[term]];
+  return term.any.map((member) => isWhereConjunction(member) ? member.all : [member]);
 }
 var ITEM_DETAILS_COLUMN = "__qt_item_details__";
+var MAX_HOST_QUERY_PARAMS = 64;
+var MAX_HOST_QUERY_VALUES = 64;
+var MAX_HOST_QUERY_VALUE_LENGTH = 4e3;
+var MAX_HOST_QUERY_STATE_BYTES = 32 * 1024;
+var HOST_QUERY_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
+function parseHostQueryState(input) {
+  const fail = (why) => {
+    throw Error(`Invalid host query state: ${why}`);
+  };
+  if (!isRecord(input)) return fail("expected an object.");
+  if (Object.keys(input).some((key) => key !== "version" && key !== "params")) fail("unexpected properties.");
+  const version = input.version;
+  if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) return fail("unsupported version.");
+  if (!isRecord(input.params)) return fail("params must be an object.");
+  const names = Object.keys(input.params).sort();
+  if (names.length > MAX_HOST_QUERY_PARAMS) fail("too many parameters.");
+  const params = {};
+  for (const name of names) {
+    const values = input.params[name];
+    if (!HOST_QUERY_PARAM_NAME.test(name)) fail("invalid parameter name.");
+    if (!Array.isArray(values) || values.length > MAX_HOST_QUERY_VALUES || values.some((value) => typeof value !== "string" || value.length > MAX_HOST_QUERY_VALUE_LENGTH))
+      fail(`parameter ${name} must be a list of strings.`);
+    params[name] = [...values];
+  }
+  const state = { version, params };
+  if (new TextEncoder().encode(JSON.stringify(state)).length > MAX_HOST_QUERY_STATE_BYTES) fail("payload too large.");
+  return state;
+}
 var EMPTY_QUERY = {
   select: [],
   where: [],
@@ -704,7 +1195,7 @@ function normalizeWhereClause(item) {
   return clause;
 }
 function cloneWhereTerm(term) {
-  const copy = isOrGroup(term) ? { ...term, any: term.any.map((c) => ({ ...c })) } : { ...term };
+  const copy = isWhereGroup(term) ? { ...term, any: term.any.map((c) => isWhereConjunction(c) ? { all: c.all.map((m) => ({ ...m })) } : { ...c }) } : { ...term };
   if (term.setFilter) copy.setFilter = { ...term.setFilter, values: [...term.setFilter.values] };
   return copy;
 }
@@ -715,6 +1206,13 @@ function normalizeSetFilter(item) {
   if (item.values.length > MAX_WHERE_CLAUSES || !item.values.every((value) => typeof value === "string" && value.length <= MAX_FILTER_VALUE_LENGTH)) return void 0;
   return { id, mode: item.mode, values: [...item.values] };
 }
+function suppliedPredicateCount(term) {
+  if (!isRecord(term) || !Array.isArray(term.any)) return 1;
+  let count = 0;
+  for (const member of term.any)
+    count += isRecord(member) && Array.isArray(member.all) ? Math.max(1, member.all.length) : 1;
+  return count;
+}
 function normalizeWhereTerms(input) {
   const where = [];
   let literalBudget = MAX_WHERE_CLAUSES;
@@ -725,14 +1223,31 @@ function normalizeWhereTerms(input) {
       const members = [];
       for (const inner of item.any) {
         if (literalBudget <= 0) break;
+        if (isRecord(inner) && Array.isArray(inner.all)) {
+          const all = [];
+          for (const literal of inner.all) {
+            if (literalBudget <= 0) break;
+            const clause2 = normalizeWhereClause(literal);
+            if (clause2) {
+              all.push(clause2);
+              literalBudget--;
+            }
+          }
+          if (all.length === 1) members.push(all[0]);
+          else if (all.length > 1) members.push({ all });
+          continue;
+        }
         const clause = normalizeWhereClause(inner);
         if (clause) {
           members.push(clause);
           literalBudget--;
         }
       }
-      if (members.length === 1) where.push(members[0]);
-      else if (members.length > 1) where.push({ any: members });
+      if (members.length === 1) {
+        const only = members[0];
+        if (isWhereConjunction(only)) where.push(...only.all);
+        else where.push(only);
+      } else if (members.length > 1) where.push({ any: members });
     } else {
       const clause = normalizeWhereClause(item);
       if (clause) {
@@ -751,7 +1266,7 @@ function normalizeMetricWhere(value) {
   if (value === void 0) return { invalid: false };
   if (!Array.isArray(value)) return { invalid: true };
   const where = normalizeWhereTerms(value);
-  const supplied = value.reduce((count, term) => count + (isRecord(term) && Array.isArray(term.any) ? term.any.length : 1), 0);
+  const supplied = value.reduce((count, term) => count + suppliedPredicateCount(term), 0);
   const kept = where.reduce((count, term) => count + predicatesOf(term).length, 0);
   return { ...where.length ? { where } : {}, invalid: supplied !== kept };
 }
@@ -808,6 +1323,13 @@ function normalizeQuery(input, fallback, links) {
     offset: boundedInteger(raw.offset, fallback.offset, 0, MAX_QUERY_OFFSET)
   };
   if (raw.fitToScreen === true) out.fitToScreen = true;
+  if (links && raw.hostState !== void 0) {
+    try {
+      out.hostState = parseHostQueryState(raw.hostState);
+    } catch {
+      out.hostState = { version: 0, params: {} };
+    }
+  }
   if (raw.grouping != null) out.grouping = normalizeGroupingState(raw.grouping, links);
   if (Array.isArray(raw.aggregations)) {
     const aggregations = [];
@@ -879,8 +1401,20 @@ function normalizeGroupingState(value, links) {
   const fail = (message) => {
     diagnostics.push(`Invalid grouping: ${message}`);
   };
-  const keys = Array.isArray(raw.keys) ? raw.keys.slice(0, MAX_GROUP_BY_FIELDS).filter((key) => !!boundedString(key, MAX_FIELD_NAME_LENGTH)) : [];
-  if (!Array.isArray(raw.keys) || !keys.length || keys.length !== raw.keys.length || new Set(keys).size !== keys.length)
+  const keys = [];
+  for (const [index, key] of (Array.isArray(raw.keys) ? raw.keys.slice(0, MAX_GROUP_BY_FIELDS) : []).entries()) {
+    if (boundedString(key, MAX_FIELD_NAME_LENGTH)) {
+      keys.push(key);
+      continue;
+    }
+    if (!isRecord(key)) continue;
+    const field = boundedString(key.field, MAX_FIELD_NAME_LENGTH), zone = key.timeZone;
+    if (field && GROUP_KEY_INTERVALS.includes(key.interval) && (zone === void 0 || typeof zone === "string" && zone.length > 0 && zone.length <= 80 && !/^[+-]/.test(zone)))
+      keys.push({ field, interval: key.interval, ...zone !== void 0 ? { timeZone: zone } : {} });
+    else fail(`key ${index + 1} must be a field name or a calendar key {field, interval, timeZone} with interval hour, day, week, month or year; hour-of-day and day-of-week are metric intervals.`);
+  }
+  const keyNames = groupKeyFields(keys);
+  if (!Array.isArray(raw.keys) || !keys.length || keys.length !== raw.keys.length || new Set(keyNames).size !== keys.length)
     fail(`keys must list 1\u2013${MAX_GROUP_BY_FIELDS} distinct field names.`);
   const summaries = [];
   if (!Array.isArray(raw.summaries) || raw.summaries.length > 64) fail("summaries must be a list of at most 64 columns.");
@@ -897,7 +1431,7 @@ function normalizeGroupingState(value, links) {
     }
     const column = { id: item.id, op: item.op };
     if (summaryIds.has(column.id)) fail(`${name} uses the same id as another summary column.`);
-    else if (keys.includes(column.id)) fail(`${name} uses the same id as group key "${column.id}"; summary ids must differ from source field names.`);
+    else if (keyNames.includes(column.id)) fail(`${name} uses the same id as group key "${column.id}"; summary ids must differ from source field names.`);
     summaryIds.add(column.id);
     if (item.op === "link") {
       const link = normalizeLinkSpec(item.link);
@@ -946,13 +1480,13 @@ function normalizeGroupingState(value, links) {
   }
   if (!isRecord(raw.source)) fail("source must be the record query that is grouped.");
   else if (raw.source.grouping != null) fail("only one grouping stage is supported; the source query cannot itself be grouped.");
-  const { grouping: _nested, ...source } = isRecord(raw.source) ? raw.source : {};
+  const { grouping: _nested, hostState: _host, ...source } = isRecord(raw.source) ? raw.source : {};
   if (Array.isArray(raw.diagnostics))
     for (const message of raw.diagnostics.slice(0, 20))
       diagnostics.push(typeof message === "string" && message ? message.slice(0, MAX_LABEL_LENGTH) : "Invalid grouping definition.");
   const normalizedSource = normalizeQueryState(source);
   if (Array.isArray(source.where)) {
-    const supplied = source.where.reduce((count, term) => count + (isRecord(term) && Array.isArray(term.any) ? term.any.length : 1), 0);
+    const supplied = source.where.reduce((count, term) => count + suppliedPredicateCount(term), 0);
     if (supplied !== normalizedSource.where.reduce((count, term) => count + predicatesOf(term).length, 0)) fail("source filters contain malformed predicates or exceed the predicate budget.");
   }
   return { keys, summaries, representative, source: normalizedSource, ...diagnostics.length ? { diagnostics: [...new Set(diagnostics)] } : {} };
@@ -997,7 +1531,7 @@ function normalizeLinkSpec(value) {
 }
 function keptEveryTerm(supplied, kept) {
   if (!Array.isArray(supplied)) return false;
-  const count = supplied.reduce((total, term) => total + (isRecord(term) && Array.isArray(term.any) ? Math.max(1, term.any.length) : 1), 0);
+  const count = supplied.reduce((total, term) => total + Math.max(1, suppliedPredicateCount(term)), 0);
   return count === kept.reduce((total, term) => total + predicatesOf(term).length, 0);
 }
 function normalizeLinkPatch(value) {
@@ -1024,6 +1558,7 @@ function queriesEqual(a, b) {
   if (!sameArray(a.aggregations ?? [], b.aggregations ?? [])) return false;
   if (JSON.stringify(a.itemDetails) !== JSON.stringify(b.itemDetails)) return false;
   if (JSON.stringify(a.grouping) !== JSON.stringify(b.grouping)) return false;
+  if (JSON.stringify(a.hostState) !== JSON.stringify(b.hostState)) return false;
   return true;
 }
 function sameArray(a, b) {
@@ -1034,137 +1569,6 @@ function sameArray(a, b) {
   return true;
 }
 
-// src/relativeTime.ts
-var UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 };
-var MAX_RELATIVE_TIME_MS = 864e13;
-function parseRelativeDuration(value) {
-  const valid = /^[+-](?:[0-9]+(?:ms|s|m|h|d|w))+$/.exec(value);
-  if (!valid || valid[0] !== value) return null;
-  const body = value.slice(1);
-  const components = /([0-9]+)(ms|s|m|h|d|w)/g;
-  let total = 0;
-  for (const match of body.matchAll(components)) {
-    const amount = Number(match[1]);
-    const unit = UNIT_MS[match[2]];
-    if (!Number.isSafeInteger(amount) || amount > Math.floor((MAX_RELATIVE_TIME_MS - total) / unit)) return null;
-    total += amount * unit;
-  }
-  return value[0] === "-" && total !== 0 ? -total : total;
-}
-function evaluationTime(options2) {
-  const now = options2.now ?? Date.now();
-  if (!Number.isSafeInteger(now) || Math.abs(now) > MAX_RELATIVE_TIME_MS) throw new Error("Invalid query evaluation time");
-  return now;
-}
-function relativeTimestamp(now, offsetMs) {
-  const result = now + offsetMs;
-  if (!Number.isSafeInteger(result) || Math.abs(result) > MAX_RELATIVE_TIME_MS) throw new Error("Relative time exceeds datetime limits");
-  return result;
-}
-
-// src/ops.ts
-var NULLITY = ["is_null", "is_not_null"];
-var COMPLEMENT_OP = {
-  "=": "!=",
-  "!=": "=",
-  ">": "<=",
-  "<=": ">",
-  ">=": "<",
-  "<": ">=",
-  is_null: "is_not_null",
-  is_not_null: "is_null",
-  matches_regex: "not_matches_regex",
-  not_matches_regex: "matches_regex"
-};
-function negateClause(clause, allowedOps) {
-  if (clause.value === "0" && !clause.negated) {
-    const zeroComplement = clause.op === "length_gt" ? "length_eq" : clause.op === "length_eq" ? "length_gt" : null;
-    if (zeroComplement && (!allowedOps || allowedOps.includes(zeroComplement))) {
-      return { field: clause.field, op: zeroComplement, value: "0" };
-    }
-  }
-  const complement = COMPLEMENT_OP[clause.op];
-  if (complement && (!allowedOps || allowedOps.includes(complement))) {
-    const next2 = { field: clause.field, op: complement, value: clause.value };
-    return next2;
-  }
-  const next = { field: clause.field, op: clause.op, value: clause.value };
-  if (!clause.negated) next.negated = true;
-  return next;
-}
-function isNegativePredicate(clause) {
-  return Boolean(clause.negated) || clause.op === "!=" || clause.op === "not_matches_regex" || clause.op === "is_not_null";
-}
-var POSITIVE_OP_ORDER = ["=", ">", ">=", "contains", "starts_with", "ends_with", "length_gt", "length_lt", "length_eq", "matches_regex", "includes"];
-function opPairsForField(field) {
-  const ops = opsForField(field);
-  const allow = new Set(ops);
-  const pairs = [];
-  for (const op of POSITIVE_OP_ORDER) {
-    if (!allow.has(op)) continue;
-    const neg = negateClause({ field: "", op, value: "" }, ops);
-    pairs.push({ keep: { op, negated: false }, exclude: { op: neg.op, negated: Boolean(neg.negated) } });
-  }
-  if (allow.has("is_null") || allow.has("is_not_null")) {
-    pairs.push({ keep: { op: "is_null", negated: false }, exclude: { op: "is_not_null", negated: false } });
-  }
-  return pairs;
-}
-var OPS_BY_TYPE = {
-  text: [
-    "=",
-    "!=",
-    "contains",
-    "starts_with",
-    "ends_with",
-    "matches_regex",
-    "not_matches_regex",
-    "length_gt",
-    "length_lt",
-    "length_eq",
-    ...NULLITY
-  ],
-  enum: ["=", "!=", ...NULLITY],
-  number: ["=", "!=", ">", ">=", "<", "<=", ...NULLITY],
-  datetime: ["=", "!=", ">", ">=", "<", "<=", ...NULLITY],
-  bool: ["=", "!=", ...NULLITY],
-  textarray: ["includes", ...NULLITY]
-};
-var NULLARY_OPS = new Set(NULLITY);
-function opsForField(field) {
-  return field.filter?.ops ?? OPS_BY_TYPE[field.type];
-}
-function opAllowedForType(type, op) {
-  return OPS_BY_TYPE[type].includes(op);
-}
-function coerceValue(type, raw, now) {
-  switch (type) {
-    case "number": {
-      const n = Number(raw);
-      if (raw.trim() === "" || Number.isNaN(n)) throw new Error(`not a number: ${JSON.stringify(raw)}`);
-      return n;
-    }
-    case "bool": {
-      const v = raw.toLowerCase();
-      if (v === "true" || v === "1" || v === "t") return true;
-      if (v === "false" || v === "0" || v === "f") return false;
-      throw new Error(`not a bool: ${JSON.stringify(raw)}`);
-    }
-    case "datetime": {
-      if (raw.startsWith("+") || raw.startsWith("-")) {
-        const offset = parseRelativeDuration(raw);
-        if (offset === null) throw new Error(`not a signed duration: ${JSON.stringify(raw)}`);
-        return relativeTimestamp(now ?? Date.now(), offset);
-      }
-      const ms = Date.parse(raw);
-      if (Number.isNaN(ms)) throw new Error(`not a datetime: ${JSON.stringify(raw)}`);
-      return ms;
-    }
-    default:
-      return raw;
-  }
-}
-
 // src/agg.ts
 var AGG_OPS_BY_TYPE = {
   number: ["count", "count_distinct", "sum", "avg", "min", "max"],
@@ -1231,7 +1635,8 @@ function createSetFilter(field, mode, values, id, target = "array") {
 }
 function stripSetFilter(term) {
   const strip = ({ setFilter: _metadata, ...clause }) => clause;
-  return isOrGroup(term) ? { any: term.any.map(strip) } : strip(term);
+  if (!isWhereGroup(term)) return strip(term);
+  return { any: term.any.map((member) => isWhereConjunction(member) ? { all: member.all.map(strip) } : strip(member)) };
 }
 function readSetFilter(where, index) {
   const term = where[index];
@@ -1296,6 +1701,7 @@ function compactQuery(q) {
   if (q.itemDetails) c.d = q.itemDetails;
   if (q.fitToScreen) c.fs = true;
   if (q.grouping) c.b = q.grouping;
+  if (q.hostState) c.h = q.hostState;
   return c;
 }
 var MAX_QUERY_STATE_BYTES = 4 * 1024 * 1024;
@@ -1422,7 +1828,7 @@ function decodeToken(token, strict) {
     const c = versioned ? unpackQuery(raw) : raw;
     if (strict && c.w) {
       if (c.w.some((term) => !term || typeof term !== "object")) throw new QueryDecodeError("invalid", "Invalid query predicates.");
-      const count = c.w.reduce((n, term) => n + predicatesOf(term).length, 0);
+      const count = c.w.reduce((n, term) => n + suppliedPredicateCount(term), 0);
       const normalized = normalizeQueryState({ where: c.w });
       const normalizedCount = normalized.where.reduce((n, term) => n + predicatesOf(term).length, 0);
       if (count > 100 || count !== normalizedCount || c.w.some((term) => predicatesOf(term).some((clause) => !clause || typeof clause !== "object" || clause.negated !== void 0 && typeof clause.negated !== "boolean")))
@@ -1437,8 +1843,16 @@ function decodeToken(token, strict) {
       aggregations: c.g,
       itemDetails: c.d,
       fitToScreen: c.fs,
-      grouping: c.b
+      grouping: c.b,
+      hostState: c.h
     });
+    if (strict && c.h !== void 0) {
+      try {
+        parseHostQueryState(c.h);
+      } catch {
+        throw new QueryDecodeError("invalid", "Invalid host state in query link.");
+      }
+    }
     if (strict && c.g && out.aggregations?.length !== c.g.length) throw new QueryDecodeError("invalid", "Invalid query metrics.");
     return out;
   } catch (error) {
@@ -1505,7 +1919,7 @@ function termIsPushdown(term, byName, resolveField2) {
 }
 function toAggregationQuery(q, schema) {
   if (q.grouping) throw new Error("Metrics over grouped rows require grouped-query execution.");
-  const suppliedPredicateCount = q.where.reduce((n, t) => n + predicatesOf(t).length, 0);
+  const suppliedCount = q.where.reduce((n, t) => n + predicatesOf(t).length, 0);
   q = normalizeQueryState(q);
   if (q.aggregations?.some((a) => a.dateGrouping)) throw new Error("Date grouping currently requires local metric execution.");
   if (q.aggregations?.some((a) => a.diagnostics?.length || a.expression !== void 0 || a.expressionY !== void 0 || a.distribution || a.scope === "shownRows" || a.sort?.length || a.groupLimit || a.where?.length || a.minCount !== void 0)) throw new Error("Metric definition requires the version 2 metric transport.");
@@ -1523,7 +1937,7 @@ function toAggregationQuery(q, schema) {
   );
   const diagnostics = [];
   for (const c of q.aggregations ?? []) if (!aggregations.includes(c)) diagnostics.push({ metricId: c.id, code: "unsupported_metric", message: "Metric requires unavailable backend fields.", from: 0, to: 1 });
-  if (where.length !== q.where.length || suppliedPredicateCount !== q.where.reduce((n, t) => n + predicatesOf(t).length, 0)) diagnostics.push({ code: "residual_filter", message: "All-matching metrics are unavailable with residual client-only filters.", from: 0, to: 1 });
+  if (where.length !== q.where.length || suppliedCount !== q.where.reduce((n, t) => n + predicatesOf(t).length, 0)) diagnostics.push({ code: "residual_filter", message: "All-matching metrics are unavailable with residual client-only filters.", from: 0, to: 1 });
   return { where, aggregations, ...diagnostics.length ? { diagnostics } : {} };
 }
 
@@ -3121,176 +3535,6 @@ function formulaRuntime(ast, inputs, extension) {
   }
 }
 
-// src/metricDates.ts
-import { Temporal } from "temporal-polyfill";
-var METRIC_DATE_INTERVALS = [
-  "hour",
-  "day",
-  "week",
-  "month",
-  "year"
-];
-function metricDateTime(value, timeZone = "UTC") {
-  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2}))?$/.test(
-    value
-  ))
-    throw Error(
-      "Date grouping requires ISO dates or timestamps with a timezone."
-    );
-  const time = Date.parse(value), month = Number(value.slice(5, 7)), day = Number(value.slice(8, 10));
-  const calendar = /* @__PURE__ */ new Date(0);
-  calendar.setUTCFullYear(Number(value.slice(0, 4)), month, 0);
-  if (!Number.isFinite(time) || month < 1 || month > 12 || day < 1 || day > calendar.getUTCDate())
-    throw Error("Invalid date grouping value.");
-  return value.length === 10 && timeZone !== "UTC" ? Temporal.PlainDate.from(value).toZonedDateTime(timeZone).epochMilliseconds : time;
-}
-function metricOffsetTransition(start, end, timeZone) {
-  if (end <= start) return void 0;
-  const offset = (time) => Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone).offsetNanoseconds;
-  const before = offset(start);
-  if (before === offset(end)) return void 0;
-  while (end - start > 1) {
-    const middle = Math.floor((start + end) / 2);
-    if (offset(middle) === before) start = middle;
-    else end = middle;
-  }
-  return end;
-}
-function metricDateFloor(time, interval, timeZone = "UTC") {
-  if (timeZone !== "UTC") {
-    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
-    if (interval === "hour") {
-      const floor = time - zoned.minute * 6e4 - zoned.second * 1e3 - zoned.millisecond;
-      return metricOffsetTransition(floor, time, timeZone) ?? floor;
-    }
-    let date2 = zoned.toPlainDate();
-    if (interval === "week") date2 = date2.subtract({ days: date2.dayOfWeek - 1 });
-    if (interval === "month" || interval === "year")
-      date2 = date2.with({ day: 1 });
-    if (interval === "year") date2 = date2.with({ month: 1 });
-    return date2.toZonedDateTime(timeZone).epochMilliseconds;
-  }
-  const date = new Date(time);
-  date.setUTCMinutes(0, 0, 0);
-  if (interval !== "hour") date.setUTCHours(0);
-  if (interval === "week")
-    date.setUTCDate(date.getUTCDate() - (date.getUTCDay() + 6) % 7);
-  if (interval === "month" || interval === "year") date.setUTCDate(1);
-  if (interval === "year") date.setUTCMonth(0);
-  return date.getTime();
-}
-function metricDateNext(time, interval, timeZone = "UTC") {
-  if (timeZone !== "UTC") {
-    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
-    if (interval === "hour") {
-      const target = zoned.toPlainDateTime().with({
-        minute: 0,
-        second: 0,
-        millisecond: 0,
-        microsecond: 0,
-        nanosecond: 0
-      }).add({ hours: 1 });
-      let next = target.toZonedDateTime(timeZone).epochMilliseconds;
-      if (next <= time)
-        next = target.toZonedDateTime(timeZone, {
-          disambiguation: "later"
-        }).epochMilliseconds;
-      return metricOffsetTransition(time, next, timeZone) ?? next;
-    }
-    let date2 = zoned.toPlainDate();
-    if (interval === "month") date2 = date2.with({ day: 1 }).add({ months: 1 });
-    else if (interval === "year")
-      date2 = date2.with({ month: 1, day: 1 }).add({ years: 1 });
-    else if (interval === "week")
-      date2 = date2.subtract({ days: date2.dayOfWeek - 1 }).add({ weeks: 1 });
-    else date2 = date2.add({ days: 1 });
-    return date2.toZonedDateTime(timeZone).epochMilliseconds;
-  }
-  const date = new Date(time);
-  if (interval === "hour") date.setUTCHours(date.getUTCHours() + 1);
-  else if (interval === "month") date.setUTCMonth(date.getUTCMonth() + 1);
-  else if (interval === "year") date.setUTCFullYear(date.getUTCFullYear() + 1);
-  else date.setUTCDate(date.getUTCDate() + (interval === "week" ? 7 : 1));
-  return date.getTime();
-}
-function metricCustomEndTime(value, timeZone = "UTC") {
-  const time = metricDateTime(value, timeZone);
-  return value.length === 10 ? metricDateNext(time, "day", timeZone) - 1 : time;
-}
-function validateDateGrouping(config) {
-  if (typeof config.field !== "string" || !config.field || config.field.length > 256 || !METRIC_DATE_INTERVALS.includes(config.interval) || typeof config.includeEmpty !== "boolean" || !["query", "observed", "custom"].includes(config.range) || config.partialIntervals !== void 0 && !["include", "exclude"].includes(config.partialIntervals))
-    throw Error("Invalid date grouping definition.");
-  if (config.timeZone !== void 0) {
-    if (typeof config.timeZone !== "string" || !config.timeZone || config.timeZone.length > 80 || /^[+-]/.test(config.timeZone))
-      throw Error(
-        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
-      );
-    try {
-      new Intl.DateTimeFormat("en-US", { timeZone: config.timeZone });
-    } catch {
-      throw Error(
-        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
-      );
-    }
-  }
-  if (config.includeEmpty && config.range === "custom") {
-    const start = metricDateTime(config.start ?? "", config.timeZone), end = metricCustomEndTime(config.end ?? "", config.timeZone);
-    if (end < start)
-      throw Error("The end date must be on or after the start date.");
-  }
-}
-function metricDateRange(config, query, observed, now, canonical) {
-  let min = Infinity, max = -Infinity;
-  for (const time of observed) {
-    min = Math.min(min, time);
-    max = Math.max(max, time);
-  }
-  if (config.range === "observed")
-    return observed.length ? [min, max] : void 0;
-  if (config.range === "custom") {
-    const start2 = metricDateFloor(
-      metricDateTime(config.start ?? "", config.timeZone),
-      config.interval,
-      config.timeZone
-    );
-    const end2 = metricDateFloor(
-      metricCustomEndTime(config.end ?? "", config.timeZone),
-      config.interval,
-      config.timeZone
-    );
-    if (observed.length && (start2 > min || end2 < max))
-      throw Error(
-        "Custom date bounds must include all observed buckets. Narrow the query filters to exclude data."
-      );
-    return [start2, end2];
-  }
-  let start = -Infinity, end = Infinity;
-  for (const term of query.where) {
-    if (isOrGroup(term) || term.negated || canonical(term.field) !== canonical(config.field))
-      continue;
-    if (!["=", ">", ">=", "<", "<="].includes(term.op)) continue;
-    const time = Number(coerceValue("datetime", term.value, now));
-    if (term.op === ">" || term.op === ">=" || term.op === "=")
-      start = Math.max(start, time + (term.op === ">" ? 1 : 0));
-    if (term.op === "<" || term.op === "<=" || term.op === "=")
-      end = Math.min(end, time - (term.op === "<" ? 1 : 0));
-  }
-  if (!Number.isFinite(start) || !Number.isFinite(end)) {
-    const missing = [
-      ...Number.isFinite(start) ? [] : ["a lower bound (>= or >)"],
-      ...Number.isFinite(end) ? [] : ["an upper bound (<= or <)"]
-    ].join(" and ");
-    throw Error(
-      `Include empty dates with range "query" needs a bounded date filter on ${config.field}: add ${missing} as top-level filters (bounds inside OR groups do not count). Otherwise use range "observed" to fill from the first to the last observed date, or range "custom" with start and end.`
-    );
-  }
-  if (end < start) return void 0;
-  return [
-    metricDateFloor(start, config.interval, config.timeZone),
-    metricDateFloor(end, config.interval, config.timeZone)
-  ];
-}
-
 // src/metricPrecision.ts
 function assertMetricNumber(value) {
   if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) {
@@ -3307,11 +3551,110 @@ function checkedMetricResult(result) {
   }
 }
 
+// src/metricDistributions.ts
+function percentile(sorted, p) {
+  if (!Number.isFinite(p) || p < 0 || p > 1)
+    throw Error("Percentile must be between zero and one.");
+  if (sorted.some((v, i) => !Number.isFinite(v) || i > 0 && v < sorted[i - 1]))
+    throw Error("Percentile inputs must be sorted finite numbers.");
+  sorted.forEach(assertMetricNumber);
+  if (!sorted.length) return null;
+  const position = (sorted.length - 1) * p, lower = Math.floor(position), fraction = position - lower;
+  const a = sorted[lower], b = sorted[Math.min(lower + 1, sorted.length - 1)];
+  const raw = (1 - fraction) * a + fraction * b;
+  assertMetricNumber(raw);
+  const value = Math.min(b, Math.max(a, raw));
+  return value;
+}
+function boxSummary(values, whiskers = "minmax") {
+  if (values.some((v) => !Number.isFinite(v)))
+    throw Error("Distribution inputs must be finite numbers.");
+  values.forEach(assertMetricNumber);
+  const sorted = [...values].sort((a, b) => a - b), n = sorted.length;
+  if (!n) return null;
+  const min = sorted[0], max = sorted[n - 1], q1 = percentile(sorted, 0.25), median = percentile(sorted, 0.5), q3 = percentile(sorted, 0.75);
+  const lowFence = q1 - 1.5 * (q3 - q1), highFence = q3 + 1.5 * (q3 - q1);
+  const low = whiskers === "tukey" ? sorted.find((v) => v >= lowFence) : min;
+  const high = whiskers === "tukey" ? [...sorted].reverse().find((v) => v <= highFence) : max;
+  const outside = whiskers === "tukey" ? sorted.filter((v) => v < low || v > high) : [];
+  const outliers = outside.length <= 20 ? outside : [...outside.slice(0, 10), ...outside.slice(-10)];
+  const rawMean = sorted.reduce((sum, value) => sum + value / n, 0);
+  assertMetricNumber(rawMean);
+  const mean = Math.min(max, Math.max(min, rawMean));
+  [min, q1, median, q3, max, mean, low, high].forEach(assertMetricNumber);
+  return {
+    n,
+    min,
+    q1,
+    median,
+    q3,
+    max,
+    mean,
+    low,
+    high,
+    outliers,
+    outlierCount: outside.length,
+    whiskers,
+    method: "exact-linear"
+  };
+}
+function histogramEdges(values, bins) {
+  if (!Number.isInteger(bins) || bins < 2 || bins > 30)
+    throw Error("Choose 2\u201330 histogram bins.");
+  if (values.some((v) => !Number.isFinite(v)))
+    throw Error("Histogram inputs must be finite numbers.");
+  values.forEach(assertMetricNumber);
+  if (!values.length) return [];
+  let min = Infinity, max = -Infinity;
+  for (const value of values) {
+    min = Math.min(min, value);
+    max = Math.max(max, value);
+  }
+  if (min === max) return [min, max];
+  if (!Number.isFinite(max - min))
+    throw Error("Histogram range exceeds finite numeric precision.");
+  const edges = Array.from(
+    { length: bins + 1 },
+    (_, i) => min + (max - min) * (i / bins)
+  );
+  edges[0] = min;
+  edges[bins] = max;
+  edges.forEach(assertMetricNumber);
+  if (edges.some((value, i) => i > 0 && value <= edges[i - 1]))
+    throw Error(
+      "Histogram bins are finer than numeric precision. Reduce the bin count."
+    );
+  return edges;
+}
+function histogramCounts(values, edges) {
+  if (values.some((v) => !Number.isFinite(v)))
+    throw Error("Histogram inputs must be finite numbers.");
+  if (!edges.length) {
+    if (values.length) throw Error("Histogram values require edges.");
+    return [];
+  }
+  if (edges.length < 2 || edges.some(
+    (v, i) => !Number.isFinite(v) || i > 0 && (v < edges[i - 1] || v === edges[i - 1] && edges.length !== 2)
+  ))
+    throw Error("Histogram edges must be ordered finite boundaries.");
+  values.forEach(assertMetricNumber);
+  edges.forEach(assertMetricNumber);
+  const counts = Array(edges.length - 1).fill(0);
+  for (const value of values) {
+    if (value < edges[0] || value > edges[edges.length - 1])
+      throw Error("Value falls outside shared histogram edges.");
+    let bin = 0;
+    while (bin < counts.length - 1 && value >= edges[bin + 1]) bin++;
+    counts[bin] = counts[bin] + 1;
+  }
+  return counts;
+}
+
 // src/metricSeries.ts
 var MAX_METRIC_WINDOW_PERIODS = 1e3;
 var MERGEABLE = ["SUM", "COUNT", "MIN", "MAX", "AVG"];
 function hasMetricSeries(c) {
-  return c.window !== void 0 || c.share !== void 0 || c.dateGrouping?.partialIntervals !== void 0;
+  return c.window !== void 0 || c.share !== void 0 || c.dateGrouping?.partialIntervals !== void 0 || c.dateGrouping?.occurrence !== void 0;
 }
 var soleAggregate = (plan) => plan.ast.kind === "call" && plan.aggregates.includes(plan.ast) ? plan.ast.name : void 0;
 var partBudget = (c, plan) => (c.window && (c.window.reduce ?? "total") === "total" ? plan.aggregates.reduce((n, node) => n + (node.name === "AVG" ? 2 : 1), 0) : 1) * (c.share ? 2 : 1);
@@ -3324,7 +3667,7 @@ function validateMetricSeries(c, plan) {
     );
   const metric = plan, sole = soleAggregate(metric);
   if (window) {
-    if (!c.dateGrouping)
+    if (!c.dateGrouping || isMetricCycle(c.dateGrouping.interval))
       throw new FormulaError(
         "A window needs a calendar interval on the first grouping field."
       );
@@ -3374,12 +3717,12 @@ function validateMetricSeries(c, plan) {
       `A window or share runs one metric per aggregate; this one needs more than ${MAX_AGGREGATIONS}.`
     );
 }
-function wholeIntervalSpan(c, query, schema, now) {
-  const { field, interval, timeZone } = c.dateGrouping;
+function metricDateBounds(c, query, schema, now) {
+  const { field } = c.dateGrouping;
   const canonical = (name) => resolveFieldName(schema, name) ?? name;
   let lower = -Infinity, upper = Infinity;
   for (const term of [...query.where, ...c.where ?? []]) {
-    if (isOrGroup(term) || term.negated || canonical(term.field) !== canonical(field) || !["=", ">", ">=", "<", "<="].includes(term.op))
+    if (isWhereGroup(term) || term.negated || canonical(term.field) !== canonical(field) || !["=", ">", ">=", "<", "<="].includes(term.op))
       continue;
     if (term.value === "") continue;
     let time;
@@ -3394,6 +3737,11 @@ function wholeIntervalSpan(c, query, schema, now) {
     if (term.op === "<" || term.op === "<=" || term.op === "=")
       upper = Math.min(upper, time + (term.op === "<" ? 0 : 1));
   }
+  return { lower, upper };
+}
+function wholeIntervalSpan(c, query, schema, now) {
+  const { interval, timeZone } = c.dateGrouping;
+  const { lower, upper } = metricDateBounds(c, query, schema, now);
   const floor = (time) => metricDateFloor(time, interval, timeZone);
   const end = floor(Math.min(upper, now));
   if (!Number.isFinite(lower)) return { end };
@@ -3431,45 +3779,88 @@ function planMetricSeries(query, schema, options2 = {}) {
   function prepare(c) {
     const issue = validateMetric(c, schema, options2.resolveComputed)[0];
     if (issue) return { kind: "error", clause: c, error: issue.message };
+    function whole(config) {
+      let where2 = c.where ?? [], dateGrouping2 = config;
+      const span = wholeIntervalSpan(
+        { ...c, dateGrouping: config },
+        query,
+        schema,
+        now
+      );
+      if (span.start !== void 0 && span.end <= span.start) {
+        if (!isMetricCycle(config.interval)) return void 0;
+        span.end = span.start;
+      }
+      const field = resolveFieldName(schema, config.field) ?? config.field;
+      const iso = (time) => new Date(time).toISOString();
+      where2 = [
+        ...where2,
+        ...span.start !== void 0 ? [{ field, op: ">=", value: iso(span.start) }] : [],
+        { field, op: "<", value: iso(span.end) }
+      ];
+      if (config.includeEmpty && config.range !== "observed" && !isMetricCycle(config.interval)) {
+        const floor = (time) => metricDateFloor(time, config.interval, config.timeZone);
+        let from = span.start, through = span.end - 1;
+        if (config.range === "custom") {
+          const start = floor(
+            metricDateTime(config.start ?? "", config.timeZone)
+          );
+          from = Math.max(from ?? start, start);
+          through = Math.min(
+            through,
+            metricCustomEndTime(config.end ?? "", config.timeZone)
+          );
+        }
+        if (from !== void 0) {
+          if (through < from) return void 0;
+          dateGrouping2 = {
+            ...config,
+            range: "custom",
+            start: iso(from),
+            end: iso(through)
+          };
+        }
+      }
+      return { where: where2, dateGrouping: dateGrouping2 };
+    }
     let where = c.where ?? [];
     let dateGrouping;
     if (c.dateGrouping) {
-      const { partialIntervals, ...config } = c.dateGrouping;
-      dateGrouping = config;
-      if (partialIntervals === "exclude") {
-        const span = wholeIntervalSpan(c, query, schema, now);
-        if (span.start !== void 0 && span.end <= span.start)
-          return { kind: "empty", clause: c };
-        const field = resolveFieldName(schema, config.field) ?? config.field;
-        const iso = (time) => new Date(time).toISOString();
-        where = [
-          ...where,
-          ...span.start !== void 0 ? [{ field, op: ">=", value: iso(span.start) }] : [],
-          { field, op: "<", value: iso(span.end) }
-        ];
-        if (config.includeEmpty && config.range !== "observed") {
-          const floor = (time) => metricDateFloor(time, config.interval, config.timeZone);
-          let from = span.start, through = span.end - 1;
-          if (config.range === "custom") {
-            const start = floor(
-              metricDateTime(config.start ?? "", config.timeZone)
-            );
-            from = Math.max(from ?? start, start);
-            through = Math.min(
-              through,
-              metricCustomEndTime(config.end ?? "", config.timeZone)
-            );
-          }
-          if (from !== void 0) {
-            if (through < from) return { kind: "empty", clause: c };
-            dateGrouping = {
-              ...config,
-              range: "custom",
-              start: iso(from),
-              end: iso(through)
-            };
-          }
-        }
+      const { partialIntervals, occurrence, ...config } = c.dateGrouping;
+      const narrowed = occurrence ? whole({
+        ...config,
+        interval: occurrence.interval,
+        includeEmpty: occurrence.includeEmpty
+      }) : partialIntervals === "exclude" ? whole(config) : { where, dateGrouping: config };
+      if (!narrowed) return { kind: "empty", clause: c };
+      ({ where, dateGrouping } = narrowed);
+      if (occurrence) {
+        const {
+          dateGrouping: _date,
+          where: _where,
+          scope: _scope,
+          distribution: _distribution,
+          display: _display,
+          sort: _sort,
+          groupLimit: _limit,
+          minCount: _min,
+          label: _label,
+          layout: _layout,
+          ...rest
+        } = c;
+        return {
+          kind: "occurrence",
+          clause: c,
+          parts: [
+            {
+              ...rest,
+              id: id(),
+              ...c.scope ? { scope: c.scope } : {},
+              ...where.length ? { where } : {},
+              dateGrouping
+            }
+          ]
+        };
       }
     }
     const scoped = (groupBy) => ({
@@ -3517,16 +3908,33 @@ function planMetricSeries(query, schema, options2 = {}) {
         ...scoped(groupBy)
       })
     );
+    const all = [
+      ...parts(c.groupBy),
+      ...c.share === "group0" ? parts(c.groupBy.slice(0, 1)) : c.share === "total" ? parts([]) : []
+    ];
+    const measure = metricMinCountMeasure(c);
+    const minPart = measure ? all.length : void 0;
+    if (measure)
+      all.push({
+        id: id(),
+        op: "count",
+        expression: metricExpression({
+          id: "",
+          groupBy: [],
+          op: measure.op,
+          field: resolveFieldName(schema, measure.field) ?? measure.field
+        }),
+        groupBy: c.groupBy,
+        ...scoped(c.groupBy)
+      });
     return {
       kind: "series",
       clause: c,
       plan,
-      parts: [
-        ...parts(c.groupBy),
-        ...c.share === "group0" ? parts(c.groupBy.slice(0, 1)) : c.share === "total" ? parts([]) : []
-      ],
+      parts: all,
       ...reductions ? { reductions } : {},
-      size: texts.length
+      size: texts.length,
+      ...minPart !== void 0 ? { minPart } : {}
     };
   }
   const queries = [];
@@ -3548,14 +3956,16 @@ function planMetricSeries(query, schema, options2 = {}) {
         const c = item.clause;
         if (item.kind === "error")
           return { id: c.id, buckets: [], error: item.error };
-        if (item.kind === "empty")
-          return {
+        if (item.kind === "empty") {
+          const none = {
             id: c.id,
             buckets: [],
             scope: c.scope ?? "allMatching",
             groupCount: 0,
             coverage: "exact"
           };
+          return c.dateGrouping?.occurrence ? combineOccurrences(c, none) : none;
+        }
         const entries = item.parts.map(
           (part) => byId.get(part.id) ?? {
             id: part.id,
@@ -3565,6 +3975,8 @@ function planMetricSeries(query, schema, options2 = {}) {
         );
         if (item.kind === "plain") return { ...entries[0], id: c.id };
         try {
+          if (item.kind === "occurrence")
+            return combineOccurrences(c, entries[0]);
           return combineSeries(item, entries);
         } catch (e) {
           return {
@@ -3617,7 +4029,7 @@ function combineSeries(item, entries) {
         "A window or share needs every group, but the engine returned only some of them."
       );
   }
-  const numerator = entries.slice(0, item.size), denominator = c.share ? entries.slice(item.size) : [];
+  const numerator = entries.slice(0, item.size), denominator = c.share ? entries.slice(item.size, item.minPart) : [], threshold = item.minPart !== void 0 ? entries[item.minPart] : void 0;
   const dateOf = (keys) => keys[0] === null || keys[0] === void 0 ? void 0 : keys[0];
   const times = /* @__PURE__ */ new Map();
   if (window)
@@ -3727,10 +4139,32 @@ function combineSeries(item, entries) {
       ...own.intervals !== void 0 ? { intervals: own.intervals } : {}
     };
   });
+  const thresholdTracks = threshold ? tracks(threshold) : void 0, thresholdBuckets = threshold ? exact(threshold) : void 0;
+  const measureOf = (keys) => {
+    const at = positionOf(keys);
+    let members;
+    if (!window || at === void 0)
+      members = [thresholdBuckets.get(JSON.stringify(keys))];
+    else {
+      const from = Math.max(0, at - periods + 1), track = thresholdTracks.get(JSON.stringify(keys.slice(1)));
+      members = Array.from(
+        { length: at - from + 1 },
+        (_, i) => track?.[from + i]
+      );
+    }
+    const sum = new Accumulator("SUM");
+    for (const bucket of members) sum.add(bucket);
+    return sum.result();
+  };
   let hiddenGroups;
-  if (c.minCount !== void 0) {
+  const min = metricMinCount(c);
+  if (min !== void 0) {
     const kept = buckets.filter(
-      (b) => b.count === 0 || b.count >= c.minCount
+      (b) => metricMinCountKeeps(
+        min,
+        b.count,
+        threshold ? measureOf(b.keys) : void 0
+      )
     );
     hiddenGroups = buckets.length - kept.length;
     buckets = kept;
@@ -3749,31 +4183,87 @@ function combineSeries(item, entries) {
     ...hiddenGroups !== void 0 ? { hiddenGroups } : {}
   };
 }
-
-// src/groupKeys.ts
-function datetimeValue(value) {
-  const time = value instanceof Date ? value.getTime() : typeof value === "number" ? value : typeof value === "string" && value !== "" ? Date.parse(value) : NaN;
-  return Number.isFinite(time) ? new Date(time).toISOString() : null;
-}
-function keyClause(field, value) {
-  if (!field || field.type === "textarray" || !isFilterable(field)) return null;
-  if (value == null) return { field: field.name, op: "is_null", value: "" };
-  if (field.type === "datetime") {
-    const iso = datetimeValue(value);
-    return iso === null ? null : { field: field.name, op: "=", value: iso };
-  }
-  if (typeof value === "number" ? !Number.isFinite(value) : typeof value !== "string" && typeof value !== "boolean")
-    return null;
-  return { field: field.name, op: "=", value: String(value) };
-}
-function groupKeyTerms(keys, group, schema) {
-  const terms = [];
-  for (const key of keys) {
-    const term = keyClause(resolveField(schema, key), group[key]);
-    if (!term) return null;
-    terms.push(term);
+function combineOccurrences(c, entry) {
+  const config = c.dateGrouping, cycle = config.interval;
+  if (!isMetricCycle(cycle)) throw Error("Invalid date grouping occurrence.");
+  if (entry.error) throw Error(entry.error);
+  if (entry.coverage === "partial" || (entry.groupCount ?? entry.buckets.length) > entry.buckets.length)
+    throw Error(
+      "Occurrences need every interval, but the engine returned only some of them."
+    );
+  const slots = /* @__PURE__ */ new Map();
+  const slotOf = (keys) => {
+    const key = JSON.stringify(keys);
+    let slot = slots.get(key);
+    if (!slot) slots.set(key, slot = { keys, count: 0, values: [] });
+    return slot;
+  };
+  for (const bucket of entry.buckets) {
+    if (bucket.keys[0] === null || bucket.keys[0] === void 0) continue;
+    const slot = slotOf([
+      metricCycleSlot(metricDateTime(bucket.keys[0]), cycle, config.timeZone),
+      ...bucket.keys.slice(1)
+    ]);
+    slot.count += bucket.count;
+    if (slot.error) continue;
+    if (bucket.error) slot.error = bucket.error;
+    else if (typeof bucket.value === "number") slot.values.push(bucket.value);
+    else if (bucket.value !== null)
+      slot.error = "Occurrence values must be numeric.";
+  }
+  if (config.includeEmpty) {
+    const tails = /* @__PURE__ */ new Map();
+    for (const slot of slots.values())
+      tails.set(JSON.stringify(slot.keys.slice(1)), slot.keys.slice(1));
+    if (c.groupBy.length === 1 && !tails.size) tails.set("[]", []);
+    for (const number of metricCycleSlots(cycle))
+      for (const tail of tails.values()) slotOf([number, ...tail]);
+  }
+  const box = occurrenceDistribution(c);
+  let buckets = [...slots.values()].map((slot) => {
+    const bucket = {
+      keys: slot.keys,
+      count: slot.count,
+      value: null,
+      occurrences: slot.values.length
+    };
+    if (slot.error) return { ...bucket, error: slot.error };
+    try {
+      if (box) {
+        const summary = boxSummary(slot.values, c.distribution.whiskers);
+        bucket.distribution = { kind: "box", summary };
+        bucket.value = summary?.median ?? null;
+      } else if (slot.values.length) {
+        const mean = slot.values.reduce((sum, value) => sum + value, 0) / slot.values.length;
+        assertMetricNumber(mean);
+        bucket.value = mean;
+      }
+    } catch (e) {
+      return { ...bucket, value: null, error: e.message };
+    }
+    return bucket;
+  });
+  let hiddenGroups;
+  const min = metricMinCount(c);
+  if (min !== void 0) {
+    const kept = buckets.filter(
+      (b) => b.count === 0 || b.count >= min
+    );
+    hiddenGroups = buckets.length - kept.length;
+    buckets = kept;
   }
-  return terms;
+  sortMetricBuckets(buckets, c);
+  const groupCount = buckets.length;
+  if (c.groupLimit) buckets = buckets.slice(0, c.groupLimit);
+  return {
+    id: c.id,
+    buckets,
+    scope: entry.scope ?? c.scope ?? "allMatching",
+    ...entry.processedRows !== void 0 ? { processedRows: entry.processedRows } : {},
+    groupCount,
+    coverage: "exact",
+    ...hiddenGroups !== void 0 ? { hiddenGroups } : {}
+  };
 }
 
 // src/grouping.ts
@@ -3793,29 +4283,37 @@ function withoutGrouping(query) {
   return result;
 }
 function exitGrouping(query) {
-  return query.grouping ? query.grouping.source : query;
+  if (!query.grouping) return query;
+  if (!query.hostState && !query.grouping.source.hostState) return query.grouping.source;
+  const { hostState: _source, ...source } = query.grouping.source;
+  return query.hostState ? { ...source, hostState: query.hostState } : source;
 }
 function withGroupingKeys(query, keys) {
   const before = query.grouping;
   if (!keys.length) return exitGrouping(query);
-  if (!before)
+  const names = groupKeyFields(keys);
+  if (!before) {
+    const { hostState, ...source } = query;
     return {
-      select: keys.map((field) => ({ field })),
+      select: names.map((field) => ({ field })),
       where: [],
       orderBy: [],
       limit: query.limit,
       offset: 0,
-      grouping: { keys, summaries: [], representative: null, source: query }
+      grouping: { keys, summaries: [], representative: null, source },
+      ...hostState ? { hostState } : {}
     };
-  const removed = new Set(before.keys.filter((key) => !keys.includes(key)));
-  const columns = query.select.length ? query.select : before.keys.map((field) => ({ field }));
+  }
+  const previous = groupKeyFields(before.keys);
+  const removed = new Set(previous.filter((key) => !names.includes(key)));
+  const columns = query.select.length ? query.select : previous.map((field) => ({ field }));
   return {
     ...query,
     grouping: { ...before, keys },
     offset: 0,
     aggregations: [],
     select: [
-      ...keys.filter((key) => !before.keys.includes(key)).map((field) => ({ field })),
+      ...names.filter((key) => !previous.includes(key)).map((field) => ({ field })),
       ...columns.filter((c) => !removed.has(c.field))
     ],
     where: query.where.filter(
@@ -3905,14 +4403,15 @@ function createGroupingModel(inputSchema) {
     if (link.to.kind === "template")
       for (const name of templateFields(link.to.template)) names.add(name);
     else if (link.to.keyFilters !== false)
-      for (const key of keys) names.add(key);
+      for (const key of keys) names.add(groupKeyField(key));
     return [...names];
   }
   function linkProblem(column, keys, summaries) {
     const link = column.link;
     if (column.op !== "link") return null;
     if (!link) return "Invalid link definition.";
-    const readable = (name) => keys.includes(name) || summaries.some((other) => other.id === name && other.op !== "link");
+    const names = groupKeyFields(keys);
+    const readable = (name) => names.includes(name) || summaries.some((other) => other.id === name && other.op !== "link");
     if (typeof link.label === "object" && !readable(link.label.column))
       return `Unknown link label column: ${link.label.column}.`;
     if (link.to.kind === "template") {
@@ -3920,7 +4419,7 @@ function createGroupingModel(inputSchema) {
       return urlTemplateProblem(link.to.template, [], readable);
     }
     if (link.to.keyFilters !== false)
-      for (const key of keys) {
+      for (const key of names) {
         const field = sourceField(key);
         if (field?.type === "textarray")
           return `Key filters cannot match the textarray key ${field.label}.`;
@@ -3969,11 +4468,12 @@ function createGroupingModel(inputSchema) {
         aggregate: { measure: false, groupable: false }
       },
       ...keys.flatMap((key) => {
-        const field = sourceField(key);
+        const field = sourceField(groupKeyField(key));
         if (!field) return [];
         return [{
-          name: key,
-          label: field.label,
+          // A calendar key's column holds each interval's start instant.
+          name: field.name,
+          label: isCalendarGroupKey(key) ? `${field.label} (${key.interval})` : field.label,
           type: field.type,
           source: { kind: "backend" },
           ...field.select ? { select: { ...field.select } } : {},
@@ -4054,7 +4554,7 @@ function createGroupingModel(inputSchema) {
       name: `${inputSchema.name}:groups`,
       idField: GROUP_ID_FIELD,
       fields,
-      defaultSelect: keys.filter((key) => sourceField(key)).map((field) => ({ field })),
+      defaultSelect: groupKeyFields(keys).filter((key) => sourceField(key)).map((field) => ({ field })),
       defaultLimit: 25
     };
     return schema;
@@ -4066,13 +4566,8 @@ function createGroupingModel(inputSchema) {
       return value;
     throw new Error("Group keys must be finite scalar values.");
   }
-  function groupId(row, keys, schema) {
-    const tuple = [...keys].sort().map((key) => [
-      key,
-      keyValue(
-        readFieldValue(schema.fields.find((f2) => f2.name === key), row)
-      )
-    ]);
+  function groupId(values) {
+    const tuple = [...values].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, value]) => [key, keyValue(value)]);
     if (tuple.some(
       ([key, value]) => String(key).length + String(value).length > 1e4
     ))
@@ -4141,11 +4636,21 @@ function createGroupingModel(inputSchema) {
       throw new Error("Grouping row budget exceeded.");
     let bytes = rows.length * 16;
     let operations = 0;
+    const readers = keys.map((key) => {
+      const name = groupKeyField(key);
+      const field = schema.fields.find((f2) => f2.name === name);
+      const calendar = isCalendarGroupKey(key) ? calendarKeyReader(key) : null;
+      return [
+        name,
+        (row) => calendar ? calendar(readFieldValue(field, row)) : readFieldValue(field, row)
+      ];
+    });
     const groups = /* @__PURE__ */ new Map();
     for (const row of rows) {
-      const id = groupId(row, keys, schema);
+      const values = readers.map(([, read]) => read(row));
+      const id = groupId(readers.map(([name], i) => [name, values[i]]));
       const bucket = groups.get(id);
-      if (bucket) bucket.push(row);
+      if (bucket) bucket.rows.push(row);
       else {
         if (groups.size >= MAX_RESULT_GROUPS)
           throw new Error(
@@ -4154,7 +4659,7 @@ function createGroupingModel(inputSchema) {
         bytes += id.length * 2 + 256;
         if (bytes > 16e6)
           throw new Error("Grouping retained-memory budget exceeded.");
-        groups.set(id, [row]);
+        groups.set(id, { keys: values, rows: [row] });
       }
     }
     const formulas = new Map(
@@ -4181,15 +4686,13 @@ function createGroupingModel(inputSchema) {
         compiled.plan?.aggregates.map(nodeCost) ?? []
       ])
     );
-    return [...groups].map(([id, members]) => {
+    return [...groups].map(([id, { keys: values, rows: members }]) => {
       const output = Object.assign(/* @__PURE__ */ Object.create(null), {
         [GROUP_ID_FIELD]: id
       });
-      for (const key of keys)
-        output[key] = readFieldValue(
-          schema.fields.find((f2) => f2.name === key),
-          members[0]
-        );
+      readers.forEach(([name], i) => {
+        output[name] = values[i];
+      });
       const chosen = rule && summaries.some((column) => column.op === "row") ? representative(members, rule, schema) : null;
       for (const column of summaries) {
         if (column.op === "link") continue;
@@ -4209,7 +4712,7 @@ function createGroupingModel(inputSchema) {
                   throw new Error("Grouping operation budget exceeded.");
                 const rowPlan = rowPlans[i];
                 if (!rowPlan) return { value: 1 };
-                const values = Object.fromEntries(
+                const values2 = Object.fromEntries(
                   rowPlan.dependencies.map((name) => {
                     const value = readFieldValue(
                       schema.fields.find((f2) => f2.name === name),
@@ -4221,7 +4724,7 @@ function createGroupingModel(inputSchema) {
                     ];
                   })
                 );
-                return formulaRuntime(rowPlan.ast, values);
+                return formulaRuntime(rowPlan.ast, values2);
               })
             )
           );
@@ -4290,10 +4793,33 @@ function createGroupingModel(inputSchema) {
   function validate(definition) {
     if (definition.diagnostics?.length)
       throw new Error(definition.diagnostics.join(" "));
-    if (!definition.keys.length || definition.keys.length > MAX_GROUP_BY_FIELDS || new Set(definition.keys).size !== definition.keys.length || definition.keys.some(
-      (key) => key === GROUP_ID_FIELD || !groupableFields.some((f2) => f2.name === key)
+    const names = definition.keys.map(
+      (key) => typeof key === "string" || isCalendarGroupKey(key) ? groupKeyField(key) : ""
+    );
+    if (!definition.keys.length || definition.keys.length > MAX_GROUP_BY_FIELDS || new Set(names).size !== names.length || names.some(
+      (key) => typeof key !== "string" || key === GROUP_ID_FIELD || !groupableFields.some((f2) => f2.name === key)
     ))
       throw new Error("Choose valid group keys from the source schema.");
+    for (const key of definition.keys) {
+      if (!isCalendarGroupKey(key)) continue;
+      const field = sourceField(key.field);
+      if (isMetricCycle(key.interval))
+        throw new Error(
+          `Group key ${field.label}: hour-of-day and day-of-week are metric intervals (dateGrouping); a group key takes hour, day, week, month or year.`
+        );
+      if (!GROUP_KEY_INTERVALS.includes(key.interval))
+        throw new Error(
+          `Group key ${field.label}: choose an hour, day, week, month or year interval.`
+        );
+      if (field.type !== "datetime")
+        throw new Error(
+          `Group key ${field.label}: a calendar interval needs a datetime field.`
+        );
+      if (key.timeZone !== void 0 && !isGroupingTimeZone(key.timeZone))
+        throw new Error(
+          `Group key ${field.label}: use a valid IANA timezone, such as America/Denver or UTC.`
+        );
+    }
     if (definition.summaries.length > MAX_SUMMARY_COLUMNS)
       throw new Error("Too many aggregate columns.");
     const ids = /* @__PURE__ */ new Set([
@@ -4449,105 +4975,6 @@ function toServerQueryV2(q, schema, execution) {
   };
 }
 
-// src/metricDistributions.ts
-function percentile(sorted, p) {
-  if (!Number.isFinite(p) || p < 0 || p > 1)
-    throw Error("Percentile must be between zero and one.");
-  if (sorted.some((v, i) => !Number.isFinite(v) || i > 0 && v < sorted[i - 1]))
-    throw Error("Percentile inputs must be sorted finite numbers.");
-  sorted.forEach(assertMetricNumber);
-  if (!sorted.length) return null;
-  const position = (sorted.length - 1) * p, lower = Math.floor(position), fraction = position - lower;
-  const a = sorted[lower], b = sorted[Math.min(lower + 1, sorted.length - 1)];
-  const raw = (1 - fraction) * a + fraction * b;
-  assertMetricNumber(raw);
-  const value = Math.min(b, Math.max(a, raw));
-  return value;
-}
-function boxSummary(values, whiskers = "minmax") {
-  if (values.some((v) => !Number.isFinite(v)))
-    throw Error("Distribution inputs must be finite numbers.");
-  values.forEach(assertMetricNumber);
-  const sorted = [...values].sort((a, b) => a - b), n = sorted.length;
-  if (!n) return null;
-  const min = sorted[0], max = sorted[n - 1], q1 = percentile(sorted, 0.25), median = percentile(sorted, 0.5), q3 = percentile(sorted, 0.75);
-  const lowFence = q1 - 1.5 * (q3 - q1), highFence = q3 + 1.5 * (q3 - q1);
-  const low = whiskers === "tukey" ? sorted.find((v) => v >= lowFence) : min;
-  const high = whiskers === "tukey" ? [...sorted].reverse().find((v) => v <= highFence) : max;
-  const outside = whiskers === "tukey" ? sorted.filter((v) => v < low || v > high) : [];
-  const outliers = outside.length <= 20 ? outside : [...outside.slice(0, 10), ...outside.slice(-10)];
-  const rawMean = sorted.reduce((sum, value) => sum + value / n, 0);
-  assertMetricNumber(rawMean);
-  const mean = Math.min(max, Math.max(min, rawMean));
-  [min, q1, median, q3, max, mean, low, high].forEach(assertMetricNumber);
-  return {
-    n,
-    min,
-    q1,
-    median,
-    q3,
-    max,
-    mean,
-    low,
-    high,
-    outliers,
-    outlierCount: outside.length,
-    whiskers,
-    method: "exact-linear"
-  };
-}
-function histogramEdges(values, bins) {
-  if (!Number.isInteger(bins) || bins < 2 || bins > 30)
-    throw Error("Choose 2\u201330 histogram bins.");
-  if (values.some((v) => !Number.isFinite(v)))
-    throw Error("Histogram inputs must be finite numbers.");
-  values.forEach(assertMetricNumber);
-  if (!values.length) return [];
-  let min = Infinity, max = -Infinity;
-  for (const value of values) {
-    min = Math.min(min, value);
-    max = Math.max(max, value);
-  }
-  if (min === max) return [min, max];
-  if (!Number.isFinite(max - min))
-    throw Error("Histogram range exceeds finite numeric precision.");
-  const edges = Array.from(
-    { length: bins + 1 },
-    (_, i) => min + (max - min) * (i / bins)
-  );
-  edges[0] = min;
-  edges[bins] = max;
-  edges.forEach(assertMetricNumber);
-  if (edges.some((value, i) => i > 0 && value <= edges[i - 1]))
-    throw Error(
-      "Histogram bins are finer than numeric precision. Reduce the bin count."
-    );
-  return edges;
-}
-function histogramCounts(values, edges) {
-  if (values.some((v) => !Number.isFinite(v)))
-    throw Error("Histogram inputs must be finite numbers.");
-  if (!edges.length) {
-    if (values.length) throw Error("Histogram values require edges.");
-    return [];
-  }
-  if (edges.length < 2 || edges.some(
-    (v, i) => !Number.isFinite(v) || i > 0 && (v < edges[i - 1] || v === edges[i - 1] && edges.length !== 2)
-  ))
-    throw Error("Histogram edges must be ordered finite boundaries.");
-  values.forEach(assertMetricNumber);
-  edges.forEach(assertMetricNumber);
-  const counts = Array(edges.length - 1).fill(0);
-  for (const value of values) {
-    if (value < edges[0] || value > edges[edges.length - 1])
-      throw Error("Value falls outside shared histogram edges.");
-    let bin = 0;
-    while (bin < counts.length - 1 && value >= edges[bin + 1]) bin++;
-    counts[bin] = counts[bin] + 1;
-  }
-  return counts;
-}
-
 // src/metrics.ts
 var aggregates = /* @__PURE__ */ new Set([
   "COUNT",
@@ -4801,8 +5228,11 @@ function hasRegex(plan) {
 function distributionActive(c) {
   return !!c.distribution && (!c.display || c.display.kind === "box" || c.display.kind === "histogram");
 }
+function occurrenceDistribution(c) {
+  return distributionActive(c) && !!c.dateGrouping?.occurrence;
+}
 function metricPlans(c, schema, resolve) {
-  if (distributionActive(c)) {
+  if (distributionActive(c) && !occurrenceDistribution(c)) {
     const p = compileFormula(
       c.distribution.input,
       resolve ? schema.fields.filter(
@@ -4862,21 +5292,28 @@ function validateMetric(c, schema, resolve) {
         throw new FormulaError(
           "Date grouping must use the first grouping field, with a datetime type."
         );
-      if (distributionActive(c))
+      const { occurrence } = c.dateGrouping;
+      if (occurrence) {
+        if (distributionActive(c) && c.distribution.kind !== "box")
+          throw new FormulaError(
+            "Occurrences summarise as a mean or a box plot, not a histogram."
+          );
+        if (c.display?.kind === "scatter")
+          throw new FormulaError(
+            "Occurrences summarise single-value metrics, not scatters."
+          );
+        if (c.window || c.share !== void 0)
+          throw new FormulaError(
+            "Windows and shares do not apply to occurrences of a slot."
+          );
+      } else if (distributionActive(c))
         throw new FormulaError(
           "Date grouping currently supports scalar metrics, not distributions."
         );
     }
     if (c.groupLimit !== void 0 && (!Number.isInteger(c.groupLimit) || c.groupLimit < 1 || c.groupLimit > 1e4))
       throw new FormulaError("Group limit must be 1\u201310,000.");
-    if (c.minCount !== void 0) {
-      if (!Number.isInteger(c.minCount) || c.minCount < 1 || c.minCount > 1e6)
-        throw new FormulaError("Minimum rows per group must be 1\u20131,000,000.");
-      if (!c.groupBy.length)
-        throw new FormulaError(
-          "Minimum rows per group requires at least one grouping field."
-        );
-    }
+    if (c.minCount !== void 0) validateMinCount(c, schema);
     validateMetricWhere(c.where, schema);
     for (const s of c.sort ?? []) {
       if (s.key === "y" && c.display?.kind !== "scatter")
@@ -4903,6 +5340,81 @@ function validateMetric(c, schema, resolve) {
     ];
   }
 }
+function metricMinCount(c) {
+  const m = c.minCount;
+  return m === void 0 ? void 0 : typeof m === "number" ? m : m?.min;
+}
+function metricMinCountMeasure(c) {
+  const m = c.minCount;
+  if (m === void 0 || m === null || typeof m !== "object") return void 0;
+  return m.distinct !== void 0 ? { op: "count_distinct", field: m.distinct } : { op: "sum", field: m.sum };
+}
+function metricMinCountText(c, label = (field) => field) {
+  const min = metricMinCount(c), measure = metricMinCountMeasure(c);
+  if (min === void 0) return void 0;
+  const n = min.toLocaleString();
+  if (!measure) return `${n} ${min === 1 ? "row" : "rows"}`;
+  return measure.op === "sum" ? `${n} total ${label(measure.field)}` : `${n} distinct ${label(measure.field)} ${min === 1 ? "value" : "values"}`;
+}
+function metricMinCountPlan(c, schema, resolve) {
+  const measure = metricMinCountMeasure(c);
+  return measure ? compileMetric(
+    metricExpression({
+      id: "",
+      groupBy: [],
+      op: measure.op,
+      field: resolveFieldName(schema, measure.field) ?? measure.field
+    }),
+    schema,
+    resolve
+  ) : void 0;
+}
+function metricMinCountKeeps(min, count, measure) {
+  if (count === 0) return true;
+  if (!measure) return count >= min;
+  return measure.error !== void 0 || Number(measure.value ?? 0) >= min;
+}
+function validateMinCount(c, schema) {
+  const m = c.minCount;
+  const measured = m !== null && typeof m === "object";
+  const min = measured ? m.min : m;
+  const label = measured ? "Minimum per group" : "Minimum rows per group";
+  if (typeof min !== "number" || !Number.isInteger(min) || min < 1 || min > 1e6)
+    throw new FormulaError(`${label} must be 1\u20131,000,000.`);
+  if (measured) {
+    const o = m;
+    if (Object.keys(o).some((k) => !["min", "distinct", "sum"].includes(k)) || o.distinct === void 0 === (o.sum === void 0))
+      throw new FormulaError(
+        "A minimum per group needs exactly one of distinct and sum."
+      );
+    const name = o.distinct ?? o.sum;
+    const op = o.distinct !== void 0 ? "count_distinct" : "sum";
+    const resolved = typeof name === "string" ? resolveFieldName(schema, name) ?? name : "";
+    const field = schema.fields.find((f2) => f2.name === resolved);
+    if (op === "sum" && field && field.type !== "number")
+      throw new FormulaError(
+        `A summed minimum requires a numeric field, not ${resolved}.`
+      );
+    if (!field || isComputedField(resolved) || !isMeasurable(field) || !aggOpsForField(field).includes(op))
+      throw new FormulaError(
+        op === "sum" ? `Field ${String(name)} cannot be summed for a minimum per group.` : `Field ${String(name)} cannot count distinct values for a minimum per group.`
+      );
+    if (distributionActive(c))
+      throw new FormulaError(
+        "A distinct or summed minimum currently supports scalar metrics, not distributions."
+      );
+    if (c.window && op === "count_distinct")
+      throw new FormulaError(
+        "A distinct minimum cannot be combined across a window's intervals."
+      );
+    if (c.dateGrouping?.occurrence)
+      throw new FormulaError(
+        "A distinct or summed minimum does not apply to occurrences of a slot; use a minimum of rows."
+      );
+  }
+  if (!c.groupBy.length)
+    throw new FormulaError(`${label} requires at least one grouping field.`);
+}
 function validateMetricWhere(where, schema) {
   if (where === void 0) return;
   if (!Array.isArray(where)) throw new FormulaError("Invalid metric filter.");
@@ -4930,13 +5442,23 @@ function metricPopulationError(clause, support) {
     return "This server does not support metric filters.";
   if (clause.minCount !== void 0 && !support.minCount)
     return "This server does not support a minimum rows per group.";
+  if (metricMinCountMeasure(clause) && !support.minCountMeasures)
+    return "This server does not support a minimum of distinct values or a sum per group.";
   return void 0;
 }
 function metricDependencies(c, schema, resolve) {
   return [
     .../* @__PURE__ */ new Set([
       ...c.groupBy.map((name) => resolveFieldName(schema, name) ?? name),
-      ...metricPlans(c, schema, resolve).flatMap((p) => p.dependencies)
+      ...metricPlans(c, schema, resolve).flatMap((p) => p.dependencies),
+      // An invalid minimum fails validation, not dependency discovery.
+      ...(() => {
+        try {
+          return metricMinCountPlan(c, schema, resolve)?.dependencies;
+        } catch {
+          return void 0;
+        }
+      })() ?? []
     ])
   ].sort();
 }
@@ -4946,7 +5468,7 @@ function metricComputationKey(clauses) {
       id: c.id,
       diagnostics: c.diagnostics,
       unsupportedOp: c.unsupportedOp,
-      expression: distributionActive(c) ? void 0 : metricExpression(c),
+      expression: distributionActive(c) && !occurrenceDistribution(c) ? void 0 : metricExpression(c),
       expressionY: c.display?.kind === "scatter" ? c.expressionY : void 0,
       scope: c.scope ?? "allMatching",
       groupBy: c.groupBy,
@@ -5046,7 +5568,7 @@ function toMetricQuery(q, schema, execution) {
         code: "unexpanded_series",
         from: 0,
         to: 1,
-        message: "Windows, shares and whole intervals are computed from plain metrics; expand the query with planMetricSeries first."
+        message: "Windows, shares, whole intervals and occurrences are computed from plain metrics; expand the query with planMetricSeries first."
       });
   for (const c of q.aggregations ?? [])
     if (c.dateGrouping)
@@ -5395,7 +5917,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
                 config.interval,
                 config.timeZone
               );
-              dateKey = new Date(dateStart).toISOString();
+              dateKey = isMetricCycle(config.interval) ? metricCycleSlot(dateStart, config.interval, config.timeZone) : new Date(dateStart).toISOString();
             }
             keys[0] = dateKey;
           }
@@ -5429,7 +5951,8 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
               tick();
               reserve(8);
               groupBytes += 8;
-              observed.push(metricDateTime(group.keys[0]));
+              if (!isMetricCycle(config.interval))
+                observed.push(metricDateTime(group.keys[0]));
               const tuple = group.keys.slice(1);
               const key = JSON.stringify(tuple);
               if (!series2.has(key)) {
@@ -5444,7 +5967,24 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
             groupBytes += 132;
             series2.set("[]", []);
           }
-          const range = metricDateRange(
+          const slots = isMetricCycle(config.interval) ? metricCycleSlots(config.interval) : void 0;
+          for (const slot of slots ?? [])
+            for (const tuple of series2.values()) {
+              tick();
+              const keys = [slot, ...tuple];
+              const key = JSON.stringify(keys);
+              if (key.length > keyLimit)
+                throw Error("Metric grouping key length budget exceeded.");
+              if (!groups.has(key)) {
+                if (groups.size >= (options2.maxGroups ?? 1e4))
+                  throw Error("Metric group budget exceeded.");
+                const bytes = 256 + 16 * keys.length + 4 * key.length;
+                reserve(bytes);
+                groupBytes += bytes;
+                groups.set(key, { keys, rows: [] });
+              }
+            }
+          const range = slots ? void 0 : metricDateRange(
             config,
             q,
             observed,
@@ -5539,12 +6079,16 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           );
         };
         const populations = /* @__PURE__ */ new Map();
+        const minPlan = metricMinCountPlan(c, schema, options2.resolveComputed);
+        const measures = /* @__PURE__ */ new Map();
         let buckets = [...groups.values()].map((g) => {
           const bucket = {
             keys: g.keys,
             count: g.rows.length,
             value: null
           };
+          if (minPlan && g.rows.length)
+            measures.set(bucket, reduce(minPlan, g.rows, /* @__PURE__ */ new Set()));
           if (distributionActive(c)) {
             const values = [];
             bucket.nullCount = 0;
@@ -5607,9 +6151,10 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           }
         }
         let hiddenGroups;
-        if (c.minCount !== void 0) {
+        const min = metricMinCount(c);
+        if (min !== void 0) {
           const kept = buckets.filter(
-            (b) => b.count === 0 || b.count >= c.minCount
+            (b) => metricMinCountKeeps(min, b.count, minPlan ? measures.get(b) : void 0)
           );
           hiddenGroups = buckets.length - kept.length;
           buckets = kept;
@@ -5710,7 +6255,7 @@ function matchesClause(row, clause, schema, options2 = {}) {
     { ...clause, field },
     evaluationTime(options2)
   );
-  prepareDatetimePredicates([{ kind: "lit", predicate: prepared }], byName);
+  prepareDatetimePredicates([{ branches: [[prepared]] }], byName);
   return matchesWith(byName, row, prepared);
 }
 function applyAggregations(rows, q, schema, options2 = {}) {
@@ -5858,25 +6403,15 @@ function prepareWhereClause(clause, now) {
   };
 }
 function prepareWhereTerm(term, resolveField2, now) {
-  if (isOrGroup(term)) {
-    return {
-      kind: "or",
-      predicates: term.any.map(
-        (c) => prepareWhereClause({ ...c, field: resolveField2(c.field) }, now)
-      )
-    };
-  }
   return {
-    kind: "lit",
-    predicate: prepareWhereClause(
-      { ...term, field: resolveField2(term.field) },
-      now
+    branches: branchesOf(term).map(
+      (branch) => branch.map((c) => prepareWhereClause({ ...c, field: resolveField2(c.field) }, now))
     )
   };
 }
 function prepareDatetimePredicates(terms, fields) {
   for (const term of terms)
-    for (const p of term.kind === "lit" ? [term.predicate] : term.predicates) {
+    for (const p of term.branches.flat()) {
       const field = fields.get(p.clause.field);
       if (field?.type !== "datetime" || p.clause.value === "" || p.clause.op === "is_null" || p.clause.op === "is_not_null")
         continue;
@@ -5884,8 +6419,7 @@ function prepareDatetimePredicates(terms, fields) {
     }
 }
 function matchesTerm(byName, row, term) {
-  if (term.kind === "lit") return matchesWith(byName, row, term.predicate);
-  return term.predicates.some((p) => matchesWith(byName, row, p));
+  return term.branches.some((branch) => branch.every((p) => matchesWith(byName, row, p)));
 }
 function matchesWith(byName, row, prepared) {
   const { clause } = prepared;
@@ -6053,6 +6587,7 @@ function memoryStorageAdapter() {
   const saved = /* @__PURE__ */ new Map();
   const defaults = /* @__PURE__ */ new Map();
   return {
+    storesHostState: true,
     async loadLast(key) {
       const query = last.get(key);
       return query ? normalizeQueryState(query) : null;
@@ -6143,6 +6678,7 @@ function localStorageAdapter() {
     else ls.removeItem(DEFAULT_PREFIX + key);
   };
   return {
+    storesHostState: true,
     async loadLast(key) {
       if (!ls) return null;
       try {
@@ -6325,7 +6861,7 @@ function sourceDependencies(query, schema, resolveComputed) {
   if (query.grouping) {
     const model = createGroupingModel(schema);
     model.validate(query.grouping);
-    for (const key of query.grouping.keys) fields.add(key);
+    for (const key of groupKeyFields(query.grouping.keys)) fields.add(key);
     for (const summary of query.grouping.summaries) {
       if (summary.op === "link") continue;
       if (summary.op === "row") fields.add(summary.field);
@@ -6372,8 +6908,9 @@ function clauseKey(clause) {
   ]);
 }
 function whereTermKey(term) {
-  if (!isOrGroup(term)) return clauseKey(term);
-  return `any:${JSON.stringify(term.any.map(clauseKey).sort())}`;
+  if (!isWhereGroup(term)) return clauseKey(term);
+  const branchKey = (member) => isWhereConjunction(member) ? `all:${JSON.stringify(member.all.map(clauseKey).sort())}` : clauseKey(member);
+  return `any:${JSON.stringify(term.any.map(branchKey).sort())}`;
 }
 function appendWhereTerms(where, terms) {
   const present = new Set(where.map(whereTermKey));
@@ -6391,7 +6928,7 @@ function filterUnits(where) {
   for (const term of where) {
     const last = units[units.length - 1];
     const previous = last?.[last.length - 1];
-    if (last && previous && !isOrGroup(term) && !isOrGroup(previous) && term.op === "!=" && previous.op === "!=" && term.field === previous.field)
+    if (last && previous && !isWhereGroup(term) && !isWhereGroup(previous) && term.op === "!=" && previous.op === "!=" && term.field === previous.field)
       last.push(term);
     else units.push([term]);
   }
@@ -6629,6 +7166,8 @@ function toQueryRequestV3(query, baseSchema, capabilities, execution, options2 =
   let resultSchema = sourceSchema;
   if (q.grouping) {
     if (!capabilities.groupedRows) diagnostics.push("This server does not support grouped rows.");
+    else if (q.grouping.keys.some(isCalendarGroupKey) && !capabilities.calendarGroupKeys)
+      diagnostics.push("This server does not support grouping keys by calendar interval.");
     try {
       const model = createGroupingModel(sourceSchema);
       model.validate(q.grouping);
@@ -6656,6 +7195,8 @@ function toQueryRequestV3(query, baseSchema, capabilities, execution, options2 =
   for (const metric of metrics) {
     diagnostics.push(...validateMetric(metric, resultSchema).map((issue) => issue.message));
     if (metric.dateGrouping && !capabilities.calendarGrouping) diagnostics.push("This server does not support calendar grouping.");
+    else if (isMetricCycle(metric.dateGrouping?.interval) && !capabilities.calendarCycles)
+      diagnostics.push("This server does not support hour-of-day or day-of-week grouping.");
   }
   const revisions = /* @__PURE__ */ Object.create(null);
   for (const [id, revision] of Object.entries(execution?.resolvedRevisions ?? {})) {
@@ -6714,6 +7255,13 @@ function inspectBucketQuery(query, bucket, clause, schema) {
   for (const [index, name] of clause.groupBy.entries()) {
     const field = resolveField(fields, name);
     const key = bucket.keys[index] ?? null;
+    if (clause.dateGrouping && index === 0 && key !== null && isMetricCycle(clause.dateGrouping.interval)) {
+      if (!field || field.type !== "datetime" || !isFilterable(field)) return null;
+      const slot = cycleSlotTerms(query, clause, fields, field.name, key);
+      if (!slot) return null;
+      terms.push(...slot);
+      continue;
+    }
     if (clause.dateGrouping && index === 0 && key !== null) {
       if (!field || field.type !== "datetime" || !isFilterable(field)) return null;
       let start;
@@ -6760,7 +7308,54 @@ function inspectBucketQuery(query, bucket, clause, schema) {
       { field: field.name, op: inclusiveMax ? "<=" : "<", value: String(max) }
     );
   }
-  return { ...query, where: appendWhereTerms(query.where, terms), offset: 0 };
+  const where = appendWhereTerms(query.where, terms);
+  if (isMetricCycle(clause.dateGrouping?.interval) && where.reduce((n, term) => n + predicatesOf(term).length, 0) > MAX_WHERE_CLAUSES) return null;
+  return { ...query, where, offset: 0 };
+}
+function cycleSlotTerms(query, clause, schema, field, key) {
+  const config = clause.dateGrouping, cycle = config.interval;
+  if (!isMetricCycle(cycle) || typeof key !== "number" || !metricCycleSlots(cycle).includes(key)) return null;
+  const now = Date.now();
+  let { lower, upper } = metricDateBounds(clause, query, schema, now);
+  const whole = config.occurrence ? { ...clause, dateGrouping: { ...config, interval: config.occurrence.interval } } : config.partialIntervals === "exclude" ? clause : void 0;
+  if (whole) {
+    const span = wholeIntervalSpan(whole, query, schema, now);
+    lower = span.start ?? -Infinity;
+    upper = span.end;
+  }
+  if (!Number.isFinite(lower) || !Number.isFinite(upper)) return null;
+  const budget = Math.floor(MAX_WHERE_CLAUSES / 2);
+  const ranges = [];
+  const unit = metricCalendarUnit(cycle);
+  for (let start = metricDateFloor(lower, unit, config.timeZone); start < upper; ) {
+    const next = metricDateNext(start, unit, config.timeZone);
+    if (!Number.isFinite(next) || next <= start) return null;
+    if (metricCycleSlot(start, cycle, config.timeZone) === key) {
+      const from = Math.max(start, lower), to = Math.min(next, upper);
+      const last = ranges[ranges.length - 1];
+      if (from < to) {
+        if (last && last[1] === from) last[1] = to;
+        else if (ranges.push([from, to]) > budget) return null;
+      }
+    }
+    start = next;
+  }
+  const iso = (time) => new Date(time).toISOString();
+  if (!ranges.length)
+    return [
+      { field, op: ">=", value: iso(lower) },
+      { field, op: "<", value: iso(lower) }
+    ];
+  const terms = [
+    { field, op: ">=", value: iso(ranges[0][0]) },
+    { field, op: "<", value: iso(ranges[ranges.length - 1][1]) }
+  ];
+  for (let i = 0; i + 1 < ranges.length; i++)
+    terms.push({ any: [
+      { field, op: "<", value: iso(ranges[i][1]) },
+      { field, op: ">=", value: iso(ranges[i + 1][0]) }
+    ] });
+  return terms;
 }
 function groupSourceQuery(query, group, schema) {
   if (!query.grouping) return null;
@@ -6777,10 +7372,15 @@ export {
   FORMULA_FUNCTIONS,
   FormulaError,
   GROUP_ID_FIELD,
+  GROUP_KEY_INTERVALS,
   GROUP_LINK_RENDER,
   ITEM_DETAILS_COLUMN,
   MAX_AGGREGATIONS,
   MAX_GROUP_BY_FIELDS,
+  MAX_HOST_QUERY_PARAMS,
+  MAX_HOST_QUERY_STATE_BYTES,
+  MAX_HOST_QUERY_VALUES,
+  MAX_HOST_QUERY_VALUE_LENGTH,
   MAX_METRIC_WINDOW_PERIODS,
   MAX_ORDER_BY_TERMS,
   MAX_PROPERTIES,
@@ -6794,6 +7394,7 @@ export {
   MAX_SELECT_COLUMNS,
   MAX_SUMMARY_COLUMNS,
   MAX_WHERE_CLAUSES,
+  METRIC_CYCLE_INTERVALS,
   METRIC_DATE_INTERVALS,
   METRIC_FUNCTIONS,
   NULLARY_OPS,
@@ -6808,6 +7409,8 @@ export {
   applyPatch,
   applyQuery,
   boxSummary,
+  branchesOf,
+  calendarGroupKey,
   coerceValue,
   compareMetricValues,
   compileFormula,
@@ -6826,6 +7429,9 @@ export {
   exitGrouping,
   filterValues,
   formulaRuntime,
+  groupKeyField,
+  groupKeyFields,
+  groupKeyTerms,
   groupLinkQuery,
   groupPreview,
   groupSourceQuery,
@@ -6837,18 +7443,24 @@ export {
   httpQuerySnapshotStore,
   indexFields,
   inspectBucketQuery,
+  isCalendarGroupKey,
   isComputedCellError,
   isComputedField,
   isFilterable,
   isGroupLinkField,
   isGroupLinkValue,
   isGroupable,
+  isGroupingTimeZone,
   isMeasurable,
+  isMetricCycle,
   isNegativePredicate,
   isOrGroup,
+  isOrOfAndsGroup,
   isPushdownFilter,
   isSelectable,
   isSortable,
+  isWhereConjunction,
+  isWhereGroup,
   itemPageFields,
   jsonPropertyViewStorage,
   loadSchema,
@@ -6863,14 +7475,23 @@ export {
   memoryQuerySnapshotCache,
   memoryStorageAdapter,
   metricAggregatePlans,
+  metricCalendarUnit,
   metricComputationKey,
   metricCustomEndTime,
+  metricCycleSlot,
+  metricCycleSlots,
+  metricDateBounds,
   metricDateFloor,
   metricDateNext,
   metricDateRange,
   metricDateTime,
   metricDependencies,
   metricExpression,
+  metricMinCount,
+  metricMinCountKeeps,
+  metricMinCountMeasure,
+  metricMinCountPlan,
+  metricMinCountText,
   metricPlans,
   metricPopulationError,
   negateClause,
@@ -6878,9 +7499,11 @@ export {
   normalizePropertyView,
   normalizeQueryState,
   objectReferenceKey,
+  occurrenceDistribution,
   opAllowedForType,
   opPairsForField,
   opsForField,
+  parseHostQueryState,
   parseRelativeDuration,
   percentile,
   planMetricSeries,