Skip to main content

Source jobs and revisions

Sources and source jobs are the durable-baseline side of AetherFS.

Source lifecycle routes​

Key routes:

  • POST /v1/sources
  • GET /v1/sources
  • GET /v1/sources/{sourceId}
  • POST /v1/sources/{sourceId}/startImport
  • GET /v1/sources/{sourceId}/jobs/{jobId}
  • POST /v1/sources/{sourceId}/refresh
  • POST /v1/sources/{sourceId}/promoteSession

Source kinds​

The public source contract distinguishes kinds such as:

  • git remote
  • uploaded snapshot
  • host-path localfs
  • uploaded git bundle

Users should treat these as different source origins, not as different session types.

Revisions​

Each source may have a latest revision identifier.

That revision is what sessions often anchor to when they start from a source. This is one of the key user-facing guarantees behind repeatability.

Jobs​

Import, refresh, and promotion flows return job objects with states such as:

  • queued
  • running
  • succeeded
  • failed

Treat those as asynchronous workflows. Do not block a UI on the assumption they complete immediately.

Promotion​

Promotion is how a successful session becomes part of a reusable future baseline.

Use promotion when:

  • a reviewed outcome should become the next starting point
  • the result matters beyond one temporary session