Conversion to remediation tutorial

This tutorial starts after assessment acceptance and planning. It uses synthetic identifiers and JSON files so you can exercise the remote API without placing source code, credentials, or client details in the command payload.

Prerequisites

You need an active engagement, an accepted assessment, and at least one object in planned or rework. Configure AIRLIFT_API_URL and a short-lived DATABRICKS_TOKEN, then confirm the resources visible to your authenticated organization:

fa engagement list
fa assessment list
fa inventory list --assessment-id <assessment-id>

Run the factory path

1. Create a batch with fa conversion batch create --file batch.json.
2. Start it with fa conversion batch start --file batch-start.json.
3. For each object, call fa conversion attempt start, execute your adapter, then call fa conversion attempt record.
4. Register successful output using fa artifact register.
5. Create a residue for each failed object.
6. Reconcile with fa conversion batch complete.

The batch completes only after Airlift can account for every object. If a converted attempt's output digest has no matching target artifact, or a failed attempt has no active residue, reconciliation is blocked with an actionable error.

Complete the human path

fa residue assign --file assignment.json --idempotency-key example-assignment
fa artifact register --file repaired-artifact.json --idempotency-key example-repair-artifact
fa residue resolve --file resolution.json --idempotency-key example-resolution
fa residue review --file review.json --idempotency-key example-review

Assignment works directly from open. A delivery lead may record an optional forecast first with fa residue estimate; it is planning metadata, not a developer prerequisite.

Use a different admitted person for review than for resolve. Use an Experiments run reference in the resolution file. Review closes the engineering case; it does not mint a migration certificate. Continue with validation.

Inspect in the App

Open Conversion to see batch and attempt lineage. Open Remediation to see the human/agent lanes, effort, skills, assignment, external work reference, artifact, and review status. Refreshing or replaying the event stream reconstructs the same projections.

Expected denial checks

Verify these before connecting real scope:

• duplicate object IDs are rejected at batch creation;
• an object outside the accepted assessment is rejected;
• starting an attempt with a different converter generation is rejected;
• batch completion blocks on missing attempts or artifacts;
• an agent cannot assign or review remediation;
• a resolver cannot review the same residue;
• a foreign-organization artifact, batch, or residue ID is not readable or mutable.

These are production controls, not optional tutorial assertions.