omnigraph/vendor/lance-table/protos/AGENTS.md

# Protobuf Guidelines

Also see [root AGENTS.md](../AGENTS.md) for cross-language standards.

## Compatibility

- All changes must be backwards compatible. Never re-use or change field numbers of existing fields.

## Schema Design

- Use `optional` when you need to distinguish "not set" from "zero value" — `optional` enables presence tracking (`has_*` methods) and maps to `Option<T>` in Rust. Bare proto3 fields have no presence semantics: they always hold a value (defaulting to zero), so you cannot tell if the sender explicitly set them.
- Use structured message types (e.g., `BasePath`) instead of plain scalars, and scope fields to operation-specific messages (e.g., `InsertTransaction`) rather than generic top-level ones.
- Don't duplicate data across messages — store each fact once and derive relationships. Prefer parallel sequences over maps when keys already exist in another field.

## Documentation

- Document the semantic meaning of both present and absent states for `optional` fields — explain when each case applies.
- Use precise domain terminology in field descriptions — avoid ambiguous abbreviations or terms that collide with domain concepts.
fix(deps): vendor lance-table 7.0.0 + lance#7480 so merge-updated tables survive filtered reads after deletes iss-merge-rowid-overlap-corrupts-filtered-reads / lance#7444: an update-style merge_insert over a merge-written fragment legally reuses the updated rows' stable row ids (row-id-lineage spec: updates preserve _rowid) while the superseded fragment keeps its full sequence plus a deletion vector. A later delete leaves the overlapping id range sparsely tiled, and lance-table 7.0.0's RowIdIndex::new asserted dense tiling — failing every filtered read that builds the id→address map ("Wrong range" debug assert; "all columns in a record batch must have the same length" or a silently-wrong batch in release). The upstream fix (lance#7480, merged 2026-07-01) landed hours AFTER v8.0.0 was cut, so no release ≤ 8.0.0 carries it. Consume it now as a vendored pin: vendor/lance-table is the pristine published 7.0.0 source plus ONLY the #7480 rowids/index.rs hunk (drop the false tiling assert; hard-error on the true invariant — one live id claimed by two fragments) and upstream's regression unit test, wired via [patch.crates-io]. The fix is read-side only, so already-written graphs become readable as-is — no data repair. Removal condition (see vendor/lance-table/README.omnigraph.md): drop the vendor dir + patch entry at the first Lance bump whose lance-table ships lance#7480 (9.0.0, or a backported 8.0.1). The surface guard filtered_scan_tolerates_merge_update_row_id_overlap keeps that honest in both directions. Turns the previous commit's red tests green. Full workspace gate passes (cargo test --workspace --locked --no-fail-fast, 68 suites). 2026-07-02 02:17:25 +03:00			`# Protobuf Guidelines`

			`Also see [root AGENTS.md](../AGENTS.md) for cross-language standards.`

			`## Compatibility`

			`- All changes must be backwards compatible. Never re-use or change field numbers of existing fields.`

			`## Schema Design`

			- Use `optional` when you need to distinguish "not set" from "zero value" — `optional` enables presence tracking (`has_*` methods) and maps to `Option<T>` in Rust. Bare proto3 fields have no presence semantics: they always hold a value (defaulting to zero), so you cannot tell if the sender explicitly set them.
			- Use structured message types (e.g., `BasePath`) instead of plain scalars, and scope fields to operation-specific messages (e.g., `InsertTransaction`) rather than generic top-level ones.
			`- Don't duplicate data across messages — store each fact once and derive relationships. Prefer parallel sequences over maps when keys already exist in another field.`

			`## Documentation`

			- Document the semantic meaning of both present and absent states for `optional` fields — explain when each case applies.
			`- Use precise domain terminology in field descriptions — avoid ambiguous abbreviations or terms that collide with domain concepts.`