Client verify — fail fast when the peer is wrong

Addressed clients should not hang on a dead peer or silently talk past a stale contract. Hyperlink.verifyConnection is the probe; addressed Hyperlink.client (and Hyperlink.ws) run it by default. Nodeless Hyperlink.connect(tag, protocol) does not — call the probe yourself when you want fail-fast there.

Handoff SSOT: docs/handoffs/loud-failures-design.md · docs/handoffs/verify-connection-classification.md.

Default-on (addressed clients)

Building an addressed client Layer probes the peer before the handle is usable:

Mode	Behavior
`"reject"` (default)	Probe fails → Layer fails (`NodeUnreachable`, or deep errors below)
`"status"`	Probe runs; failure is ignored (connect proceeds)
`false`	Skip verify

import * as Hyperlink from "hyperlink-ts/Hyperlink"
import { Layer } from "effect"

// Opt out for a nested/bootstrap client (Lookup.client / identity ping do this internally):
Hyperlink.client(Emails, WorkerNode).pipe(
  Layer.provide(Hyperlink.clientVerify(false)),
)

// Soft: probe but don't fail the Layer
Hyperlink.client(Emails, WorkerNode).pipe(
  Layer.provide(Hyperlink.clientVerify("status")),
)

Tag-aware addressed clients escalate to deep verify (node-handle status RPC + service readiness + F4 contractHash). Nodeless / bootstrap paths that would deadlock keep verify off.

Explicit probe

import * as Hyperlink from "hyperlink-ts/Hyperlink"

yield* Hyperlink.verifyConnection(WorkerNode) // tier 1 — transport reachability
yield* Hyperlink.verifyConnection(WorkerNode, { timeout: "1 second" })
yield* Hyperlink.verifyConnection(WorkerNode, { deep: true }) // + node status RPC
yield* Hyperlink.verifyConnection(WorkerNode, {
  deep: true,
  serviceKey: Emails.key,
  contractHash: Hyperlink.contractHash(Emails),
})
yield* Hyperlink.verifyConnection(WorkerNode, { all: true }) // every declared endpoint

Failure ladder

Failure	When
`NodeUnreachable`	Transport probe fails (tier 1)
`ProtocolUnanswered`	Transport up, node status RPC silent
`ServiceNotServed` / `ServiceNotReady`	Deep + `serviceKey` key missing / not ready
`ContractMismatch`	Deep + `contractHash` disagrees with the peer (F4)
`ProtocolMismatch`	Wrong transport (e.g. http client → ws server) on a call
`MissingClientProtocol`	Nodeless `client(tag)` with no ambient protocol

Catch via Exit / _tag — remediation messages name the fix.

Client verify — fail fast when the peer is wrong

Default-on (addressed clients)

Explicit probe

Failure ladder

See also