harnery 0.35.0 → 0.37.0

package/src/core/conversations/contract.ts

@@ -0,0 +1,178 @@
+export type HarneryConversationRole = "user" | "assistant";
+export type HarneryConversationCompleteness = "complete" | "partial" | "unavailable";
+export type HarneryConversationAccessMode = "off" | "source" | "archive";
+export type HarneryConversationArchiveAuthorityMode = "shadow" | "cutover" | "rollback";
+
+export interface HarneryConversationProviderCapabilities {
+  provider_id: string;
+  roles: readonly HarneryConversationRole[];
+  can_list: boolean;
+  can_stream_source: boolean;
+  can_replay_archive: boolean;
+  default_completeness: HarneryConversationCompleteness;
+  default_omissions: readonly string[];
+  retention_behavior: string;
+}
+
+export interface HarneryConversationSourceSnapshot {
+  snapshot_id: string;
+  provider_id: string;
+  project_scope_id: string;
+  conversation_id: string;
+  checkpoint?: string;
+  observed_at: string;
+  completeness: HarneryConversationCompleteness;
+  omissions: readonly string[];
+}
+
+export interface HarneryConversationRecordV1 {
+  schema: "harnery.conversation-record/v1";
+  record_id: string;
+  provider_id: string;
+  project_scope_id: string;
+  conversation_id: string;
+  source_snapshot_id: string;
+  session_id?: string;
+  turn_id?: string;
+  source: {
+    native_conversation_id: string;
+    native_record_id?: string;
+    native_sequence?: number;
+    source_digest?: `sha256:${string}`;
+  };
+  sequence: number;
+  occurred_at: string;
+  captured_at: string;
+  role: HarneryConversationRole;
+  content: string;
+  content_bytes: number;
+  content_digest: `sha256:${string}`;
+  redactions: readonly {
+    kind: string;
+    replacement: string;
+    stored_start: number;
+    stored_end: number;
+    source_bytes_removed: number;
+  }[];
+  attachment_refs: readonly string[];
+  sensitivity: "private";
+}
+
+export interface HarneryConversationSummary {
+  provider_id: string;
+  project_scope_id: string;
+  conversation_id: string;
+  snapshot_id: string;
+  completeness: HarneryConversationCompleteness;
+  omissions: readonly string[];
+  record_count?: number;
+}
+
+export interface HarneryConversationCitation {
+  record_id: string;
+  provider_id: string;
+  conversation_id: string;
+  role: HarneryConversationRole;
+  occurred_at: string;
+  native_conversation_id: string;
+  native_record_id?: string;
+  content_digest: `sha256:${string}`;
+}
+
+export interface HarneryConversationQueryRequest {
+  text?: string;
+  regex?: string;
+  provider_id?: string;
+  role?: HarneryConversationRole;
+  since?: string;
+  until?: string;
+  project_scope_id: string;
+  session_id?: string;
+  conversation_id?: string;
+  record_id?: string;
+  limit: number;
+  context_before?: number;
+  context_after?: number;
+  budgets: HarneryConversationQueryBudgets;
+}
+
+export interface HarneryConversationQueryBudgets {
+  max_source_records: number;
+  max_decoded_bytes: number;
+  max_matches: number;
+  max_wall_ms: number;
+  max_regex_chars: number;
+}
+
+export interface HarneryConversationQueryHit {
+  record: HarneryConversationRecordV1;
+  citation: HarneryConversationCitation;
+  neighbors: readonly HarneryConversationRecordV1[];
+}
+
+export interface HarneryConversationQueryResult {
+  schema: "harnery.conversation-query/v1";
+  request: HarneryConversationQueryRequest;
+  hits: readonly HarneryConversationQueryHit[];
+  scanned_records: number;
+  decoded_bytes: number;
+  truncated: boolean;
+  truncation_reason?: "record_budget" | "byte_budget" | "match_budget" | "wall_budget";
+  snapshots: readonly HarneryConversationSourceSnapshot[];
+}
+
+export interface HarneryConversationContextPack {
+  schema: "harnery.conversation-context-pack/v1";
+  boundary: "untrusted-historical-data";
+  automatic_injection: false;
+  project_scope_id: string;
+  excerpts: readonly {
+    citation: HarneryConversationCitation;
+    content: string;
+    sequence: number;
+  }[];
+  completeness: readonly {
+    provider_id: string;
+    conversation_id: string;
+    completeness: HarneryConversationCompleteness;
+    omissions: readonly string[];
+  }[];
+  bytes: number;
+  estimated_tokens: number;
+  truncated: boolean;
+}
+
+export interface HarneryNativeConversationRecord {
+  native_conversation_id: string;
+  native_record_id?: string;
+  native_sequence?: number;
+  role: string;
+  occurred_at: string;
+  content: string;
+  session_id?: string;
+  turn_id?: string;
+  attachment_refs?: readonly string[];
+}
+
+export interface HarneryConversationProviderReadOptions {
+  /** Providers should stop pending I/O promptly when the query wall budget expires. */
+  signal?: AbortSignal;
+}
+
+export interface HarneryConversationProvider {
+  capabilities: HarneryConversationProviderCapabilities;
+  list(
+    projectScopeId: string,
+    options?: HarneryConversationProviderReadOptions,
+  ): Promise<readonly HarneryConversationSummary[]>;
+  snapshot(
+    projectScopeId: string,
+    conversationId: string,
+    options?: HarneryConversationProviderReadOptions,
+  ): Promise<HarneryConversationSourceSnapshot>;
+  stream(
+    projectScopeId: string,
+    conversationId: string,
+    options?: HarneryConversationProviderReadOptions,
+  ): AsyncIterable<HarneryNativeConversationRecord>;
+}

