Build and run validation suites

Airlift's validation laboratory is executable orchestration, not a checklist. For each converted object it combines the assigned object profile, artifact digest, requested readiness tracks, and migration scope into a deterministic suite specification. The worker sends that specification to Fabric Experiments, admits the returned immutable evidence, updates readiness, and creates discrepancies for failed required checks.

Use the laboratory after conversion, transfer, and target deployment have produced the artifacts and snapshots you want to judge.

View full size

1. Find eligible objects

fa inventory list --estate-id "$ESTATE_ID" --json \
  | jq '.rows[] | select(.state == "converted" or .state == "certified")'

fa profiles --json

Every selected object needs a versioned validation-profile assignment. The profile says which of the nine readiness tracks are required; it does not assert that any track has passed.

2. Request a validation execution

Create validation-request.json:

{
  "engagementId": "eng_01J00000000000000000000000",
  "estateId": "est_01J00000000000000000000000",
  "waveId": "wav_01J00000000000000000000000",
  "objectIds": [
    "obj_01J00000000000000000000000",
    "obj_01J00000000000000000000001"
  ],
  "suiteVersion": "client-regression-suite@3",
  "requestedTracks": [
    "code",
    "data_movement",
    "functional_parity",
    "non_functional"
  ],
  "reason": "Validate the Wave 2 candidate before certificate evaluation."
}

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

The command creates Airlift-owned scope and request state. In Temporal mode the Airlift worker starts validationWorkflowV1, which delegates each generated suite to the configured Experiments runner. Repeating the same logical start attaches to the same workflow ID.

3. Implement the Experiments runner

The worker expects three callbacks through ExperimentsValidationAdapter:

npm install @fabricorg/airlift@0.16.0 @fabricorg/airlift-worker@0.14.0

import { ExperimentsValidationAdapter } from '@fabricorg/airlift-worker/validation';

const adapter = new ExperimentsValidationAdapter({
  begin: async (request) => {
    // Create or attach to one Experiments request using request.idempotencyKey.
    return { providerRequestRef };
  },
  run: async ({ suite, idempotencyKey }) => {
    // Execute suite.requiredChecks against the source watermark and target snapshot.
    // Persist the complete LiveEvidence document before returning its immutable ref.
    return { providerRunRef, evidenceRef, evidence, sourceWatermark, targetSnapshot };
  },
  complete: async ({ results, idempotencyKey }) => {
    // Persist a manifest containing every object result and return its digest.
    return { providerRunRef, evidenceManifestRef, evidenceManifestDigest };
  },
});

Also provide validationEvidencePublisher. It must write the evidence body and registry entry before Airlift invokes validation_run_record. With no publisher, validation fails closed. The built-in stub is for hermetic tests only and identifies its output as synthetic.

Common generated checks cover compilation, dynamic SQL and cast behavior, row counts, checksums, null/decimal/time-zone/collation semantics, deletes and restart behavior, business queries, errors, performance, cost, security, concurrency, deployment drift, acceptance, and rollback readiness. Your runner maps those stable check IDs to concrete source and Databricks assertions.

4. Inspect results and readiness

fa validation runs --object-id "$OBJECT_ID" --json
fa validation readiness --object-id "$OBJECT_ID" --json
fa discrepancy list --object-id "$OBJECT_ID"

An Experiments run can pass or fail. Airlift stores the provider run reference, evidence reference and SHA-256 digest, artifact digest, source watermark, target snapshot, tool version, verdict, and admitted producer. A passing run is still only evidence for the tracks explicitly linked to it.

5. Triage and remediate a failure

fa discrepancy show "$DISCREPANCY_ID" --json
fa discrepancy triage \
  --file discrepancy-triage.json \
  --idempotency-key "$DISCREPANCY_ID-triage-v1"
fa discrepancy resolve \
  --file discrepancy-resolution.json \
  --idempotency-key "$DISCREPANCY_ID-resolution-v1"

The bounded Harness triage agent may propose category, severity, disposition, and a rationale. Its only admitted mutation is airlift.discrepancy_triage. It cannot accept a difference, submit evidence, waive a requirement, mint a certificate, or change release state.

Low and medium differences may be accepted by an authorized natural person who did not triage the same discrepancy. High and critical differences are non-acceptable and must be remediated. Resolution does not close the discrepancy: discrepancy_verify requires a separately admitted, passing Experiments run for the same object and matching provider evidence identity.

6. Evaluate certificate readiness

fa certificate list --object-id "$OBJECT_ID"
fa certificate mint \
  --file certificate-mint.json \
  --idempotency-key "$OBJECT_ID-certificate-v1"

Certificate minting is normally performed by the admitted worker after it recalculates the profile and readiness digests. The action fails if required evidence is pending, failed, stale, or not covered by an approved and unexpired waiver. Business acceptance remains a separate human decision. The resulting envelope is signed and names exactly the profile, artifacts, snapshots, provider evidence, policy revision, and tool versions it covers.

Use the Validation laboratory screen for executions and discrepancy actions. Use the Assurance center for the readiness matrix, certificates, waivers, and evidence-pack exports.