Build an accepted inventory, dependency graph, Databricks target blueprint, wave scenario, and immutable assessment pack through Airlift.

Assessment to frozen plan

This tutorial exercises Airlift's authenticated F1 workflow. It starts with a registered estate and active engagement, admits a normalized assessment, records dependency edges, accepts the scope, generates a Databricks target scenario, and freezes the selected plan.

The CLI is a remote client. Set the URL of your deployed Airlift Databricks App and a Databricks OAuth token first:

export AIRLIFT_API_URL="https://your-airlift-app.example"
export DATABRICKS_TOKEN="<short-lived-oauth-token>"
npx --yes --package @fabricorg/airlift-cli@0.18.4 fa version

The API derives the actor and organization from authenticated Databricks identity. None of the following requests contains an actor or tenant field.

1. Register the estate

Create estate.json:

{
  "name": "Synthetic Synapse warehouse",
  "sourceSystem": "synapse",
  "owner": "migration-team@example.test",
  "environment": "prod",
  "priority": "priority",
  "connectionRef": "databricks-connection://migration/synapse-metadata"
}

fa estate register --file estate.json --idempotency-key tutorial-estate-1 --json
fa estate list --json

Copy the returned estateId. Add it to the estateIds array in an engagement create file, then create and activate the engagement. See Engagements and connections for that request.

2. Run and record the assessment

The Airlift worker composes the source adapter. assessment_start records the governed request; assessment_record admits the immutable result produced by that adapter.

assessment-start.json

{
  "estateId": "est_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "toolVersion": "lakebridge@0.14.x",
  "requestRef": "synthetic-assessment-001"
}

fa assessment start \
  --file assessment-start.json \
  --idempotency-key tutorial-assessment-start-1 \
  --json

The configured worker normally records the result. Adapter developers can test the same contract with a synthetic assessment-record.json:

{
  "assessmentId": "asm_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "estateId": "est_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "jobRunRef": "jobs/run/synthetic-001",
  "reportRef": "volume://airlift/tutorial/assessment.json",
  "reportDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "inventoryDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "dependencyDigest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "toolVersion": "lakebridge@0.14.x",
  "objectCounts": {
    "tables": 1,
    "views": 1,
    "storedProcedures": 0,
    "etlJobs": 1,
    "other": 0
  }
}

fa assessment record \
  --file assessment-record.json \
  --idempotency-key tutorial-assessment-record-1

On later runs, Airlift compares the newly admitted inventory and dependency digests with the preceding assessment for the same estate. Discover → Assessment studio displays per-category object-count deltas and makes digest drift an explicit review state. Missing digests are treated as drift, not as proof that nothing changed.

Register normalized objects through airlift.object_register. Each object records its type, source identity, complexity, and assessment reference. Supported inventory types include tables, views, routines, ETL jobs, notebooks, reports, semantic models, ML assets, security objects, and external dependencies.

fa inventory register --file object-table.json --idempotency-key tutorial-object-table
fa inventory register --file object-job.json --idempotency-key tutorial-object-job
fa inventory list --estate-id est_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --assessment-id asm_01ARZ3NDEKTSV4RRFFQ69G5FAV --json

3. Build and accept the dependency graph

A dependency graph is created with an expected edge count. Adapters then submit batches of at most 500 secret-free edges. Airlift validates every object reference, rejects self-references and duplicates, and refuses acceptance until the declared count is complete.

The governed action sequence is dependency_graph_start, dependency_batch_record, then dependency_graph_accept. The CLI commands below submit those exact actions through the authenticated API.

graph-start.json

{
  "engagementId": "eng_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "assessmentId": "asm_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "expectedEdgeCount": 1,
  "graphRef": {
    "system": "lakebridge",
    "type": "dependency_graph",
    "id": "synthetic-graph-001"
  },
  "toolVersion": "lakebridge@0.14.x"
}

graph-batch.json

{
  "dependencyGraphId": "dpg_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "edges": [
    {
      "fromObjectId": "obj_01ARZ3NDEKTSV4RRFFQ69G5FAW",
      "toObjectId": "obj_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "kind": "data",
      "confidence": 1,
      "critical": true
    }
  ]
}

fa inventory graph start --file graph-start.json --idempotency-key tutorial-graph-start
fa inventory graph record --file graph-batch.json --idempotency-key tutorial-graph-batch-1
fa inventory graph show dpg_01ARZ3NDEKTSV4RRFFQ69G5FAV --json

Graph acceptance is a human-authority operation:

graph-accept.json

{
  "dependencyGraphId": "dpg_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "expectedEdgeCount": 1
}

