Residue and discrepancies are normal specialist work. Learn the Fix list, the blocked-reason model, who acts next, recovery actions in the App, and the honesty rule for stale evidence.

When something fails

Something will fail. Unsupported source behavior, a failed independent check, a deployment observation that does not match the requirement — every real migration produces work that automation cannot finish alone. Airlift treats that work as a first-class part of the job, not as an error state:

Connect → Inventory → Scope → Build → Move → Prove → Go-live
              ↘ Fixes (residue / discrepancies) ↗

This page explains the Fix list: how a failure becomes a work item, how the App tells you why progress stopped and who acts next, and the recovery action that clears each item. Follow the guided migration journey first if you have not seen the eight stage workspaces this page builds on.

Failure is a work item, not a dead end

Two kinds of failure land in the Fix list:

Residue. Source behavior the converter could not carry across — an unsupported transaction pattern, a temporary-table idiom, an orchestration construct with no target equivalent. Each case is a named item with an owner, a diagnosis, and the evidence needed to close it.
Discrepancies. A failed required check from an independent validation run against an exact artifact digest. Each discrepancy has a governed disposition path, not a retry button.

Residue and discrepancies are normal specialist work on any real estate. Airlift makes them explicit, assignable, measurable, and independently reviewable instead of hiding them inside an automation percentage. A Fix list with open items is not a broken migration; it is a migration telling the truth about the work that remains.

Read one Fix list item

Every item in the Fix list answers the same questions the stage guidance panel answers:

Why progress stopped. The blocked reason in plain language — what automation could not do, or which independent check failed, and the concrete migration risk of carrying on anyway. Ledger codes and digests stay in the collapsed evidence drawer.
Who acts next. The named owner in a plain role: you, an assigned teammate, the system, or a lead.
Recovery action. One primary action — the exact repair, disposition, or re-observation that can clear the item.
Evidence that clears it. The immutable artifact, passing run, review, or provider observation Airlift must admit. Closing an external ticket never clears the ledger.

Airlift remediation case explaining why automation stopped and the evidence needed to resolve it — A Fix list item names the blocked reason, the owner, and the evidence needed to close it.
What you are seeing
A residue case makes human remediation explicit, assignable, measurable, and independently reviewable.
What to do next
Implement the repair, register the immutable artifact, run validation, and request independent review.
Read the developer workflow

Who acts next

The Fix list names an owner for every item. The same role model applies across stages:

Owner	Acts when	Typical recovery
You (the migrator running the job)	The item needs a repair only a person can design	Implement the fix, register the immutable artifact, request validation
An assigned teammate	The item needs a specialist — a stored-procedure redesign, a schema decision	Take the assignment; the item stays on their list until evidence is admitted
The system	A worker or admitted provider can produce the evidence	Starts the job once you trigger it; Airlift records progression
A lead or second approver	The item needs review, a waiver, or a business decision	Reviews independently; the resolver cannot review their own case

Separation of duties is enforced, not suggested: a resolver cannot review the same case, and a bounded Harness agent may triage a discrepancy but can never accept, resolve, verify, waive, or certify it. Nothing in the Fix list gives an agent an alternative mutation path.

Recovery actions in the App

Each failure type has one primary recovery action. The App never asks you to guess it:

Failure	Recovery action	Evidence that clears it
Conversion residue	Implement the repair, register the immutable artifact, run validation, request independent review	Repaired artifact digest plus a passing validation run and a distinct reviewer
Validation discrepancy	Triage, then accept with a bounded waiver, or resolve and verify	A disposition by the owning role plus a verifying re-run
Blocked or unmatched deployment requirement	Correct the requirement or re-observe the Runway release	A verified observation matching digest, environment, operation, and terminal state
Stale or expired evidence	Refresh the evidence from its source	A new admitted observation bound to the same scope

Each action invokes the same governed Platform action the CLI invokes. A UI click never advances the ledger by itself, and a reopened item keeps its full history.

The honesty rule: a failed refresh never renders fresh

When evidence is refreshed from a provider and the refresh fails or returns only part of the picture, the App keeps showing the last known state as what it is: stale, with the blocked reason attached. A failed or partial evidence refresh never renders as "fresh". You always see one of three honest states:

Observed — admitted evidence bound to this exact scope and digest.
Stale or blocked — the last admitted state, plus the reason the refresh could not complete and who acts next.
Not yet observed — no evidence admitted; a zero means nothing was recorded, not that something succeeded.

Configuration is never evidence. A connected-looking setup, a green provider console, or a closed external ticket does not change what the App renders until Airlift admits the matching observation.

The first path never asks you to paste a digest

Humans repair things; they do not transcribe hashes. The App derives every digest, idempotency key, and scope binding from governed records. The primary recovery path is always a button on the item itself — register this artifact, request this validation, assign this owner. Copying a digest out of one system and pasting it into a form is the advanced fallback, never the first path, and the evidence drawer offers copy-to-clipboard when an integration genuinely needs the value.

Use the CLI with the same truth

The App and fa read the same governed projections, so the Fix list is identical from either surface:

fa residue list --engagement-id <engagement-id> --json
fa residue show <residue-id> --json
fa residue resolve --file residue-resolution.json --idempotency-key residue-resolution-<residue-id> --json
fa discrepancy list --engagement-id <engagement-id> --json
fa discrepancy triage --file discrepancy-triage.json --idempotency-key discrepancy-triage-<discrepancy-id> --json

Use the returned owner, blocked reason, and next action; do not compute a second readiness model in automation. See remediation and residue for the full case lifecycle and validation and readiness for the discrepancy disposition path.

AI assistance boundary

An assistant may explain a Fix list item in more conversational language, summarize the blocked reason, or link the deeper developer article. It reads the same deterministic guidance card you do and must never invent a different next action, approve a disposition, waive a check, certify an object, or close an item without the owning governed Platform action and its required evidence.

When something fails (the Fix list)