# Architecture
# Architecture [#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 [#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 [#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 [#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:
```bash
fa actions
fa actions --json > .airlift/action-contract.json
```
## Worker and durable cutover [#worker-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:
1. re-read frozen scope, fresh readiness, certificates, and approvals;
2. create a durable external checkpoint;
3. apply the non-idempotent endpoint change once;
4. verify external state independently;
5. compensate once when verification proves a failed effect was applied;
6. 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 [#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 [#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.
# Deploy Airlift
# Deploy Airlift [#deploy-airlift]
An Airlift installation has four runtime responsibilities:
| Component | Responsibility | Recommended placement |
| -------------- | -------------------------------------------------------------- | ----------------------------------- |
| console | authenticated migration workbench and governed command ingress | Databricks App |
| durable store | Platform invocation, event, idempotency, and projection state | Lakebase or compatible PostgreSQL |
| migration jobs | Lakebridge assessment and conversion adapters | Databricks Jobs |
| worker | schedules, activities, and the durable cutover workflow | separately operated Temporal worker |
The console is not the worker. Keep interactive request handling separate from durable
orchestration so a console deployment cannot interrupt an active migration workflow.
## Validate the Asset Bundle [#validate-the-asset-bundle]
The repository contains a declarative Databricks Asset Bundle:
```bash
pnpm validate:databricks
databricks bundle validate -t
databricks bundle deploy -t
```
Bundle variables supply environment-specific resource names and references. Do not
commit workspace URLs, access tokens, client secrets, warehouse IDs, database passwords,
or signing keys.
## Configure durable storage [#configure-durable-storage]
Production installations use `AIRLIFT_STORE=postgres`. Bind either a Databricks
Lakebase resource or a compatible PostgreSQL connection, then run schema creation as an
explicit controlled-startup step:
```ts
const store = await createAirliftStoreFromEnv(process.env);
await store.ensureSchema();
```
Schema creation must not happen as an import side effect. Run it once during controlled
startup for both the console and worker composition roots.
## Configure identity and authorization [#configure-identity-and-authorization]
The Databricks App authenticates the workspace user before resolving display labels from
forwarded headers. The application derives actor and organization from authenticated
server context; neither value may come from form data, action parameters, workflow
signals, or CLI flags.
Production startup requires:
* a tenant-scoped authorization directory;
* admitted worker and validation-provider principals;
* Databricks App identity verification;
* an immutable evidence registry;
* an Ed25519 signing key stored through a deployment secret reference.
Use [security configuration](/docs/reference/security) and
[`fa doctor`](/docs/cli/doctor) to validate the configuration shape.
## Configure Lakebridge jobs [#configure-lakebridge-jobs]
Provision assessment and conversion jobs in the target workspace. Airlift records job
run IDs, tool versions, output references, and digests; reports and converted artifacts
remain in workspace-controlled artifact storage.
Required adapter settings include the job IDs, an artifact-volume root, the accepted
Lakebridge version, bounded polling, and stable idempotency tokens. Version drift or
malformed output fails the action instead of producing evidence.
## Configure the Temporal worker [#configure-the-temporal-worker]
Create the worker with Temporal mode and an explicitly injected cutover effector:
```ts
await createAirliftWorker({
mode: 'temporal',
runtime,
effector: cutoverEffector,
});
```
The effector identifies its certified profile, implementation version, and certification
digest, then implements `createCheckpoint`, `applyCutover`, `verifyCutover`, and
`compensateCutover`. Apply and compensation are each attempted once. Unknown outcomes
remain unresolved for reconciliation; they are never converted into success by a retry.
### Production migration-route boundary [#production-migration-route-boundary]
The routed worker composition now exists, but no routed worker is **deployed** by this
repository's default composition root. Route availability is worker capability evidence,
never configuration: the console and authenticated remote API probe the Temporal server
for an active poller on `airlift-routed-v1` whose worker identity carries the exact
organization (`airlift-route-worker::`). Without a matching
poller every start is rejected before a governed request is created or Temporal is
contacted; no environment flag can turn the control on by itself.
A routed worker serves exactly one organization per deployment. It requires Temporal
mode, `AIRLIFT_ROUTE_ORGANIZATION_ID`, the production PostgreSQL store, and the exact
activities `acknowledgeMigrationRouteStartV1`, `runMigrationRouteDiscoveryV1`,
`runMigrationRouteAssessmentV1`, `runMigrationRouteConversionV1`,
`runMigrationRouteTransferV1`, `runMigrationRouteDeploymentV1`,
`runMigrationRouteValidationV1`, `runMigrationRouteCutoverRehearsalV1`,
`completeMigrationRouteV1`, and `failMigrationRouteV1`. The same worker polls a
five-minute `migrationRouteReconcileWorkflow` schedule that owns acknowledgement loss,
lost executions, unknown outcomes, and recorded cancellation requests. Two trusted system
principals must be admitted with the worker-owned `airlift:journey:record` permission:
`svc-airlift-route-worker` owns every route lifecycle action (acknowledgement, progress,
linkage, terminal state, reconciliation), while `svc-airlift-worker` owns the assessment
and conversion actions it invokes. Human route requests and cancellation requests use
the same permission but remain natural-person-only at ingress. Provider credentials and
effectors stay worker-only.
The worker composes real Synapse and SQL Server discovery, assessment, exact conversion,
and exact predecessor-bound transfer, deployment, and validation adapters. The routed
composition fails startup with a precise unavailable list when any consequential adapter
is missing or stubbed. Two production inputs remain named and fail closed: the
credential-backed Synapse/SQL Server provider-binding seam (a deployment must inject it
explicitly) and a certified cutover rehearsal effect, so the cutover stage still rejects
non-production effects. Cancellation has no separate cancel activity: the operator's
governed cancellation request is durable intent, the console cancels the exact workflow,
and the workflow's non-cancellable terminal path — or the reconcile schedule when the
execution is already gone — persists `cancelled`.
Recovery preserves the governed request lifecycle. A request is committed as
`start_pending` before Temporal start; an exact retry may attach only to the same
immutable request in `start_pending` or `running`. A failure or cancellation before
acknowledgement converges to a terminal projection instead of leaving a stranded row.
Deployment is still blocked until the credential-backed provider seam exists and live
certification proves restart, drift, rollback, cleanup-manifest, and delayed-cost-check
behavior on disposable resources.
## Pre-production verification [#pre-production-verification]
Before admitting migration data, prove:
1. authenticated identity and cross-tenant denial;
2. durable write, projection read-back, and idempotent replay;
3. Lakebridge job connectivity, version enforcement, and artifact digest verification;
4. evidence-signing and offline certificate verification;
5. Temporal bundle determinism, query, cancellation, restart, and replay;
6. frozen-scope staleness, timed rehearsal, certified-effector binding, checkpoint,
apply-once, verification, uncertainty, compensation, and rollback behavior;
7. parallel-run, cutover-verification, hypercare, incident, and source-disposition
evidence paths.
See [production readiness](/docs/status) for the reusable acceptance contract.
# TechFabric Airlift developer documentation
# Move your estate to Databricks, with proof [#move-your-estate-to-databricks-with-proof]
TechFabric Airlift runs your migration as one governed job instead of a spreadsheet of
hand-offs. A migration team connects a source estate, inventories it, scopes the work,
builds the Databricks target, moves the data, proves parity, and goes live — and Airlift
records every decision, artifact, and piece of evidence on one policy-enforced ledger so
the speed never costs you the audit.
```text
Connect → Inventory → Scope → Build → Move → Prove → Go-live
↘ Fixes (residue / discrepancies) ↗
```
Speed comes from doing each stage once against a shared, typed inventory. Safety comes
from the proof behind it: nothing reaches Go-live without independent validation evidence
and a migration certificate that is **system-minted and Ed25519-signed**, derived from
recorded evidence — never authored by the caller. What the certificate does and does not
claim is spelled out in the [trust appendix](/docs/parity-certificates).
## Who uses which surface [#who-uses-which-surface]
| You are | Your home | What you do there |
| ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| a migrator | the Airlift Databricks App | run each stage, work the Fixes queue, watch progress and blockers |
| a migration lead or approver | the Airlift Databricks App | freeze scope, approve waves, accept for the business, decide go-live |
| an auditor or sponsor | the App trust view | read certificates, evidence, and the audit export — read-mostly |
| automation or CI | the `fa` CLI and versioned remote API | record diagnostics and evidence under the admitted automation role — never approve, waive, certify, or cut over |
Every surface invokes the same governed actions; the App, CLI, and API never take
different mutation paths.
## Start in the App [#start-in-the-app]
Follow the [App walkthrough](/docs/getting-started/ui-walkthroughs) — annotated,
public synthetic screenshots of one migration from engagement setup through cutover,
each paired with the exact next developer action.
## What Airlift implements under each stage [#what-airlift-implements-under-each-stage]
| Stage | What your project calls or implements | What Airlift records/enforces |
| ---------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Connect / Inventory | source metadata/export adapter or Lakebridge Profiler/Analyzer | run identity, inventory/dependency digests, tool version |
| Build | Lakebridge, entity mapper, pipeline implementation, or stream bootstrap | method, immutable artifacts, residue disposition |
| Move | source-specific snapshot/incremental driver | watermarks, restart checkpoints, lag, counts, reconciliation |
| Prove | Lakebridge Reconcile, Experiments testkit, or admitted external runner | provider run, immutable evidence, readiness observation |
| Go-live | client-certified checkpoint/apply-once/verify/compensate effector | approvals, separation of duties, freeze digest, rehearsal, operational evidence, durable outcome, rollback, hypercare |
| the certificate itself | no caller implementation | profile-derived, system-minted and Ed25519-signed envelope — see [parity certificates](/docs/parity-certificates) |
## Supported source profiles [#supported-source-profiles]
Airlift ships profiles for warehouses and databases, SAP and SaaS applications, ETL
platforms, mainframe data, federated query engines, and event streams. Every profile
publishes evidence-derived support alongside separate non-evidentiary implementation routing. An
empty tenant registry is always `cataloged`, regardless of shipped implementation paths.
Run
`fa source inspect ` to see the exact boundary, then open
[source systems](/docs/sources) for developer routes.
## The governed programming model [#the-governed-programming-model]
Every meaningful state change is an `airlift.*` Platform action. Console handlers,
workers, and agents invoke the same authenticated runtime. Event handlers return pending
domain events; projections build the inventory, funnel, readiness matrix, wave board,
certificate ledger, and audit trail. Agents may propose or record conversion work but
cannot approve, waive, certify, or cut over.
Read [architecture](/docs/architecture) for package boundaries and
[action catalog](/docs/reference/action-catalog) for the exact mutation contract.
## Automation and CLI [#automation-and-cli]
Install the CLI when you need scripted source plans, diagnostics, or evidence admission:
```bash
npm install --global @fabricorg/airlift-cli
fa sources
fa source inspect dynamics_365
fa source plan dynamics_365 \
--variant dynamics_365_finance_operations \
--json > dynamics-finance-plan.json
```
The generated plan covers inventory, code conversion, data movement, orchestration,
security, validation, performance, consumers, cutover, and post-parity modernization.
It names the applicable specialist adapter boundary, the Airlift actions your integration
must invoke, project outputs, and exit criteria.
Use the same registry in application code:
```ts
import {
AIRLIFT_ACTION_IDS,
createSourceMigrationPlan,
resolveSourceSystemProfile,
} from '@fabricorg/airlift';
const source = resolveSourceSystemProfile('d365');
const plan = createSourceMigrationPlan(source.id, {
variant: 'dynamics_365_finance_operations',
});
console.log(source.workloadSurfaces);
console.log(plan.steps.map((step) => step.airliftActions));
console.log(AIRLIFT_ACTION_IDS.assessmentRecord);
```
Continue with the [source developer workflow](/docs/sources/developer-workflow) for the
complete assessment-to-cutover integration.
## Documentation map [#documentation-map]
* [App walkthrough](/docs/getting-started/ui-walkthroughs) — the primary path through one migration.
* [Quickstart](/docs/getting-started/quickstart) — build, test, run, and inspect a plan.
* [CLI command reference](/docs/cli/command-reference) — every implemented command.
* [Cutover commands](/docs/cli/cutover) — frozen scope through hypercare and source disposition.
* [Source systems](/docs/sources) — executable source-specific routes and known gaps.
* [Migration lifecycle](/docs/migration) — how adapters and actions compose by phase.
* [Parity certificates](/docs/parity-certificates) — the certificate honesty model.
* [Operations](/docs/operations) — identity, evidence, recovery, and scale.
* [Integrations](/docs/integrations) — Platform, Harness, Experiments, Runway, Radar, Tower.
* [Reference](/docs/reference) — actions, events, profiles, configuration, and errors.
Use [production readiness](/docs/status) to verify the installation, source profile,
evidence providers, and cutover effector before operating on production data.
# How Airlift works
# How Airlift works [#how-airlift-works]
Airlift does not replace Lakebridge, a data-transfer engine, or a validation runner. It
connects them through a governed migration model so developers can answer four questions
for every object:
1. What is in scope and what depends on it?
2. Which artifact was produced, by which tool generation?
3. Which independent evidence shows that it is ready?
4. Which approved, reversible wave may move it into production?
## The lifecycle [#the-lifecycle]
| Stage | Tool or integration | What Airlift records and enforces |
| --------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| assess | Lakebridge Profiler and Analyzer | source identity, inventory, dependencies, exclusions, complexity, immutable reports |
| plan | target-design and delivery decisions | object ownership, dependency-aware waves, scope freeze, separation of duties |
| convert | Lakebridge plus optional bounded repair | attempts, tool versions, artifact digests, warnings, and residue disposition |
| transfer | project-specific snapshot and incremental driver | watermarks, manifests, lag, restart checkpoints, counts, and reconciliation |
| validate | Lakebridge Reconcile, Experiments, or another admitted provider | provider run, evidence digest, snapshots, verdicts, and readiness observations |
| certify | Airlift policy evaluation | a system-minted signed envelope derived from the active evidence profile |
| cut over | Temporal workflow plus a target-specific effector | approvals, checkpoint, apply-once result, independent verification, and rollback |
| modernize | Databricks-native release work | a separate backlog and validation profile that preserves baseline parity history |
## Assess the complete estate [#assess-the-complete-estate]
The assessment adapter executes Lakebridge against exported source assets and records
the run and immutable outputs. Inventory SQL together with orchestration, external data,
security mappings, and downstream consumers; otherwise a “converted” warehouse can
still fail when its pipelines or reports move.
Use a source profile to generate the applicable commands and outputs:
```bash
fa source inspect synapse
fa source plan synapse
```
## Plan dependency-aware waves [#plan-dependency-aware-waves]
`airlift.wave_plan` and `airlift.wave_assign` group objects into rehearsable units. The
planner, owner, object assignments, validation expectations, and rollback responsibility
remain explicit. Once approved, a wave cannot silently gain new objects.
## Convert without hiding residue [#convert-without-hiding-residue]
Run deterministic conversion first. If policy admits bounded repair, an agent may return
one typed candidate; it cannot approve, certify, waive, or cut over anything. Route every
unsupported construct into one visible lane:
* deterministic conversion;
* bounded repair candidate;
* human engineering;
* governed exclusion.
Both automated and human conversion use `airlift.conversion_start` and
`airlift.conversion_record`, which keeps provenance and funnel state consistent.
## Validate independently [#validate-independently]
Conversion produces a candidate, not proof. Validation providers compare source and
target behavior and write detailed results to immutable storage. Airlift admits the run
reference, digest, snapshots, tool version, and verdict, then links that observation to
one exact object-profile requirement.
A table, stored procedure, pipeline, and report can require different evidence. A passed
table comparison does not certify a failed orchestration path or downstream consumer.
## Mint a certificate from current evidence [#mint-a-certificate-from-current-evidence]
`airlift.migration_certificate_mint` accepts an object identity and expected digests,
not a caller-authored certificate. The handler derives the signed envelope from the
current governed projection and fails on missing, stale, mismatched, or waived evidence
that policy does not permit.
The useful progress metric is therefore the percentage of in-scope objects deployed and
certified against their assigned profile, with provenance and a rollback path—not the
percentage of files that produced output.
## Cut over with durable verification [#cut-over-with-durable-verification]
Before cutover, Airlift rechecks frozen wave scope, fresh certificates, readiness, and
authenticated approvals. The worker then:
1. creates a durable checkpoint;
2. applies the non-idempotent external effect once;
3. verifies the resulting state independently;
4. records success only after verification;
5. leaves uncertainty unresolved for reconciliation rather than guessing.
Rollback is a governed action with its own reason, evidence, and result.
## Preserve an attestable trail [#preserve-an-attestable-trail]
`airlift.evidence_export` assembles the assessment, conversion, validation,
certification, approval, cutover, and rollback history for an object or wave. The export
is content-digested. Signed certificate envelopes can be verified independently with the
Airlift CLI.
This is Airlift's role: migration tools perform specialist work; Airlift makes their
outputs traceable, policy-bound, independently provable, and safe to use in a production
decision.
# Parity and migration certificates
A migration's credibility is decided by one question: *how do you know the converted
object is safe for its intended release?* Airlift answers with two deliberately distinct
artifacts. Keeping them separate prevents “the rows matched” from becoming “the object is
ready to cut over.”
## Parity facet [#parity-facet]
`airlift.parity_certify` records what a particular comparison actually proved. Required
reproducibility fields include the validator generation, validation run, and source and
target snapshots:
```ts
interface ParityCertificate {
evidenceDepth: 'row_count' | 'aggregates' | 'sampled_rows' | 'full_checksum';
rowCountSource: number;
rowCountTarget: number;
aggregateChecksums?: Record;
sampledRowCount?: number;
checksumMatch?: boolean;
toolVersion: string;
validationRunRef: string;
sourceSnapshotAt: string;
targetSnapshotAt: string;
}
```
`airlift.parity_evidence.v1` enforces:
1. **Minimum depth.** An organization can require evidence stronger than row counts.
2. **No overclaiming.** `sampled_rows` requires a sample count; `full_checksum` requires
its verdict; aggregate depths require their checksums.
3. **Freshness.** Source and target snapshots must remain inside policy's evidence
window.
This facet is inspectable evidence. It does not by itself advance the object to the
migration-certified state.
## Readiness profiles [#readiness-profiles]
Every object receives a versioned profile over nine tracks:
* inventory;
* target design;
* code;
* data movement;
* deployment;
* functional parity;
* non-functional behavior;
* business acceptance;
* cutover readiness.
Each requirement is explicitly `required` or `not_applicable`. Evidence can be pending,
passed, failed, stale, or governed by a time-bounded waiver when policy permits it.
Identity, tenant isolation, separation of duties, functional parity, and uncertain
non-idempotent cutover outcomes are not waivable.
Validation runs enter readiness only when:
* the producer principal is admitted for the organization/provider;
* the provider run completed successfully;
* its immutable evidence reference and SHA-256 digest match the admitted registry;
* the artifact digest, source watermark, target snapshot, tool version, and completion
timestamp are present;
* the functional-parity observation resolves to the active parity run.
## System-minted signed envelope [#system-minted-signed-envelope]
`airlift.migration_certificate_mint` accepts no caller-authored certificate payload. A
system principal supplies only the object ID and the expected profile/readiness digests;
the handler derives the envelope from current governed projections and fails closed on
drift.
The envelope binds:
* organization, estate, object, and optional wave;
* profile ID/version/digest and readiness digest;
* artifact digest, source watermark, and target snapshot;
* parity certificate ID and evidence-manifest digest;
* policy revision and tool generations;
* issuer, issue time, signer key ID, signed digest, and Ed25519 signature.
Private keys come from secret-backed deployment configuration. Offline verification uses
the corresponding key-ID/public-key directory. A hash without a valid signature is never
described as signed evidence.
## Stale and revoked state [#stale-and-revoked-state]
Artifact, watermark, target snapshot, profile, readiness, dependency, policy, or release
drift invalidates the certificate's claim. Airlift preserves the old envelope and marks
it stale or revoked; it never deletes history. Sending an object to rework also removes
its active certification from the wave gate.
## Why this is the moat [#why-this-is-the-moat]
Lakebridge and other engines will keep improving conversion. Airlift's independent value
is the versioned answer to what was validated, by whom, against which identities, under
which profile and policy, and with which signature. Conversion produces a candidate;
independent evidence and governed acceptance produce certification.
# Production readiness
# Production readiness [#production-readiness]
Airlift separates installed capability from project readiness. A successful build or
configured connector does not prove that a source estate is safe to migrate.
## Installation checks [#installation-checks]
The installation must prove:
* authenticated actor and organization derivation;
* fail-closed authorization and cross-tenant denial;
* durable event, projection, idempotency, and recovery behavior;
* secret-backed evidence signing and public-key verification;
* Lakebridge job and artifact-store connectivity;
* Temporal workflow replay, cancellation, timeout, and restart behavior.
Run the structural diagnostic first:
```bash
fa doctor --profile production
```
`doctor` validates configuration shape. Connectivity and behavior require integration
and deployment tests.
## Source-profile checks [#source-profile-checks]
For the selected source, retain evidence for:
* accepted inventory, dependencies, exclusions, and source version;
* representative deterministic conversion and residue classification;
* snapshot and incremental transfer, watermark, restart, lag, and reconciliation;
* object-specific functional, data, security, and performance scenarios;
* business-owner acceptance of the selected validation profile.
Generate the source-specific checklist with:
```bash
fa source plan
```
## Automated cutover checks [#automated-cutover-checks]
Do not enable automated cutover until the target-specific effector proves:
1. a durable pre-effect checkpoint;
2. one non-idempotent apply attempt;
3. independent observation of the resulting external state;
4. explicit handling of `verified`, `not_applied`, `failed_applied`, and `uncertain` outcomes;
5. one compensation attempt after a definitively failed applied effect;
6. a frozen scope, timed runbook, passing rehearsal, and unexpired matching effector certification;
7. passing parallel-run evidence and no open incidents.
Projects that do not provide and certify this effector can use an approved manual
procedure while Airlift records scope, approvals, evidence, outcome, and rollback state.
Automated production cutover remains disabled for that project.
## Claim language [#claim-language]
Use precise terms in project documentation:
* **configured** means required settings are present;
* **connected** means the external boundary completed an authenticated smoke test;
* **validated** means the named scenarios produced immutable admitted evidence;
* **certified** means Airlift minted a signed certificate from the active profile;
* **cut over** means the external effect was independently verified and recorded.
Do not use one term as a substitute for another.
## Modernization and value checks [#modernization-and-value-checks]
Before promoting a modernization release, prove that its baseline migration certificate
is still active, the separate Runway deployment reconciled to the intended artifact, the
Experiments comparison passed every functional guardrail and declared outcome metric,
and the promoter is separate from the recommender and decision-maker.
Before publishing measured value to a client, retain at least three scoped observations
and achieve medium or high computed confidence. A new observation makes an earlier
summary stale. Engagement results are not universal product claims.
# Databricks application-kit commands
# Databricks application-kit commands [#databricks-application-kit-commands]
Use `fa application-kit` when a migration or Databricks-native modernization should
produce an operational application, not only tables, pipelines, and dashboards. Airlift
turns the opportunity into a typed delivery and evidence contract. It does not generate a
success claim from a checklist and it does not deploy the release.
An application kit has two layers:
* a shared foundation: Databricks Apps, Lakebase, Unity Catalog, portable runtime
bindings, an immutable release intent, an isolated preview, and a restore rehearsal;
* one or more domain modules: schemas, grants, synthetic fixtures, BDD scenarios, and
module-specific evidence requirements.
## List available modules [#list-available-modules]
```bash
fa application-kit module list
fa application-kit module list --json
```
| Module | Typical application behavior |
| ------------------------- | --------------------------------------------------------------------------------- |
| `customer_intelligence` | customer profiles, consent, governed features, and service workflows |
| `agent_operations` | agent memory, checkpoints, review queues, tool audit, and evaluation handoff |
| `risk_compliance` | alerts, cases, policy retrieval, separation of duties, and decision evidence |
| `intelligent_operations` | assets, work orders, operational scores, alerts, and maintenance workflows |
| `migration_control_plane` | migration scope, conversion, validation, release references, and cutover evidence |
## Initialize a manifest [#initialize-a-manifest]
```bash
fa application-kit init \
--name "Customer operations" \
--module customer_intelligence \
--cloud azure \
> application-kit.json
```
`--cloud` accepts `aws`, `azure`, or `gcp`. The generated manifest uses logical resource
names and opaque references. It never contains a workspace ID, database connection
string, token, or secret value. Every Databricks App runs with a dedicated service
principal whose grants are resolved per environment.
The generated foundation includes:
```json
{
"foundation": {
"databricksApp": true,
"lakebase": true,
"unityCatalog": true,
"declarativeAutomationBundle": true,
"dedicatedServicePrincipal": true,
"runtimeBindings": [
{
"name": "application-state",
"resourceType": "lakebase",
"permission": "write",
"required": true,
"source": "valueFrom"
},
{
"name": "governed-data",
"resourceType": "unity_catalog_schema",
"permission": "read",
"required": true,
"source": "valueFrom"
}
],
"syncedTables": [],
"preview": {
"isolatedBranch": true,
"restoreRequired": true,
"rehearsalRequired": true
}
}
}
```
Add Synced Table contracts when application serving needs governed lakehouse data in
Lakebase. Each row declares a direction, opaque source and target references, business
keys, and a freshness SLO. Airlift records the requirement; the admitted Databricks
adapter and release own materialization.
## Inspect and plan [#inspect-and-plan]
```bash
fa application-kit validate --file application-kit.json
fa application-kit inspect --file application-kit.json
fa application-kit plan \
--file application-kit.json \
--json > application-plan.json
```
The plan is deterministic. It expands each module into required BDD and assurance
scenarios and produces explicit handoffs:
* Fabric Platform: governed application mutations and audit;
* Fabric Harness: bounded agent execution and Databricks transport;
* Fabric Experiments: BDD, A/B, performance, quality, and agent/model evaluations;
* Fabric Runway: bundle validation, preview, deployment, promotion, and rollback;
* Fabric Radar: SLO and operational evidence;
* Fabric Tower: work references only; and
* TechFabric Airlift: application-modernization scope, requirements, and evidence decision.
The plan contains `deploymentCli: "fr"`. There is deliberately no
`fa application-kit deploy` command.
## Qualify evidence [#qualify-evidence]
Without evidence, only the contract can be proven:
```bash
fa application-kit qualify \
--file application-plan.json \
--level contract_only
```
Hermetic qualification requires a passing bundle-validation reference, secret scan,
synthetic-fixture digest, BDD contract, and every required runtime binding:
```bash
fa application-kit qualify \
--file application-plan.json \
--evidence application-evidence.json \
--level hermetic_proven
```
Workspace qualification additionally requires:
* a successful Runway deployment for the qualified artifact digest;
* a passing Experiments execution for that same artifact digest;
* an isolated branch preview and tested restore reference; and
* a healthy Radar observation when the plan declares an operational SLO.
```bash
fa application-kit qualify \
--file application-plan.json \
--evidence application-evidence.json \
--level workspace_proven \
--json > application-qualification.json
```
Digest drift, failed scenarios, missing bindings, or missing required operational
evidence blocks. Airlift stores only provider references and digests; it does not copy
the provider's release, test, or monitoring state.
## Register the immutable plan [#register-the-immutable-plan]
```bash
fa application-kit register \
--file application-plan.json \
--engagement-id \
--estate-id \
--artifact-id \
--idempotency-key
```
Registration invokes governed `airlift.artifact_register` with media type
`application/vnd.fabric.airlift.application-kit+json`. Store the plan body in an
admitted immutable artifact location; Airlift records its reference, digest, producer,
and audit event.
Query only registered application-kit artifacts without filtering the general artifact
ledger yourself:
```bash
fa application-kit list --engagement-id
fa application-kit show --json
```
`module list` is the only module-discovery spelling. Generate the complete current command
surface with `fa commands --json`.
## Execute through the owning products [#execute-through-the-owning-products]
```bash
fr validate --dir generated
fr deploy --dir generated --environment preview
fx apply experiments/
fx report
```
Use Runway for deploy, promote, and rollback. Use Experiments for executable BDD, A/B,
performance, and quality evidence. Application-kit qualification is a read-only Airlift
decision over those foreign results.
See [Operational application modernization](/docs/migration/operational-applications) for
the complete developer lifecycle and proof model.
# Enterprise application-pack commands
# Enterprise application-pack commands [#enterprise-application-pack-commands]
`fa application-pack` is for migrations where the unit of scope is a business object or
data product, not a source table. The executable generation supports SAP Business Data
Cloud and Dynamics 365 / Dataverse.
The compiler carries these requirements with each entity:
* business and alternate keys;
* entity relationships and cardinality;
* snapshot, delta cursor, delete, and restart behavior;
* effective dating and history;
* currency, unit, and hierarchy meaning;
* field-level and row-level authorization;
* privacy classifications;
* business control totals; and
* downstream consumer transitions.
## Create a credential-free manifest [#create-a-credential-free-manifest]
```json
{
"schemaVersion": 1,
"source": {
"system": "dynamics_365_dataverse",
"productVersion": "current",
"snapshotAt": "2030-01-15T12:00:00.000Z",
"connectionRef": "databricks-connection://migration/dataverse"
},
"estate": { "name": "Customer service" },
"entities": [
{
"entityId": "account",
"name": "Account",
"kind": "business_object",
"keys": ["accountid"],
"relationships": [],
"changeBehavior": {
"mode": "managed_connector",
"cursorField": "versionnumber",
"deleteMode": "tombstone",
"effectiveDating": false
},
"semantics": {
"currencyFields": ["revenue"],
"unitFields": [],
"hierarchyFields": ["parentaccountid"],
"controlTotals": ["active_account_count"]
},
"authorization": {
"fieldSecurity": false,
"rowSecurity": false,
"privacyClassifications": ["customer"]
},
"consumers": ["customer-360"],
"sourceFragment": { "logicalName": "account" },
"provenance": {
"sourceRef": "dataverse://metadata/account",
"extractor": "your-dataverse-exporter",
"extractorVersion": "1.0.0",
"observedAt": "2030-01-15T12:00:00.000Z"
},
"unsupportedReasons": []
}
]
}
```
`connectionRef` is an opaque reference. The source adapter or managed connector owns
authentication and ingestion. Airlift does not broker OAuth or store source tokens.
## Inspect and plan [#inspect-and-plan]
```bash
fa application-pack inspect --file application-manifest.json
fa application-pack plan \
--file application-manifest.json \
--json > application-plan.json
```
The plan routes each entity to `deterministic`, `agent_repairable`, or `human_only` and
retains the exact source fragment and provenance digest. It defines the managed-source
checkpoint contract, Experiments validation requirements, Runway deployment handoff,
business-owner acceptance, consumer transitions, and remediation acceptance criteria.
Connector completion is never business-semantic proof. An entity remains blocked when
delete behavior, effective dating, currencies, units, hierarchies, authorization,
control totals, or consumers are unresolved.
## Register [#register]
```bash
fa application-pack register \
--file application-plan.json \
--engagement-id \
--estate-id \
--artifact-id \
--idempotency-key
```
This invokes governed `airlift.artifact_register`. The artifact body remains in your
admitted store; Airlift records the reference, digest, producer generation, and media
type.
SAP S/4HANA, ECC, BW/4HANA, HANA, Datasphere, other Dynamics profiles, Salesforce,
Workday, and ServiceNow remain cataloged profiles. They are not executable application
packs until their source contracts and recurring evidence ship.
# Capability commands
# Capability commands [#capability-commands]
`fa capability` operates the tenant-scoped capability registry. It does not install a
converter, deploy an application, or certify client objects.
## Query [#query]
```bash
fa capability list
fa capability list --source snowflake --variant snowflake_enterprise
fa capability list --source redshift --capability incremental_cdc --json
fa capability list --source synapse --construct merge_statement --artifact-kind source
fa capability show cap_ --json
fa capability matrix --source synapse --variant synapse_dedicated_sql
```
`matrix` overlays active evidence on the installed source profile and prints each
capability's delivery mode, proof level, provider, and provider version. Missing cells are
reported as `unproved`.
Construct filters select registry-v2 cells. Text matrix output lists these cells separately
and states that they do not aggregate into variant proof.
## Mutate through governed actions [#mutate-through-governed-actions]
All lifecycle mutations use a JSON parameter file and a stable idempotency-key prefix:
```bash
fa capability propose --file proposal.json --idempotency-key proposal-v1
fa capability evidence --file evidence.json --idempotency-key evidence-v1
fa capability promote --file promotion.json --idempotency-key promotion-v1
fa capability expire --file expiry.json --idempotency-key expiry-v1
fa capability revoke --file revocation.json --idempotency-key revocation-v1
fa capability reconcile --file reconciliation.json --idempotency-key reconcile-v1
```
The API derives organization and identity from the authenticated principal. Parameter
files cannot select another organization or supply an approving actor.
| Command | Required authority | Result |
| ----------- | --------------------------------- | -------------------------------------------------- |
| `propose` | human operator | proposed source/capability/provider generation |
| `evidence` | admitted system | immutable proof reference and digest |
| `promote` | different human reviewer | active claim at or below proven strength |
| `expire` | admitted system or human operator | inactive time-bounded claim |
| `revoke` | human reviewer | explicitly withdrawn claim |
| `reconcile` | admitted system | matched observation or fail-closed expiry on drift |
See [Capability registry](/docs/sources/capability-registry) for schemas and the proof
ladder.
## Diagnose a source or engagement [#diagnose-a-source-or-engagement]
```bash
fa source doctor snowflake --variant snowflake --level executable
fa source limitations redshift --variant redshift_serverless
fa source certify synapse --variant synapse_dedicated_sql --level certifiable
fa engagement preflight eng_
```
`doctor` and `certify` query active, unexpired tenant evidence and exit with status `1`
when blocked. Their text output includes a reason and next action for each blocker; `--json`
returns the stable diagnosis contract for CI. `source certify` checks whether provider
capabilities are strong enough for the requested outcome; it does not mint a migration certificate. Migration certificates are still
minted only from object-specific admitted validation evidence through `fa certificate
mint`.
An engagement preflight derives its required level from the selected services:
| Engagement service | Capability target |
| -------------------------- | ------------------------------------------- |
| `discovery` | `assessable` |
| `factory_pilot` | `executable` |
| `migration_factory` | `certifiable` |
| `managed_migration_office` | `certifiable` |
| `cutover_assurance` | `cutover_certified` |
| `modernization` | adds an evidenced modernization requirement |
# Catalog commands
# Catalog commands [#catalog-commands]
The CLI exposes two different catalogs:
* `fa sources` describes source-system migration routes and common workload areas;
* `fa profiles` describes object-type evidence requirements used to mint a
certificate.
Do not substitute one for the other. A source profile helps construct the project; a
validation profile is enforced by certificate policy.
## Actions [#actions]
```bash
fa actions
fa actions --json
```
The command reads the installed action definitions and prints action ID, version,
required permissions, policies, and emitted events. Use it to detect documentation or
deployment drift; it does not invoke an action.
## Validation profiles [#validation-profiles]
```bash
fa profiles
fa profiles --json
```
The command prints built-in profile ID/version, object type, canonical SHA-256 digest,
and required readiness tracks. The digest is computed from canonical JSON using the same
function as certificate minting.
Catalog JSON is deterministic and suitable for release manifests or policy review.
See [source planning commands](/docs/cli/sources) for the source catalog.
# Certificate commands
# Certificate commands [#certificate-commands]
## Inspect [#inspect]
```bash
fa certificate inspect migration-certificate.json
```
Inspection validates the envelope schema and reports certificate, organization, estate,
object, wave, profile, issuer, key ID, and computed unsigned-envelope digest. It shows
whether the digest matches the signed digest but does not claim signature validity.
## Verify [#verify]
Create a JSON file that maps key IDs to Ed25519 public PEM values:
```json
{
"airlift-migration-cert-v1": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
}
```
Then verify:
```bash
fa certificate verify migration-certificate.json --keys public-keys.json
```
Without `--keys`, verification reads `AIRLIFT_EVIDENCE_VERIFY_KEYS_JSON`. The command
recomputes canonical content, requires the signed digest to match, selects the declared
key ID, and verifies the Ed25519 signature. Malformed input, tampering, unknown keys, and
invalid signatures return non-zero.
# Command reference
# Command reference [#command-reference]
The examples assume `fa` resolves to the installed CLI. Run `fa help` to print the
same command inventory from the installed generation.
## Global automation options [#global-automation-options]
`--format text|table|json|yaml|jsonl` may appear on any command that produces structured
data. `--json` remains an alias for `--format json`. JSONL emits one item per line when the
result is an array. Human-readable text or tables remain the default.
Use `--file -` to read a JSON manifest or mutation request from stdin. Use
`--correlation-id ` to propagate a trace identifier into a governed mutation and
`--timeout ` to bound remote calls. Neither option can override identity,
organization, policy, or approvals.
Run `fa help ` for focused help, `fa commands --json` for the machine-readable
command contract, and `fa completion bash|zsh|fish` for shell completion. The
[generated command index](/docs/cli/generated-command-index) is built from that same
manifest.
Remote commands require `AIRLIFT_API_URL` and `DATABRICKS_TOKEN`. Mutation commands also
require a stable, non-secret `--idempotency-key` prefix. See [authenticated
automation](/docs/cli/remote-automation) for identity and retry semantics.
Modernization and measurement commands are documented together in
[Modernization and value commands](/docs/cli/modernization-and-value).
Source capability commands and their evidence-authority split are documented in
[Capability commands](/docs/cli/capabilities).
The executable Synapse manifest compiler and governed registration flow are documented
in [Synapse golden-path commands](/docs/cli/synapse).
Executable SQL Server, Snowflake, Redshift, Oracle, Teradata, and Hadoop manifest
compilation, governed registration, and certification are documented in
[migration-pack commands](/docs/cli/migration-packs).
Native ADF import and file generation, plus normalized-manifest routing for SSIS,
PowerCenter, SAS, DataStage, Talend, ODI, dbt, and Airflow, are documented in
[pipeline import and generation](/docs/cli/migration-ir).
Business-semantic SAP BDC and Dataverse compilation is documented in [enterprise
application-pack commands](/docs/cli/application-packs). Existing Databricks estate
modernization is documented in [Databricks-native commands](/docs/cli/databricks-native).
Portable Databricks Apps and Lakebase foundation/module planning, same-digest evidence
qualification, and the `fa` versus `fr` boundary are documented in [application-kit
commands](/docs/cli/application-kits).
Qualification, reusable delivery kits, connector policies, external value claims,
activation evidence, and public-content checks are documented in [delivery and claim
commands](/docs/cli/delivery).
Deployment-access inspection and admitted preflight recording (`fa access`) are documented
in [Databricks access and integrations](/docs/integrations/databricks-access).
Evaluation-candidate freeze, rehearsal, and window inspection (`fa evaluator`) are
documented in [Evaluator readiness](/docs/integrations/evaluator-readiness).
Unity Catalog evidence recording (`fa uc-evidence`) is documented in
[Unity Catalog evidence](/docs/integrations/uc-evidence).
Organization provisioning and retirement are platform-installer-only actions in the
`airlift-platform` tenant; no tenant CLI command exists. See the
[local lifecycle cookbook](/docs/getting-started/local-lifecycle-cookbook).
Parity certification is recorded by the admitted worker through `airlift.parity_certify`;
no caller-authored parity command exists. See [Parity certificates](/docs/parity-certificates).
Waiver requests and approvals are App decision-card surfaces; the CLI deliberately exposes
no waiver subcommand. See [Waivers and staleness](/docs/operations/waivers-and-staleness).
## `fa organization membership set` [#fa-organization-membership-set]
```bash
fa organization membership set \
--file membership-changes.json \
--idempotency-key membership-grant-2026-08
```
Apply governed organization membership grants and revocations through
`airlift.organization_membership_set`. The file holds one tenant-free `changes` array;
the authenticated API derives the organization from the caller's membership. Requires
the `admin` role (`airlift:membership:manage`) and refuses to leave an organization
without an active admin. See
[Organization membership](/docs/reference/organization-membership).
## `fa engagement list|show` [#fa-engagement-listshow]
```bash
fa engagement list
fa engagement show eng_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
```
Query engagements in the organization derived from the authenticated Databricks
principal. There is no organization selection flag.
## `fa engagement preflight` [#fa-engagement-preflight]
```bash
fa engagement preflight eng_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa engagement preflight eng_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
```
Evaluate every scoped source variant against the evidence level implied by the engagement
services. Exit status `1` means the engagement is blocked. The result includes missing or
stale claims, next actions, governed human lanes, and the requested support level.
## `fa engagement create|update` [#fa-engagement-createupdate]
```bash
fa engagement create \
--file engagement.json \
--idempotency-key project-42-create
fa engagement update \
--file engagement-update.json \
--idempotency-key project-42-scope-v2
```
The create file accepts `name`, one or more `services`, `owner`, and optional target
dates, estate IDs, and structured external references. The update file includes
`engagementId` plus at least one changed field. The API validates referenced estates and
rejects edits after scope is frozen.
## `fa engagement activate|freeze` [#fa-engagement-activatefreeze]
```bash
fa engagement activate eng_01ARZ3NDEKTSV4RRFFQ69G5FAV \
--idempotency-key project-42-activate
fa engagement freeze eng_01ARZ3NDEKTSV4RRFFQ69G5FAV \
--idempotency-key project-42-freeze
```
Activation moves a draft scope to active. Freeze computes and records the canonical
scope digest. A frozen engagement rejects later edits.
## `fa connection list|register` [#fa-connection-listregister]
```bash
fa connection list --engagement-id eng_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa connection register \
--file source-binding.json \
--idempotency-key project-42-synapse-binding
```
The registration file contains the engagement ID, display name, direction, capabilities,
and an opaque `credentialRef` such as
`databricks-connection://migration/synapse-metadata`. It never contains a password,
token, private key, or connection string.
## `fa connection verify|retire` [#fa-connection-verifyretire]
```bash
fa connection verify bnd_01ARZ3NDEKTSV4RRFFQ69G5FAV \
--digest aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
--idempotency-key project-42-synapse-verify
fa connection retire bnd_01ARZ3NDEKTSV4RRFFQ69G5FAV \
--reason "Credential rotated" \
--idempotency-key project-42-synapse-retire
```
Verification records an admitted SHA-256 evidence digest and authenticated verifier.
Retirement is terminal for that binding; register a new binding for a rotated reference.
## `fa estate list|show|register` [#fa-estate-listshowregister]
```bash
fa estate list --json
fa estate show est_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa estate register --file estate.json --idempotency-key estate-synapse-1
```
Register a source estate or query the tenant-scoped estate projection. Registration
accepts a source profile ID, owner, environment, priority, and optional opaque connection
reference.
## `fa assessment list|status|start|record|accept|export` [#fa-assessment-liststatusstartrecordacceptexport]
```bash
fa assessment list --estate-id est_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa assessment status asm_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa assessment start --file assessment-start.json --idempotency-key assess-start-1
fa assessment record --file assessment-record.json --idempotency-key assess-record-1
fa assessment accept --file assessment-accept.json --idempotency-key assess-accept-1
fa assessment export --file assessment-export.json --idempotency-key assess-export-1
```
Start and record compose the configured worker/source-adapter lifecycle. Acceptance is a
human decision that binds normalized inventory and accepted dependency digests. Export
returns a content-digested pack containing the accepted assessment, inventory,
dependencies, and applicable plan scenarios.
## `fa inventory list|register` [#fa-inventory-listregister]
```bash
fa inventory list --estate-id est_01ARZ3NDEKTSV4RRFFQ69G5FAV \
--assessment-id asm_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa inventory register --file object.json --idempotency-key object-sales-1
```
Inventory registration normalizes one source object into the governed migration ledger.
Use repeated idempotent calls for objects emitted by an assessment adapter. Filter by
`--assessment-id` whenever an estate has multiple snapshots so results cannot be mixed.
## `fa inventory graph-*` [#fa-inventory-graph-]
```bash
fa inventory graph list --assessment-id asm_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa inventory graph show dpg_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa inventory graph start --file graph-start.json --idempotency-key graph-start-1
fa inventory graph record --file graph-batch.json --idempotency-key graph-batch-1
fa inventory graph accept --file graph-accept.json --idempotency-key graph-accept-1
```
One graph declares its expected edge count. Each record call accepts at most 500 edges.
A human operator accepts the complete graph and Airlift computes its digest and cycle
count.
## `fa plan list|show|compare|generate|select|freeze` [#fa-plan-listshowcomparegenerateselectfreeze]
```bash
fa plan list --engagement-id eng_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa plan compare --engagement-id eng_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa plan show pln_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa plan generate --file plan.json --idempotency-key plan-parity-1
fa plan select pln_01ARZ3NDEKTSV4RRFFQ69G5FAV --idempotency-key plan-select-1
fa plan freeze pln_01ARZ3NDEKTSV4RRFFQ69G5FAV --idempotency-key plan-freeze-1
```
Generation maps accepted objects to Databricks target patterns, topologically groups
candidate waves, detects cycles, and calculates transparent effort/value estimates.
Freeze requires a selected scenario, frozen engagement scope, and no blocking issues.
## `fa wave list` [#fa-wave-list]
```bash
fa wave list
fa wave list --estate-id est_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
```
Query materialized execution waves. Plan candidates remain part of the frozen plan until
the operator materializes execution waves through governed wave actions.
## `fa cutover` and `fa hypercare` [#fa-cutover-and-fa-hypercare]
```bash
fa cutover list
fa cutover status wav_01J00000000000000000000000 --json
fa cutover freeze --file wave-freeze.json --idempotency-key wave-freeze-v1
fa cutover runbook --file runbook.json --idempotency-key runbook-v1
fa cutover rehearse --file rehearsal.json --idempotency-key rehearsal-v1
fa cutover observe --file observation.json --idempotency-key parallel-run-v1
fa cutover certify-effector --file effector.json --idempotency-key effector-v1
fa cutover approve wav_01J00000000000000000000000 --idempotency-key approval-1
fa cutover start wav_01J00000000000000000000000 --window 2030-09-14T02:00Z --reason "Approved production window"
fa cutover workflow-status airlift-v2-wav_
fa hypercare start --file start.json --idempotency-key hypercare-v1
fa hypercare observe --file observation.json --idempotency-key hypercare-observe-1
fa hypercare complete --file decision.json --idempotency-key hypercare-decision-1
fa hypercare decommission --file disposition.json --idempotency-key disposition-1
```
These commands operate Airlift-owned migration cutover policy and its durable workflow.
They do not deploy or promote release artifacts and do not create monitoring state. See
the complete [cutover command reference](/docs/cli/cutover).
## `fa artifact list|show|register` [#fa-artifact-listshowregister]
```bash
fa artifact list --engagement-id eng_01J00000000000000000000000
fa artifact list --object-id obj_01J00000000000000000000000 --json
fa artifact show art_01J00000000000000000000000
fa artifact register --file artifact.json --idempotency-key artifact-v1
```
Query or register immutable artifact references. Registration requires the artifact
store reference, SHA-256 digest, media type, producer generation, and engagement/object
lineage. Artifact bodies and credentials are never uploaded to Airlift.
## `fa conversion list|show|diff` [#fa-conversion-listshowdiff]
```bash
fa conversion list --object-id obj_01J00000000000000000000000
fa conversion show cnv_01J00000000000000000000000 --json
fa conversion diff obj_01J00000000000000000000000 --json
```
Read the conversion-attempt ledger. `diff` returns the same object's ordered attempt
records for comparing method, tool/model/prompt generation, content digests, diagnostic,
and validation reference. Fetch code bodies from the artifact store.
## `fa conversion batch-*` [#fa-conversion-batch-]
```bash
fa conversion batch list --engagement-id eng_01J00000000000000000000000
fa conversion batch show cbh_01J00000000000000000000000 --json
fa conversion batch create --file batch.json --idempotency-key batch-1
fa conversion batch start --file batch-start.json --idempotency-key batch-1-start
fa conversion batch complete --file batch-start.json --idempotency-key batch-1-complete
```
Create an accepted-scope batch, admit worker attempts, and reconcile terminal results.
Completion derives counts and blocks on missing attempts, missing artifact lineage, or
failed objects without residue.
## `fa conversion attempt-*|retry` [#fa-conversion-attempt-retry]
```bash
fa conversion attempt start --file attempt-start.json --idempotency-key object-1-start
fa conversion attempt record --file attempt-result.json --idempotency-key object-1-result
fa conversion retry --file retry-start.json --idempotency-key object-1-retry-2
```
`retry` is an explicit alias for starting another conversion attempt. Use a new stable
key and an eligible `rework` object. Airlift preserves prior attempts.
## `fa residue list|show|create|estimate|assign|resolve|review|cancel` [#fa-residue-listshowcreateestimateassignresolvereviewcancel]
```bash
fa residue list --engagement-id eng_01J00000000000000000000000
fa residue show res_01J00000000000000000000000 --json
fa residue create --file residue.json --idempotency-key residue-1
fa residue estimate --file estimate.json --idempotency-key residue-1-estimate
fa residue assign --file assignment.json --idempotency-key residue-1-assign
fa residue resolve --file resolution.json --idempotency-key residue-1-resolve
fa residue review --file review.json --idempotency-key residue-1-review
fa residue cancel --file cancellation.json --idempotency-key residue-1-cancel
```
Operate the remediation lifecycle. Assignment works directly from an `open` case and,
like review, requires natural-person authority. `estimate` is optional delivery-planning
metadata; it is not required before assignment. Resolution requires an artifact from the
same object plus a validation evidence reference. The resolver cannot review the same
case. In the App, cancellation is disclosed separately and requires a reason plus explicit
confirmation.
## `fa transfer list|status|plan|run|checkpoint|pause|resume|reconcile|reconcile-record|fail|cancel` [#fa-transfer-liststatusplanruncheckpointpauseresumereconcilereconcile-recordfailcancel]
```bash
fa transfer list --engagement-id eng_01J00000000000000000000000
fa transfer status xfr_01J00000000000000000000000 --json
fa transfer plan --file transfer-plan.json --idempotency-key transfer-plan-v1
fa transfer run xfr_01J00000000000000000000000 --idempotency-key transfer-run-v1
fa transfer pause xfr_01J00000000000000000000000 --reason "Source maintenance" --idempotency-key transfer-pause-1
fa transfer resume xfr_01J00000000000000000000000 --idempotency-key transfer-resume-1
fa transfer reconcile xfr_01J00000000000000000000000 --idempotency-key transfer-reconcile-1
```
`plan`, `run`, `pause`, `resume`, `reconcile`, and `cancel` are operator controls. `checkpoint`, `reconcile-record`, and `fail` submit runner evidence and require admitted automation; a natural-person invocation is rejected. See [data transfer and reconciliation](/docs/migration/transfer) for input schemas and the Temporal execution boundary.
## `fa deployment list|status|require` [#fa-deployment-liststatusrequire]
```bash
fa deployment list --engagement-id eng_01J00000000000000000000000
fa deployment status dpr_01J00000000000000000000000 --json
fa deployment require --file deployment-requirement.json --idempotency-key wave-3-release
```
`require` declares the Runway operation, environment, immutable artifacts, and terminal
state needed by the migration. Airlift computes the desired digest. The admitted Runway
integration records observations and reconciliation; caller-authored `observe`, `sync`,
and `reconcile` commands do not exist. Use `fr` for deployment execution. See
[Deploy with Fabric Runway](/docs/integrations/runway).
## `fa migration-ir qualify` [#fa-migration-ir-qualify]
```bash
fa migration-ir qualify \
--file generated/artifact-set.json \
--root generated \
--bindings release-bindings.json \
--resolutions residue-resolutions.json \
--proof hermetic_proven \
--output qualification.json
```
The command verifies generated bytes, invokes Databricks bundle validation, checks runtime
binding and residue evidence, and optionally evaluates matching Runway and Experiments
workspace evidence. It is read-only and never writes a provider verdict to the Airlift
ledger. See [release qualification](/docs/migration/release-qualification).
## `fa validation list|status|runs|readiness|run|cancel` [#fa-validation-liststatusrunsreadinessruncancel]
```bash
fa validation run --file validation-request.json --idempotency-key wave-2-validation-v3
fa validation list --engagement-id "$ENGAGEMENT_ID"
fa validation status "$VALIDATION_EXECUTION_ID" --json
fa validation runs --object-id "$OBJECT_ID" --json
fa validation readiness --object-id "$OBJECT_ID" --json
fa validation cancel "$VALIDATION_EXECUTION_ID" --reason "Superseded suite" --idempotency-key validation-cancel-v1
```
`run` creates Airlift validation scope; the durable worker delegates the generated suite
to Experiments. `runs` shows admitted provider runs. `readiness` shows derived track
observations. Cancellation is governed and leaves external provider state subject to
reconciliation.
## `fa discrepancy list|show|create|triage|accept|resolve|verify` [#fa-discrepancy-listshowcreatetriageacceptresolveverify]
```bash
fa discrepancy list --object-id "$OBJECT_ID"
fa discrepancy show "$DISCREPANCY_ID" --json
fa discrepancy create --file discrepancy.json --idempotency-key discrepancy-42-create
fa discrepancy triage --file triage.json --idempotency-key discrepancy-42-triage
fa discrepancy accept --file triage-acceptance.json --idempotency-key discrepancy-42-accept
fa discrepancy resolve --file resolution.json --idempotency-key discrepancy-42-resolution
fa discrepancy verify --file verification.json --idempotency-key discrepancy-42-verify
```
Human operators can triage, accept eligible low/medium differences, and submit
remediation. `create` and `verify` are admitted automation operations. Verification takes
a `validationRunId` and succeeds only for a passing Experiments run belonging to the
same object and matching the resolution evidence identity.
## `fa certificate list|show|mint|invalidate` [#fa-certificate-listshowmintinvalidate]
```bash
fa certificate list --object-id "$OBJECT_ID"
fa certificate show "$CERTIFICATE_ID" --json
fa certificate mint --file certificate-mint.json --idempotency-key object-42-mint-v1
fa certificate invalidate --file certificate-invalidate.json --idempotency-key object-42-stale-v1
```
List and show are authenticated reads. Mint and invalidate call the system-owned
certificate actions and normally require the admitted worker principal. They do not
replace offline `certificate inspect` and `certificate verify`.
## `fa evidence export` [#fa-evidence-export]
```bash
fa evidence export --file evidence-export.json --idempotency-key wave-2-evidence-v1
```
Creates a content-digested governed evidence pack for an object or wave. The export
contains references and policy evidence, not artifact bodies or credentials.
## `fa help` [#fa-help]
```bash
fa help
fa --help
fa -h
```
Print every command and the CLI mutation boundary. Exit `0`.
## `fa version` [#fa-version]
```bash
fa version
fa --version
fa -V
```
Print the installed CLI version. Exit `0`.
## `fa docs [topic]` [#fa-docs-topic]
```bash
fa docs
fa docs sources/sql-server
fa docs migration/validation --json
```
Print `https://airlift.techfabric.com/docs`, optionally with the URL-encoded topic appended.
This command prints a URL; it does not launch a browser.
## `fa sources` [#fa-sources]
```bash
fa sources
fa sources --json
```
List the installed source profiles with archetype, evidence-derived level, implementation
routing (non-evidence),
variants, applicable
Lakebridge capabilities, program track, and migration-area metadata.
## `fa sources export --plans` [#fa-sources-export---plans]
```bash
fa sources export --plans --format jsonl
fa sources export --plans --json
```
Export one canonical plan record per source × variant in the installed registry. Each
record wraps a compiled plan with `sourceSystem`, `sourceVariant`, `implementationRoutingLevel`,
`externalGates`, a `docsUrl`, and a `contentDigest` computed over the plan alone, so
unchanged plans keep the same digest across CLI releases for incremental re-indexing. The
default text output emits the same JSONL form as `--format jsonl`; `--json` emits a single
canonical array instead. `--plans` is required; omitting it returns exit `2`.
## `fa source inspect ` [#fa-source-inspect-source]
```bash
fa source inspect sql_server
fa source inspect mssql --json
fa source inspect teradata
```
Resolve a profile ID or alias and print its variants, archetype, implementation routing
(non-evidence), adapter
contract, workload surfaces, applicable Lakebridge routing, transfer strategy,
validation checks, residue, and modernization targets. Unknown sources fail with exit
`1`. Run `fa sources --json` for canonical IDs and variants.
## `fa source plan ` [#fa-source-plan-source]
```bash
fa source plan synapse
fa source plan dynamics_365 --variant dynamics_365_finance_operations --json
```
Generate the deterministic archetype-aware plan. Each phase contains specialist
adapter commands or boundaries, exact governed Airlift action IDs, outputs, and exit
criteria. `--variant` selects a registered specialization. There is no legacy schema
selector. Generating a plan does not create governed state.
## `fa source certification-check ` [#fa-source-certification-check-file]
```bash
fa source certification-check source-certification.json
fa source certification-check source-certification.json --json
```
Validate an immutable live-run manifest and report evidence missing for its requested
support level. Eligible returns `0`; missing required evidence returns `1`. The command
does not promote the registry or mint a certificate.
## `fa doctor` [#fa-doctor]
```bash
fa doctor
fa doctor --profile local
fa doctor --profile production --json
```
Check Node, persistence, authorization, evidence registry, signing and verification,
Databricks forwarded identity, Lakebridge job binding, Temporal mode, and the cutover
effector boundary. Production profile failures return exit `1`; warnings do not.
`doctor` validates configuration shape. It cannot prove connectivity, validate client
data, or certify a cutover effector.
## `fa actions` [#fa-actions]
```bash
fa actions
fa actions --json
```
Print every governed action with its version, required permissions, policies, and emitted
events. The command reads the installed contract; it never invokes an action.
## `fa profiles` [#fa-profiles]
```bash
fa profiles
fa profiles --json
```
Print built-in object validation profiles, their canonical SHA-256 digests, and required
readiness tracks. These are certificate profiles, not source-system profiles.
## `fa certificate inspect ` [#fa-certificate-inspect-file]
```bash
fa certificate inspect migration-certificate.json
fa certificate inspect migration-certificate.json --json
```
Parse the certificate schema and show its identity, profile, issuer, key, signed digest,
computed digest, and digest match. Inspection does not verify the signature.
## `fa certificate verify ` [#fa-certificate-verify-file]
```bash
fa certificate verify migration-certificate.json --keys public-keys.json
AIRLIFT_EVIDENCE_PUBLIC_KEYS_JSON='{"airlift-prod":"...PEM..."}' \
fa certificate verify migration-certificate.json
```
Verify both envelope digest and Ed25519 signature. `--keys` accepts a JSON object mapping
key IDs to public PEM strings. Without it, the command reads Airlift's verifier
configuration from the environment. Valid returns `0`; invalid returns `1`.
## Usage failures [#usage-failures]
Unknown commands, missing required arguments, or unsupported subcommands print a concise
message plus `Run 'fa help' for usage.` and return exit `2`. Remote authentication
returns `3`, not found returns `4`, blocked/conflict returns `5`, and dependency outage
returns `6`. Malformed local files, unknown source profiles, and failed diagnostics
return `1`.
# Cutover and hypercare commands
# Cutover and hypercare commands [#cutover-and-hypercare-commands]
`fa cutover` manages migration cutover truth and starts Airlift's durable workflow.
`fa deployment` does not deploy releases; use the Runway CLI for release execution and
then admit the resulting immutable reference through an Airlift deployment requirement.
Set the authenticated API boundary once:
```bash
export AIRLIFT_API_URL=https://
export DATABRICKS_TOKEN=
```
The API derives organization and identity from authentication. No cutover command
accepts an actor or organization override.
## Inspect control state [#inspect-control-state]
```bash
fa cutover list --estate-id est_01J00000000000000000000000
fa cutover status wav_01J00000000000000000000000 --json
```
The response includes the frozen digest, runbook, rehearsal, operational evidence,
effector certification, incidents, hypercare, source disposition, and any stale reason.
## Freeze exact scope [#freeze-exact-scope]
```json title="wave-freeze.json"
{
"engagementId": "eng_01J00000000000000000000000",
"waveId": "wav_01J00000000000000000000000",
"transfers": {
"applicability": "required",
"ids": ["xfr_01J00000000000000000000000"]
},
"deployments": {
"applicability": "required",
"ids": ["dpr_01J00000000000000000000000"]
},
"releaseEvidenceRefs": [
{
"system": "runway",
"type": "promoted_release",
"id": "release-v42",
"digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
],
"reason": "Freeze the certified production scope for the approved window."
}
```
```bash
fa cutover freeze --file wave-freeze.json --idempotency-key wave-freeze-v1
```
For a genuinely inapplicable transfer or deployment track, use
`{"applicability":"not_applicable","reason":"..."}`. Airlift requires a reason; an
empty list cannot silently bypass the track.
## Configure and rehearse the runbook [#configure-and-rehearse-the-runbook]
```json title="runbook.json"
{
"waveId": "wav_01J00000000000000000000000",
"version": "2026.09.14-1",
"reason": "Pin the approved timed procedure and restore path.",
"steps": [
{
"stepId": "checkpoint",
"name": "Create routing checkpoint",
"ownerRole": "cutover_operator",
"offsetMinutes": -15,
"expectedDurationMinutes": 5,
"actionKind": "governed_action",
"actionRef": "effector:checkpoint"
},
{
"stepId": "switch",
"name": "Apply consumer routing once",
"ownerRole": "cutover_operator",
"offsetMinutes": 0,
"expectedDurationMinutes": 10,
"actionKind": "governed_action",
"actionRef": "effector:apply",
"rollbackStepId": "restore"
},
{
"stepId": "restore",
"name": "Restore the checkpoint",
"ownerRole": "cutover_operator",
"offsetMinutes": 15,
"expectedDurationMinutes": 10,
"actionKind": "governed_action",
"actionRef": "effector:compensate"
}
]
}
```
```bash
fa cutover runbook --file runbook.json --idempotency-key runbook-v1
fa cutover rehearse --file rehearsal-result.json --idempotency-key rehearsal-v1
```
`rehearse` requires an admitted automation principal and immutable evidence reference.
A human cannot author a passing rehearsal verdict.
## Admit operational evidence [#admit-operational-evidence]
```json title="parallel-run.json"
{
"waveId": "wav_01J00000000000000000000000",
"phase": "parallel_run",
"providerRef": {
"system": "radar",
"type": "observation_window",
"id": "window-42",
"digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},
"evidenceDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"sloProfileId": "airlift.cutover.production_slo.v1",
"observedFrom": "2030-09-13T00:00:00.000Z",
"observedUntil": "2030-09-14T00:00:00.000Z",
"verdict": "passed"
}
```
```bash
fa cutover observe --file parallel-run.json --idempotency-key parallel-run-v1
```
Only Radar or an admitted external monitor may provide operational evidence. Airlift
retains the foreign reference, digest, window, SLO profile, and verdict; the monitor
definition and raw observations remain with the provider.
## Certify the effector and approve the wave [#certify-the-effector-and-approve-the-wave]
```bash
fa cutover certify-effector \
--file effector-certification.json \
--idempotency-key effector-cert-v1
fa cutover approve wav_01J00000000000000000000000 \
--note "Change authority approval" \
--idempotency-key wave-approval-1
```
Certification requires a passing rehearsal and a natural-person certifier. The file
identifies the implementation and proves `checkpoint`, `apply_once`, `verify`, and
`compensate`. Approval is a separate governed action and follows separation of duties.
## Start the durable workflow [#start-the-durable-workflow]
```bash
fa cutover start wav_01J00000000000000000000000 \
--window 2030-09-14T02:00Z \
--reason "Approved customer change window"
fa cutover workflow-status airlift-v2-wav_
fa cutover wake airlift-v2-wav_
```
`start` calls the dedicated workflow endpoint. It does not invoke
`airlift.cutover_execute` from the CLI process. The worker re-reads governed readiness,
waits durably for approvals, performs checkpoint/apply-once/verify, and records the
outcome through Platform actions.
## Incidents and hypercare [#incidents-and-hypercare]
```bash
fa cutover incident-open --file incident.json --idempotency-key incident-1
fa cutover incident-resolve --file incident-resolution.json --idempotency-key incident-1-resolve
fa hypercare start --file hypercare-start.json --idempotency-key hypercare-v1
fa hypercare observe --file hypercare-observation.json --idempotency-key hypercare-observe-1
fa hypercare complete --file hypercare-decision.json --idempotency-key hypercare-accept-1
fa hypercare decommission --file source-disposition.json --idempotency-key source-disposition-1
```
An open incident blocks readiness or hypercare acceptance. Resolution requires immutable
evidence. Hypercare completion and source disposition are human decisions with
separation-of-duties checks; agents and monitors cannot accept or decommission.
## Exit behavior [#exit-behavior]
| Code | Meaning |
| ---- | ----------------------------------------------------- |
| `0` | request completed or attached to an existing workflow |
| `2` | invalid command arguments |
| `4` | authentication failed |
| `5` | authorization failed |
| `6` | dependency unavailable or invalid API response |
| `7` | governed readiness conflict |
# Databricks-native commands
# Databricks-native commands [#databricks-native-commands]
Use `fa databricks-native` when the customer already runs Databricks. This is not a
pretend migration from an external system. The source estate is `databricks`, and the
program starts from an immutable current-state baseline.
## Register the source profile [#register-the-source-profile]
```bash
fa source inspect databricks
fa source plan databricks --variant databricks_unity_catalog
```
Available variants are `databricks_unity_catalog`,
`databricks_workspace_consolidation`, and `databricks_cost_performance`.
## Create the native manifest [#create-the-native-manifest]
```json
{
"schemaVersion": 1,
"estate": {
"name": "Analytics platform",
"variant": "databricks_unity_catalog",
"workspaceRefs": ["workspace://analytics-prod"],
"snapshotAt": "2030-01-15T12:00:00.000Z"
},
"reason": "unity_catalog_upgrade",
"baselineEvidenceRef": "evidence://experiments/native-baseline-v1",
"assets": [
{
"assetId": "sales-database",
"name": "Sales Hive database",
"kind": "hive_metastore_object",
"dependencies": [],
"owner": "sales-data",
"currentStateDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"issues": ["Uses workspace-local storage paths."],
"metrics": { "tables": 42 }
}
]
}
```
Inventory may cover workspaces, metastores, Hive Metastore objects, Unity Catalog
assets, jobs, pipelines, notebooks, warehouses, clusters, policies, permissions,
dashboards, models, endpoints, shares, lineage, cost observations, and operational
dependencies. Store identities, digests, aggregate metrics, and issues—not credentials
or raw client data.
Typed reasons include Unity Catalog upgrades, workspace consolidation, permission and
path modernization, serverless or Lakeflow adoption, Delta and liquid clustering,
runtime upgrades, dashboard transitions, and cost/performance optimization.
## Inspect and plan [#inspect-and-plan]
```bash
fa databricks-native inspect --file native-manifest.json
fa databricks-native plan \
--file native-manifest.json \
--json > native-plan.json
```
Every asset becomes a deterministic, advisory, or human recommendation. The plan
requires baseline behavior, allow-and-deny permission tests, performance and cost
guardrails, immutable release and rollback evidence, an operational observation window,
and owner acceptance.
## Register [#register]
```bash
fa databricks-native register \
--file native-plan.json \
--engagement-id \
--estate-id \
--artifact-id \
--idempotency-key
```
The plan records the family execution contract:
* Airlift owns the baseline, modernization intent, recommendations, evidence references,
promotion policy, and value record.
* Harness may produce bounded advice or repair candidates.
* Experiments owns A/B, BDD, parity, performance, and cost evaluations.
* Runway owns preview, deployment, promotion, reconciliation, and rollback.
* Radar owns operational observations.
* Tower owns work references.
* Platform owns governed mutations and audit.
Use `fa` to inspect Airlift migration/modernization status and request governed changes.
Use `fr` to execute releases. Airlift may block on Runway or Radar evidence; it never
copies their state or provides a second deploy command.
# Delivery and claim commands
# Delivery and claim commands [#delivery-and-claim-commands]
`fa delivery` makes the migration method repeatable without turning internal delivery
state into public documentation or unsupported claims. These commands are local,
deterministic checks; governed engagement mutations still use the normal authenticated
commands.
## Qualify a source engagement [#qualify-a-source-engagement]
Create a credential-reference-only qualification file with source and target authority,
representative-data approval, object count, required/excluded surfaces, network shape,
RPO/RTO, and cutover/rollback owners.
```bash
fa delivery preflight --file qualification.json
```
The command returns assessment and cutover-design readiness separately. Missing source
authority, target authority, or representative-data approval blocks assessment. Missing
cutover or rollback owners blocks cutover design. Private-link and offline shapes add a
connectivity rehearsal instead of pretending online dependencies are available.
## Generate the delivery kit [#generate-the-delivery-kit]
```bash
fa delivery kit \
--file qualification.json \
--json > delivery-kit.json
```
The generated kit contains contracts for:
* source qualification;
* assessment report;
* target blueprint;
* wave plan;
* human-residue estimate;
* migration certificate;
* cutover and rollback runbook; and
* measured value report.
It also lists factory setup, client adapter, human remediation, cutover assurance,
modernization, and hypercare playbooks plus backup/restore, signer rotation, connector
rotation, retention/export, disaster recovery, and upgrade/rollback operations.
## Validate a connector operating envelope [#validate-a-connector-operating-envelope]
```bash
fa delivery connector-policy-check --file connector-policy.json
```
A promoted connector policy must bound concurrency, rate, quota, cost, timeout, retry
classes, and circuit breaking. Checkpoint and reconciliation are mandatory. The schema
fixes non-idempotent effects at one attempt.
## Gate an external value claim [#gate-an-external-value-claim]
```bash
fa delivery claim-check --file external-claim.json
```
Eligibility requires at least three engagements, at least ten comparable observations,
medium or high confidence, observed methods beyond expert estimates alone, a versioned
cohort and release generation, exclusions, limitations, a reviewed methodology, and an
immutable evidence digest. A rejected packet exits nonzero and emits exact blockers.
This is stricter than an engagement-scoped client value report. It exists for aggregate
external language. Never hard-code “60% faster” into product material.
## Check activation evidence [#check-activation-evidence]
```bash
fa delivery activation-check --file activation-evidence.json
```
Requirements are data, not hard-coded program assumptions. Record each credential
category's current required and observed counts, approved outcome references,
thought-leadership references, repeatable demo evidence, reviewer, and evidence digest.
Repository tests do not count as customer outcomes.
## Scan public developer content [#scan-public-developer-content]
```bash
fa delivery public-check --file public-document.md
```
The scanner blocks known private path, deployment, evidence-ledger, credential, and
client-identity patterns. It complements review and CI; it does not declassify a document
or replace client approval.
# fa doctor
# `fa doctor` [#fa-doctor]
```bash
fa doctor --profile local
fa doctor --profile production --json
```
Doctor checks Node generation, store selection and binding shape, authorization
directory, evidence registry, Ed25519 signer/verifier configuration, Databricks Apps
identity gates, Lakebridge job configuration, Temporal selection, and the client-effector
boundary. It also checks the observation-only Runway API binding and the Experiments
case-module/evidence-store binding used by release qualification.
Production profile fails when durable store, authorization, identity, signing, live
Lakebridge, Runway observation, or Experiments validation structure is missing. Temporal
absence and the composition-injected cutover
effector remain explicit warnings because connectivity and client certification cannot
be proven from environment shape.
Doctor prints variable names, key IDs, counts, and dispositions. It does not print
connection strings, private keys, tokens, authorization-directory contents, or other
secret values. A passing shape check is not deployment or client certification evidence.
# Live evidence commands
# Live evidence commands [#live-evidence-commands]
Airlift admits immutable artifact references into the migration ledger. It does not turn a
JSON file into a validation verdict, deployment result, or cutover authorization. Fabric
Experiments, Runway, Radar, and client-approved adapters retain ownership of their results;
Airlift stores their identifiers, content digests, producer generations, and lineage.
## 1. Inspect before admission [#1-inspect-before-admission]
```bash
fa evidence inspect live-evidence.json
fa evidence inspect live-evidence.json --json > .airlift/evidence-inspection.json
```
Inspection is local. It validates the secret-free schema, timestamp order, source identity,
run references, artifact digests, and disallowed credential-like keys. A historical failed
run remains valid evidence—it is reported as failed rather than erased.
## 2. Admit artifact references [#2-admit-artifact-references]
```bash
fa evidence admit \
--file live-evidence.json \
--engagement-id \
--estate-id \
--idempotency-key source-workspace-run-v1 \
--json > .airlift/evidence-admission.json
```
The command invokes the governed `airlift.artifact_register` action once for the manifest
and once for each referenced artifact. It records no file bodies and no credentials. The
JSON result includes `providerVerdictsAdmitted: false`; provider evidence must still enter
through its admitted principal and policy path before readiness can pass. Artifact
admission cannot manufacture an Experiments verdict.
## 3. Inspect the admitted ledger [#3-inspect-the-admitted-ledger]
```bash
fa evidence list --engagement-id
fa evidence show --json
fa artifact list --engagement-id
```
In the Databricks App, open **Engagements → active engagement → Artifacts** for immutable
references and **Runs** for assessment, conversion, transfer, deployment, and validation
execution references.
## 4. Export governed evidence [#4-export-governed-evidence]
```bash
fa evidence export \
--file evidence-export.json \
--idempotency-key wave-evidence-export-v1
```
An evidence export is a content-digested view of the governed event trail and current
projection. The digest proves byte identity; only a valid signing envelope proves signer
identity. Retain the export with the application build, source snapshot, provider runs,
certificates, approvals, and observation windows that supported the decision.
## Automation outcomes [#automation-outcomes]
| Exit | Meaning |
| ---- | ---------------------------------------------------------------- |
| `0` | schema inspection, admission, query, or export request succeeded |
| `1` | the governed action or policy rejected the request |
| `2` | command usage or the local manifest is invalid |
| `4` | the requested remote resource was not found |
| `6` | authentication, transport, or service availability failed |
# Generated command index
# Generated command index [#generated-command-index]
This page is generated from Fabric Airlift CLI 0.18.4. The same manifest
drives `fa help`, group help, shell completion, tests, and this reference. It describes
developer commands only; it does not include credentials, tenant data, deployment state, or
internal delivery notes.
Use resource-first paths: `fa `. For a nested resource, continue the
path: `fa inventory graph list`, `fa conversion batch create`, and
`fa application-kit module list`. There are no deprecated spellings or hidden aliases.
Global automation options:
* `--format text|table|json|yaml|jsonl`; `--json` is the concise JSON form;
* `--file -` reads a JSON request or manifest from stdin;
* `--timeout ` bounds remote requests and explicit waits; and
* `--correlation-id ` carries a caller trace ID into governed mutations.
Generate completion with `fa completion bash`, `fa completion zsh`, or
`fa completion fish`. Emit this command model for tooling with `fa commands --json`.
## `fa organization` [#fa-organization]
Govern the projected organization membership registry.
| Command | Behavior |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `fa organization membership set --file --idempotency-key ` | Apply governed membership grants and revocations (admin role; last-admin protected). |
## `fa engagement` [#fa-engagement]
Create and govern migration engagements.
| Command | Behavior |
| --------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `fa engagement list` | List engagements visible to the authenticated principal. |
| `fa engagement show ` | Show one engagement. |
| `fa engagement status ` | Show the derived eight-phase migration status and blockers. |
| `fa engagement create\|update --file --idempotency-key ` | Create or update an engagement. |
| `fa engagement activate\|freeze --idempotency-key ` | Advance the engagement lifecycle. |
| `fa engagement preflight ` | Evaluate source-capability and human-lane blockers. |
## `fa connection` [#fa-connection]
Register source connection references without storing credentials.
| Command | Behavior |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `fa connection list [--engagement-id ]` | List connection bindings. |
| `fa connection register --file --idempotency-key ` | Register a secret-backed connection reference. |
| `fa connection verify --digest --idempotency-key ` | Verify a binding with the digest of a recorded connectivity diagnostic. |
| `fa connection retire --reason --idempotency-key ` | Retire a connection binding. |
| `fa connection test [--json]` | Report observed connectivity state for a binding; exit 0 only when observed. |
| `fa connection diagnose --file --idempotency-key ` | Record an admitted connectivity diagnostic (system principal). |
## `fa access` [#fa-access]
Inspect derived Databricks deployment access and record admitted access preflights.
| Command | Behavior |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `fa access show [--json]` | Report the derived access-preflight state and five target-integration states; exit 0 only when access is observed. |
| `fa access record --file --idempotency-key ` | Record an admitted access preflight (system principal). |
## `fa evaluator` [#fa-evaluator]
Inspect derived evaluation readiness and record admitted candidate freezes and rehearsals.
| Command | Behavior |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `fa evaluator window [--json]` | Report derived evaluation readiness and the evaluation-window manifest; exit 0 only when evaluation\_ready is true. |
| `fa evaluator freeze --file --idempotency-key ` | Freeze an evaluation candidate (admitted system principal; in-process path). |
| `fa evaluator rehearsal --file --idempotency-key ` | Record an evaluator rehearsal against the frozen candidate (admitted system principal; in-process path). |
## `fa uc-evidence` [#fa-uc-evidence]
Inspect the derived Databricks-native evidence state and record admitted projection runs and reconciliations.
| Command | Behavior |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `fa uc-evidence show [--engagement-id ] [--json]` | Report the derived UC evidence state; exit 0 only when the evidence is current. |
| `fa uc-evidence record --kind projection-run\|reconciliation --file --idempotency-key ` | Record an admitted UC projection run or target reconciliation (admitted system principal; in-process path). |
## `fa estate` [#fa-estate]
Register and inspect source estates.
| Command | Behavior |
| ----------------------------------------------------------------- | ------------------- |
| `fa estate list` | List estates. |
| `fa estate show ` | Show an estate. |
| `fa estate register --file --idempotency-key ` | Register an estate. |
## `fa assessment` [#fa-assessment]
Run and accept governed source assessments.
| Command | Behavior |
| ------------------------------------------------------------------------------------------ | -------------------------------- |
| `fa assessment list [--estate-id ]` | List assessments. |
| `fa assessment status ` | Show assessment status. |
| `fa assessment start\|record\|accept\|export --file --idempotency-key ` | Mutate the assessment lifecycle. |
## `fa inventory` [#fa-inventory]
Register inventory and build dependency graphs.
| Command | Behavior |
| --------------------------------------------------------------------------------------- | ------------------------------------ |
| `fa inventory list [--estate-id ] [--assessment-id ]` | List migration objects. |
| `fa inventory register --file --idempotency-key ` | Register inventory. |
| `fa inventory graph list [--assessment-id ]` | List dependency graphs. |
| `fa inventory graph show ` | Show graph edges. |
| `fa inventory graph start\|record\|accept --file --idempotency-key ` | Build and accept a dependency graph. |
## `fa plan` [#fa-plan]
Generate, compare, select, and freeze migration plans.
| Command | Behavior |
| --------------------------------------------------------------- | ------------------------ |
| `fa plan list\|compare [--engagement-id ]` | List or compare plans. |
| `fa plan show ` | Show a migration plan. |
| `fa plan generate --file --idempotency-key ` | Generate a plan. |
| `fa plan select\|freeze --idempotency-key ` | Select or freeze a plan. |
## `fa migration` [#fa-migration]
Start or cancel a governed production migration route from an exact frozen plan.
| Command | Behavior |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `fa migration start --engagement-id --frozen-plan-id ` | Submit the exact frozen plan to the authenticated product API; execution continues asynchronously. |
| `fa migration cancel --engagement-id [--reason ]` | Record an operator cancellation for the active route; the worker reconciles terminal convergence. |
## `fa wave` [#fa-wave]
Inspect dependency-aware migration waves.
| Command | Behavior |
| --------------------------------- | ------------------- |
| `fa wave list [--estate-id ]` | List cutover waves. |
## `fa conversion` [#fa-conversion]
Run conversion batches and govern remediation residue.
| Command | Behavior |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `fa conversion list [--object-id ]` | List conversion attempts with their hazard-scan state (clean, hazardous, or unassessed). |
| `fa conversion show ` | Show a conversion attempt; hazardous attempts block certification until their conversion\_hazard residue is reviewed. |
| `fa conversion diff ` | Compare attempts for an object. |
| `fa conversion batch list [--engagement-id ]` | List conversion batches. |
| `fa conversion batch show ` | Show a conversion batch. |
| `fa conversion batch create\|start\|complete --file --idempotency-key ` | Mutate a conversion batch. |
| `fa conversion attempt start\|record --file --idempotency-key ` | Start or record a conversion attempt. |
| `fa conversion retry --file --idempotency-key ` | Retry through the governed conversion action. |
## `fa residue` [#fa-residue]
Estimate, assign, and resolve human or agent remediation.
| Command | Behavior |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `fa residue list [--engagement-id ] [--object-id ]` | List remediation residue. |
| `fa residue show ` | Show one residue item; conversion\_hazard cases name their exact origin conversion and assessment digest. |
| `fa residue create\|estimate\|assign\|resolve\|review\|cancel --file --idempotency-key ` | Mutate the residue lifecycle. After an approved review, retry certification with a FRESH idempotency key — a denied key stays denied. |
## `fa transfer` [#fa-transfer]
Plan, operate, and reconcile data movement.
| Command | Behavior |
| --------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `fa transfer list [--engagement-id ] [--estate-id ]` | List transfer plans. |
| `fa transfer status ` | Show transfer status. |
| `fa transfer plan\|checkpoint\|reconcile-record\|fail --file --idempotency-key ` | Record transfer plans and evidence. |
| `fa transfer run\|resume\|reconcile --idempotency-key ` | Operate a transfer workflow. |
| `fa transfer pause\|cancel --reason --idempotency-key ` | Pause or cancel a transfer. |
## `fa validation` [#fa-validation]
Run Experiments-backed parity validation and inspect readiness.
| Command | Behavior |
| ------------------------------------------------------------------- | ---------------------------------------- |
| `fa validation list [--engagement-id ] [--estate-id ]` | List validation executions. |
| `fa validation status ` | Show validation status. |
| `fa validation runs\|readiness [--object-id ]` | Inspect admitted evidence and readiness. |
| `fa validation run --file --idempotency-key ` | Request validation. |
| `fa validation cancel --reason --idempotency-key ` | Cancel validation. |
## `fa certificate` [#fa-certificate]
Inspect, verify, mint, and invalidate migration certificates.
| Command | Behavior |
| ------------------------------------------------------------------------------ | --------------------------------------- |
| `fa certificate list [--object-id ]` | List certificates. |
| `fa certificate show ` | Show a governed certificate record. |
| `fa certificate inspect ` | Inspect a certificate envelope locally. |
| `fa certificate verify [--keys ]` | Verify digest and signature locally. |
| `fa certificate mint\|invalidate --file --idempotency-key ` | Mutate governed certificate state. |
## `fa cutover` [#fa-cutover]
Freeze, approve, execute, and observe governed cutover.
| Command | Behavior |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `fa cutover list [--estate-id ]` | List cutover controls. |
| `fa cutover status ` | Show cutover readiness. |
| `fa cutover freeze\|runbook\|rehearse\|observe\|certify-effector --file --idempotency-key ` | Record cutover control evidence. |
| `fa cutover incident-open\|incident-resolve --file --idempotency-key ` | Govern a cutover incident. |
| `fa cutover approve [--note ] --idempotency-key ` | Approve through the authenticated mutation boundary. |
| `fa cutover start --window --reason [--wait] [--timeout ]` | Start or attach to the durable cutover workflow. |
| `fa cutover workflow-status\|wake ` | Query or wake a durable cutover workflow. |
## `fa hypercare` [#fa-hypercare]
Record post-cutover observation and decommission evidence.
| Command | Behavior |
| -------------------------------------------------------------------------------------------------- | ------------------------------- |
| `fa hypercare start\|observe\|complete\|decommission --file --idempotency-key ` | Mutate the hypercare lifecycle. |
## `fa artifact` [#fa-artifact]
Register and inspect content-digested migration artifacts.
| Command | Behavior |
| ------------------------------------------------------------------- | ----------------------------------------- |
| `fa artifact list [--engagement-id ] [--object-id ]` | List artifacts. |
| `fa artifact show ` | Show one artifact. |
| `fa artifact register --file --idempotency-key ` | Register an immutable artifact reference. |
## `fa deployment` [#fa-deployment]
Declare and inspect deployment requirements; Runway executes releases.
| Command | Behavior |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `fa deployment list [--engagement-id ] [--estate-id ]` | List deployment requirements. |
| `fa deployment status ` | Show a deployment requirement. |
| `fa deployment require --file --idempotency-key ` | Declare a required Runway outcome. |
| `fa deployment connect --file --idempotency-key ` | Connect an existing requirement to a Runway deployment reference. |
## `fa modernization` [#fa-modernization]
Separate baseline migration from measurable Databricks modernization.
| Command | Behavior |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `fa modernization list [--engagement-id ] [--object-id ]` | List modernization items. |
| `fa modernization show ` | Show one modernization item. |
| `fa modernization recommend\|decide\|plan\|start\|evidence\|promote\|rework --file --idempotency-key ` | Mutate modernization state. |
## `fa value` [#fa-value]
Record baselines and publish measurable outcome reports.
| Command | Behavior |
| ---------------------------------------------------------------------------------- | ----------------------- |
| `fa value observations\|summaries\|reports [--engagement-id ]` | Inspect value evidence. |
| `fa value record\|summarize\|publish --file --idempotency-key ` | Mutate value evidence. |
## `fa capability` [#fa-capability]
Inspect and govern source-capability evidence.
| Command | Behavior |
| -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `fa capability list [--source ] [--variant ] [--capability ] [--construct ] [--artifact-kind ]` | List capability entries. |
| `fa capability show ` | Show one capability entry. |
| `fa capability matrix --source [--variant ]` | Render the capability matrix. |
| `fa capability propose\|evidence\|promote\|expire\|revoke\|reconcile --file --idempotency-key ` | Mutate capability evidence. |
## `fa source` [#fa-source]
Inspect, plan, diagnose, and qualify supported source profiles.
| Command | Behavior |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `fa source inspect ` | Inspect one source profile. |
| `fa source plan [--variant ]` | Create a source migration plan. |
| `fa source recipe [--variant ]` | Render the complete developer command and artifact sequence for one source. |
| `fa source constructs [--variant ] [--construct ] [--artifact-kind ]` | List repository-owned construct routing without implying provider proof. |
| `fa source doctor\|certify [--variant ] [--level ]` | Diagnose or certify capability evidence. |
| `fa source limitations [--variant ]` | List explicit source limitations. |
| `fa source certification-check ` | Evaluate source certification evidence. |
## `fa migration-pack` [#fa-migration-pack]
Compile and qualify source-specific migration packs.
| Command | Behavior |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `fa migration-pack inspect\|plan --file ` | Inspect or compile a migration pack. |
| `fa migration-pack register --file --engagement-id --estate-id --artifact-id --idempotency-key ` | Register a compiled pack. |
| `fa migration-pack certification-check --file ` | Evaluate pack certification evidence. |
## `fa migration-ir` [#fa-migration-ir]
Import, compile, generate, and qualify ETL migration IR.
| Command | Behavior |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `fa migration-ir import --source --file --estate-name --snapshot-at [--product-version ] [--credential-map ] [--output ]` | Import a supported source export. |
| `fa migration-ir inspect\|compile --file ` | Inspect or compile migration IR. |
| `fa migration-ir generate --file --out-dir [--artifact-set ] [--engagement-id --estate-id --artifact-ref-prefix ]` | Generate Databricks artifacts. |
| `fa migration-ir materialize --file --out-dir ` | Materialize generated files. |
| `fa migration-ir validate --file [--root ]` | Validate generated files. |
| `fa migration-ir qualify --file --root [--proof ] [--bindings ] [--resolutions ] [--workspace-evidence ] [--output ] [--databricks-cli ]` | Qualify a release candidate. |
| `fa migration-ir register --file --engagement-id --estate-id --artifact-id --idempotency-key ` | Register migration IR. |
## `fa lakebase` [#fa-lakebase]
Plan and qualify SQL Server migrations to Databricks Lakebase.
| Command | Behavior |
| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `fa lakebase inspect\|plan --file ` | Inspect or compile a Lakebase target plan. |
| `fa lakebase register --file --engagement-id --estate-id --artifact-id --idempotency-key ` | Register the immutable plan with an engagement. |
| `fa lakebase qualification-check --file ` | Evaluate digest-bound compatibility or managed Lakebase evidence. |
## `fa application-pack` [#fa-application-pack]
Compile enterprise application migration packs.
| Command | Behavior |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `fa application-pack inspect\|plan --file ` | Inspect or compile an application pack. |
| `fa application-pack register --file --engagement-id --estate-id