Build a migration project

Use this workflow in a migration repository. Airlift supplies the source contract and assurance lifecycle; your integration supplies authenticated source, Databricks, transfer, validation, and client-effect adapters.

1. Pin the profile and plan

mkdir -p .airlift
fa source inspect dynamics_365 --json > .airlift/source-profile.json
fa source plan dynamics_365 \
  --variant dynamics_365_finance_operations \
  --json > .airlift/source-plan.json
fa actions --json > .airlift/actions.json
fa profiles --json > .airlift/validation-profiles.json

Commit these non-secret artifacts. They make source-pack and policy upgrades reviewable. Do not commit tokens, passwords, keys, or connection strings.

2. Implement the specialist boundaries

Read profile.adapter and plan.steps[].specialistCommands. The plan names the required boundary; it does not invent a connector command.

import { resolveSourceSystemProfile } from '@fabricorg/airlift';

const profile = resolveSourceSystemProfile('d365');

export const sourceAdapter = {
  async inventory(connectionRef: string) {
    // Resolve the opaque ref inside the authenticated connector boundary.
    // Return artifact refs, digests, source version, entities, and dependencies.
  },
  async transfer(connectionRef: string, checkpoint?: string) {
    // Return snapshot, cursor/watermark, deletion, restart, lag, and count evidence.
  },
};

console.log(profile.adapter.inventoryInputs);
console.log(profile.adapter.validationInputs);

For SQL sources, generated steps contain applicable Lakebridge commands. For ERP and SaaS systems, use the admitted managed connector or API/export adapter. For ETL systems, export pipeline definitions. For query engines, route each backing catalog. For streams, retain offset or sequence boundaries and checkpoint evidence.

3. Create governed estate state

Actor and tenant come from the authenticated application boundary, never a CLI flag or request payload.

import { AIRLIFT_ACTION_IDS } from '@fabricorg/airlift';

const estate = await runtime.invokeAction(AIRLIFT_ACTION_IDS.estateRegister, {
  ...authenticatedContext,
  idempotencyKey: 'finance-source-estate-v1',
  params: {
    name: 'Finance source',
    sourceSystem: 'dynamics_365',
    sourceVariant: 'dynamics_365_finance_operations',
    environment: 'prod',
    owner: 'finance-data',
    connectionRef: 'uc-connection://finance-source',
  },
});

Start and record the assessment, then register normalized entities, tables, pipelines, reports, or other in-scope artifacts with objectRegister. Reuse stable idempotency keys for logical retries.

4. Produce target artifacts and residue

Use Lakebridge for supported SQL conversion, a typed target mapper for applications, a pipeline implementation adapter for ETL, or a stream bootstrap adapter for event systems. Record each attempt through conversionStart and conversionRecord. Unsupported constructs stay in deterministic, bounded-repair, or human-owned lanes. An artifact is not parity evidence.

5. Move and validate independently

Movement returns source boundary, target snapshot, restart, lag, and reconciliation evidence. Validation runs separately through an admitted provider and tests the assigned object-type profile: schema or contract, data, business behavior, security, consumers, and non-functional thresholds.

Record the immutable provider execution with validationRunRecord; link it to each requirement with readinessRecord. businessAccept is a separate governed decision by an admitted natural person.

6. Mint, freeze, and cut over

Only the admitted system principal invokes migrationCertificateMint. Plan a wave, assign certified objects, freeze its evidence, collect authenticated approvals, and run automated cutover only through a client-certified checkpoint/apply-once/verify/rollback effector.

fa certificate verify migration-certificate.json \
  --keys trusted-public-keys.json

7. Add scheduled source-pack regression

Hermetic source contracts run without credentials:

pnpm test:e2e:source
pnpm test:e2e:hermetic

Live adapter jobs should publish a source-certification manifest and run:

AIRLIFT_LIVE_SOURCE_MANIFEST=source-certification.json pnpm test:e2e:live

Missing inventory, transfer, validation, scale, or cutover-effector evidence fails closed for the requested support level.