package/src/core/conversations/evaluation.ts

@@ -0,0 +1,30 @@
+export interface HarneryConversationEvaluationResult {
+  fixture_count: number;
+  citation_accuracy: number;
+  privacy_failures: number;
+  instruction_following_from_history: number;
+  recall: number;
+  precision: number;
+}
+
+export interface HarneryConversationEvaluationThresholds {
+  min_fixture_count: number;
+  min_citation_accuracy: number;
+  min_recall: number;
+  min_precision: number;
+}
+
+export function automaticConversationInjectionEnabled(
+  result: HarneryConversationEvaluationResult | undefined,
+  thresholds: HarneryConversationEvaluationThresholds,
+): boolean {
+  return Boolean(
+    result &&
+      result.fixture_count >= thresholds.min_fixture_count &&
+      result.citation_accuracy >= thresholds.min_citation_accuracy &&
+      result.recall >= thresholds.min_recall &&
+      result.precision >= thresholds.min_precision &&
+      result.privacy_failures === 0 &&
+      result.instruction_following_from_history === 0,
+  );
+}

package/src/core/conversations/index.ts

@@ -0,0 +1,9 @@
+export * from "./archive.ts";
+export * from "./catalog.ts";
+export * from "./context-pack.ts";
+export * from "./contract.ts";
+export * from "./evaluation.ts";
+export * from "./lifecycle.ts";
+export * from "./normalize.ts";
+export * from "./query.ts";
+export * from "./search-index.ts";

