Architecture
Understand Airlift's domain module, governed mutation pipeline, workers, adapters, and extension boundaries.
Architecture
Airlift owns the migration lifecycle: estates, objects, waves, readiness, certificates, and cutover decisions. It composes execution, conversion, validation, persistence, and observability through published contracts rather than rebuilding those capabilities.
Request and evidence flow
Specialist tools perform the work. Airlift admits their outputs by immutable reference, checks provenance and policy, and makes the resulting decision traceable. Converter success alone never proves production readiness.
Repository map
| Path | Developer responsibility |
|---|---|
packages/airlift | domain module, governed actions, policies, projections, source profiles, certificate contracts |
packages/cli | authenticated engagement onboarding plus local source planning, diagnostics, catalogs, and certificate verification |
packages/adapter-lakebridge | Databricks job submission and immutable Lakebridge result references |
packages/store | durable event and projection persistence |
apps/airlift-worker | assessment and conversion activities, schedules, cutover workflow, effector seam |
apps/console | Databricks Apps identity boundary and operator workbench |
Source integrations extend narrow adapters. They do not add a parallel database or
mutation API. Start with createSourceMigrationPlan() to discover the commands, actions,
outputs, and evidence expected by a source profile.
Governed domain module
Every externally meaningful state change is an airlift.* Platform action. Handlers
return pending domain events; the host appends them only after schema, authorization,
policy, and state-machine checks pass. This produces one mutation and audit path for the
console, workers, agents, and application integrations.
The event ledger folds into organization-scoped views for inventory, the migration funnel, readiness, waves, conversion attempts, certificates, and audit. Illegal transitions—such as certifying before conversion or recording a cutover before it is authorized—are rejected structurally.
Use the CLI to inspect the installed action surface:
fa actions
fa actions --json > .airlift/action-contract.jsonWorker and durable cutover
The application owns its deterministic Temporal domain workflow. Harness supplies the worker and connection plumbing. Workflow code performs no I/O; activities call adapters and invoke governed actions with stable idempotency keys.
Cutover follows a strict sequence:
- re-read frozen scope, fresh readiness, certificates, and approvals;
- create a durable external checkpoint;
- apply the non-idempotent endpoint change once;
- verify external state independently;
- compensate once when verification proves a failed effect was applied;
- record success/rollback, or leave an uncertain outcome open for reconciliation.
The authenticated airlift.wave_approve action is the only approval authority. Temporal
signals can wake a readiness check but cannot carry actor identity, approval, denial, or
waiver authority.
Extension seams
| Seam | Development implementation | Production implementation |
|---|---|---|
| store | in-memory event store | durable Postgres-compatible store through @fabricorg/airlift/store |
| converter | StubLakebridgeAdapter | version-pinned Lakebridge workspace jobs |
| repair | disabled unless injected | bounded Harness agent producing one reviewable candidate |
| transfer | typed contract driver | source-specific snapshot/incremental driver with checkpoints and reconciliation |
| validation | fixtures or test runner | admitted provider with immutable evidence and snapshot identities |
| cutover | StubCutoverEffector in local mock mode | certified checkpoint/apply-once/verify/compensate implementation |
Ownership boundaries
| Airlift does not implement | Compose instead |
|---|---|
| SQL transpilation | Databricks Lakebridge |
| Temporal connection and worker plumbing | Fabric Harness Temporal package |
| row comparison and test execution | Lakebridge Reconcile or Experiments testkit |
| mutation pipeline and audit storage | Fabric Platform and Platform Host |
| Databricks authentication and clients | Fabric Harness Databricks package |
| general-purpose agent runtime | Fabric Harness |
These boundaries keep source adapters replaceable and prevent a migration project from creating competing definitions of deployment, monitoring, or task state.