Engineering remediation

View full size

A residue case turns a failed or incomplete conversion into managed engineering work. It records why automation stopped, which skills are needed, who owns the next step, any optional delivery forecast, which artifact contains the fix, and which independent validation run supports closure.

This is how Airlift actively helps a migration: automation handles repeatable objects; specialists receive a prioritized, contextual queue for the work that requires judgment; engineering leadership can see remaining effort and commercial treatment without pretending every object was automated.

Airlift Migration Assistant

On a focused blocker, select Ask Migration Assistant. The right-hand drawer starts with the exact residue state already recorded by Airlift, so a developer can ask:

• What should I do next?
• Why did automation stop?
• What evidence clears this blocker?
• How should I diagnose or validate this construct?

The first answer always comes from the governed projection. It identifies the affected object, current residue state, accountable role, next valid control, and evidence needed to unlock the following step. This works even when no model provider is configured.

When a model is configured, a finite Harness agent may explain the failure and suggest bounded diagnostic checks. The preferred provider is Unity AI Gateway or Databricks Model Serving through the App service principal. Airlift sends only a bounded, object-scoped context envelope and redacts common credential-shaped values. Never put credentials in residue text; keep secrets in Databricks secret resources.

An optional Databricks Genie Agent can answer curated migration-analytics questions or return diagnostic SQL through user OBO. Airlift displays that SQL for review and never executes it automatically.

Configure the Migration Assistant

1. Open Advanced tools → Migration Assistant and inspect the three readiness cards.
2. Prefer a Unity AI Gateway model service or Model Serving endpoint and grant the App service principal access.
3. Bind AIRLIFT_GENIE_PROVIDER, AIRLIFT_GENIE_MODEL, and the inference mode during deployment. For an external provider, bind AIRLIFT_GENIE_API_KEY from a Databricks secret resource; do not enter it in Airlift.
4. Ask a known blocker question and verify the response labels its provider.
5. Remove model access and verify the same question safely falls back to Airlift ledger.

See the Airlift Migration Assistant developer guide for exact bundle commands, external-provider settings, permissions, and failure behavior.

State machine

A rejected review returns the case to assigned and clears the prior resolution fields. The assignee must submit a new artifact/evidence pair. The resolver cannot review the same case. Agent and system principals cannot assign commercial work or review closure.

The state transitions are the Platform actions airlift.residue_create, airlift.residue_estimate, airlift.residue_assign, airlift.residue_resolve, airlift.residue_review, and airlift.residue_cancel.

Conversion-hazard cases

The conversion_hazard category (residue contract v2) tracks converter output that was reported as converted but proven invalid or silently lossy by the qualified hazard scan — see conversion hazards for the hazard codes. Each case carries a required typed origin (conversionId, assessmentDigest, findingCodes) binding it to one exact conversion attempt and one exact scan result; deduplication is origin-exact, so a new conversion attempt or re-scan opens a new case and an older reviewed case never unlocks newer output. The trusted worker opens these cases automatically; people assign, resolve (with a repaired target_code artifact for the same object), and review them.

While the exact-origin case is not independently reviewed, airlift.conversion_hazard_gate.v1 blocks parity certification, migration-certificate minting, and cutover for the object. A certification request denied by the gate stays denied under its original idempotency key: after the approved review, submit the certification again with a fresh idempotency key — replaying the old key returns the recorded denial, by design.

1. Create and classify

Create residue-create.json:

{
  "engagementId": "eng_01J00000000000000000000000",
  "objectId": "obj_01J00000000000000000000002",
  "category": "unsupported_construct",
  "lane": "human",
  "summary": "Rewrite dynamic SQL for Databricks SQL",
  "detail": "The deterministic pass cannot prove identifier construction semantics.",
  "requiredSkills": ["T-SQL", "Databricks SQL"],
  "commercialAttribution": "managed_service"
}

fa residue create --file residue-create.json --idempotency-key object-2-residue-1
fa residue list --engagement-id eng_01J00000000000000000000000

Categories are unsupported_construct, compile_failure, validation_failure, missing_semantics, security_design, consumer_change, client_decision, and conversion_hazard (worker-created with a required exact origin — see conversion-hazard cases). Use the agent lane only when the input fits the bounded repair contract. Use human when semantic judgment, client choice, security design, or cross-system work is required.

Commercial attribution is explicit: included, change_request, client_owned, or managed_service. This field does not invoice a client; it gives delivery and commercial systems an auditable source for downstream reporting.

2. Assign an owner

Assignment is the first required remediation action. A delivery lead can assign an open case directly; developers do not need to estimate project effort before beginning work.

