Capability registry

View full size

A source pack tells your code which migration workflow to assemble. The capability registry tells operators what the installed provider generation has actually proved. Use both:

• the source profile is deterministic developer guidance;
• the capability matrix is tenant-scoped governed evidence;
• object readiness and migration certificates prove a specific client workload;
• cutover policy decides whether a wave can move.

These layers intentionally do not imply each other.

Matrix dimensions

Every registered source variant can carry independent entries for:

Delivery mode is automated, mixed, human, external, not_applicable, or unavailable. A human or mixed entry must name the skills required. This makes specialist remediation a designed lane that can be assigned and estimated, not an exception hidden inside an automation percentage.

Proof ladder

An entry stores the provider version, run and build references, SHA-256 digest, optional dataset reference, completion time, and validity window. Airlift does not copy provider artifacts into its event log.

Register and prove a capability

Registry v1 entries describe a whole source variant capability. Registry v2 adds a construct-scoped cell without changing v1 replay. For example, add this block to a v2 proposal:

{
  "schemaVersion": 2,
  "constructScope": {
    "construct": "merge_statement",
    "artifactKind": "source",
    "targetPattern": "Databricks SQL MERGE INTO",
    "automationDisposition": "deterministic",
    "sourceVersion": "Synapse SQL 2025",
    "documentationReference": "/docs/sources/synapse"
  }
}

The disposition is one of deterministic, agent_repairable, human_remediation, retain_or_federate, replace_native, retire, excluded, or unsupported. Construct proof is deliberately non-aggregating: it cannot raise the whole variant's support level or clear engagement preflight by itself.

Create capability-proposal.json:

{
  "schemaVersion": 1,
  "sourceSystem": "synapse",
  "sourceVariant": "synapse_dedicated_sql",
  "capability": "assessment",
  "availability": "automated",
  "providerId": "lakebridge.analyzer",
  "providerVersion": "0.7.0",
  "targetProofLevel": "workspace_proven",
  "limitations": ["ADF orchestration requires a separate export"],
  "requiredHumanSkills": [],
  "validationProfileIds": ["synapse-assessment-v1"],
  "expiresAt": "2031-08-03T00:00:00Z",
  "reason": "Register the provider boundary for independent review."
}

fa capability propose \
  --file capability-proposal.json \
  --idempotency-key synapse-assessment-proposal-v1

The result is proposed; it is not active. An admitted automation principal records an immutable test result:

{
  "capabilityEntryId": "cap_<id>",
  "evidence": {
    "evidenceId": "cev_synapse_assessment_workspace_01",
    "kind": "workspace_run",
    "ref": "artifact-store://airlift/evidence/synapse-assessment.json",
    "digest": "<64 lowercase hex characters>",
    "buildRef": "ci://fabric-airlift/build/123",
    "datasetRef": "dataset://synapse-representative/v1",
    "runRef": "databricks://jobs/assessment/runs/456",
    "providerVersion": "0.7.0",
    "completedAt": "2030-08-03T18:00:00Z",
    "validUntil": "2031-08-03T00:00:00Z"
  }
}

fa capability evidence \
  --file capability-evidence.json \
  --idempotency-key synapse-assessment-workspace-proof-v1

A different human reviewer can then promote no higher than the strongest admitted evidence:

fa capability promote \
  --file capability-promotion.json \
  --idempotency-key synapse-assessment-promotion-v1

Use expire, revoke, and reconcile for time expiry, an explicit human withdrawal, and provider-version observation respectively. History remains in the event and audit ledger.

Read the installed matrix

fa capability list --source synapse --variant synapse_dedicated_sql
fa capability list --source synapse --construct merge_statement --artifact-kind source
fa capability matrix --source synapse --variant synapse_dedicated_sql
fa capability matrix --source synapse --variant synapse_dedicated_sql --json
fa source doctor synapse --variant synapse_dedicated_sql
fa source limitations synapse --variant synapse_dedicated_sql
fa source certify synapse --variant synapse_dedicated_sql --level certifiable
fa engagement preflight eng_<id>

The matrix prints implementationRoutingLevel, derivedSupportLevel, lifecycle cells, and the independent required-construct denominator. Build automation and deployment gate only against the evidence-derived level or exact cells. Implementation routing selects an intended workflow; it never represents achieved proof.

source doctor explains every missing, proposed, expired, unavailable, or under-proved requirement and prints the next action. source limitations lists the currently governed constraints and specialist skills. source certify is a fail-closed capability-readiness check; despite its concise name, it does not mint a migration certificate or activate a provider claim.

engagement preflight derives its target from the engagement services, resolves every scoped estate to its source variant, and evaluates the same requirements. It returns a non-zero exit code while any estate is blocked. Human and mixed delivery modes can satisfy a requirement when they have sufficient evidence, but remain visible as staffed lanes.

In TypeScript:

import {
  buildSourceCapabilityMatrixRow,
  resolveSourceSystemProfile,
  type SourceCapabilityRow,
} from '@fabricorg/airlift';

const profile = resolveSourceSystemProfile('synapse');
const entries: SourceCapabilityRow[] = await loadTenantCapabilityRows();
const matrix = buildSourceCapabilityMatrixRow(
  profile,
  'synapse_dedicated_sql',
  entries,
);

The generated capability catalog lists the identifiers exported by the installed SDK. It is regenerated during every docs build so source variants, delivery modes, proof levels, and CLI documentation cannot silently drift from code.