Connection diagnostics

Connection bindings start as configuration. A binding is usable for assessment only when Airlift has an admitted, fresh, capability-covering connectivity diagnostic for it. Configuration, environment variables, lifecycle status (pending/verified), screenshots, and caller-declared metadata never raise connectivity state.

One shared observed-state vocabulary

Connectivity renders through the same five-token observed-state model as the Databricks target integrations:

Only observed marks a binding usable for assessment. The freshness window is a module constant (CONNECTION_DIAGNOSTIC_FRESHNESS_HOURS = 24), never organization-configurable: widening it by configuration would raise health by configuration, which the observed-state law forbids.

Probes and capability coverage

Required coverage derives from the binding's own declared capabilities, never from what a submitter chose to run. Every diagnostic requires the three connectivity probes — endpoint_reachable, authentication, tls_verified — plus one permission probe per declared capability:

A diagnostic that omits a required probe, marks a required probe not_applicable, or submits a probe for an undeclared capability is rejected. Coverage is conjunctive, never best-effort.

Recording a diagnostic

Diagnostics enter Airlift only through airlift.connection_diagnostic_record, invoked by an admitted system principal. The admission policy fails closed when:

• the actor is not a system principal;
• no airliftConnectionDiagnosticVerifier service is configured;
• the verifier cannot confirm the immutable evidence reference and digest.

The handler derives diagnosticDigest and outcome — a caller can never supply either — and checks the bindingRevisionDigest against the binding's current configuration, so a diagnostic recorded against a superseded credential or capability set can never verify.

Probe output is secret-safe: any field containing a credential reference or userinfo is rejected.

Verifying a binding

fa connection verify requires the digest of a recorded, revision-matched, fully passing diagnostic:

fa connection test <bnd_id>            # observed connectivity report; exit 0 iff observed

fa connection diagnose <bnd_id> \
  --file probes.json \
  --idempotency-key <key>              # admitted system principal only

fa connection verify <bnd_id> \
  --digest <recorded-diagnostic-digest> \
  --idempotency-key <key>

A caller-chosen digest is not evidence: verification rejects any digest that is not the recorded diagnostic digest, and it rejects when the freshest diagnostic is blocked or stale.

Blockers

Every non-observed state renders a five-part blocker in the App and fa connection test: what happened, why it matters, who acts, the required evidence, and one primary action. The engagement status discover phase surfaces the same underlying condition while no source binding is observed — it carries the what/why summary and the primary action, and the App renders the full five-part detail.

Honest support boundary

Fixtures and development self-review never admit connectivity. observed requires an admitted probe run against the real source. The development-assurance journey injects a permissive development verifier behind the same explicit escape hatch that already governs development self-review, and the resulting state never authorizes production cutover.

Production deployments currently fail closed. No production runtime wires an admitted airliftConnectionDiagnosticVerifier yet: until a source-specific probe provider is implemented and admitted, governed deployments cannot record connectivity diagnostics, and every binding stays not_observed. That is the deliberate, honest default — a permissive production verifier would admit arbitrary evidence. The probe-provider seam is named in the A0 remaining exit and tracked as a dated staged-compliance exception.