Module storage_layer 

Storage trait surface — MR-793.

TableStorage is the engine-internal trait that exposes the staged-write primitives (stage_append, stage_merge_insert, stage_overwrite, stage_create_btree_index, stage_create_inverted_index) plus commit_staged as the canonical way for new engine writers to advance Lance HEAD without coupling “write bytes” with “advance HEAD” in one Lance API call.

Transitional residuals on the trait

Several inline-commit methods remain on the trait surface as documented residuals: delete_where (Lance 4.0.0’s DeleteJob is pub(crate) — see #6658), create_vector_index (segment-commit-path requires build_index_metadata_from_segments which is pub(crate) — see #6666), and the legacy append_batch / merge_insert_batches / overwrite_batch / create_btree_index / create_inverted_index paths kept while engine call sites finish migrating off of them (Phase 1b / Phase 9 of MR-793). These are named honestly at every call site; the forbidden-API guard test catches direct lance::* misuse outside the storage layer.

Sealed

TableStorage: sealed::Sealed. Only types in this crate can implement the trait, so a downstream crate cannot subvert the contract by providing its own impl.

Opaque handles

SnapshotHandle and StagedHandle wrap lance::Dataset and StagedWrite respectively. Their inner Lance types are pub(crate) — engine code outside table_store cannot reach through. This is the §III.9 alignment: lance::Dataset does not appear in trait signatures.

Migration status (MR-793 PR #70)

Phases 1a / 2 / 4 / 5 / 6 are landed: trait scaffolding, three new staged primitives (stage_overwrite, scalar index staging), and migration of ensure_indices, branch_merge, schema_apply onto the staged surface. Phase 1b (call-site conversion to Arc<dyn TableStorage>), Phase 9 (demote unused inline-commit methods to pub(crate)), Phase 7 (recovery reconciler — MR-847), and Phase 8 (index reconciler — MR-848) are deferred to follow-ups.

Structs

SnapshotHandle

Opaque handle to a snapshot of a single sub-table dataset at a specific version.

StagedHandle

Opaque handle to a staged Lance transaction (data write or scalar index build) that has not yet advanced HEAD.

Traits

TableStorage

Engine-internal trait covering every Lance dataset operation an omnigraph engine call site might perform.