Deploy Airlift

An Airlift installation has four runtime responsibilities:

The console is not the worker. Keep interactive request handling separate from durable orchestration so a console deployment cannot interrupt an active migration workflow.

Validate the Asset Bundle

The repository contains a declarative Databricks Asset Bundle:

pnpm validate:databricks
databricks bundle validate -t <target>
databricks bundle deploy -t <target>

Bundle variables supply environment-specific resource names and references. Do not commit workspace URLs, access tokens, client secrets, warehouse IDs, database passwords, or signing keys.

Configure durable storage

Production installations use AIRLIFT_STORE=postgres. Bind either a Databricks Lakebase resource or a compatible PostgreSQL connection, then run schema creation as an explicit controlled-startup step:

const store = await createAirliftStoreFromEnv(process.env);
await store.ensureSchema();

Schema creation must not happen as an import side effect. Run it once during controlled startup for both the console and worker composition roots.

Configure identity and authorization

The Databricks App authenticates the workspace user before resolving display labels from forwarded headers. The application derives actor and organization from authenticated server context; neither value may come from form data, action parameters, workflow signals, or CLI flags.

Production startup requires:

• a tenant-scoped authorization directory;
• admitted worker and validation-provider principals;
• Databricks App identity verification;
• an immutable evidence registry;
• an Ed25519 signing key stored through a deployment secret reference.

Use security configuration and fa doctor to validate the configuration shape.

Configure Lakebridge jobs

Provision assessment and conversion jobs in the target workspace. Airlift records job run IDs, tool versions, output references, and digests; reports and converted artifacts remain in workspace-controlled artifact storage.

Required adapter settings include the job IDs, an artifact-volume root, the accepted Lakebridge version, bounded polling, and stable idempotency tokens. Version drift or malformed output fails the action instead of producing evidence.

Configure the Temporal worker

Create the worker with Temporal mode and an explicitly injected cutover effector:

await createAirliftWorker({
  mode: 'temporal',
  runtime,
  effector: cutoverEffector,
});

The effector identifies its certified profile, implementation version, and certification digest, then implements createCheckpoint, applyCutover, verifyCutover, and compensateCutover. Apply and compensation are each attempted once. Unknown outcomes remain unresolved for reconciliation; they are never converted into success by a retry.

Production migration-route boundary

The routed worker composition now exists, but no routed worker is deployed by this repository's default composition root. Route availability is worker capability evidence, never configuration: the console and authenticated remote API probe the Temporal server for an active poller on airlift-routed-v1 whose worker identity carries the exact organization (airlift-route-worker:<organizationId>:<buildId>). Without a matching poller every start is rejected before a governed request is created or Temporal is contacted; no environment flag can turn the control on by itself.

A routed worker serves exactly one organization per deployment. It requires Temporal mode, AIRLIFT_ROUTE_ORGANIZATION_ID, the production PostgreSQL store, and the exact activities acknowledgeMigrationRouteStartV1, runMigrationRouteDiscoveryV1, runMigrationRouteAssessmentV1, runMigrationRouteConversionV1, runMigrationRouteTransferV1, runMigrationRouteDeploymentV1, runMigrationRouteValidationV1, runMigrationRouteCutoverRehearsalV1, completeMigrationRouteV1, and failMigrationRouteV1. The same worker polls a five-minute migrationRouteReconcileWorkflow schedule that owns acknowledgement loss, lost executions, unknown outcomes, and recorded cancellation requests. Two trusted system principals must be admitted with the worker-owned airlift:journey:record permission: svc-airlift-route-worker owns every route lifecycle action (acknowledgement, progress, linkage, terminal state, reconciliation), while svc-airlift-worker owns the assessment and conversion actions it invokes. Human route requests and cancellation requests use the same permission but remain natural-person-only at ingress. Provider credentials and effectors stay worker-only.

The worker composes real Synapse and SQL Server discovery, assessment, exact conversion, and exact predecessor-bound transfer, deployment, and validation adapters. The routed composition fails startup with a precise unavailable list when any consequential adapter is missing or stubbed. Two production inputs remain named and fail closed: the credential-backed Synapse/SQL Server provider-binding seam (a deployment must inject it explicitly) and a certified cutover rehearsal effect, so the cutover stage still rejects non-production effects. Cancellation has no separate cancel activity: the operator's governed cancellation request is durable intent, the console cancels the exact workflow, and the workflow's non-cancellable terminal path — or the reconcile schedule when the execution is already gone — persists cancelled.

Recovery preserves the governed request lifecycle. A request is committed as start_pending before Temporal start; an exact retry may attach only to the same immutable request in start_pending or running. A failure or cancellation before acknowledgement converges to a terminal projection instead of leaving a stranded row. Deployment is still blocked until the credential-backed provider seam exists and live certification proves restart, drift, rollback, cleanup-manifest, and delayed-cost-check behavior on disposable resources.

Pre-production verification

Before admitting migration data, prove:

1. authenticated identity and cross-tenant denial;
2. durable write, projection read-back, and idempotent replay;
3. Lakebridge job connectivity, version enforcement, and artifact digest verification;
4. evidence-signing and offline certificate verification;
5. Temporal bundle determinism, query, cancellation, restart, and replay;
6. frozen-scope staleness, timed rehearsal, certified-effector binding, checkpoint, apply-once, verification, uncertainty, compensation, and rollback behavior;
7. parallel-run, cutover-verification, hypercare, incident, and source-disposition evidence paths.

See production readiness for the reusable acceptance contract.