backends.Capability

What a backend can do.

Usage

backends.Capability

The first four flags are cumulative tiers (see Tier and tier_of); the rest are orthogonal refinements the engine and the docs use to explain behavior.

Attributes

Name	Description
ADDRESSABLE	A recorded state can be read back later without a native ref.
ATOMIC_REF	Pins have create-if-absent semantics.
BRANCH_IS_STORAGE	Deleting a branch reclaims its data immediately (Neon); `gc` never
CHEAP_FINGERPRINT	Fingerprints are metadata-only; no heavy connection is opened.
CONDITIONAL_REF	fork (and promote / merge, where declared) honour `expected` in
CREATE	Can make an empty store at a locator, mark it as tether’s, tell when
DIFF	Can describe what changed between two recorded states.
FINGERPRINT	Can read the current state (drift detection). Every backend has this.
FORK	Can create a writable branch off a pin.
HISTORY	Can list the system’s native history (ObjectBackend.history).
MERGE	Can three-way merge a working branch into the base branch
NEEDS_QUIESCENCE	commit should check for active writers first.
NONE	No capabilities.
PIN	Can create and delete a durable, GC-proof native ref for a state.
PROMOTE	Can fast-forward the base branch to a working branch’s head
RETENTION_BOUND	Recorded/pinned states expire with the system’s retention window.

ADDRESSABLE

A recorded state can be read back later without a native ref.

ADDRESSABLE=auto()

ATOMIC_REF

Pins have create-if-absent semantics.

ATOMIC_REF=auto()

BRANCH_IS_STORAGE

Deleting a branch reclaims its data immediately (Neon); gc never

BRANCH_IS_STORAGE=auto()

deletes such a working branch without force_prune.

CHEAP_FINGERPRINT

Fingerprints are metadata-only; no heavy connection is opened.

CHEAP_FINGERPRINT=auto()

CONDITIONAL_REF

fork (and promote / merge, where declared) honour expected in

CONDITIONAL_REF=auto()

one step the system makes atomic – git’s update-ref with an old value, Icechunk’s from_snapshot_id on object stores – so a concurrent writer is refused, never overwritten. Without it a backend that takes expected compares the head just before the move (check_expected), and a write in between can slip through; one that does not take it moves unconditionally, and the engine warns (see fork_ref). The conformance suite fails a backend that declares this and ignores expected.

CREATE

Can make an empty store at a locator, mark it as tether’s, tell when

CREATE=auto()

nothing but tether’s own refs remain in it, and remove it (ObjectBackend.create / owner / is_ref_empty / delete_store). Experimental: the feature built on it (add --create, gc --delete-stores; tether.experimental.lifecycle) is the one tether operation with no repair, and has not yet run against real resources.

DIFF

Can describe what changed between two recorded states.

DIFF=auto()

FINGERPRINT

Can read the current state (drift detection). Every backend has this.

FINGERPRINT=auto()

FORK

Can create a writable branch off a pin.

FORK=auto()

HISTORY

Can list the system’s native history (ObjectBackend.history).

HISTORY=auto()

MERGE

Can three-way merge a working branch into the base branch

MERGE=auto()

(ObjectBackend.merge), raising MergeConflict when it cannot.

NEEDS_QUIESCENCE

commit should check for active writers first.

NEEDS_QUIESCENCE=auto()

NONE

No capabilities.

NONE=0

Can create and delete a durable, GC-proof native ref for a state.

PIN=auto()

PROMOTE

Can fast-forward the base branch to a working branch’s head

PROMOTE=auto()

(ObjectBackend.promote).

RETENTION_BOUND

Recorded/pinned states expire with the system’s retention window.

RETENTION_BOUND=auto()