Guided migration journey (App walkthrough)
The primary App-first walkthrough of one Azure Synapse to Databricks Lakehouse migration — artifacts first, with one governed next action per phase.
Follow the guided migration journey
This is the primary App walkthrough. It follows one synthetic Azure Synapse to
Databricks Lakehouse engagement through the App, reading the same governed projection
the CLI and API read. App walkthroughs is the annotated screenshot
catalog with matching fa commands; Demonstrate an Azure migration
adapts this journey into a presentation script for engineering audiences.
Every screenshot is an automated capture from a governed, public synthetic workspace. The images contain no client data, credentials, real workspace identifiers, or production claims. If this is your first visit, start with the in-app guidance to learn the product tour, persistent Guide, and contextual help controls.
Start with the artifact and the next action
Airlift does not ask developers to interpret a dashboard and guess what to do. Every engagement phase page reads the governed migration projection and presents one What Airlift needs next panel before metrics and ledgers, alongside direct links to the artifacts that phase has already produced.
The panel always answers:
- What this phase does. The outcome this workspace governs and why it exists.
- What Airlift observed. The current phase summary from governed records.
- Why progress stopped. The first missing prerequisite or active blocker.
- What is the risk if bypassed? The concrete migration failure the gate prevents.
- Who acts next? The engineer, architect, provider, or independent approver who owns the action.
- Evidence that clears the gate. The exact artifact, run, digest, approval, or provider observation Airlift must admit.
The engagement overview explains the current phase, blocker count, evidence totals, and the next action that can advance the migration.
Progress is derived from admitted evidence across eight migration phases.
Use the primary next-action button; navigation alone never changes readiness.
Choose the primary Do this next action. It opens the relevant form or returns you to the earliest incomplete phase. It never changes readiness merely by navigating.
The eight phase workspaces
| Phase | Developer work | Evidence Airlift expects |
|---|---|---|
| Discover | Run the source assessment and review inventory and dependencies | Admitted report plus accepted inventory and dependency digests |
| Plan | Select a target blueprint and dependency-ordered waves | Selected and frozen plan bound to accepted source digests |
| Convert | Run converter batches, inspect attempts, and repair residue | Immutable target artifacts plus governed residue closure |
| Move data | Plan snapshot/incremental movement and operate checkpoints | Verified bindings, watermarks, restart checkpoints, and reconciliation digest |
| Deploy | Declare the required release and use Runway to execute it | Matching release reference, artifact digest, environment, operation, and terminal state |
| Validate | Request independent Experiments-backed checks | Passing object-specific runs and disposition of discrepancies |
| Certify | Review profiles, readiness tracks, and acceptance | System-minted certificates backed by active admitted evidence |
| Cut over | Freeze the wave, rehearse, approve, execute once, and verify | Certified scope, approvals, runbook, operational evidence, and rollback proof |
Later phases remain visible but are locked until the earliest incomplete gate is cleared. The primary action on a locked page returns to that earlier phase and preserves the engagement identifier.
Discover: admit the assessment
The discovery workspace turns Lakebridge Profiler and Analyzer output into reviewed inventory and dependency evidence. The artifact that matters is the immutable assessment pack; the next action is to accept or dispute its scope.
Discovery turns source assessment output into reviewed inventory and dependency evidence.
Accepted scope is content-digested so later planning cannot silently use a different inventory.
Review exclusions and dependencies, export the immutable assessment pack, and proceed to planning.
Plan: freeze scope against accepted digests
Planning binds the target blueprint, dependency order, and wave scope to the accepted discovery digests. Freezing is the artifact; conversion starts only against a frozen plan.
Planning binds the target blueprint, dependency order, delivery economics, and wave scope to accepted discovery evidence.
Freezing prevents silent scope changes while conversion and transfer work are underway.
Confirm the target mappings and dependency-ordered wave, then start conversion for that frozen scope.
Convert: candidates become immutable artifacts
The conversion factory records deterministic attempts and registers every output as an immutable artifact with its producer generation and content digest. Converter success is an attempt outcome, not parity evidence.
The conversion factory records deterministic attempts and immutable outputs while preserving unsupported behavior as residue.
Converter success is not parity evidence; every output retains tool generation and content lineage.
Inspect the failed construct, implement the repair, and register its immutable output.
Repair residue: normal specialist work
Unsupported transaction, temporary-table, or orchestration behavior surfaces as a named residue case with an owner, a diagnosis, and the evidence needed to close it. Residue is normal specialist work on any real estate, not a defect in the walkthrough: Airlift makes it explicit, assignable, measurable, and independently reviewable instead of hiding it in an automation percentage.
A residue case makes human remediation explicit, assignable, measurable, and independently reviewable.
Closing an external ticket cannot clear the ledger; the repaired artifact and validation evidence must be admitted.
Implement the repair, register the immutable artifact, run validation, and request independent review.
Move data: restartable, reconciled transfer
The transfer workspace tracks snapshot and incremental movement through watermarks, restart checkpoints, counts, rejects, and a reconciliation digest. A completed copy job is insufficient without that evidence.
The transfer workspace tracks snapshot and incremental movement through restartable checkpoints and reconciliation evidence.
A completed copy job is insufficient without matching watermarks, counts, rejects, and restart semantics.
Verify source and target bindings, execute the transfer runner, and inspect its reconciliation digest.
Deploy: a contract between Airlift and Runway
The deployment page is a contract between Airlift and Runway:
- Airlift records what must be deployed and decides whether observed evidence matches.
- Runway deploys, promotes, rolls back, reconciles, and owns environment state.
A page showing four zeros means no release requirement has been declared. It does not mean deployment succeeded, failed, or is complete.
| Counter | Meaning | What to do |
|---|---|---|
| Requirements | Desired release outcomes recorded for this engagement | If zero, select deployable artifacts and create the first requirement |
| Awaiting observation | A requirement exists but no verified matching Runway result has been admitted | Deploy with Runway, then admit or reconcile its release reference |
| Matched | Required and observed digest, environment, operation, and state match | Continue to independent validation |
| Blocked or uncertain | Evidence failed, is unverifiable, or differs from the requirement | Inspect the requirement detail and correct or re-observe the Runway release |
Create the first deployment requirement
- Select the immutable converted code, configuration, and deployment manifests that form one release.
- Choose Deploy a new release for the first release. Use Promote only for an existing release and Roll back only for an intentional recovery.
- Choose the environment where the next validation run will execute.
- Normally require Release succeeded.
- Create the requirement. Airlift computes the desired digest and waits; it does not execute Runway.
Runway then deploys the same artifact set. Airlift advances the deployment gate only when the admitted Runway observation matches every required field.
Airlift declares the release outcome and digest that migration requires; Runway owns deployment and environment state.
Awaiting observation means a requirement exists but no matching verified Runway result has been admitted.
Deploy the exact artifact set with Runway, then reconcile the returned release reference and digest.
Validate: independent evidence against exact digests
The validation laboratory requests object-specific Experiments checks against exact artifact digests, separating validation evidence from the converter that produced the candidate. Failed required checks become discrepancies with a governed disposition path.
Validation requests object-specific checks and records independent Experiments evidence against exact artifact digests.
The laboratory separates validation evidence from the converter that produced the candidate.
Select converted objects and required evidence tracks, request validation, and resolve any discrepancies.
Certify: readiness is evidence-derived
The assurance center is a read-only projection of which object-specific evidence tracks have passed, failed, expired, or been waived. Certificates are system-minted from admitted evidence; nobody authors one.
The assurance center is a read-only projection of which object-specific evidence tracks have passed, failed, expired, or been waived.
Certificates are system-minted from admitted evidence rather than authored by a developer.
Resolve failed or stale tracks and complete business acceptance before requesting certification.
Cut over: every gate agrees before execution
The cutover control room stays blocked until frozen scope, evidence, rehearsal, distinct approvals, operational health, and rollback capability all agree. It reflects the durable workflow and governed gate; it is not a manually editable checklist.
Cutover remains blocked until scope, evidence, rehearsal, approvals, operational health, and rollback capability all agree.
The control room reflects the durable workflow and governed gate; it is not a manually editable checklist.
Resolve every named blocker, rehearse the exact runbook, and obtain distinct approvals before execution.
If someone asks about audit
The walkthrough leads with artifacts and next actions, not the ledger. When an audience asks how Airlift proves what ran, open the run ledger: it links provider-owned executions to the governed engagement without copying their internal state, and a provider success remains evidence to evaluate rather than an automatic readiness advance.
The run ledger links provider-owned executions to the governed engagement without copying their internal state.
A provider success remains evidence to evaluate; it does not automatically advance Airlift readiness.
Open the relevant run reference and verify that its digest, scope, producer, and verdict match the gate.
Use contextual help
Select a question-mark control to define a term without leaving the page. Tooltips render in the browser document layer, reposition on scrolling and resizing, and stay inside the viewport. They are available by pointer and keyboard; press Escape to close one and return focus to its help control.
A help card is supplementary. Blockers, prerequisites, and recovery instructions always remain visible in the phase guidance panel.
Use the CLI with the same truth
The App and fa read the same organization-scoped projections:
fa engagement status <engagement-id> --json
fa artifact list --engagement-id <engagement-id> --json
fa deployment list --engagement-id <engagement-id> --json
fa validation list --engagement-id <engagement-id> --jsonUse the returned currentPhase, blockers, and phase nextAction; do not compute a
second percentage in automation. A UI click, task completion, or LLM response never
advances the ledger without the owning governed Platform action and its required evidence.
AI assistance boundary
An assistant may summarize the same phase guidance, link the relevant developer guide, or explain a field in more conversational language. Airlift does not let an LLM invent readiness: the assistant must treat the governed projection as ground truth. It cannot mint evidence, change the current phase, approve a waiver, certify an object, or authorize cutover.