summa-client-typescript 2.0.0

package/dist/generated/summa.d.ts

@@ -0,0 +1,1071 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+export declare const protobufPackage = "summa";
+/** Method for fusing sub-query result lists */
+export declare enum FusionMethod {
+    /** FUSION_RRF - Reciprocal Rank Fusion (rank-based, default) */
+    FUSION_RRF = 0,
+    /** FUSION_NORMALIZED_WEIGHTED_SUM - Min-max normalized weighted score sum */
+    FUSION_NORMALIZED_WEIGHTED_SUM = 1,
+    /** FUSION_CANDIDATES - Return complete bounded nomination lists/union for coordinator-side fusion. */
+    FUSION_CANDIDATES = 2,
+    UNRECOGNIZED = -1
+}
+export declare function fusionMethodFromJSON(object: any): FusionMethod;
+export declare function fusionMethodToJSON(object: FusionMethod): string;
+/** Scope is explicit: document features never become body ordinal zero. */
+export declare enum ScoreScope {
+    SCORE_SCOPE_UNSPECIFIED = 0,
+    SCORE_SCOPE_DOCUMENT = 1,
+    SCORE_SCOPE_CHUNK = 2,
+    UNRECOGNIZED = -1
+}
+export declare function scoreScopeFromJSON(object: any): ScoreScope;
+export declare function scoreScopeToJSON(object: ScoreScope): string;
+/** How to combine scores for multi-valued documents */
+export declare enum MultiValueCombiner {
+    /** COMBINER_LOG_SUM_EXP - Softmax-weighted smooth maximum (default); count-invariant */
+    COMBINER_LOG_SUM_EXP = 0,
+    /** COMBINER_MAX - Take maximum score */
+    COMBINER_MAX = 1,
+    /** COMBINER_AVG - Average all scores */
+    COMBINER_AVG = 2,
+    /** COMBINER_SUM - Sum all scores */
+    COMBINER_SUM = 3,
+    /** COMBINER_WEIGHTED_TOP_K - Weighted top-k with decay */
+    COMBINER_WEIGHTED_TOP_K = 4,
+    UNRECOGNIZED = -1
+}
+export declare function multiValueCombinerFromJSON(object: any): MultiValueCombiner;
+export declare function multiValueCombinerToJSON(object: MultiValueCombiner): string;
+export declare enum VectorIndexAlterState {
+    VECTOR_INDEX_ALTER_STATE_UNSPECIFIED = 0,
+    VECTOR_INDEX_ALTER_STATE_BUILT = 1,
+    VECTOR_INDEX_ALTER_STATE_DEFERRED_FLAT = 2,
+    VECTOR_INDEX_ALTER_STATE_PARAMETERS_ONLY = 3,
+    UNRECOGNIZED = -1
+}
+export declare function vectorIndexAlterStateFromJSON(object: any): VectorIndexAlterState;
+export declare function vectorIndexAlterStateToJSON(object: VectorIndexAlterState): string;
+/** Query types */
+export interface Query {
+    term?: TermQuery | undefined;
+    boolean?: BooleanQuery | undefined;
+    boost?: BoostQuery | undefined;
+    all?: AllQuery | undefined;
+    sparseVector?: SparseVectorQuery | undefined;
+    denseVector?: DenseVectorQuery | undefined;
+    match?: MatchQuery | undefined;
+    range?: RangeQuery | undefined;
+    prefix?: PrefixQuery | undefined;
+    binaryDenseVector?: BinaryDenseVectorQuery | undefined;
+    /** Top-level only (cannot be nested) */
+    fusion?: FusionQuery | undefined;
+    phrase?: PhraseQuery | undefined;
+}
+/** Weighted sub-query for hybrid fusion */
+export interface WeightedQuery {
+    query: Query | undefined;
+    /** Legacy RRF/NWS contribution; 0 or unset = 1.0 */
+    weight: number;
+    /** Required, unique feature identity when l1 or score_export is supplied. */
+    name: string;
+    scope: ScoreScope;
+    /** Backfill this branch without using it to nominate candidates (L1/export only). */
+    scoreOnly: boolean;
+}
+/**
+ * Union fusion of independently-executed sub-queries (e.g. sparse + dense
+ * hybrid retrieval). Unlike the reranker (which can only re-score documents
+ * the first-stage query found), fusion keeps documents found by ANY
+ * sub-query. Only valid at the top level of SearchRequest.query; composes
+ * with SearchRequest.reranker (the fused list becomes the L1 candidates).
+ */
+export interface FusionQuery {
+    queries: WeightedQuery[];
+    method: FusionMethod;
+    /** RRF rank constant; 0 = default 60 */
+    rrfK: number;
+    /**
+     * Combiner for fused per-chunk (ordinal) scores into a document score.
+     * Fusion runs at chunk granularity: same-chunk hits across sub-queries
+     * compound, and results carry per-chunk ordinal_scores.
+     * Unset (0) = MAX (recommended; LogSumExp is unsuitable at RRF magnitudes).
+     */
+    combiner: MultiValueCombiner;
+    /** Common document eligibility for every branch. Does not create an L1 feature. */
+    filters: Query[];
+    /**
+     * Independent per-branch nomination depth (L1/export only). 0 uses
+     * candidate_limit. The complete union survives until L1 ranking/export.
+     */
+    candidateDepth: number;
+}
+/**
+ * Fixed preprocessing trained offline, never derived from a shard/result page.
+ * The only L1 scoring contract: a compiled symbolic formula over branch scores.
+ */
+export interface L1Ranking {
+    /** Omitted=true: backfill only missing raw cells. False uses organic values. */
+    backfill?: boolean | undefined;
+    /** Raw defaults for missing formula variables; omitted variables use zero. */
+    missingValues: {
+        [key: string]: number;
+    };
+    /**
+     * Required, nonempty expression over named raw scores and reserved `rrf`.
+     * Runs before passage/document selection. Requires formula_v1.
+     */
+    formula: string;
+}
+export interface L1Ranking_MissingValuesEntry {
+    key: string;
+    value: number;
+}
+export interface ScoreExport {
+    /**
+     * Maximum raw passage rows per hit; 0 = all (65536). With l1, exported rows
+     * are the best passages after complete scoring. Without l1, exceeding this
+     * bound fails instead of silently omitting features the caller needs to rank.
+     */
+    passagesPerDocument: number;
+    /**
+     * Diagnostics: score every stored passage of nominated documents. Default
+     * false scores the union of nominated passages only, plus document context.
+     */
+    allPassages: boolean;
+    /**
+     * Capability 4: score real body ordinals for document-only nominees.
+     * Requires backfill and a chunk-scoped feature. Existing body nominations
+     * retain their original passage union; no organic votes are fabricated.
+     */
+    seedDocumentPassages: boolean;
+}
+/**
+ * Sparse vector query for similarity search
+ * Either provide (indices, values) directly, or provide text for server-side tokenization
+ */
+export interface SparseVectorQuery {
+    field: string;
+    /** Pre-computed token indices */
+    indices: number[];
+    /** Pre-computed token values */
+    values: number[];
+    /** Raw text (tokenized server-side if tokenizer configured) */
+    text: string;
+    /** How to combine scores for multi-value fields */
+    combiner: MultiValueCombiner;
+    /** BMP/MaxScore pruning factor (0 = schema default, 1 = exact). */
+    heapFactor: number;
+    /** Temperature for LogSumExp (default: 1.5) */
+    combinerTemperature: number;
+    /** K for WeightedTopK (default: 5) */
+    combinerTopK: number;
+    /** Decay for WeightedTopK (default: 0.7) */
+    combinerDecay: number;
+    /** Min abs(weight) for query dims (0 = no filtering) */
+    weightThreshold: number;
+    /** Max query dimensions to process (0 = all) */
+    maxQueryDims: number;
+    /** Fraction of query dims to keep (0 = no pruning, 0.1 = top 10%) */
+    pruning: number;
+    /** BMP LSP gamma (unset = depth-derived, 0 = exhaustive). */
+    lspGamma?: number | undefined;
+    /** Nomination query dimensions (1..64) */
+    seismicCut?: number | undefined;
+    /** Summary pruning factor (0..1) */
+    seismicFactor?: number | undefined;
+    /** Exact shared-forward scan; false allows approximation */
+    exhaustive?: boolean | undefined;
+}
+/** Dense vector query for similarity search */
+export interface DenseVectorQuery {
+    field: string;
+    vector: number[];
+    /** Number of clusters to probe (for IVF indexes) */
+    nprobe: number;
+    /** How to combine scores for multi-value fields */
+    combiner: MultiValueCombiner;
+    /** Temperature for LogSumExp (default: 1.5) */
+    combinerTemperature: number;
+    /** K for WeightedTopK (default: 5) */
+    combinerTopK: number;
+    /** Decay for WeightedTopK (default: 0.7) */
+    combinerDecay: number;
+}
+/** Binary dense vector query for Hamming distance search */
+export interface BinaryDenseVectorQuery {
+    field: string;
+    /** Packed-bit query vector (ceil(dim/8) bytes) */
+    vector: Uint8Array;
+    /** How to combine scores for multi-value fields */
+    combiner: MultiValueCombiner;
+    combinerTemperature: number;
+    combinerTopK: number;
+    combinerDecay: number;
+}
+export interface TermQuery {
+    field: string;
+    term: string;
+    /** Optional hint for the field's tokenizer (see MatchQuery.tokenizer_hint) */
+    tokenizerHint: string;
+}
+export interface BooleanQuery {
+    must: Query[];
+    should: Query[];
+    mustNot: Query[];
+}
+export interface BoostQuery {
+    query: Query | undefined;
+    boost: number;
+}
+export interface AllQuery {
+}
+/**
+ * Range query on a fast field (inclusive bounds)
+ * Exactly one pair of bounds should be set (u64, i64, or f64)
+ */
+export interface RangeQuery {
+    field: string;
+    minU64?: number | undefined;
+    maxU64?: number | undefined;
+    minI64?: number | undefined;
+    maxI64?: number | undefined;
+    minF64?: number | undefined;
+    maxF64?: number | undefined;
+}
+/**
+ * Full-text match query - tokenizes text server-side and searches as OR of tokens
+ * Use this instead of TermQuery when searching with natural language text
+ */
+export interface MatchQuery {
+    field: string;
+    text: string;
+    /**
+     * Optional hint passed to the field's tokenizer. Static tokenizers ignore
+     * it; a `lex(by: languages, ...)` tokenizer
+     * reads it as a comma-separated list of language codes ("ru,en") and stems
+     * each query token with the first listed language of the token's script.
+     * Empty = the tokenizer's default.
+     */
+    tokenizerHint: string;
+    /**
+     * Proximity rescoring (sequential dependence): the top candidates of the
+     * BM25 pass gain a bonus for adjacent query terms occurring next to each
+     * other (ordered windows) or within `proximity_window` positions
+     * (unordered windows, half weight), scaled by this weight. 0 = off.
+     * Approximate: the bonus applies to an over-fetched candidate pool.
+     */
+    proximityWeight: number;
+    /** Unordered window size; 0 = 8. */
+    proximityWindow: number;
+    /**
+     * Approximate MaxScore: scale the pruning threshold by 1/heap_factor
+     * (0/unset or 1 = exact, rank-safe; 0.8 prunes more aggressively at some
+     * recall cost). Must be finite and in [0, 1]. This option applies to text queries.
+     */
+    heapFactor: number;
+    /**
+     * Long queries: keep only the `max_terms` rarest (highest idf) tokens for
+     * scoring; 0 = all tokens. Approximate.
+     */
+    maxTerms: number;
+}
+/**
+ * Phrase query - text is tokenized server-side with the field's tokenizer
+ * (so stemming matches indexing) and the terms must occur at the distances
+ * the tokenizer assigned (consecutively unless the tokenizer dropped stop
+ * words between them, whose positions are kept as gaps) or within `slop`
+ * positions of that. Requires the field to be indexed with token positions
+ * (`indexed<token_position>` or `indexed<positions>`); without positions the
+ * engine degrades to a MUST of the terms. Scored with BM25 over the phrase
+ * frequency (occurrences of the whole phrase) and the summed idf of its terms.
+ * A phrase whose words are all stop words is rejected standalone and dropped
+ * (with a server warning) when it is a clause of a BooleanQuery.
+ */
+export interface PhraseQuery {
+    field: string;
+    text: string;
+    slop: number;
+    /** See MatchQuery.tokenizer_hint */
+    tokenizerHint: string;
+}
+/**
+ * Prefix query - matches all documents containing any term starting with prefix
+ * Score is always 1.0 (filter-style). Efficient as a MUST clause in BooleanQuery.
+ */
+export interface PrefixQuery {
+    field: string;
+    prefix: string;
+}
+/**
+ * L2 reranker: rerank L1 candidates by exact vector distance
+ * For dense vectors: set `vector` (f32). For binary dense vectors: set `binary_vector` (bytes).
+ */
+export interface Reranker {
+    /** Vector field (dense or binary dense) */
+    field: string;
+    /** Query vector (f32, for dense fields) */
+    vector: number[];
+    combiner: MultiValueCombiner;
+    combinerTemperature: number;
+    combinerTopK: number;
+    combinerDecay: number;
+    /** Matryoshka pre-filter dims (0 = disabled) */
+    matryoshkaDims: number;
+    /** Query vector (packed bits, for binary dense fields) */
+    binaryVector: Uint8Array;
+    /** Reciprocal Rank Fusion k (0 = disabled, typical: 60) */
+    rrfK: number;
+}
+/** Search request/response */
+export interface SearchRequest {
+    indexName: string;
+    query: Query | undefined;
+    limit: number;
+    offset: number;
+    fieldsToLoad: string[];
+    /** Optional L2 reranker */
+    reranker: Reranker | undefined;
+    /**
+     * First-stage candidate pool. 0 uses offset + limit; explicit values must
+     * be between offset + limit and the 2x ceiling.
+     */
+    candidateLimit: number;
+    /**
+     * Anytime mode: wall-clock budget in milliseconds for the scoring phase.
+     * Text (BM25) MaxScore executors stop at the deadline and return the best
+     * results found so far; `SearchResponse.truncated` reports that it fired.
+     * 0 = unbounded (exact top-k).
+     */
+    timeBudgetMs: number;
+    /**
+     * Cross-shard text statistics for BM25 (see `GetTextStats`). When set they
+     * replace the backend's own statistics for the listed fields and terms;
+     * unset = the backend aggregates over its own segments.
+     */
+    textStats: TextStats | undefined;
+    /** Requires named, scoped fusion branches. The formula may reference the RRF feature. */
+    l1: L1Ranking | undefined;
+    /**
+     * With no l1, exports the complete candidate union for external inference.
+     * Export-only requests require offset=0 and a limit covering the whole union.
+     */
+    scoreExport: ScoreExport | undefined;
+    /**
+     * Return RRF diagnostics alongside the requested ranking score. Requires
+     * top-level fusion and complete nomination; does not change ranking.
+     */
+    includeRrfScores: boolean;
+    /**
+     * Preserve bounded per-shard nomination and selection traces. Default false;
+     * does not rerun subqueries or change retrieval/ranking budgets.
+     */
+    tracing: boolean;
+}
+export interface GetTextStatsRequest {
+    indexName: string;
+    /**
+     * The query whose BM25 terms are collected (after this backend's own
+     * tokenization); sparse, dense and filter clauses contribute nothing.
+     */
+    query: Query | undefined;
+}
+export interface GetTextStatsResponse {
+    stats: TextStats | undefined;
+}
+/** BM25 statistics of a set of text terms. */
+export interface TextStats {
+    /** Documents in the index (or the sum over shards). */
+    totalDocs: number;
+    fields: TextFieldStats[];
+}
+export interface TextFieldStats {
+    field: string;
+    /**
+     * Scoring units of the field: documents for a plain field, chunks for a
+     * chunked one.
+     */
+    corpusSize: number;
+    /** Average length of a scoring unit in tokens. */
+    avgLen: number;
+    terms: TermDocFreq[];
+}
+export interface TermDocFreq {
+    /** Index-time token bytes. */
+    term: Uint8Array;
+    docFreq: number;
+}
+/** Unique document address: segment + local doc_id */
+export interface DocAddress {
+    /** Segment ID (hex, 32 chars) */
+    segmentId: string;
+    /** Segment-local document ID */
+    docId: number;
+}
+export interface SearchHit {
+    address: DocAddress | undefined;
+    score: number;
+    fields: {
+        [key: string]: FieldValueList;
+    };
+    /** Per-ordinal scores for multi-value fields */
+    ordinalScores: OrdinalScore[];
+    /** Present only when score_export is requested. */
+    candidateScores: CandidateScores | undefined;
+    /** Present when include_rrf_scores is requested. */
+    rrfScore?: number | undefined;
+    rrfContributions: RrfContribution[];
+}
+export interface SearchHit_FieldsEntry {
+    key: string;
+    value: FieldValueList | undefined;
+}
+/**
+ * One organic nomination vote. Document context has no ordinal; chunk votes
+ * are combined per ordinal before the document's fusion combiner is applied.
+ */
+export interface RrfContribution {
+    queryIndex: number;
+    /** Empty for unnamed legacy branches. */
+    queryName: string;
+    /** One-based rank in the complete merged nomination list. */
+    rank: number;
+    /** Branch weight / (k + rank). */
+    score: number;
+    ordinal?: number | undefined;
+}
+export interface CandidateScores {
+    /**
+     * Branch name -> raw score. Absent key means unavailable indexed data;
+     * a valid nonmatch is explicitly 0. Negative dense scores are preserved.
+     */
+    document: {
+        [key: string]: number;
+    };
+    passages: PassageScores[];
+    /** Before limiting exported rows; L1 selected from all of these passages. */
+    scoredPassages: number;
+}
+export interface CandidateScores_DocumentEntry {
+    key: string;
+    value: number;
+}
+export interface PassageScores {
+    ordinal: number;
+    scores: {
+        [key: string]: number;
+    };
+    /** Final formula score when l1 is present, otherwise no ranking score. */
+    l1Score?: number | undefined;
+}
+export interface PassageScores_ScoresEntry {
+    key: string;
+    value: number;
+}
+/** List of field values — supports multi-value fields (e.g. multiple URIs per document) */
+export interface FieldValueList {
+    values: FieldValue[];
+}
+/** Score contribution from a specific ordinal in a multi-valued field */
+export interface OrdinalScore {
+    /** Which value in the multi-valued field (0-indexed) */
+    ordinal: number;
+    /** Score contribution from this ordinal */
+    score: number;
+}
+export interface FieldValue {
+    text?: string | undefined;
+    u64?: number | undefined;
+    i64?: number | undefined;
+    f64?: number | undefined;
+    bytesValue?: Uint8Array | undefined;
+    sparseVector?: SparseVector | undefined;
+    denseVector?: DenseVector | undefined;
+    /** JSON serialized as string */
+    jsonValue?: string | undefined;
+    /** Packed-bit binary vector */
+    binaryDenseVector?: Uint8Array | undefined;
+}
+/** Sparse vector with term indices and weights */
+export interface SparseVector {
+    indices: number[];
+    values: number[];
+}
+/** Dense vector (float32 values) */
+export interface DenseVector {
+    values: number[];
+}
+export interface SearchResponse {
+    hits: SearchHit[];
+    totalHits: number;
+    tookMs: number;
+    timings: SearchTimings | undefined;
+    /**
+     * True when `time_budget_ms` expired before every candidate was scored;
+     * the hits are then the best-so-far, not the exact top-k.
+     */
+    truncated: boolean;
+    /** Feature contracts: "formula_v1" or "feature_export_v2". */
+    rankingMethod: string;
+    /**
+     * Present for FUSION_CANDIDATES. Hits hold hydrated union entries once;
+     * these lists preserve independent branch scores and nominated ordinals.
+     */
+    fusionCandidates: FusionCandidateList[];
+    /** Present only when tracing is requested. */
+    trace: SearchTrace | undefined;
+    /**
+     * Capability 4 acknowledgment, true only when every backend honored the
+     * requested document-only passage seeding policy. Old adapters default false.
+     */
+    seededDocumentPassages: boolean;
+}
+export interface SearchTrace {
+    shards: ShardSearchTrace[];
+}
+export interface ShardSearchTrace {
+    /** Populated by the broker; empty on direct server calls. */
+    shardId: string;
+    backendId: string;
+    indexName: string;
+    queries: QueryTrace[];
+    /** Shard results before broker selection. */
+    selected: FusionCandidate[];
+    rankingMethod: string;
+    truncated: boolean;
+    /** Common fusion filters applied during nomination. */
+    filters: Query[];
+}
+export interface QueryTrace {
+    queryIndex: number;
+    queryName: string;
+    /** Original branch/root expression, including nested clauses. */
+    query: Query | undefined;
+    scope: ScoreScope;
+    scoreOnly: boolean;
+    candidateDepth: number;
+    totalSeen: number;
+    /** All organic nominations within the requested depth, before fusion/L1/L2. */
+    candidates: FusionCandidate[];
+}
+export interface FusionCandidateList {
+    queryIndex: number;
+    candidates: FusionCandidate[];
+}
+export interface FusionCandidate {
+    address: DocAddress | undefined;
+    score: number;
+    ordinalScores: OrdinalScore[];
+}
+/** Detailed timing breakdown for search phases (all values in microseconds) */
+export interface SearchTimings {
+    /** L1 retrieval (query scoring across segments) */
+    searchUs: number;
+    /** L2 reranking (dense vector rescoring) */
+    rerankUs: number;
+    /** Document field loading from store */
+    loadUs: number;
+    /** Wall-clock total (includes overhead) */
+    totalUs: number;
+    /** Missing-only feature backfill and formula selection. */
+    candidateScoringUs: number;
+}
+/** Get document request/response */
+export interface GetDocumentRequest {
+    indexName: string;
+    address: DocAddress | undefined;
+}
+export interface GetDocumentResponse {
+    fields: {
+        [key: string]: FieldValueList;
+    };
+}
+export interface GetDocumentResponse_FieldsEntry {
+    key: string;
+    value: FieldValueList | undefined;
+}
+/** Index info request/response */
+export interface GetIndexInfoRequest {
+    indexName: string;
+}
+export interface GetIndexInfoResponse {
+    indexName: string;
+    numDocs: number;
+    numSegments: number;
+    /** Schema in SDL format */
+    schema: string;
+    /** Memory usage breakdown (if available) */
+    memoryStats: MemoryStats | undefined;
+    /** Per-field vector statistics */
+    vectorStats: VectorFieldStats[];
+    /**
+     * Per text field: how it is tokenized, so clients pick query forms
+     * without parsing the schema SDL.
+     */
+    textFields: TextFieldInfo[];
+    /** 3 requires symbolic L1 formula; preserves organic scores, optional backfill and raw defaults. */
+    candidateScoringVersion: number;
+    /** Fields requiring lookup preparation/migration. */
+    unpreparedCandidateFields: string[];
+    /** Includes tombstones; num_docs counts live rows. */
+    physicalNumDocs: number;
+    numDeletedDocs: number;
+    /** num_deleted_docs / physical_num_docs; zero for an empty index. */
+    deletedRatio: number;
+}
+/** Tokenization facts of one text field. */
+export interface TextFieldInfo {
+    field: string;
+    /** The field uses a `lex(...)` tokenizer. */
+    lexical: boolean;
+    /**
+     * A `lex(by: <field>)` tokenizer: the query's `tokenizer_hint` selects
+     * the stemmer (empty when the field has no hint field).
+     */
+    hintField: string;
+    /**
+     * `lex(variants: true)`: the written word is indexed next to its stem and
+     * folded forms, so one clause per field suffices (phrases match the
+     * written form, match queries the stem).
+     */
+    variants: boolean;
+    /** Token positions are indexed, so phrase queries verify adjacency. */
+    positions: boolean;
+    /** `indexed<chunked>`: every value is its own BM25 unit with an ordinal. */
+    chunked: boolean;
+}
+/** Per-field vector statistics (dense or sparse) */
+export interface VectorFieldStats {
+    fieldName: string;
+    /** "dense" or "sparse" */
+    vectorType: string;
+    totalVectors: number;
+    /** dim for dense, num_dimensions for sparse */
+    dimension: number;
+    /** sparse only: avg postings per vector (0 for dense) */
+    avgTermsPerVector: number;
+}
+/** Memory usage statistics */
+export interface MemoryStats {
+    /** Total estimated memory usage in bytes */
+    totalBytes: number;
+    /** Indexing buffer memory (pending documents not yet flushed) */
+    indexingBuffer: IndexingBufferStats | undefined;
+    /** Segment reader memory (loaded for search) */
+    segmentReader: SegmentReaderStats | undefined;
+}
+/** Indexing buffer memory breakdown */
+export interface IndexingBufferStats {
+    totalBytes: number;
+    postingsBytes: number;
+    sparseVectorsBytes: number;
+    denseVectorsBytes: number;
+    internerBytes: number;
+    positionIndexBytes: number;
+    pendingDocs: number;
+    uniqueTerms: number;
+}
+/**
+ * Segment-reader heap memory (search structures and decompressed caches).
+ * File-backed mappings and pinned residency are intentionally excluded:
+ * mapped file extent is not equivalent to resident memory.
+ */
+export interface SegmentReaderStats {
+    totalBytes: number;
+    termDictCacheBytes: number;
+    storeCacheBytes: number;
+    sparseIndexBytes: number;
+    denseIndexBytes: number;
+    numSegmentsLoaded: number;
+}
+/** Create index request/response */
+export interface CreateIndexRequest {
+    indexName: string;
+    /** Schema definition */
+    schema: string;
+}
+export interface CreateIndexResponse {
+    success: boolean;
+}
+/** Field entry for multi-value field support */
+export interface FieldEntry {
+    name: string;
+    value: FieldValue | undefined;
+}
+/**
+ * Named document for batch indexing
+ * Uses repeated FieldEntry to support multi-value fields (same name, multiple values)
+ */
+export interface NamedDocument {
+    fields: FieldEntry[];
+}
+/** Batch index documents request */
+export interface BatchIndexDocumentsRequest {
+    indexName: string;
+    documents: NamedDocument[];
+}
+export interface BatchIndexDocumentsResponse {
+    indexedCount: number;
+    errorCount: number;
+    errors: DocumentError[];
+}
+/**
+ * Requests are bounded before conversion or writer admission. Both require a
+ * primary-key schema and an explicit Commit. No cross-partition transaction.
+ */
+export interface DeleteDocumentsRequest {
+    indexName: string;
+    /** <=100,000 keys, <=8 MiB total key bytes */
+    primaryKeys: string[];
+}
+export interface UpsertDocumentsRequest {
+    indexName: string;
+    /** <=1,000 documents, <=32 MiB encoded request (<=200 MiB for one document) */
+    documents: NamedDocument[];
+}
+export interface DocumentMutationResponse {
+    /**
+     * Admitted operations, not affected rows. A missing deletion is accepted.
+     * Every input is accepted or has one error; Commit publishes accepted work.
+     */
+    acceptedCount: number;
+    errors: DocumentError[];
+}
+/** Per-document error detail (e.g. duplicate primary key) */
+export interface DocumentError {
+    /** 0-based index in the request batch */
+    index: number;
+    /** Human-readable error message */
+    error: string;
+}
+/** Index document request/response */
+export interface IndexDocumentRequest {
+    indexName: string;
+    fields: FieldEntry[];
+}
+export interface IndexDocumentsResponse {
+    indexedCount: number;
+    errors: DocumentError[];
+}
+/** Commit request/response */
+export interface CommitRequest {
+    indexName: string;
+}
+export interface CommitResponse {
+    success: boolean;
+    numDocs: number;
+}
+/** Force merge request/response */
+export interface ForceMergeRequest {
+    indexName: string;
+    /**
+     * Expensive physical removal of deleted rows, once per final output.
+     * Omitted/false copies encoded data and carries deletion masks unchanged.
+     */
+    compact: boolean;
+}
+export interface ForceMergeResponse {
+    success: boolean;
+    numSegments: number;
+}
+/** Delete index request/response */
+export interface DeleteIndexRequest {
+    indexName: string;
+}
+export interface DeleteIndexResponse {
+    success: boolean;
+}
+/** List indexes request/response */
+export interface ListIndexesRequest {
+}
+export interface ListIndexesResponse {
+    indexNames: string[];
+}
+/** Retrain vector index request/response */
+export interface RetrainVectorIndexRequest {
+    indexName: string;
+}
+export interface RetrainVectorIndexResponse {
+    success: boolean;
+}
+export interface AlterVectorIndexRequest {
+    indexName: string;
+    fieldName: string;
+    /**
+     * SDL field type/options, for example:
+     * dense_vector<768, f16> [indexed<scann, tree_levels: 2, nprobe: 1024>]
+     */
+    fieldSchema: string;
+}
+export interface AlterVectorIndexResponse {
+    publicationGeneration: number;
+    state: VectorIndexAlterState;
+}
+/** Reorder request/response */
+export interface ReorderRequest {
+    indexName: string;
+}
+export interface ReorderResponse {
+    success: boolean;
+    numSegments: number;
+}
+export declare const Query: MessageFns<Query>;
+export declare const WeightedQuery: MessageFns<WeightedQuery>;
+export declare const FusionQuery: MessageFns<FusionQuery>;
+export declare const L1Ranking: MessageFns<L1Ranking>;
+export declare const L1Ranking_MissingValuesEntry: MessageFns<L1Ranking_MissingValuesEntry>;
+export declare const ScoreExport: MessageFns<ScoreExport>;
+export declare const SparseVectorQuery: MessageFns<SparseVectorQuery>;
+export declare const DenseVectorQuery: MessageFns<DenseVectorQuery>;
+export declare const BinaryDenseVectorQuery: MessageFns<BinaryDenseVectorQuery>;
+export declare const TermQuery: MessageFns<TermQuery>;
+export declare const BooleanQuery: MessageFns<BooleanQuery>;
+export declare const BoostQuery: MessageFns<BoostQuery>;
+export declare const AllQuery: MessageFns<AllQuery>;
+export declare const RangeQuery: MessageFns<RangeQuery>;
+export declare const MatchQuery: MessageFns<MatchQuery>;
+export declare const PhraseQuery: MessageFns<PhraseQuery>;
+export declare const PrefixQuery: MessageFns<PrefixQuery>;
+export declare const Reranker: MessageFns<Reranker>;
+export declare const SearchRequest: MessageFns<SearchRequest>;
+export declare const GetTextStatsRequest: MessageFns<GetTextStatsRequest>;
+export declare const GetTextStatsResponse: MessageFns<GetTextStatsResponse>;
+export declare const TextStats: MessageFns<TextStats>;
+export declare const TextFieldStats: MessageFns<TextFieldStats>;
+export declare const TermDocFreq: MessageFns<TermDocFreq>;
+export declare const DocAddress: MessageFns<DocAddress>;
+export declare const SearchHit: MessageFns<SearchHit>;
+export declare const SearchHit_FieldsEntry: MessageFns<SearchHit_FieldsEntry>;
+export declare const RrfContribution: MessageFns<RrfContribution>;
+export declare const CandidateScores: MessageFns<CandidateScores>;
+export declare const CandidateScores_DocumentEntry: MessageFns<CandidateScores_DocumentEntry>;
+export declare const PassageScores: MessageFns<PassageScores>;
+export declare const PassageScores_ScoresEntry: MessageFns<PassageScores_ScoresEntry>;
+export declare const FieldValueList: MessageFns<FieldValueList>;
+export declare const OrdinalScore: MessageFns<OrdinalScore>;
+export declare const FieldValue: MessageFns<FieldValue>;
+export declare const SparseVector: MessageFns<SparseVector>;
+export declare const DenseVector: MessageFns<DenseVector>;
+export declare const SearchResponse: MessageFns<SearchResponse>;
+export declare const SearchTrace: MessageFns<SearchTrace>;
+export declare const ShardSearchTrace: MessageFns<ShardSearchTrace>;
+export declare const QueryTrace: MessageFns<QueryTrace>;
+export declare const FusionCandidateList: MessageFns<FusionCandidateList>;
+export declare const FusionCandidate: MessageFns<FusionCandidate>;
+export declare const SearchTimings: MessageFns<SearchTimings>;
+export declare const GetDocumentRequest: MessageFns<GetDocumentRequest>;
+export declare const GetDocumentResponse: MessageFns<GetDocumentResponse>;
+export declare const GetDocumentResponse_FieldsEntry: MessageFns<GetDocumentResponse_FieldsEntry>;
+export declare const GetIndexInfoRequest: MessageFns<GetIndexInfoRequest>;
+export declare const GetIndexInfoResponse: MessageFns<GetIndexInfoResponse>;
+export declare const TextFieldInfo: MessageFns<TextFieldInfo>;
+export declare const VectorFieldStats: MessageFns<VectorFieldStats>;
+export declare const MemoryStats: MessageFns<MemoryStats>;
+export declare const IndexingBufferStats: MessageFns<IndexingBufferStats>;
+export declare const SegmentReaderStats: MessageFns<SegmentReaderStats>;
+export declare const CreateIndexRequest: MessageFns<CreateIndexRequest>;
+export declare const CreateIndexResponse: MessageFns<CreateIndexResponse>;
+export declare const FieldEntry: MessageFns<FieldEntry>;
+export declare const NamedDocument: MessageFns<NamedDocument>;
+export declare const BatchIndexDocumentsRequest: MessageFns<BatchIndexDocumentsRequest>;
+export declare const BatchIndexDocumentsResponse: MessageFns<BatchIndexDocumentsResponse>;
+export declare const DeleteDocumentsRequest: MessageFns<DeleteDocumentsRequest>;
+export declare const UpsertDocumentsRequest: MessageFns<UpsertDocumentsRequest>;
+export declare const DocumentMutationResponse: MessageFns<DocumentMutationResponse>;
+export declare const DocumentError: MessageFns<DocumentError>;
+export declare const IndexDocumentRequest: MessageFns<IndexDocumentRequest>;
+export declare const IndexDocumentsResponse: MessageFns<IndexDocumentsResponse>;
+export declare const CommitRequest: MessageFns<CommitRequest>;
+export declare const CommitResponse: MessageFns<CommitResponse>;
+export declare const ForceMergeRequest: MessageFns<ForceMergeRequest>;
+export declare const ForceMergeResponse: MessageFns<ForceMergeResponse>;
+export declare const DeleteIndexRequest: MessageFns<DeleteIndexRequest>;
+export declare const DeleteIndexResponse: MessageFns<DeleteIndexResponse>;
+export declare const ListIndexesRequest: MessageFns<ListIndexesRequest>;
+export declare const ListIndexesResponse: MessageFns<ListIndexesResponse>;
+export declare const RetrainVectorIndexRequest: MessageFns<RetrainVectorIndexRequest>;
+export declare const RetrainVectorIndexResponse: MessageFns<RetrainVectorIndexResponse>;
+export declare const AlterVectorIndexRequest: MessageFns<AlterVectorIndexRequest>;
+export declare const AlterVectorIndexResponse: MessageFns<AlterVectorIndexResponse>;
+export declare const ReorderRequest: MessageFns<ReorderRequest>;
+export declare const ReorderResponse: MessageFns<ReorderResponse>;
+/** Search service */
+export type SearchServiceDefinition = typeof SearchServiceDefinition;
+export declare const SearchServiceDefinition: {
+    readonly name: "SearchService";
+    readonly fullName: "summa.SearchService";
+    readonly methods: {
+        /** Search for documents */
+        readonly search: {
+            readonly name: "Search";
+            readonly requestType: MessageFns<SearchRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<SearchResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Get document by ID */
+        readonly getDocument: {
+            readonly name: "GetDocument";
+            readonly requestType: MessageFns<GetDocumentRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<GetDocumentResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Get index info */
+        readonly getIndexInfo: {
+            readonly name: "GetIndexInfo";
+            readonly requestType: MessageFns<GetIndexInfoRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<GetIndexInfoResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /**
+         * Text statistics (document frequencies, corpus sizes, average lengths)
+         * of the BM25 terms of a query over this backend's index. A broker that
+         * scatters one index over several shards sums the responses and sends the
+         * total back as `SearchRequest.text_stats`, so every shard scores with
+         * the same IDF.
+         */
+        readonly getTextStats: {
+            readonly name: "GetTextStats";
+            readonly requestType: MessageFns<GetTextStatsRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<GetTextStatsResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+    };
+};
+/** Index service */
+export type IndexServiceDefinition = typeof IndexServiceDefinition;
+export declare const IndexServiceDefinition: {
+    readonly name: "IndexService";
+    readonly fullName: "summa.IndexService";
+    readonly methods: {
+        /** Create a new index (supports both structured schema and SDL string) */
+        readonly createIndex: {
+            readonly name: "CreateIndex";
+            readonly requestType: MessageFns<CreateIndexRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<CreateIndexResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Add documents to index (streaming) */
+        readonly indexDocuments: {
+            readonly name: "IndexDocuments";
+            readonly requestType: MessageFns<IndexDocumentRequest>;
+            readonly requestStream: true;
+            readonly responseType: MessageFns<IndexDocumentsResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Add documents in batch */
+        readonly batchIndexDocuments: {
+            readonly name: "BatchIndexDocuments";
+            readonly requestType: MessageFns<BatchIndexDocumentsRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<BatchIndexDocumentsResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Stage whole-document deletions by exact primary key, including every chunk. */
+        readonly deleteDocuments: {
+            readonly name: "DeleteDocuments";
+            readonly requestType: MessageFns<DeleteDocumentsRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<DocumentMutationResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Stage complete replacements (inserts if absent). Commit publishes them. */
+        readonly upsertDocuments: {
+            readonly name: "UpsertDocuments";
+            readonly requestType: MessageFns<UpsertDocumentsRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<DocumentMutationResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Commit pending changes */
+        readonly commit: {
+            readonly name: "Commit";
+            readonly requestType: MessageFns<CommitRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<CommitResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Force merge segments */
+        readonly forceMerge: {
+            readonly name: "ForceMerge";
+            readonly requestType: MessageFns<ForceMergeRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<ForceMergeResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Run bounded text, BMP, Seismic, and binary ANN layout maintenance */
+        readonly reorder: {
+            readonly name: "Reorder";
+            readonly requestType: MessageFns<ReorderRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<ReorderResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Delete an index */
+        readonly deleteIndex: {
+            readonly name: "DeleteIndex";
+            readonly requestType: MessageFns<DeleteIndexRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<DeleteIndexResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** List all indexes */
+        readonly listIndexes: {
+            readonly name: "ListIndexes";
+            readonly requestType: MessageFns<ListIndexesRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<ListIndexesResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Retrain global vector codebooks and atomically rebuild every ANN segment */
+        readonly retrainVectorIndex: {
+            readonly name: "RetrainVectorIndex";
+            readonly requestType: MessageFns<RetrainVectorIndexRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<RetrainVectorIndexResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** Atomically replace one vector field's IVF/ScaNN algorithm or parameters */
+        readonly alterVectorIndex: {
+            readonly name: "AlterVectorIndex";
+            readonly requestType: MessageFns<AlterVectorIndexRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns<AlterVectorIndexResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+    };
+};
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create(base?: DeepPartial<T>): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+export {};
+//# sourceMappingURL=summa.d.ts.map