Skip to main content

Core concepts

This page defines the terms used throughout the docs.

Session​

A session is the primary unit of work in AetherFS.

A session gives you an isolated filesystem and a unit of lifecycle management. Most API calls and most Aether CLI workflows are scoped to a session.

You can think of a session as a working copy with additional system-managed state.

Underlay or source​

A session can start from a source.

A source is the initial content or baseline that the session is created from. Depending on the product flow, a source may represent a repository, a snapshot, a template, or another upstream content root.

Users generally care about two things:

  • Which source a session was created from.
  • Whether the session is still aligned with that source.

Mutable overlay​

Once a session exists, changes happen inside that session’s working filesystem. The important product behavior is simple:

  • The source provides the starting point.
  • The session holds the working changes.
  • Persistence operations decide what should be kept or promoted.

Checkpoint​

A checkpoint is a named or identifiable saved state of a session.

Use checkpoints when you want a recoverable milestone without implying a final published result.

Typical uses:

  • Save a known-good state before a large edit.
  • Capture progress before handoff to another reviewer.
  • Restore a workspace after a failed experiment.

Commit​

A commit is a persistence action that records a session outcome in a durable way.

Use commits when the work is no longer just a temporary workspace state and should be treated as a preserved result.

Depending on the product flow, commits may be used for:

  • Capturing finalized changes.
  • Shipping changes into a downstream system.
  • Recording a durable outcome that can be referenced later.

Fork​

A fork creates a new session from an existing one.

Use a fork when you need:

  • Parallel experimentation.
  • Separate review branches.
  • A new session for a different person or agent.
  • A clean boundary between “current work” and “next attempt.”

Manifest​

A manifest is a structured listing of filesystem state for a session or a subtree.

You typically use manifest-style APIs to:

  • Enumerate files and directories.
  • Inspect metadata without downloading content.
  • Build tree browsers.
  • Detect changes or compare states.

CAS hash or content hash​

Some public APIs expose content hashes or CAS extents.

A content hash is mainly useful when a client needs to know whether it is still looking at the exact bytes it expects.

Use it for things like:

  • stale-write protection
  • verification
  • exact content comparison without rereading the whole file

CAS extents are more specialized.

They describe which byte ranges of a file are already backed by hashed content chunks, so advanced clients can:

  • plan sparse or partial writes
  • reuse existing byte ranges
  • avoid re-uploading content during sync or transfer flows

Most users do not need to think about extents at all.

The point of exposing these fields is to let advanced clients do safer and cheaper byte-level workflows, not to make users learn the internal storage model.

Optimistic concurrency​

Many write operations use an expected hash or similar guard.

That means the system lets you say, in effect, “apply this only if the file or session is still in the state I think it is.”

Use this pattern when:

  • Multiple actors may modify the same session.
  • You need safe retries.
  • You want to avoid silent overwrites.

Approval​

Some workflows include explicit approval steps.

Approvals are for human or policy-driven review points where a proposed action, change set, or workflow stage should not proceed automatically.

Annotation​

An annotation is structured metadata attached to a session or path.

Use annotations for:

  • Review notes.
  • Classification.
  • Status marking.
  • Workflow-specific metadata that should travel with the session.

Message bus​

The message bus is a session-scoped communication surface.

Use it when tools or humans need to exchange events or messages tied to a session without storing them as filesystem content.

Knowledge cache​

The knowledge cache is a session-associated store for structured data that should be retrieved later by key or namespace.

Use it for:

  • Enrichment data.
  • Workflow context.
  • Tool-produced summaries.
  • Derived facts that should outlive a single process.

Health, analytics, and usage​

The platform also exposes non-file signals:

  • Health for current state and availability.
  • Analytics for higher-level observations or summaries.
  • Usage for measuring activity or consumption.

These are separate from filesystem content and should be treated as control or observability data.