Register migration artifacts

Artifact registration tells Airlift exactly what output was produced, where its bytes live, and which immutable content version must be validated, deployed, and reviewed. It is not a file upload and it is not a claim that the migration is correct.

Airlift always stores four things:

1. the migration engagement and object the output belongs to;
2. an opaque reference to the system that owns the bytes;
3. a SHA-256 fingerprint of the exact bytes;
4. the tool and version that produced them.

This prevents a ticket, mutable branch, or converter success message from being treated as proof. Validation, release, review, and certification can all bind to the same digest.

Artifacts produced by a normalized source extractor may additionally use the strict v2 workbench envelope. It records construct, automation disposition, target pattern, source-fragment digest, dependencies, warnings, and extractor provenance. Those are declared routing facts, not execution or validation proof. If no active registry cell matches the exact source variant, artifact kind, and construct, the App, API, and fa render no governed capability claim rather than inferring support.

For catalog-governed Synapse constructs, the registration action also resolves the bound estate and requires an exact repository catalog row for source variant, artifact kind, and construct. The declared disposition and target prefix must match that row. This write-time gate prevents newly registered workbench metadata from drifting away from the assessment and conversion route. It does not upgrade the artifact's evidence or support level.

Catalog constructs are source-bound: an ADF/Synapse construct cannot be registered against a Teradata or other source estate. Historical catalog claims without an estate binding are also shown as requiring review rather than silently treated as ungoverned.

View full size

What should I register for a repaired conversion?

Register the finalized output that preserves the missing source behavior:

• repaired SQL or stored procedure → target_code;
• repaired Python, Scala, notebook source, or dbt model → target_code;
• Databricks job, pipeline, cluster, Unity Catalog grant, or other declarative setting → target_configuration;
• executable regression or parity scenario → test;
• validation result or signed comparison report → evidence.

For the remediation flow shown in the App, choose Target code unless the repair consists only of configuration. Store the file in a durable provider first—normally a Unity Catalog Volume, a pinned source-control commit, or an immutable release—and then register its reference.

Artifact kinds

Kind describes the artifact's role in the migration. It does not describe where it is stored.

Field reference

The App renders a neutral Registry-correlated route only when the artifact and an active construct cell agree on source variant, artifact kind, construct, extractor/provider generation, target pattern, and automation disposition. That correlation explains the declared route; it is not execution or validation proof. A caller-declared label, mismatched producer, or mismatched route remains uncorroborated.

The App separately renders Catalog-aligned route when the immutable row still agrees with the current repository catalog. A diverged or removed historical route produces a visible review warning and recovery link; replay is preserved, and the warning never silently edits the original event. Registry correlation and catalog alignment are distinct, non-proof signals.

Never put credentials, tokens, signed URLs, connection strings, or code bodies in a reference field. Airlift records lineage; the provider remains responsible for storage and access.

Calculate the digest

Calculate SHA-256 after the final edit and from the same bytes addressed by the provider reference.

sha256sum repaired-output.sql

shasum -a 256 repaired-output.sql

Copy only the 64-character lowercase digest. If the file changes, calculate a new digest and register a new artifact. Do not update the existing artifact row.

Register from the App

1. Open the blocked remediation case.
2. Select Register repaired artifact.
3. Confirm the object and choose the artifact kind.
4. Enter the provider reference.
5. Calculate and enter the SHA-256 digest.
6. Record the media type and producer generation.
7. Select Register immutable reference.

When registration succeeds, the App returns to the same remediation case. The next step changes to independent validation and review; registration alone does not clear the gate.

Register from the CLI

Create artifact.json:

{
  "engagementId": "eng_01J00000000000000000000000",
  "objectId": "obj_01J00000000000000000000001",
  "kind": "target_code",
  "name": "Repaired customer balance procedure",
  "artifactRef": {
    "system": "databricks",
    "type": "volume_object",
    "id": "/Volumes/<catalog>/<schema>/<volume>/repaired-customer-balance.sql"
  },
  "digest": "YOUR_64_CHARACTER_SHA256",
  "mediaType": "application/sql",
  "toolVersion": "human-remediation@1"
}

Then invoke the governed mutation:

fa artifact register \
  --file artifact.json \
  --idempotency-key repaired-customer-balance-v1

