Skip to main content

Session lifecycle

AetherFS is easiest to understand as a session lifecycle.

1. Create a session​

A workflow starts by creating a session.

Creation usually includes:

  • A source or starting point.
  • Optional labels, tags, or metadata.
  • Optional policy or ownership context.

At this point, the session becomes the workspace that tools and users interact with.

2. Inspect the initial state​

Before changing content, most clients do one or more of the following:

  • Retrieve session metadata.
  • Inspect the manifest or directory tree.
  • Read specific files.
  • Attach a local Aether CLI mount if a filesystem view is needed.

This phase establishes the baseline the workflow will operate on.

3. Make changes​

Changes may come from:

  • A human using mounted files.
  • An automated workflow using API calls.
  • An agent producing patches or file mutations.
  • A mixed workflow combining local edits and service-side actions.

During this stage, clients often track:

  • File content changes.
  • Directory operations.
  • Annotations or review notes.
  • Bus messages or progress events.
  • Knowledge entries that help downstream tools.

4. Review or coordinate​

Not every session needs formal review, but many real workflows do.

Common review patterns include:

  • Listing changed files before persistence.
  • Recording annotations on specific paths.
  • Publishing status messages to the session bus.
  • Requesting approval for promotion or commit.
  • Forking a session for alternative approaches.

5. Save progress​

When a meaningful milestone is reached, you usually persist it somehow.

Typical options are:

  • Create a checkpoint for recovery.
  • Commit the current session state.
  • Export or archive session content.
  • Sync content into another system using the public API surface.

The right option depends on whether the state is still provisional or intended as a durable outcome.

6. Continue, fork, or restore​

After a save point, the workflow can continue in several directions:

  • Keep working in the same session.
  • Fork the session for parallel work.
  • Restore to a checkpoint.
  • Hand the session to another person or tool.
  • Finalize and retire the session.

7. Close the session​

Sessions are not meant to live forever by default.

When work is complete, the normal next step is to:

  • Keep the durable artifacts you need.
  • Remove or archive the temporary workspace.
  • Retain only the metadata required for audit, support, or workflow continuity.

Lifecycle design guidance​

When you design against AetherFS, model your workflow explicitly around these boundaries:

Creation boundary​

What source and metadata are required to start?

Mutation boundary​

Who can change files, and by which surface?

Review boundary​

Which actions need observation, annotation, or approval?

Persistence boundary​

What counts as a recoverable milestone versus a durable final result?

Retirement boundary​

When is a session no longer useful as a live workspace?

Common lifecycle patterns​

Single-session workflow​

Best for short-lived tasks with one actor and a clear finish.

Fork-and-review workflow​

Best when one session represents the baseline and one or more forks represent alternative proposals.

Checkpoint-heavy workflow​

Best for long-running tasks where recoverability matters more than branching.

Human-in-the-loop workflow​

Best when an automated system prepares work, then a human approves or rejects it before commit or export.