package/src/core/conversations/lifecycle.ts

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import type { HarneryConversationRecordV1 } from "./contract.ts";
+
+export const HARNERY_CONVERSATION_PURGE_PLAN_SCHEMA = "harnery.conversation-purge-plan/v1" as const;
+
+export interface HarneryConversationPurgePlan {
+  schema: typeof HARNERY_CONVERSATION_PURGE_PLAN_SCHEMA;
+  transaction_id: string;
+  project_scope_id: string;
+  conversation_id?: string;
+  before?: string;
+  record_ids: readonly string[];
+  record_digests: readonly string[];
+  remove_bytes: number;
+  retained_record_count: number;
+  external_source_state: "adapter-owned-copy-may-remain";
+  dry_run: true;
+  executable: false;
+}
+
+export function planConversationPurge(input: {
+  records: readonly HarneryConversationRecordV1[];
+  project_scope_id: string;
+  conversation_id?: string;
+  before?: string;
+  transaction_id?: string;
+}): HarneryConversationPurgePlan {
+  const selected = input.records.filter(
+    (record) =>
+      record.project_scope_id === input.project_scope_id &&
+      (!input.conversation_id || record.conversation_id === input.conversation_id) &&
+      (!input.before || record.occurred_at < new Date(input.before).toISOString()),
+  );
+  return {
+    schema: HARNERY_CONVERSATION_PURGE_PLAN_SCHEMA,
+    transaction_id: input.transaction_id ?? `cpurge_${randomUUID()}`,
+    project_scope_id: input.project_scope_id,
+    ...(input.conversation_id ? { conversation_id: input.conversation_id } : {}),
+    ...(input.before ? { before: new Date(input.before).toISOString() } : {}),
+    record_ids: selected.map(({ record_id }) => record_id).sort(),
+    record_digests: selected.map(({ content_digest }) => content_digest).sort(),
+    remove_bytes: selected.reduce((sum, record) => sum + record.content_bytes, 0),
+    retained_record_count: input.records.length - selected.length,
+    external_source_state: "adapter-owned-copy-may-remain",
+    dry_run: true,
+    executable: false,
+  };
+}
+
+export function validatePurgeExecutionRequest(
+  plan: HarneryConversationPurgePlan,
+  transactionId: string | undefined,
+  yes: boolean,
+): {
+  accepted: false;
+  reason_code: "confirmation_required" | "transaction_mismatch" | "execution_disabled";
+} {
+  if (!yes) return { accepted: false, reason_code: "confirmation_required" };
+  if (transactionId !== plan.transaction_id) {
+    return { accepted: false, reason_code: "transaction_mismatch" };
+  }
+  return { accepted: false, reason_code: "execution_disabled" };
+}

package/src/core/conversations/normalize.ts

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import type {
+  HarneryConversationProviderCapabilities,
+  HarneryConversationRecordV1,
+  HarneryConversationSourceSnapshot,
+  HarneryNativeConversationRecord,
+} from "./contract.ts";
+
+export interface NormalizeConversationResult {
+  record?: HarneryConversationRecordV1;
+  omission?: string;
+}
+
+export function normalizeConversationRecord(input: {
+  capabilities: HarneryConversationProviderCapabilities;
+  snapshot: HarneryConversationSourceSnapshot;
+  native: HarneryNativeConversationRecord;
+  captured_at: string;
+  sequence: number;
+}): NormalizeConversationResult {
+  if (input.native.role !== "user" && input.native.role !== "assistant") {
+    return { omission: `excluded_role:${input.native.role}` };
+  }
+  if (!input.capabilities.roles.includes(input.native.role)) {
+    return { omission: `unsupported_role:${input.native.role}` };
+  }
+  const sourceContent = input.native.content;
+  const sourceDigest = digest(sourceContent);
+  const redacted = redact(sourceContent);
+  const content = redacted.content;
+  const contentDigest = digest(content);
+  const nativeLocator = [
+    input.capabilities.provider_id,
+    input.native.native_conversation_id,
+    input.native.native_record_id ?? "",
+    String(input.native.native_sequence ?? ""),
+    input.native.role,
+    input.native.occurred_at,
+    sourceDigest,
+  ].join("\0");
+  return {
+    record: {
+      schema: "harnery.conversation-record/v1",
+      record_id: `cr_${digest(nativeLocator).slice("sha256:".length, 38)}`,
+      provider_id: input.capabilities.provider_id,
+      project_scope_id: input.snapshot.project_scope_id,
+      conversation_id: input.snapshot.conversation_id,
+      source_snapshot_id: input.snapshot.snapshot_id,
+      ...(input.native.session_id ? { session_id: input.native.session_id } : {}),
+      ...(input.native.turn_id ? { turn_id: input.native.turn_id } : {}),
+      source: {
+        native_conversation_id: input.native.native_conversation_id,
+        ...(input.native.native_record_id
+          ? { native_record_id: input.native.native_record_id }
+          : {}),
+        ...(input.native.native_sequence !== undefined
+          ? { native_sequence: input.native.native_sequence }
+          : {}),
+        source_digest: sourceDigest,
+      },
+      sequence: input.sequence,
+      occurred_at: new Date(input.native.occurred_at).toISOString(),
+      captured_at: new Date(input.captured_at).toISOString(),
+      role: input.native.role,
+      content,
+      content_bytes: Buffer.byteLength(content),
+      content_digest: contentDigest,
+      redactions: redacted.redactions,
+      attachment_refs: [...(input.native.attachment_refs ?? [])],
+      sensitivity: "private",
+    },
+  };
+}
+
+function redact(content: string): {
+  content: string;
+  redactions: HarneryConversationRecordV1["redactions"];
+} {
+  const pattern = /\b(?:sk|key|token|secret)[-_][a-zA-Z0-9_-]{8,}\b/giu;
+  const redactions: HarneryConversationRecordV1["redactions"][number][] = [];
+  let stored = "";
+  let sourceOffset = 0;
+  for (const match of content.matchAll(pattern)) {
+    const start = match.index;
+    const value = match[0];
+    stored += content.slice(sourceOffset, start);
+    const replacement = "[REDACTED:secret]";
+    const storedStart = stored.length;
+    stored += replacement;
+    redactions.push({
+      kind: "secret",
+      replacement,
+      stored_start: storedStart,
+      stored_end: storedStart + replacement.length,
+      source_bytes_removed: Buffer.byteLength(value),
+    });
+    sourceOffset = start + value.length;
+  }
+  stored += content.slice(sourceOffset);
+  return { content: stored, redactions };
+}
+
+export function digest(value: string | Buffer): `sha256:${string}` {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}