fa inventory graph accept \
  --file graph-accept.json \
  --idempotency-key tutorial-graph-accept

A cycle does not disappear. Airlift records it as an explicit planning blocker that must be dispositioned before plan freeze.

4. Accept the normalized scope

Assessment acceptance recomputes the normalized inventory digest from projected objects and binds it to the accepted dependency digest, exclusions, assumptions, engagement, and authenticated reviewer.

The assessment_accept action is a natural-person decision; the CLI submits it as fa assessment accept.

assessment-accept.json

{
  "assessmentId": "asm_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "engagementId": "eng_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "dependencyGraphId": "dpg_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "expectedObjectCount": 3,
  "exclusions": [],
  "assumptions": [
    "A representative production validation window is available."
  ]
}

fa assessment accept \
  --file assessment-accept.json \
  --idempotency-key tutorial-assessment-accept

Service accounts and agents may record assessment and graph proposals, but they cannot accept the graph or scope.

5. Generate and compare delivery scenarios

plan_generate maps every in-scope object type to a Databricks target pattern, performs a topological wave grouping, exposes cycles, and calculates effort and value from the provided assumptions. The calculations remain visible in the returned plan; they are not a hidden percentage claim.

The governed sequence is plan_generate, plan_select, then plan_freeze. Selection and freeze require human authority; generation may be performed by admitted automation.

plan-generate.json

{
  "engagementId": "eng_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "assessmentId": "asm_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "name": "Parity-first delivery plan",
  "scenario": "parity_first",
  "targetWorkspaceRef": {
    "system": "databricks",
    "type": "workspace",
    "id": "synthetic-target"
  },
  "maxObjectsPerWave": 100,
  "economics": {
    "manualHoursPerComplexityPoint": 8,
    "assistedHoursPerComplexityPoint": 3,
    "blendedHourlyCostUsd": 180,
    "sourceMonthlyRunCostUsd": 25000,
    "targetMonthlyRunCostUsd": 18000,
    "dualRunMonths": 2
  },
  "assumptions": [
    "Unity Catalog prerequisites are complete before Wave 1."
  ]
}

fa plan generate --file plan-generate.json --idempotency-key tutorial-plan-parity
fa plan compare --engagement-id eng_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa plan select pln_01ARZ3NDEKTSV4RRFFQ69G5FAV --idempotency-key tutorial-plan-select

Freeze the engagement scope before freezing its selected plan:

fa engagement freeze eng_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --idempotency-key tutorial-engagement-freeze
fa plan freeze pln_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --idempotency-key tutorial-plan-freeze

The frozen digest binds engagement scope, accepted inventory, dependencies, target workspace reference, target mappings, wave candidates, economics, assumptions, and risks.

6. Export the assessment pack

assessment-export.json

{
  "estateId": "est_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "reason": "Record the accepted discovery and selected delivery scenario."
}

fa assessment export \
  --file assessment-export.json \
  --idempotency-key tutorial-assessment-export \
  --json

The content-digested pack includes the estate, accepted assessment, normalized inventory, dependency graph and edges, applicable plan scenarios, generation time, and governance revision.

Databricks App views

The same state is available in two authenticated pages:

Discover → Assessment studio shows runs, inventory, graph edges, blockers, acceptance, and immutable export.
Plan → Target blueprint and wave planner shows target services, mappings, wave prerequisites, economics, scenario selection, and freeze evidence.

Both pages invoke the same Platform actions used by the CLI. A UI action cannot bypass schema validation, authorization, tenant isolation, policy, idempotency, or audit.

Failure and recovery behavior

Condition	Result	Recovery
unknown or cross-estate object in an edge	blocked	correct the normalized object mapping and submit a new batch
duplicate edge	blocked	remove the duplicate; do not change the idempotency key to force it through
incomplete edge count	blocked	record the remaining batches or start a corrected graph
inventory count or digest changed	conflict	reload the current assessment projection and review drift
dependency cycle	plan generated with blocker	disposition or redesign the cycle, then generate a new scenario
agent or service account attempts acceptance	forbidden	an admitted natural-person operator performs the decision
plan selected before scope freeze	selection allowed, freeze blocked	freeze the engagement, then retry the same logical freeze safely
adapter or API unavailable	exit `6`	retry with the same stable idempotency key after the dependency recovers

Scope acceptance also requires the operator to choose the engagement explicitly. Airlift never infers acceptance authority from whichever engagement happens to appear first.

This workflow produces planning evidence. It does not certify conversion, data parity, deployment, or production cutover; those use their own evidence profiles and gates.

Assessment to frozen plan

On this page