fa artifact list --object-id obj_01J00000000000000000000001

The idempotency key makes retries safe. The command records the same governed airlift.artifact_register action as the App.

For the native ADF/Synapse path, emit strict v2 registration files alongside the generated Databricks files:

fa migration-ir generate \
  --file migration-ir.json \
  --out-dir generated \
  --engagement-id "$ENGAGEMENT_ID" \
  --estate-id "$ESTATE_ID" \
  --artifact-ref-prefix "/Workspace/Shared/airlift/generated"

for registration in generated/registration/*.json; do
  registration_digest=$(sha256sum "$registration" | cut -d' ' -f1)
  fa artifact register \
    --file "$registration" \
    --idempotency-key "adf-$registration_digest"
done

Only artifacts tied to deterministic IR nodes receive registration files. Repairable, human-only, excluded, and blocked nodes stay in remediation; generation never silently promotes them into governed artifacts.

Complete a blocked repair from the CLI

Artifact registration is one step in a governed remediation, not the end of the repair. Use this sequence when the App says that a converted object is waiting for a repaired artifact:

export AIRLIFT_API_URL="https://your-airlift-app.example"
export DATABRICKS_TOKEN="$(databricks auth token --profile <profile> --output json | jq -r .access_token)"

# 1. Read the exact object, reason automation stopped, current owner, and required skills.
fa residue show "$RESIDUE_ID" --json

# 2. Put the final repaired bytes in durable storage and calculate their digest.
databricks fs cp repaired-output.sql \
  "dbfs:/Volumes/<catalog>/<schema>/<volume>/repairs/repaired-output.sql" \
  --profile <profile> --overwrite
sha256sum repaired-output.sql

# 3. Register the immutable provider reference and capture Airlift's artifact ID.
fa artifact register \
  --file artifact.json \
  --idempotency-key "$RESIDUE_ID-artifact-v1" \
  --json
fa artifact list --object-id "$OBJECT_ID" --json

# 4. Request validation against this object and artifact generation.
fa validation run \
  --file validation-request.json \
  --idempotency-key "$RESIDUE_ID-validation-v1"
fa validation list --engagement-id "$ENGAGEMENT_ID" --json

# 5. After the admitted validation run passes, submit the artifact and evidence pair.
fa residue resolve \
  --file residue-resolution.json \
  --idempotency-key "$RESIDUE_ID-resolution-v1"

# 6. A different authorized natural person records the independent review.
fa residue review \
  --file residue-review.json \
  --idempotency-key "$RESIDUE_ID-review-v1"

The CLI token is short lived. Do not save it in artifact.json, a shell history file, or the Airlift provider reference. The reference identifies the stored bytes; it is never a download credential.

If a validation provider is not installed, step 4 fails closed. A developer may still register the artifact and inspect it in the App, but must not substitute a ticket, local test result, or caller-authored passed value for admitted validation evidence.

What appears in the App

Open the engagement and select Artifacts to see the readable name, kind, object, provider reference, SHA-256 digest, media type, producer generation, normalized construct, declared route, warnings, registry corroboration, and downstream validation or release requirements. Open Run ledger to trace the governed registration and later validation execution. Return to Resolve conversion issues to see the next required action. The case advances only after the stored artifact, admitted validation, resolution, and independent review refer to the same governed object.

The shared App/API/CLI parity field set is artifactId, kind, construct, automationDisposition, targetPattern, digest, mediaType, toolVersion, and workspaceEvidence. JSON uses these exact names. Text output renders the same values in that order; legacy artifacts render visible unclassified placeholders instead of invented construct or routing data.

What happens next?

The assigned engineer requests an Experiments-backed validation run against this exact digest. After passing evidence is admitted, the engineer submits the remediation case for independent review. A different authorized principal approves or rejects it. Only then can the conversion gate advance.

See Engineering remediation for the complete state machine and Build and run validation suites for the validation request, provider contract, and result inspection commands. See Conversion factory for batch and attempt lineage.

LLM-readable documentation

The concise documentation index is available at /llms.txt. The complete developer corpus, including this guide and every code example above, is available at /llms-full.txt. Individual pages also expose Markdown through the Copy Markdown control. These exports contain public developer guidance only; deployment identifiers, client data, credentials, and internal evidence ledgers are intentionally excluded.