## backends.Capability


What a backend can do.


Usage

``` python
backends.Capability
```


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


## Attributes

| Name | Description |
|----|----|
| [ADDRESSABLE](#ADDRESSABLE) | A recorded state can be read back later without a native ref. |
| [ATOMIC_REF](#ATOMIC_REF) | Pins have create-if-absent semantics. |
| [BRANCH_IS_STORAGE](#BRANCH_IS_STORAGE) | Deleting a branch reclaims its data immediately (Neon); `gc` never |
| [CHEAP_FINGERPRINT](#CHEAP_FINGERPRINT) | Fingerprints are metadata-only; no heavy connection is opened. |
| [CONDITIONAL_REF](#CONDITIONAL_REF) | [fork](testing.ObjectBackend.md#tether.testing.ObjectBackend.fork) (and [promote](testing.ObjectBackend.md#tether.testing.ObjectBackend.promote) / [merge](testing.ObjectBackend.md#tether.testing.ObjectBackend.merge), where declared) honour `expected` in |
| [CREATE](#CREATE) | Can make an empty store at a locator, mark it as tether's, tell when |
| [DIFF](#DIFF) | Can describe what changed between two recorded states. |
| [FINGERPRINT](#FINGERPRINT) | Can read the current state (drift detection). Every backend has this. |
| [FORK](#FORK) | Can create a writable branch off a pin. |
| [HISTORY](#HISTORY) | Can list the system's native history ([ObjectBackend.history](testing.ObjectBackend.md#tether.testing.ObjectBackend.history)). |
| [MERGE](#MERGE) | Can three-way merge a working branch into the base branch |
| [NEEDS_QUIESCENCE](#NEEDS_QUIESCENCE) | [commit](vcs.VcsAdapter.md#tether.vcs.VcsAdapter.commit) should check for active writers first. |
| [NONE](#NONE) | No capabilities. |
| [PIN](#PIN) | Can create and delete a durable, GC-proof native ref for a state. |
| [PROMOTE](#PROMOTE) | Can fast-forward the base branch to a working branch's head |
| [RETENTION_BOUND](#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](testing.ObjectBackend.md#tether.testing.ObjectBackend.fork) (and [promote](testing.ObjectBackend.md#tether.testing.ObjectBackend.promote) / [merge](testing.ObjectBackend.md#tether.testing.ObjectBackend.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](testing.ObjectBackend.md#tether.testing.ObjectBackend.create) / [owner](testing.ObjectBackend.md#tether.testing.ObjectBackend.owner) / [is_ref_empty](testing.ObjectBackend.md#tether.testing.ObjectBackend.is_ref_empty) / [delete_store](testing.ObjectBackend.md#tether.testing.ObjectBackend.delete_store)). **Experimental**: the feature built on it (`add --create`, `gc --delete-stores`; [tether.experimental.lifecycle](experimental.lifecycle.md#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](testing.ObjectBackend.md#tether.testing.ObjectBackend.history)).


`HISTORY=auto()`


------------------------------------------------------------------------


#### MERGE


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


`MERGE=auto()`


([ObjectBackend.merge](testing.ObjectBackend.md#tether.testing.ObjectBackend.merge)), raising [MergeConflict](MergeConflict.md#tether.MergeConflict) when it cannot.


------------------------------------------------------------------------


#### NEEDS_QUIESCENCE


[commit](vcs.VcsAdapter.md#tether.vcs.VcsAdapter.commit) should check for active writers first.


`NEEDS_QUIESCENCE=auto()`


------------------------------------------------------------------------


#### NONE


No capabilities.


`NONE=``0`


------------------------------------------------------------------------


#### PIN


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](testing.ObjectBackend.md#tether.testing.ObjectBackend.promote)).


------------------------------------------------------------------------


#### RETENTION_BOUND


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


`RETENTION_BOUND=auto()`