Extension Workflow

Extension Workflow

Use this page when the source data changes over time and you want to keep working from the same backup lineage instead of creating unrelated standalone sets every time.

The Lifecycle

Ethernity’s primary lifecycle is:

1. backup creates the initial standalone root
2. extend appends changes to that root
3. recover restores the latest validated state by default
4. compact turns the current state back into a fresh standalone backup

This is a first-class workflow, not a maintenance trick.

What extend Does

extend appends a new generation under extensions/ inside an existing unsealed backup root.

Use it when:

• the source data changed
• you want to keep the existing backup lineage
• you do not want to create a completely separate standalone set yet

Important constraints:

• the root must be unsealed
• extend is append-only
• recovery defaults to the latest validated state across the whole chain

What compact Does

compact takes a root plus its extensions and writes a fresh standalone backup containing the latest logical state.

Use it when:

• you want a clean standalone set again
• you want to retire replay depth as an operational concern
• you want the next update cycle to start from a fresh root

compact writes a new backup. It does not rewrite the old one in place.

Typical Operator Pattern

Create the initial root:

ethernity backup \
  --input-dir ./docs \
  --output-dir ./backup-root \
  --passphrase "example passphrase"

Append changes later:

ethernity extend \
  --root-dir ./backup-root \
  --input-dir ./docs \
  --base-dir ./docs \
  --passphrase "example passphrase"

Recover the latest state:

ethernity recover \
  --scan ./backup-root \
  --passphrase "example passphrase" \
  --output ./restored-docs

Flatten to a fresh standalone set:

ethernity compact \
  --root-dir ./backup-root \
  --output-dir ./backup-compacted \
  --passphrase "example passphrase"

Selecting An Older State

Normal recovery uses the latest validated state.

If you need an older state:

• --extension-index 0 means root only
• --extension-index N means restore through extension N
• --extension-doc-hash <hex> means restore through the generation with that authenticated hash

Use those selectors only when you actually need an older generation. For routine restores, recover the latest state and validate the result.

When To Use backup Again Instead

Create a new standalone backup instead of extending when:

• you want a separate lineage
• you do not want any relationship to the old root
• the operational meaning of the data set changed enough that a new root is clearer

Use compact when you want continuity of state but a fresh standalone artifact set.

Common Mistakes

• treating extend as a niche or optional feature when the data set is clearly evolving
• trying to extend a sealed root
• forgetting that recovery defaults to the latest validated chain state
• assuming compact rewrites the old root instead of producing a new standalone backup

Related

• Backup Workflow
• Recovery Workflow
• Command Cheatsheet
• FAQ