Connection diagnostics

Source-pack v2 connectivity and permission diagnostics, observed-state derivation, admitted recording, and verification.

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:

State	Meaning
`not_configured`	The binding was retired; it is no longer a configured surface.
`not_observed`	No diagnostic recorded for the current binding revision.
`stale`	Every recorded diagnostic predates the current revision or the 24-hour freshness window.
`blocked`	The newest matching diagnostic contains a denied or failed required probe.
`observed`	The newest matching diagnostic passed every required probe inside the freshness window.

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, and not 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:

Probe	Class	Evidences
`endpoint_reachable`	connectivity	every binding
`authentication`	connectivity	every binding
`tls_verified`	connectivity	every binding
`catalog_list`	permission	`inventory_read`
`object_metadata_read`	permission	`metadata_read`
`ddl_definition_read`	permission	`metadata_read`
`row_sample_read`	permission	`snapshot_read`
`change_feed_read`	permission	`change_feed_read`
`target_namespace_write`	permission	`target_write`
`artifact_write`	permission	`artifact_write`
`target_deploy_probe`	permission	`target_deploy`
`validation_execute_probe`	permission	`validation_execute`
`cutover_effect_probe`	permission	`cutover_effect`

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.