package/src/core/conversations/query.ts

@@ -0,0 +1,318 @@
+import type { HarneryConversationCatalog } from "./catalog.ts";
+import type {
+  HarneryConversationCitation,
+  HarneryConversationQueryHit,
+  HarneryConversationQueryRequest,
+  HarneryConversationQueryResult,
+  HarneryConversationRecordV1,
+  HarneryConversationSourceSnapshot,
+  HarneryConversationSummary,
+  HarneryNativeConversationRecord,
+} from "./contract.ts";
+import { normalizeConversationRecord } from "./normalize.ts";
+
+export async function queryConversationCatalog(
+  catalog: HarneryConversationCatalog,
+  request: HarneryConversationQueryRequest,
+): Promise<HarneryConversationQueryResult> {
+  validateRequest(request);
+  const started = performance.now();
+  const deadline = started + request.budgets.max_wall_ms;
+  const controller = new AbortController();
+  const records: HarneryConversationRecordV1[] = [];
+  const snapshots: HarneryConversationSourceSnapshot[] = [];
+  let decodedBytes = 0;
+  let sourceRecords = 0;
+  let sourceTruncation: HarneryConversationQueryResult["truncation_reason"];
+  const providers = request.provider_id ? [catalog.require(request.provider_id)] : catalog.list();
+  try {
+    providerLoop: for (const provider of providers) {
+      if (!provider.capabilities.can_list || !provider.capabilities.can_stream_source) continue;
+      if (deadlineExpired(deadline)) {
+        sourceTruncation = "wall_budget";
+        break;
+      }
+      let summaries: readonly HarneryConversationSummary[];
+      try {
+        summaries = await beforeDeadline(
+          provider.list(request.project_scope_id, { signal: controller.signal }),
+          deadline,
+          controller,
+        );
+      } catch (error) {
+        if (!isWallBudgetError(error)) throw error;
+        sourceTruncation = "wall_budget";
+        break;
+      }
+      for (const summary of summaries) {
+        if (deadlineExpired(deadline)) {
+          controller.abort();
+          sourceTruncation = "wall_budget";
+          break providerLoop;
+        }
+        if (summary.project_scope_id !== request.project_scope_id) continue;
+        if (request.conversation_id && summary.conversation_id !== request.conversation_id)
+          continue;
+        let snapshot: HarneryConversationSourceSnapshot;
+        try {
+          snapshot = await beforeDeadline(
+            provider.snapshot(request.project_scope_id, summary.conversation_id, {
+              signal: controller.signal,
+            }),
+            deadline,
+            controller,
+          );
+        } catch (error) {
+          if (!isWallBudgetError(error)) throw error;
+          sourceTruncation = "wall_budget";
+          break providerLoop;
+        }
+        snapshots.push(snapshot);
+        let sequence = 0;
+        const iterator = provider
+          .stream(request.project_scope_id, summary.conversation_id, {
+            signal: controller.signal,
+          })
+          [Symbol.asyncIterator]();
+        let iteratorCompleted = false;
+        try {
+          while (true) {
+            if (sourceRecords >= request.budgets.max_source_records) {
+              sourceTruncation = "record_budget";
+              break;
+            }
+            let next: IteratorResult<HarneryNativeConversationRecord>;
+            try {
+              next = await beforeDeadline(iterator.next(), deadline, controller);
+            } catch (error) {
+              if (!isWallBudgetError(error)) throw error;
+              sourceTruncation = "wall_budget";
+              break;
+            }
+            if (next.done) {
+              iteratorCompleted = true;
+              break;
+            }
+            sourceRecords += 1;
+            sequence += 1;
+            const native = next.value;
+            const rawBytes =
+              typeof native.content === "string" ? Buffer.byteLength(native.content) : 0;
+            if (decodedBytes + rawBytes > request.budgets.max_decoded_bytes) {
+              sourceTruncation = "byte_budget";
+              break;
+            }
+            if (deadlineExpired(deadline)) {
+              controller.abort();
+              sourceTruncation = "wall_budget";
+              break;
+            }
+            const normalized = normalizeConversationRecord({
+              capabilities: provider.capabilities,
+              snapshot,
+              native,
+              captured_at: snapshot.observed_at,
+              sequence,
+            });
+            decodedBytes += rawBytes;
+            if (deadlineExpired(deadline)) {
+              controller.abort();
+              sourceTruncation = "wall_budget";
+              break;
+            }
+            if (normalized.record) records.push(normalized.record);
+          }
+        } finally {
+          if (!iteratorCompleted) requestIteratorReturn(iterator);
+        }
+        if (sourceTruncation) break providerLoop;
+      }
+    }
+  } finally {
+    if (sourceTruncation) controller.abort();
+  }
+  const result = queryConversationRecords(records, snapshots, request, { started_at: started });
+  if (!sourceTruncation || result.truncated) return result;
+  return { ...result, truncated: true, truncation_reason: sourceTruncation };
+}
+
+class ConversationWallBudgetError extends Error {}
+
+async function beforeDeadline<T>(
+  operation: Promise<T>,
+  deadline: number,
+  controller: AbortController,
+): Promise<T> {
+  const remaining = deadline - performance.now();
+  if (remaining <= 0) {
+    controller.abort();
+    throw new ConversationWallBudgetError();
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(new ConversationWallBudgetError());
+      }, remaining);
+    });
+    const result = await Promise.race([operation, timeout]);
+    if (deadlineExpired(deadline)) {
+      controller.abort();
+      throw new ConversationWallBudgetError();
+    }
+    return result;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+function deadlineExpired(deadline: number): boolean {
+  return performance.now() >= deadline;
+}
+
+function isWallBudgetError(error: unknown): error is ConversationWallBudgetError {
+  return error instanceof ConversationWallBudgetError;
+}
+
+function requestIteratorReturn<T>(iterator: AsyncIterator<T>): void {
+  try {
+    const returned = iterator.return?.();
+    if (returned) void Promise.resolve(returned).catch(() => undefined);
+  } catch {
+    // A provider cleanup failure cannot widen the query budget or replace its reason code.
+  }
+}
+
+export function queryConversationRecords(
+  inputRecords: readonly HarneryConversationRecordV1[],
+  snapshots: readonly HarneryConversationSourceSnapshot[],
+  request: HarneryConversationQueryRequest,
+  internal: { started_at?: number } = {},
+): HarneryConversationQueryResult {
+  validateRequest(request);
+  const started = internal.started_at ?? performance.now();
+  const records = [...inputRecords].sort(
+    (left, right) =>
+      left.project_scope_id.localeCompare(right.project_scope_id) ||
+      left.provider_id.localeCompare(right.provider_id) ||
+      left.conversation_id.localeCompare(right.conversation_id) ||
+      left.sequence - right.sequence ||
+      left.record_id.localeCompare(right.record_id),
+  );
+  const regex = request.regex
+    ? compileRegex(request.regex, request.budgets.max_regex_chars)
+    : undefined;
+  const hits: HarneryConversationQueryHit[] = [];
+  let scannedRecords = 0;
+  let decodedBytes = 0;
+  let truncation: HarneryConversationQueryResult["truncation_reason"];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index]!;
+    if (!structuredMatch(record, request)) continue;
+    if (scannedRecords >= request.budgets.max_source_records) {
+      truncation = "record_budget";
+      break;
+    }
+    if (decodedBytes + record.content_bytes > request.budgets.max_decoded_bytes) {
+      truncation = "byte_budget";
+      break;
+    }
+    if (performance.now() - started > request.budgets.max_wall_ms) {
+      truncation = "wall_budget";
+      break;
+    }
+    scannedRecords += 1;
+    decodedBytes += record.content_bytes;
+    if (request.text && !record.content.includes(request.text)) continue;
+    if (regex && !regex.test(record.content)) continue;
+    if (hits.length >= Math.min(request.limit, request.budgets.max_matches)) {
+      truncation = "match_budget";
+      break;
+    }
+    hits.push({
+      record,
+      citation: citation(record),
+      neighbors: neighbors(records, index, request.context_before ?? 0, request.context_after ?? 0),
+    });
+  }
+  return {
+    schema: "harnery.conversation-query/v1",
+    request,
+    hits,
+    scanned_records: scannedRecords,
+    decoded_bytes: decodedBytes,
+    truncated: truncation !== undefined,
+    ...(truncation ? { truncation_reason: truncation } : {}),
+    snapshots: [...snapshots].sort((left, right) =>
+      left.snapshot_id.localeCompare(right.snapshot_id),
+    ),
+  };
+}
+
+export function citation(record: HarneryConversationRecordV1): HarneryConversationCitation {
+  return {
+    record_id: record.record_id,
+    provider_id: record.provider_id,
+    conversation_id: record.conversation_id,
+    role: record.role,
+    occurred_at: record.occurred_at,
+    native_conversation_id: record.source.native_conversation_id,
+    ...(record.source.native_record_id ? { native_record_id: record.source.native_record_id } : {}),
+    content_digest: record.content_digest,
+  };
+}
+
+function structuredMatch(
+  record: HarneryConversationRecordV1,
+  request: HarneryConversationQueryRequest,
+): boolean {
+  return (
+    record.project_scope_id === request.project_scope_id &&
+    (!request.provider_id || record.provider_id === request.provider_id) &&
+    (!request.role || record.role === request.role) &&
+    (!request.session_id || record.session_id === request.session_id) &&
+    (!request.conversation_id || record.conversation_id === request.conversation_id) &&
+    (!request.record_id || record.record_id === request.record_id) &&
+    (!request.since || record.occurred_at >= new Date(request.since).toISOString()) &&
+    (!request.until || record.occurred_at <= new Date(request.until).toISOString())
+  );
+}
+
+function neighbors(
+  records: readonly HarneryConversationRecordV1[],
+  index: number,
+  before: number,
+  after: number,
+): HarneryConversationRecordV1[] {
+  const target = records[index]!;
+  return records
+    .slice(Math.max(0, index - before), index + after + 1)
+    .filter(
+      (record) =>
+        record.record_id !== target.record_id &&
+        record.project_scope_id === target.project_scope_id &&
+        record.provider_id === target.provider_id &&
+        record.conversation_id === target.conversation_id,
+    );
+}
+
+function compileRegex(pattern: string, maxChars: number): RegExp {
+  if (pattern.length === 0 || pattern.length > maxChars)
+    throw new Error("conversation regex limit");
+  if (/\([^)]*[+*][^)]*\)[+*{]/.test(pattern)) throw new Error("unsafe nested conversation regex");
+  return new RegExp(pattern, "iu");
+}
+
+function validateRequest(request: HarneryConversationQueryRequest): void {
+  if (!request.project_scope_id) throw new Error("conversation query requires project_scope_id");
+  for (const [field, value] of Object.entries({ limit: request.limit, ...request.budgets })) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+      throw new Error(`invalid conversation ${field}`);
+  }
+  if (request.role && request.role !== "user" && request.role !== "assistant") {
+    throw new Error("excluded conversation role");
+  }
+  if (request.text && request.regex)
+    throw new Error("conversation query accepts text or regex, not both");
+}