Summa protocol

summa.proto is the single wire-contract source for the Summa gRPC server and both maintained clients.

summa-broker.proto is the broker-only control surface (summa.broker.BrokerService: topology and backend inspection). It lives in a separate file precisely so summa.proto — and the generated Python/TypeScript clients CI keeps in lockstep with it — never changes for broker concerns. The broker re-serves summa.proto verbatim.

The protocol exposes:

• SearchService for search, document retrieval by DocAddress, and index metadata;
• IndexService for index creation, document ingestion, primary-key deletion and upserts, commit, merge, reorder, deletion, listing, vector-index retraining, and atomic vector-index alteration;
• recursive text, phrase, range, vector, reranker, and fusion query messages;
• GetTextStats and search statistics overrides for consistent cross-shard BM25;
• repeated FieldEntry/FieldValueList messages for multi-value fields.

Compatibility rules

• Never renumber or reuse a published field number.
• Add fields with new numbers and preserve protobuf defaults for older clients.
• Keep document identity as the complete DocAddress (segment_id plus segment-local doc_id).
• Treat generated Python and TypeScript files as build outputs: change this schema, then regenerate them rather than editing stubs by hand.

Regeneration and validation

From the repository root:

cd summa-client-python
uv run --locked --group dev python generate_proto.py

cd ../summa-client-typescript
pnpm install --frozen-lockfile
pnpm run generate
pnpm test

CI regenerates both clients and fails if their checked-in bindings differ from this schema. Rust server bindings are generated by summa-server/build.rs during Cargo builds.

Document mutations

DeleteDocuments stages whole-document deletion by exact text primary key, including every indexed chunk. UpsertDocuments stages full replacement NamedDocument values and inserts absent keys. Both return DocumentMutationResponse { accepted_count, errors }: accepted operations need an explicit Commit, and errors preserve original batch positions. Deleting a missing key is accepted; accepted count is not a count of removed rows.

Requests are capped at 100,000 deletion keys / 8 MiB of key bytes, or 1,000 replacement documents / 32 MiB of encoded protobuf. A single replacement may use up to 200 MiB, including the complete request envelope; clients must isolate it from ordinary batches. This matches the ingestion client transport ceiling without raising batch concurrency or the server mutation admission limit. Oversized requests fail before conversion, index lookup, or writer admission. The shared Rust validation in mutations.rs is included beside generated bindings in both server and broker. See row deletion for staged replacements, broker routing, cancellation, and publication semantics.

The summa-proto build dependency packages the canonical schemas and shared mutation validation for registry consumers. Server and broker build scripts materialize those sources in their private Cargo output directories before generating bindings; no copy of the protocol is maintained in either adapter.