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.

Inline-commit residuals live on a separate trait

The inline-commit writes that Lance cannot yet express as stage-then-commit are NOT on TableStorage. They sit on [InlineCommitResidual], reachable only via Omnigraph::storage_inline_residual(), so the default db.storage() surface is staged-only and cannot couple “write bytes” with “advance HEAD” — MR-793 acceptance §1 closes by construction. The residuals:

• delete_where — Lance #6658 (DeleteBuilder::execute_uncommitted) did not backport to the 6.x line; it first ships in v7.0.0-beta.10. Migration to staged two-phase delete is tracked as MR-A, gated on the Lance v7.x bump.
• create_vector_index — segment-commit-path needs build_index_metadata_from_segments, still pub(crate) in Lance 6.0.1 (#6666, open). Scalar indices already stage.

Each is named honestly at its call site; the forbidden-API guard test catches direct lance::* misuse outside the storage layer.

Sealed

Both TableStorage and InlineCommitResidual are : sealed::Sealed. Only types in this crate can implement them, 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 aligns with the storage-boundary invariant: lance::Dataset does not appear in trait signatures.

Migration status

Phases 1a / 2 / 4 / 5 / 6 landed in MR-793 PR #70 (trait scaffolding, staged primitives, migration of ensure_indices / branch_merge / schema_apply onto the staged surface). Phase 1b (call-site conversion) and Phase 9 landed in MR-854, which also split the inline-commit residuals onto InlineCommitResidual so db.storage() is staged-only. Phase 7 (recovery reconciler) shipped as MR-847; Phase 8 (index reconciler) is tracked as MR-848.

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.

Enums

ForkOutcome

Outcome of a per-table branch fork (fork_branch_from_state).

Traits

TableStorage

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