@remnic/core 9.65.0 → 9.65.1

package/dist/chunk-URS5GSM7.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/search/port.ts"],"sourcesContent":["import type { QmdSearchResult } from \"../types.js\";\n\n/** Alias so consumers don't need to reference \"Qmd\" in a backend-agnostic context. */\nexport type SearchResult = QmdSearchResult;\n\nexport interface SearchQueryOptions {\n  intent?: string;\n  explain?: boolean;\n  candidateLimit?: number;\n  rerank?: boolean;\n  chunkStrategy?: \"auto\" | \"regex\";\n  structuredSearches?: Array<{ type: \"lex\" | \"vec\" | \"hyde\"; query: string }>;\n}\n\n/**\n * A search that returned empty (or partial) results because the backend was\n * unavailable, still loading, or timed out — cases that are otherwise\n * indistinguishable from a genuine \"no matches\" (issue #1536, CLAUDE.md\n * rule 34).\n */\nexport interface SearchDegradation {\n  backend: \"qmd\" | \"remote\" | \"meilisearch\" | \"orama\" | \"lancedb\";\n  code:\n    | \"backend_unavailable\"\n    | \"backend_error\"\n    | \"daemon_timeout\"\n    | \"daemon_loading\"\n    | \"subprocess_error\"\n    | \"deadline_exceeded\"\n    | \"remote_error\";\n  detail?: string;\n}\n\nexport interface SearchExecutionOptions {\n  signal?: AbortSignal;\n  /**\n   * Observer invoked when the backend degrades during this call (#1536).\n   * Callers that need to distinguish empty-because-degraded from\n   * empty-because-no-matches (recall x-ray, fallback decisions) pass a\n   * collector here. Observer failures are swallowed by the notifier —\n   * observability must never break search.\n   */\n  onDegradation?: (degradation: SearchDegradation) => void;\n}\n\nexport function reportSearchDegradation(\n  execution: SearchExecutionOptions | undefined,\n  degradation: SearchDegradation\n): void {\n  try {\n    execution?.onDegradation?.(degradation);\n  } catch {\n    // Observability must never break search.\n  }\n}\n\nexport function resolveEnsureCollectionArgs(\n  collectionOrExecution?: string | SearchExecutionOptions,\n  execution?: SearchExecutionOptions\n): { collection?: string; execution?: SearchExecutionOptions } {\n  if (typeof collectionOrExecution === \"string\") {\n    return { collection: collectionOrExecution, execution };\n  }\n  return { collection: undefined, execution: collectionOrExecution ?? execution };\n}\n\n/**\n * Optional status report for search backends that track embedding backlog.\n * Backends without embedding pipelines return null from status().\n */\nexport interface SearchBackendStatus {\n  pendingEmbeddings: number | null;\n  oldestPendingAgeMs: number | null;\n  totalFiles: number | null;\n  embeddedFiles: number | null;\n}\n\n/**\n * Abstract search backend interface.\n *\n * Implementations:\n * - QmdClient (default, local hybrid BM25+vector+reranking)\n * - OramaBackend (embedded, pure JS, hybrid FTS+vector)\n * - LanceDbBackend (embedded, native Arrow bindings, RRF reranking)\n * - MeilisearchBackend (server-based SDK, hybrid search)\n * - RemoteSearchBackend (HTTP REST adapter)\n * - NoopSearchBackend (graceful degradation)\n *\n * See docs/writing-a-search-backend.md for the implementation guide.\n */\nexport interface SearchBackend {\n  // ── Lifecycle ──\n  probe(): Promise<boolean>;\n  /**\n   * Optional non-mutating availability probe for health/readiness checks.\n   * Implementations must avoid auto-upgrades, collection creation, daemon\n   * startup, or any other runtime-modifying side effects.\n   */\n  checkAvailability?(execution?: SearchExecutionOptions): Promise<boolean>;\n  isAvailable(): boolean;\n  debugStatus(): string;\n  /** Optional embedding backlog status for health surfaces. */\n  status?(): Promise<SearchBackendStatus>;\n\n  // ── Search ──\n  search(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    options?: SearchQueryOptions,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n  searchGlobal(query: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;\n  bm25Search(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n  vectorSearch(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n  hybridSearch(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n\n  // ── Maintenance ──\n  update(execution?: SearchExecutionOptions): Promise<void>;\n  /**\n   * Wall-clock ms of the most recent SUCCESSFUL index refresh, or null when the\n   * backend has never run one. Ordinary update() is fail-open: it returns\n   * silently (without throwing or advancing this timestamp) when the backend is\n   * unavailable or the call is suppressed by a min-interval / failure backoff.\n   * Callers that must know whether update() actually indexed — so they can\n   * invalidate dependent caches only on a real refresh — snapshot this before\n   * the call and treat the backend as refreshed iff the value advanced. Optional\n   * because not every backend tracks it; absent means \"assume refreshed\".\n   */\n  readonly lastUpdateRanAtMs?: number | null;\n  /**\n   * Optional strict refresh used by callers that must know whether the backend\n   * was actually refreshed before writing success markers. Ordinary update\n   * calls remain fail-open for migration/maintenance resilience.\n   */\n  updateStrict?(execution?: SearchExecutionOptions): Promise<void>;\n  updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  updateCollectionFromDir?(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void>;\n  /**\n   * True when update() refreshes every indexed collection, not just this\n   * backend's configured collection. Namespace routers use this to avoid\n   * repeating the same expensive global update once per namespace.\n   */\n  updatesAllCollections?(): boolean;\n  /**\n   * Optional strict refresh used by callers that must know whether a collection\n   * was actually refreshed before writing success markers. Ordinary update\n   * calls remain fail-open for migration/maintenance resilience.\n   */\n  updateCollectionStrict?(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  embed(): Promise<void>;\n  /**\n   * Optional strict embed used by callers that must know vectors were actually\n   * refreshed before writing success markers.\n   */\n  embedStrict?(): Promise<void>;\n  embedCollection(collection: string): Promise<void>;\n  /**\n   * Optional strict collection embed used by callers that must know vectors were\n   * actually refreshed before writing success markers.\n   */\n  embedCollectionStrict?(collection: string): Promise<void>;\n\n  // ── Collection management ──\n  /**\n   * True only when the backend can bind, isolate, search, and delete collections\n   * outside Remnic's primary memory roots.\n   */\n  supportsAdditionalCollections?(): boolean;\n  /**\n   * Prevent a collection from participating in unscoped/global searches.\n   * Dedicated corpora must call this immediately after collection creation.\n   */\n  excludeCollectionFromGlobalSearch?(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  /** Remove a non-primary collection and its backend-owned index state. */\n  deleteCollection?(collection: string, execution?: SearchExecutionOptions): Promise<boolean>;\n  /** Canonical source root currently bound to a named collection. */\n  collectionRoot?(collection: string, execution?: SearchExecutionOptions): Promise<string | null>;\n  /** Collection-scoped status for observability surfaces. */\n  collectionStatus?(collection: string): Promise<Pick<SearchBackendStatus, \"totalFiles\">>;\n  /**\n   * Optional non-mutating collection probe. Backends that can distinguish a\n   * missing collection from a transient probe failure should implement this so\n   * callers can avoid auto-creating collections in unsafe layouts.\n   */\n  checkCollection?(\n    collectionOrExecution?: string | SearchExecutionOptions,\n    execution?: SearchExecutionOptions\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n  ensureCollection(\n    memoryDir: string,\n    execution?: SearchExecutionOptions\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n  ensureCollection(\n    memoryDir: string,\n    collection?: string,\n    execution?: SearchExecutionOptions\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n}\n"],"mappings":";AA6CO,SAAS,wBACd,WACA,aACM;AACN,MAAI;AACF,eAAW,gBAAgB,WAAW;AAAA,EACxC,QAAQ;AAAA,EAER;AACF;AAEO,SAAS,4BACd,uBACA,WAC6D;AAC7D,MAAI,OAAO,0BAA0B,UAAU;AAC7C,WAAO,EAAE,YAAY,uBAAuB,UAAU;AAAA,EACxD;AACA,SAAO,EAAE,YAAY,QAAW,WAAW,yBAAyB,UAAU;AAChF;","names":[]}