Qualify a generated release

View full size

Generation answers “what files did the compiler produce?” Release qualification answers “is this exact candidate ready for the requested proof level?” Airlift keeps those questions separate so a syntactically valid bundle cannot be mistaken for a tested migration.

The release qualification path composes three owners:

Airlift may block on Runway or Experiments. It never changes their release or test state.

1. Generate and verify the candidate

fa migration-ir generate \
  --file migration-ir.json \
  --out-dir generated

fa migration-ir validate \
  --file generated/artifact-set.json \
  --root generated

validate recomputes the artifact-set digest and verifies every materialized path, body, byte length, and SHA-256 digest. It rejects missing files, modified files, duplicate paths, and path traversal.

2. Bind runtime configuration

Generated code contains no credentials. Create a binding-evidence file that maps every required binding name to an immutable reference:

{
  "source_identifier": {
    "system": "databricks",
    "type": "unity_catalog_table",
    "id": "catalog.schema.source_table",
    "digest": "<sha256-of-reviewed-binding>"
  },
  "target_identifier": {
    "system": "databricks",
    "type": "unity_catalog_table",
    "id": "catalog.schema.target_table",
    "digest": "<sha256-of-reviewed-binding>"
  },
  "experiments_profile": {
    "system": "experiments",
    "type": "validation_profile",
    "id": "migration-pipeline-v1",
    "digest": "<sha256-of-profile>"
  }
}

The file contains identifiers and digests, not tokens, passwords, connection strings, or secret values. A required binding without evidence blocks qualification.

3. Dispose every unresolved source node

The generated artifact set lists unresolvedSourceIds. Each one must remain visible until it has a reviewed disposition:

[
  {
    "sourceId": "pipeline:Orders/activity:NotifyExternalSystem",
    "resolution": "remediated",
    "evidenceRef": {
      "system": "airlift",
      "type": "residue_review",
      "id": "<reviewed-residue-id>",
      "digest": "<sha256-of-review-evidence>"
    }
  }
]

Allowed decisions are remediated, accepted_difference, and excluded. Qualification rejects a missing disposition and a resolution for a node outside the candidate.

4. Prove the hermetic candidate

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 reruns byte verification and invokes databricks bundle validate in the materialized directory. Use --databricks-cli <path> when CI pins the Databricks CLI at a non-default path. A non-zero bundle validation, missing executable, missing binding, or unreviewed residue returns a non-zero fa exit code.

Hermetic proof means the candidate is deterministic and locally executable against its synthetic contract. It does not mean the bundle was deployed, its business behavior is equivalent, or a client approved it.

5. Register the immutable candidate

Store artifact-set.json in an admitted immutable store, then register its reference:

fa migration-ir register \
  --file generated/artifact-set.json \
  --engagement-id "$ENGAGEMENT_ID" \
  --estate-id "$ESTATE_ID" \
  --artifact-id "$IMMUTABLE_ARTIFACT_REF" \
  --idempotency-key "adf-release-${SOURCE_REVISION}"

This is the governed Airlift artifact. The ledger stores its reference and digest, not the generated file bodies.

6. Deploy with Runway

Runway stages and deploys the materialized directory:

fr deploy --dir generated

Capture the Runway deployment ID and the staged Runway artifact digest. Add that immutable foreign reference to the Airlift requirement:

{
  "engagementId": "<engagement-id>",
  "estateId": "<estate-id>",
  "operation": "deploy",
  "environment": "dev",
  "artifactIds": ["<airlift-artifact-id>"],
  "requiredState": "succeeded",
  "runwayRequestRef": {
    "system": "runway",
    "type": "deployment",
    "id": "<runway-deployment-id>",
    "digest": "<runway-staged-artifact-sha256>"
  }
}

fa deployment require \
  --file deployment-requirement.json \
  --idempotency-key "adf-release-${SOURCE_REVISION}-dev"

The Airlift worker reads Runway’s authenticated projection API. It rejects a missing deployment, organization mismatch, environment mismatch, staged-artifact digest drift, or non-terminal deployment. Only after those checks does it record and reconcile the Runway observation through governed Airlift actions.

Configure the observer with:

AIRLIFT_DEPLOYMENT_ADAPTER=runway
AIRLIFT_RUNWAY_API_URL=https://<runway-app-origin>
AIRLIFT_RUNWAY_API_TOKEN=<service-credential-reference>

Supply the token through the deployment secret system; never put it in a bundle source, action payload, artifact set, or evidence document.

7. Execute behavioral validation

Create an Airlift validation request for the migrated objects and required readiness tracks:

fa validation run \
  --file validation-request.json \
  --idempotency-key "adf-release-${SOURCE_REVISION}-validation"

The worker compiles object-specific checks and delegates them to Experiments. Workspace qualification requires:

• one completed Experiments execution with no failed objects;
• a passing Experiments run for every requested object;
• every run bound to the candidate artifact-set digest;
• immutable request, run, evidence-manifest, and per-object evidence references; and
• source watermark and target snapshot identities.

See Fabric Experiments integration for the executable case-module and evidence-store boundary.

8. Evaluate workspace proof

Export the governed Airlift artifact, deployment requirement, validation execution, and validation runs, plus the Databricks workspace references asserted by the two service integrations. Put those rows in the workspaceEvidence contract consumed by fa migration-ir qualify.

The contract has two versions. Validation runs recorded against an anchored conversion attempt carry a conversionId, and a document containing them must declare "schemaVersion": 2 at its top level. Documents written before that field existed stay valid unchanged: an untagged document is read as version 1, whose runs carry no conversionId. Mixing the two — an attempt-bound run inside an untagged document — is refused rather than silently accepted, so a version-1 reader never receives version-2 content:

fa migration-ir qualify \
  --file generated/artifact-set.json \
  --root generated \
  --bindings release-bindings.json \
  --resolutions residue-resolutions.json \
  --proof workspace_proven \
  --workspace-evidence workspace-evidence.json \
  --output workspace-qualification.json

The command is a read-only decision tool. It cannot import a caller-authored success into the Airlift ledger. It verifies that:

1. artifact, deployment, and validation share one tenant, engagement, and estate;
2. the Airlift artifact and validation runs use the candidate digest;
3. the deployment is Runway-owned, terminal, and reconciled as matched;
4. Experiments classified every object exactly once with no failure; and
5. deployment and validation name the same Databricks workspace.

If any check fails, maximumProofLevel remains hermetic_proven or contract_only and the report lists exact blockers. Workspace proof is still below client proof and production certification; those require representative client acceptance and current operational, rollback, signing, and cutover evidence.

App workflow

Open Release qualification in the Airlift Databricks App. The screen joins registered ADF artifact sets to their Airlift deployment requirements and Experiments executions. It shows the candidate digest, missing evidence, and deep links to Deployment requirements and Validation laboratory. Release actions remain in Runway, and test execution remains in Experiments.