{
  "residueId": "res_01J00000000000000000000000",
  "assignedToRef": {
    "system": "delivery_directory",
    "type": "team",
    "id": "sql-modernization"
  },
  "workRef": {
    "system": "work_manager",
    "type": "work_item",
    "id": "MIG-142"
  }
}

fa residue assign --file residue-assign.json --idempotency-key residue-1-assignment-v1

The work manager owns task coordination. Airlift stores only the foreign reference. A task being marked complete never advances the residue state; closure requires the Airlift resolution and review actions below.

Optional: record a delivery forecast

Effort is planning metadata owned by a delivery lead. It supports staffing, commercial reporting, and estimate-versus-actual analysis, but it does not clear a technical gate. Record it before assignment when the program needs it:

{
  "residueId": "res_01J00000000000000000000000",
  "estimateMinutes": 240,
  "requiredSkills": ["T-SQL", "Databricks SQL"]
}

fa residue estimate --file residue-estimate.json --idempotency-key residue-1-estimate-v1

Re-estimation while estimated creates another governed event. Dashboards report the latest projection and retain the audit history for variance analysis.

3. Resolve with artifact and validation evidence

First register the repaired artifact with fa artifact register. Then create residue-resolve.json:

{
  "residueId": "res_01J00000000000000000000000",
  "resolvedArtifactId": "art_01J00000000000000000000000",
  "resolutionEvidenceRef": {
    "system": "experiments",
    "type": "validation_run",
    "id": "repair-validation-42",
    "digest": "VALIDATION_EVIDENCE_SHA256"
  },
  "actualMinutes": 210,
  "resolutionNotes": "Replaced identifier construction with an explicit mapping and passed compile and business scenarios."
}

fa residue resolve --file residue-resolve.json --idempotency-key residue-1-resolution-v1

Airlift verifies that the artifact belongs to the same engagement and object. The validation reference is provenance, not a caller-authored parity verdict; certificate admission still uses the configured Experiments evidence registry and readiness actions.

4. Review independently

{
  "residueId": "res_01J00000000000000000000000",
  "decision": "approved",
  "reviewNotes": "Artifact lineage and required validation scenarios reviewed."
}

fa residue review --file residue-review.json --idempotency-key residue-1-review-v1

Use rejected to return the case to the assignee. The API denies self-review even when a principal otherwise holds the review permission.

Exercise review in a development App

An explicitly configured development App may allow the resolver to approve the same case so one developer can exercise the complete workflow:

AIRLIFT_DEPLOYMENT_ENV=dev
DATABRICKS_APP_NAME=<product>-dev
AIRLIFT_ALLOW_DEVELOPMENT_SELF_REVIEW=1

All three conditions are required. If the flag appears under a non-dev deployment name or an App name that does not end in -dev, Airlift fails startup. The action still requires a natural-person workspace identity and airlift:residue:review; it does not bypass authorization. Airlift records reviewMode: development_self_review and labels the override in the App. Only an admitted system principal may use it to mint an explicitly development migration certificate, and production cutover always rejects that assurance mode. Staging and production continue to require a distinct reviewer.

Cancel when scope changes

fa residue cancel --file residue-cancel.json --idempotency-key residue-1-cancel

The migration remains blocked after cancellation unless another governed decision covers the object. Cancellation requires a reason and explicit confirmation in the App and is available only before resolution. Excluding the migration object is a separate governed decision; cancelling a residue does not silently exclude or certify the object.

App workflow and leadership metrics

Choose Open remediation case from an engagement status page to open Remediation already filtered to that engagement and scrolled to the exact case. Each case shows the complete resolution path even when later controls are unavailable:

1. assign a remediation owner;
2. register the repaired artifact;
3. attach Experiments validation evidence;
4. submit for independent review; and
5. record the independent review.

The current step is identified explicitly. Later steps remain visible as locked instead of disappearing. For example, an assigned case without an artifact displays A repaired artifact is required and links to the artifact registration form with the engagement and object preselected.

The focused case explains the affected object, unresolved behavior, risk of bypassing the issue, next owner, and evidence required to continue. The App renders one primary action for the current state. Optional delivery forecasting is collapsed. Cancellation is hidden in a red danger zone and remains disabled until the operator supplies a reason and confirms that cancellation does not resolve the migration blocker.

Open the organization-wide Remediation entry when you want to see work across all engagements. It shows human and agent lanes, active case count, estimated hours, commercial treatment, skills, external work references, and evidence status. Delivery leads assign and may forecast; engineers register repair evidence; a separately authorized approver records review.

Useful operating measures include active residue by category, estimated versus actual minutes, aging by state, first-pass conversion rate, repair validation pass rate, and review rejection rate. Never report an unmeasured time-savings percentage: use recorded benchmark observations and delivery actuals.