deepline 0.3.306 → 0.3.308

package/dist/bundling-sources/shared_libs/play-runtime/run-event-query.ts

@@ -0,0 +1,872 @@
+import { RUN_LOG_LEVELS, type RunLogLevel } from './run-event-catalog';
+
+/** Public criteria shared by the API, SDK and CLI; no database/runtime imports. */
+export type RunEventScalar = string | number | boolean | null;
+export type RunEventField =
+  | keyof typeof RUN_EVENT_QUERY_FIELD_CATALOG
+  | `context.${string}`;
+export type RunEventFieldOperators<T extends RunEventScalar = RunEventScalar> =
+  {
+    eq?: T;
+    ne?: T;
+    gt?: Exclude<T, boolean | null>;
+    gte?: Exclude<T, boolean | null>;
+    lt?: Exclude<T, boolean | null>;
+    lte?: Exclude<T, boolean | null>;
+    exists?: boolean;
+    in?: readonly T[];
+  };
+type Filter<T extends RunEventScalar> = T | RunEventFieldOperators<T>;
+export type RunEventWhere = {
+  eventId?: Filter<string>;
+  orgId?: Filter<string>;
+  runtimeScope?: Filter<string>;
+  runId?: Filter<string>;
+  playName?: Filter<string>;
+  occurredAt?: Filter<string>;
+  kind?: Filter<string>;
+  source?: Filter<string | null>;
+  status?: Filter<string | null>;
+  level?: Filter<RunLogLevel | null>;
+  stepId?: Filter<string | null>;
+  stepKind?: Filter<string | null>;
+  datasetId?: Filter<string | null>;
+  phase?: Filter<string | null>;
+  provider?: Filter<string | null>;
+  operation?: Filter<string | null>;
+  producerAttempt?: Filter<number | null>;
+  context?: Readonly<Record<string, Filter<RunEventScalar>>>;
+  and?: readonly RunEventWhere[];
+  or?: readonly RunEventWhere[];
+} & { [K in `context.${string}`]?: Filter<RunEventScalar> };
+export type RunEventQueryCriteria = {
+  since?: string | number;
+  until?: string | number;
+  where?: RunEventWhere | string;
+  runId?: string;
+  stepId?: string;
+  minLevel?: RunLogLevel;
+  text?: string;
+  playName?: string;
+  kind?: string;
+};
+export type NormalizedRunEventQuery = Omit<
+  RunEventQueryCriteria,
+  'since' | 'until' | 'where'
+> & {
+  since: string;
+  until: string;
+  where?: RunEventWhere;
+};
+export type RunEventQueryOptions = {
+  limit?: number;
+  cursor?: string;
+  includePayloads?: boolean;
+};
+export type RunEventMeasure =
+  | { op: 'count'; as?: string }
+  | { op: 'sum'; field: RunEventField; as?: string };
+export type RunEventSummaryOptions = {
+  groupBy: readonly RunEventField[];
+  measures?: readonly RunEventMeasure[];
+  limit?: number;
+  cursor?: string;
+};
+type RequestBase = RunEventQueryCriteria & {
+  resource: 'logs' | 'events';
+  runId?: string;
+};
+export type RunEventOperationRequest =
+  | (RequestBase & RunEventQueryOptions & { operation: 'list' })
+  | (RequestBase & { operation: 'count' })
+  | (RequestBase & RunEventSummaryOptions & { operation: 'summarize' })
+  | { operation: 'fields'; resource: 'logs' | 'events'; runId?: string };
+export type RunEventQueryEvent = {
+  eventId: string;
+  occurredAt: string;
+  ingestedAt: string;
+  runId: string;
+  playName: string;
+  kind: string;
+  level: RunLogLevel | null;
+  message: string | null;
+  source?: string;
+  stepId?: string;
+  status?: string;
+  stepKind?: string;
+  datasetId?: string;
+  phase?: string;
+  provider?: string;
+  operation?: string;
+  producerAttempt?: number;
+  context?: Record<string, RunEventScalar>;
+  eventPayload?: Record<string, unknown>;
+  payload?: unknown;
+};
+export type RunEventQueryPage = {
+  returnedCount: number;
+  hasMore: boolean;
+  nextCursor: string | null;
+};
+export type RunEventQueryRetention = {
+  retainedSince: string;
+  retentionDays: 7;
+};
+type ResultBase = {
+  query: NormalizedRunEventQuery;
+  retention: RunEventQueryRetention;
+};
+export type RunEventLogsResult = ResultBase & {
+  logs: RunEventQueryEvent[];
+  page: RunEventQueryPage;
+};
+export type RunEventEventsResult = ResultBase & {
+  events: RunEventQueryEvent[];
+  page: RunEventQueryPage;
+};
+export type RunEventListResult = RunEventLogsResult | RunEventEventsResult;
+export type RunEventCountResult = ResultBase & {
+  matchedCount: number;
+  exact: true;
+};
+export type RunEventGroupValue = RunEventScalar | { missing: true };
+export type RunEventSummaryResult = ResultBase & {
+  groupBy: readonly RunEventField[];
+  measures: readonly RunEventMeasure[];
+  groups: Array<{
+    keys: Record<string, RunEventGroupValue>;
+    measures: Record<string, number>;
+  }>;
+  page: RunEventQueryPage;
+};
+export type RunEventFieldDescriptor = {
+  field: RunEventField;
+  type: 'string' | 'number' | 'timestamp' | 'level';
+  nullable: boolean;
+  operators: readonly string[];
+  groupable: boolean;
+  summable: boolean;
+};
+export type RunEventFieldsResult = {
+  fields: readonly RunEventFieldDescriptor[];
+  context: {
+    field: 'context.<key>';
+    type: 'scalar';
+    operators: readonly string[];
+    groupable: true;
+    summable: true;
+    missing: 'distinct_from_null';
+  };
+};
+export type RunEventOperationResult =
+  | RunEventListResult
+  | RunEventCountResult
+  | RunEventSummaryResult
+  | RunEventFieldsResult;
+
+const stringField = { type: 'string', nullable: false } as const;
+const optionalString = { type: 'string', nullable: true } as const;
+/** Supported fields are declared, never inferred from rows or raw payloads. */
+export const RUN_EVENT_QUERY_FIELD_CATALOG = {
+  eventId: stringField,
+  orgId: stringField,
+  runtimeScope: stringField,
+  runId: stringField,
+  playName: stringField,
+  kind: stringField,
+  source: optionalString,
+  occurredAt: { type: 'timestamp', nullable: false },
+  status: optionalString,
+  level: { type: 'level', nullable: true },
+  stepId: optionalString,
+  stepKind: optionalString,
+  datasetId: optionalString,
+  phase: optionalString,
+  provider: optionalString,
+  operation: optionalString,
+  producerAttempt: { type: 'number', nullable: true },
+} as const;
+export const RUN_EVENT_QUERY_RETENTION_MS = 7 * 86400000;
+export const RUN_EVENT_QUERY_MAX_LIMIT = 200;
+export const RUN_EVENT_QUERY_MAX_PAYLOAD_LIMIT = 10;
+// A frozen query may expand JSON-escaped text and identities by six bytes per
+// character. Base64 adds another third, followed by a retained group key.
+// The encoder also admits the complete continuation against the request bound.
+export const RUN_EVENT_QUERY_MAX_CURSOR_BYTES = 48 * 1024;
+export const RUN_EVENT_QUERY_MAX_REQUEST_BYTES = 64 * 1024;
+const MAX_BYTES = 8192;
+const MAX_DEPTH = 8;
+const MAX_PREDICATES = 64;
+const OPERATORS = [
+  'eq',
+  'ne',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'exists',
+  'in',
+] as const;
+type Operator = (typeof OPERATORS)[number];
+/** SQL adapters consume this admitted tree, never the caller's object. */
+export type RunEventPredicate =
+  | { and: readonly RunEventPredicate[] }
+  | { or: readonly RunEventPredicate[] }
+  | {
+      field: RunEventField;
+      op: Exclude<Operator, 'exists' | 'in'>;
+      value: RunEventScalar;
+    }
+  | { field: RunEventField; op: 'exists'; value: boolean }
+  | { field: RunEventField; op: 'in'; value: readonly RunEventScalar[] };
+
+export class RunEventQueryInputError extends TypeError {
+  constructor(
+    message: string,
+    readonly code = 'invalid_run_event_query',
+  ) {
+    super(message);
+    this.name = 'RunEventQueryInputError';
+  }
+}
+export class RunEventQueryDataError extends Error {
+  constructor(
+    message: string,
+    readonly code = 'invalid_run_event_data',
+  ) {
+    super(message);
+    this.name = 'RunEventQueryDataError';
+  }
+}
+function fail(message: string): never {
+  throw new RunEventQueryInputError(message);
+}
+function object(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype ||
+      Object.getPrototypeOf(value) === null)
+  );
+}
+function bounded(value: unknown, maxBytes = MAX_BYTES): void {
+  let encoded: string | undefined;
+  try {
+    encoded = JSON.stringify(value);
+  } catch {
+    fail('Run event query must be bounded JSON without cycles.');
+  }
+  if (!encoded || new TextEncoder().encode(encoded).length > maxBytes)
+    fail(`Run event query exceeds ${maxBytes} bytes.`);
+}
+export function validateRunEventField(value: unknown): RunEventField {
+  if (typeof value !== 'string') fail('Run event field must be a string.');
+  const field = value.startsWith('$.') ? value.slice(2) : value;
+  if (
+    Object.prototype.hasOwnProperty.call(RUN_EVENT_QUERY_FIELD_CATALOG, field)
+  )
+    return field as RunEventField;
+  if (
+    /^context\.[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(field) &&
+    !['__proto__', 'prototype', 'constructor'].includes(field.slice(8))
+  )
+    return field as RunEventField;
+  const alternatives: Record<string, string> = {
+    step: 'stepId',
+    severity: 'level',
+    timestamp: 'occurredAt',
+    play: 'playName',
+    run: 'runId',
+    attempt: 'producerAttempt',
+  };
+  fail(
+    `Unsupported run event field: ${field}. Use ${alternatives[field] ?? 'a catalog field or context.<key>'}; call fields() for supported fields.`,
+  );
+}
+function scalar(
+  field: RunEventField,
+  value: unknown,
+  op: Operator,
+): RunEventScalar {
+  if (
+    value !== null &&
+    typeof value !== 'string' &&
+    typeof value !== 'number' &&
+    typeof value !== 'boolean'
+  )
+    fail(`Run event ${field} requires a JSON scalar.`);
+  if (typeof value === 'number' && !Number.isFinite(value))
+    fail(`Run event ${field} requires a finite number.`);
+  if (
+    typeof value === 'string' &&
+    new TextEncoder().encode(value).length > 1024
+  )
+    fail(`Run event ${field} value exceeds 1024 bytes.`);
+  const descriptor =
+    RUN_EVENT_QUERY_FIELD_CATALOG[
+      field as keyof typeof RUN_EVENT_QUERY_FIELD_CATALOG
+    ];
+  if (descriptor) {
+    if (value === null) {
+      if (!descriptor.nullable) fail(`Run event ${field} cannot be null.`);
+    } else if (descriptor.type === 'number') {
+      if (
+        typeof value !== 'number' ||
+        !Number.isSafeInteger(value) ||
+        value < 1
+      )
+        fail(`Run event ${field} requires a positive integer.`);
+    } else if (typeof value !== 'string')
+      fail(`Run event ${field} requires a string.`);
+    else if (
+      descriptor.type === 'level' &&
+      !RUN_LOG_LEVELS.includes(value as RunLogLevel)
+    )
+      fail('Run event level requires debug, info, warn or error.');
+    else if (descriptor.type === 'timestamp') {
+      value = normalizeRunEventQueryTimestamp(value);
+    }
+  }
+  if (
+    ['gt', 'gte', 'lt', 'lte'].includes(op) &&
+    (value === null || typeof value === 'boolean')
+  )
+    fail(`Run event ${op} requires a string or number.`);
+  return value as RunEventScalar;
+}
+function comparison(
+  field: RunEventField,
+  op: string,
+  value: unknown,
+): RunEventPredicate {
+  if (!OPERATORS.includes(op as Operator))
+    fail(`Unsupported run event operator: ${op}. Use ${OPERATORS.join(', ')}.`);
+  if (op === 'exists') {
+    if (typeof value !== 'boolean')
+      fail('Run event exists requires a boolean.');
+    return { field, op, value };
+  }
+  if (op === 'in') {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 32)
+      fail('Run event in requires between 1 and 32 scalars.');
+    return { field, op, value: value.map((item) => scalar(field, item, 'eq')) };
+  }
+  return {
+    field,
+    op: op as Exclude<Operator, 'exists' | 'in'>,
+    value: scalar(field, value, op as Operator),
+  };
+}
+function admitObject(
+  input: unknown,
+  depth = 0,
+  budget = { count: 0 },
+): RunEventPredicate {
+  if (depth > MAX_DEPTH) fail('Run event where exceeds depth 8.');
+  if (!object(input) || !Object.keys(input).length)
+    fail('Run event where requires a nonempty object.');
+  const terms: RunEventPredicate[] = [];
+  const fieldTerms = (raw: string, filter: unknown) => {
+    const field = validateRunEventField(raw);
+    const operators = object(filter)
+      ? Object.entries(filter)
+      : [['eq', filter] as const];
+    if (!operators.length)
+      fail(`Run event ${field} has an empty operator object.`);
+    for (const [op, value] of operators) {
+      if (++budget.count > MAX_PREDICATES)
+        fail('Run event where exceeds 64 predicates.');
+      terms.push(comparison(field, op, value));
+    }
+  };
+  for (const [key, filter] of Object.entries(input)) {
+    if (key === 'and' || key === 'or') {
+      if (
+        !Array.isArray(filter) ||
+        filter.length < 1 ||
+        filter.length > MAX_PREDICATES
+      )
+        fail(`Run event ${key} requires a nonempty bounded array.`);
+      const children = filter.map((item) =>
+        admitObject(item, depth + 1, budget),
+      );
+      terms.push(key === 'and' ? { and: children } : { or: children });
+    } else if (key === 'context') {
+      if (!object(filter) || !Object.keys(filter).length)
+        fail('Run event context requires flat scalar fields.');
+      for (const [contextKey, value] of Object.entries(filter))
+        fieldTerms(`context.${contextKey}`, value);
+    } else fieldTerms(key, filter);
+  }
+  return terms.length === 1 ? terms[0]! : { and: terms };
+}
+function compact(predicate: RunEventPredicate): RunEventWhere {
+  if ('and' in predicate) {
+    const merged: Record<string, unknown> = {};
+    for (const term of predicate.and) {
+      const child = compact(term);
+      for (const [key, value] of Object.entries(child)) {
+        if (key === 'and') return { and: predicate.and.map(compact) };
+        if (key === 'context') {
+          const context = (merged.context ?? {}) as Record<string, unknown>;
+          for (const [name, filter] of Object.entries(value as object)) {
+            if (Object.prototype.hasOwnProperty.call(context, name)) {
+              const combined = combineFilters(context[name], filter);
+              if (!combined) return { and: predicate.and.map(compact) };
+              context[name] = combined;
+            } else context[name] = filter;
+          }
+          merged.context = context;
+        } else if (Object.prototype.hasOwnProperty.call(merged, key)) {
+          const combined =
+            key === 'or' ? undefined : combineFilters(merged[key], value);
+          if (!combined) return { and: predicate.and.map(compact) };
+          merged[key] = combined;
+        } else merged[key] = value;
+      }
+    }
+    return merged as RunEventWhere;
+  }
+  if ('or' in predicate) return { or: predicate.or.map(compact) };
+  const filter =
+    predicate.op === 'eq'
+      ? predicate.value
+      : { [predicate.op]: predicate.value };
+  if (predicate.field.startsWith('context.'))
+    return { context: { [predicate.field.slice(8)]: filter } } as RunEventWhere;
+  return { [predicate.field]: filter } as RunEventWhere;
+}
+function combineFilters(
+  left: unknown,
+  right: unknown,
+): Record<string, unknown> | undefined {
+  const first = object(left) ? left : { eq: left };
+  const second = object(right) ? right : { eq: right };
+  if (
+    Object.keys(first).some((key) =>
+      Object.prototype.hasOwnProperty.call(second, key),
+    )
+  )
+    return undefined;
+  return { ...first, ...second };
+}
+function canonical(predicate: RunEventPredicate): RunEventPredicate {
+  if ('field' in predicate) return predicate;
+  const operator = 'and' in predicate ? 'and' : 'or';
+  const source = 'and' in predicate ? predicate.and : predicate.or;
+  const terms = source.map(canonical).flatMap((term) => {
+    if (operator === 'and' && 'and' in term) return term.and;
+    if (operator === 'or' && 'or' in term) return term.or;
+    return [term];
+  });
+  terms.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  const unique = terms.filter(
+    (term, i) =>
+      i === 0 || JSON.stringify(term) !== JSON.stringify(terms[i - 1]),
+  );
+  if (unique.length === 1) return unique[0]!;
+  return operator === 'and' ? { and: unique } : { or: unique };
+}
+/** Small grammar: fields, JSON scalars, comparisons, in/exists, &&/||, parentheses. */
+function parseDsl(input: string): RunEventPredicate {
+  let position = 0;
+  let count = 0;
+  const skip = () => {
+    while (/\s/.test(input[position] ?? '') && position < input.length)
+      position++;
+  };
+  const take = (token: string) => {
+    skip();
+    if (input.startsWith(token, position)) {
+      position += token.length;
+      return true;
+    }
+    return false;
+  };
+  const json = (): unknown => {
+    skip();
+    const start = position;
+    if (input[position] === '"') {
+      position++;
+      let closed = false;
+      while (position < input.length) {
+        const char = input[position++]!;
+        if (char === '\\') position++;
+        else if (char === '"') {
+          closed = true;
+          break;
+        }
+      }
+      if (!closed) fail('Run event DSL has an unterminated JSON string.');
+    } else {
+      const match =
+        /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(
+          input.slice(position),
+        );
+      if (!match)
+        fail('Run event DSL requires a JSON quoted string or scalar.');
+      position += match[0].length;
+    }
+    try {
+      return JSON.parse(input.slice(start, position));
+    } catch {
+      fail('Run event DSL requires valid JSON scalars.');
+    }
+  };
+  const term = (depth: number): RunEventPredicate => {
+    if (depth > MAX_DEPTH) fail('Run event where exceeds depth 8.');
+    if (take('(')) {
+      const nested = or(depth + 1);
+      if (!take(')')) fail('Run event DSL is missing a closing parenthesis.');
+      return nested;
+    }
+    skip();
+    const match = /^(?:\$\.)?[A-Za-z_][A-Za-z0-9_.]*/.exec(
+      input.slice(position),
+    );
+    if (!match) fail('Run event DSL requires a supported field.');
+    position += match[0].length;
+    const field = validateRunEventField(match[0]);
+    if (++count > MAX_PREDICATES)
+      fail('Run event where exceeds 64 predicates.');
+    skip();
+    const operation =
+      /^(==|!=|>=|<=|>|<|\b(?:eq|ne|gte|gt|lte|lt|in|exists)\b)/.exec(
+        input.slice(position),
+      );
+    if (!operation)
+      fail('Run event DSL requires a supported comparison operator.');
+    position += operation[0].length;
+    const symbols: Record<string, string> = {
+      '==': 'eq',
+      '!=': 'ne',
+      '>=': 'gte',
+      '<=': 'lte',
+      '>': 'gt',
+      '<': 'lt',
+    };
+    const op = symbols[operation[0]] ?? operation[0];
+    if (op === 'in') {
+      if (!take('[')) fail('Run event DSL in requires a JSON scalar array.');
+      const values: unknown[] = [];
+      if (!take(']')) {
+        do {
+          values.push(json());
+          if (values.length > 32)
+            fail('Run event in requires between 1 and 32 scalars.');
+        } while (take(','));
+        if (!take(']')) fail('Run event DSL in requires a closing bracket.');
+      }
+      return comparison(field, op, values);
+    }
+    return comparison(field, op, json());
+  };
+  const and = (depth: number): RunEventPredicate => {
+    const terms = [term(depth)];
+    while (take('&&')) terms.push(term(depth));
+    return terms.length === 1 ? terms[0]! : { and: terms };
+  };
+  const or = (depth: number): RunEventPredicate => {
+    const terms = [and(depth)];
+    while (take('||')) terms.push(and(depth));
+    return terms.length === 1 ? terms[0]! : { or: terms };
+  };
+  const result = or(0);
+  skip();
+  if (position !== input.length)
+    fail(`Run event DSL has unsupported input at position ${position}.`);
+  return result;
+}
+export function parseRunEventWhere(input: unknown): RunEventWhere {
+  bounded(input);
+  const where = compact(
+    canonical(typeof input === 'string' ? parseDsl(input) : admitObject(input)),
+  );
+  bounded(where);
+  return where;
+}
+export function getRunEventQueryPredicate(
+  where: RunEventWhere,
+): RunEventPredicate {
+  bounded(where);
+  return canonical(admitObject(where));
+}
+export function normalizeRunEventQueryTimestamp(
+  value: string | number,
+): string {
+  let extraMicros = '';
+  if (typeof value === 'string') {
+    const timestamp =
+      /^[+-]?\d{4,6}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.(\d{1,6}))?(?:Z|[+-]\d{2}:\d{2})$/.exec(
+        value,
+      );
+    if (!timestamp)
+      fail(
+        'Run event time bounds require an ISO timestamp with a timezone and at most six fractional digits.',
+      );
+    extraMicros = (timestamp[1] ?? '').padEnd(6, '0').slice(3);
+  }
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime()))
+    fail('Run event time bound is invalid.');
+  const canonical = date.toISOString();
+  return /[1-9]/.test(extraMicros)
+    ? canonical.replace(/Z$/, `${extraMicros}Z`)
+    : canonical;
+}
+function timestampMicros(value: string): bigint {
+  const fraction = /\.(\d+)Z$/.exec(value)?.[1] ?? '';
+  return (
+    BigInt(Date.parse(value)) * BigInt(1000) +
+    BigInt(fraction.padEnd(6, '0').slice(3))
+  );
+}
+function time(value: unknown, nowMs: number, fallback: number): string {
+  if (value === undefined) value = fallback;
+  let timestamp: number;
+  if (typeof value === 'number') timestamp = value;
+  else if (typeof value === 'string') {
+    const relative = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(value);
+    if (relative) {
+      const units: Record<string, number> = {
+        ms: 1,
+        s: 1000,
+        m: 60000,
+        h: 3600000,
+        d: 86400000,
+      };
+      timestamp = nowMs - Number(relative[1]) * units[relative[2]]!;
+    } else {
+      return normalizeRunEventQueryTimestamp(value);
+    }
+  } else fail('Run event time bounds require a timestamp or duration.');
+  return normalizeRunEventQueryTimestamp(timestamp);
+}
+function exact(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !value.trim() || value.length > 256)
+    fail(
+      `Run event ${name} requires a nonempty string of at most 256 characters.`,
+    );
+  return value;
+}
+const CRITERIA_KEYS = [
+  'since',
+  'until',
+  'where',
+  'runId',
+  'stepId',
+  'minLevel',
+  'text',
+  'playName',
+  'kind',
+];
+export function normalizeRunEventQuery(
+  criteria: RunEventQueryCriteria,
+  nowMs = Date.now(),
+): NormalizedRunEventQuery {
+  if (!object(criteria)) fail('Run event criteria requires an object.');
+  bounded(criteria, RUN_EVENT_QUERY_MAX_REQUEST_BYTES);
+  for (const key of Object.keys(criteria)) {
+    if (!CRITERIA_KEYS.includes(key))
+      fail(`Unsupported run event criterion: ${key}.`);
+  }
+  const until = time(criteria.until, nowMs, nowMs);
+  const since = time(criteria.since, nowMs, Date.parse(until) - 3600000);
+  if (
+    timestampMicros(since) >= timestampMicros(until) ||
+    timestampMicros(until) - timestampMicros(since) >
+      BigInt(RUN_EVENT_QUERY_RETENTION_MS) * BigInt(1000)
+  )
+    fail('Run event query requires a window of at most seven days.');
+  const query: NormalizedRunEventQuery = { since, until };
+  if (criteria.where !== undefined)
+    query.where = parseRunEventWhere(criteria.where);
+  for (const name of ['runId', 'stepId', 'playName', 'kind'] as const) {
+    if (criteria[name] !== undefined) query[name] = exact(criteria[name], name);
+  }
+  if (criteria.minLevel !== undefined) {
+    if (!RUN_LOG_LEVELS.includes(criteria.minLevel))
+      fail('Run event minLevel requires debug, info, warn or error.');
+    query.minLevel = criteria.minLevel;
+  }
+  if (criteria.text !== undefined) {
+    if (
+      typeof criteria.text !== 'string' ||
+      !criteria.text.length ||
+      new TextEncoder().encode(criteria.text).length > 1024
+    )
+      fail('Run event text requires between 1 and 1024 bytes.');
+    query.text = criteria.text;
+  }
+  return query;
+}
+export function normalizeRunEventOperationRequest(
+  input: unknown,
+  nowMs = Date.now(),
+): RunEventOperationRequest {
+  bounded(input, RUN_EVENT_QUERY_MAX_REQUEST_BYTES);
+  if (!object(input)) fail('Run event operation requires an object.');
+  const operation = input.operation;
+  if (!['list', 'count', 'summarize', 'fields'].includes(String(operation)))
+    fail('Run event operation requires list, count, summarize or fields.');
+  if (input.resource !== 'logs' && input.resource !== 'events')
+    fail('Run event resource requires logs or events.');
+  const allowed = [
+    'operation',
+    'resource',
+    'runId',
+    ...(operation === 'fields' ? [] : CRITERIA_KEYS),
+    ...(operation === 'list'
+      ? ['limit', 'cursor', 'includePayloads']
+      : operation === 'summarize'
+        ? ['groupBy', 'measures', 'limit', 'cursor']
+        : []),
+  ];
+  for (const key of Object.keys(input)) {
+    if (!allowed.includes(key))
+      fail(`Run event ${operation} does not support ${key}.`);
+  }
+  const base = {
+    operation,
+    resource: input.resource,
+    ...(input.runId === undefined
+      ? {}
+      : { runId: exact(input.runId, 'runId') }),
+  };
+  if (operation === 'fields') return base as RunEventOperationRequest;
+  if (input.resource === 'logs' && !base.runId)
+    fail('Run event logs require runId.');
+  if (
+    input.cursor !== undefined &&
+    (typeof input.cursor !== 'string' ||
+      !input.cursor.length ||
+      input.cursor.length > RUN_EVENT_QUERY_MAX_CURSOR_BYTES)
+  )
+    fail('Run event cursor is invalid.');
+  // A continuation carries its frozen query. Do not insert a fresh time window.
+  const rawCriteria = Object.fromEntries(
+    Object.entries(input).filter(
+      ([key]) =>
+        CRITERIA_KEYS.includes(key) &&
+        (key !== 'runId' || input.resource === 'events'),
+    ),
+  ) as RunEventQueryCriteria;
+  const query = normalizeRunEventQuery(
+    input.cursor === undefined
+      ? rawCriteria
+      : { ...rawCriteria, since: nowMs - 3600000, until: nowMs },
+    nowMs,
+  );
+  const criteria: RunEventQueryCriteria = { ...query };
+  if (input.cursor !== undefined) {
+    if (input.since === undefined) delete criteria.since;
+    else criteria.since = time(input.since, nowMs, nowMs - 3600000);
+    if (input.until === undefined) delete criteria.until;
+    else criteria.until = time(input.until, nowMs, nowMs);
+  }
+  if (operation === 'count')
+    return { ...base, ...criteria } as RunEventOperationRequest;
+  const limit = input.limit ?? (input.includePayloads === true ? 10 : 50);
+  if (
+    !Number.isSafeInteger(limit) ||
+    (limit as number) < 1 ||
+    (limit as number) > RUN_EVENT_QUERY_MAX_LIMIT
+  )
+    fail('Run event limit must be between 1 and 200.');
+  const page = {
+    limit: limit as number,
+    ...(input.cursor === undefined ? {} : { cursor: input.cursor as string }),
+  };
+  if (operation === 'list') {
+    if (
+      input.includePayloads !== undefined &&
+      typeof input.includePayloads !== 'boolean'
+    )
+      fail('Run event includePayloads requires a boolean.');
+    if (
+      input.includePayloads === true &&
+      (limit as number) > RUN_EVENT_QUERY_MAX_PAYLOAD_LIMIT
+    )
+      fail('Run event payload pages cannot exceed 10 rows.');
+    return {
+      ...base,
+      ...criteria,
+      ...page,
+      ...(input.includePayloads === undefined
+        ? {}
+        : { includePayloads: input.includePayloads }),
+    } as RunEventOperationRequest;
+  }
+  if (!Array.isArray(input.groupBy) || input.groupBy.length > 4)
+    fail('Run event groupBy requires at most four fields.');
+  const groupBy = input.groupBy.map(validateRunEventField);
+  if (new Set(groupBy).size !== groupBy.length)
+    fail('Run event groupBy fields must be distinct.');
+  const rawMeasures = input.measures ?? [{ op: 'count' }];
+  if (
+    !Array.isArray(rawMeasures) ||
+    rawMeasures.length < 1 ||
+    rawMeasures.length > 8
+  )
+    fail('Run event measures require between 1 and 8 entries.');
+  const names = new Set<string>();
+  const measures: RunEventMeasure[] = rawMeasures.map((measure) => {
+    if (!object(measure) || (measure.op !== 'count' && measure.op !== 'sum'))
+      fail('Run event measures support count and sum.');
+    for (const key of Object.keys(measure)) {
+      if (
+        !['op', 'as', ...(measure.op === 'sum' ? ['field'] : [])].includes(key)
+      )
+        fail(`Unsupported run event measure option: ${key}.`);
+    }
+    const field =
+      measure.op === 'sum' ? validateRunEventField(measure.field) : undefined;
+    if (
+      field &&
+      !field.startsWith('context.') &&
+      RUN_EVENT_QUERY_FIELD_CATALOG[
+        field as keyof typeof RUN_EVENT_QUERY_FIELD_CATALOG
+      ].type !== 'number'
+    )
+      fail(`Run event sum requires a numeric field: ${field}.`);
+    const name =
+      measure.as ?? (field ? `sum_${field.replaceAll('.', '_')}` : 'count');
+    if (
+      typeof name !== 'string' ||
+      !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(name) ||
+      names.has(name)
+    )
+      fail('Run event measure names must be distinct identifiers.');
+    names.add(name);
+    return field ? { op: 'sum', field, as: name } : { op: 'count', as: name };
+  });
+  return {
+    ...base,
+    ...criteria,
+    ...page,
+    groupBy,
+    measures,
+  } as RunEventOperationRequest;
+}
+export function getRunEventQueryFields(): RunEventFieldsResult {
+  return {
+    fields: Object.entries(RUN_EVENT_QUERY_FIELD_CATALOG).map(
+      ([field, descriptor]) => ({
+        field: field as RunEventField,
+        ...descriptor,
+        operators: OPERATORS,
+        groupable: true,
+        summable: descriptor.type === 'number',
+      }),
+    ),
+    context: {
+      field: 'context.<key>',
+      type: 'scalar',
+      operators: OPERATORS,
+      groupable: true,
+      summable: true,
+      missing: 'distinct_from_null',
+    },
+  };
+}