Add a cross-client telemetry-names contract (+ Rust reference adoption)

[joshmouch]

Why this belongs at the protocol layer

The self-instrumentation names (spans, metrics, attributes) an AHP client emits about its own operation are an interop surface, the same way the wire types are. They have to be byte-identical across clients or an operator running a fleet of mixed-language agents cannot write one OpenTelemetry dashboard or alert that works across all of them. That requirement is what makes the name contract a protocol concern rather than a per-client detail; the instrumentation code stays per-client and idiomatic, and only the names are shared. This is separate from the existing "OpenTelemetry over AHP" channel (docs/specification/telemetry-channel.md), which carries OTel data over the protocol. The scope question is open in #239.

What

Adds types/telemetry/registry.ts as the single source of truth for those names, generates an idiomatic holder per client, and wires the Rust client to emit the metrics as a reference adopter.

Client	Generated holder	Self-instrumentation today
.NET	AhpTelemetryNames (static class)	ActivitySource + Meter (in the .NET-client draft, #206)
Rust	ahp_types::telemetry (pub const &str)	metrics facade (this PR) plus tracing diagnostics
Go	telemetry.generated.go (consts)	available
Swift	AhpTelemetryNames (caseless enum)	available
Kotlin	AhpTelemetryNames (object)	available
TypeScript	the telemetry enums re-exported from the package root	available

Full rationale and the per-client OTel-export story live in docs/specification/self-instrumentation.md.

How the names are represented

The names are string enums (TelemetrySpan, TelemetryMetric, TelemetryAttribute, TelemetryOutcome), the same shape as the protocol enums (e.g. ChangesetOperationStatus). Each name's description is a JSDoc comment on its enum member, extracted by the generators the same way as any other enum (member.getJsDocs(), via the shared scripts/read-telemetry.ts helper), so the description lives next to the name with no separate lookup table:

export enum TelemetryMetric {
  /** Round-trip duration of a JSON-RPC request, tagged by rpc.method and ahp.outcome (ok|error|cancelled|timeout). */
  RequestDuration = 'ahp.client.request.duration',
  ...
}

Metric units are a small Record<TelemetryMetric, string> map. The generators emit a flat string holder (telemetry names are consumed as raw strings by Meter and metrics, not as language enums), carrying each member's description through as a doc comment on the generated constant. types/telemetry/registry.test.ts guards the invariants (dotted names, unique, every metric has a unit), and a verify-generated gate fails CI if a holder drifts from the contract.

Rust reference adoption

The ahp client emits self-instrumentation metrics through the metrics facade (messages sent and received, request duration and in-flight, reconnects, dropped events per stream, malformed frames, with rpc.* and ahp.* attributes), all named from ahp_types::telemetry. The facade is a no-op until the host installs a recorder, so it is zero-cost when unobserved. A recorder-based integration test drives a request and asserts the metrics emit with the right attributes and that the in-flight gauge returns to zero on completion; a separate test asserts a cancelled request is tagged ahp.outcome=cancelled.

Verified

go build plus gofmt -l, cargo build plus cargo fmt --check, cargo test, cargo clippy, swift build, kotlin compileKotlin, the TypeScript tsc --noEmit, and the npm test suite (typecheck, lint, the verify-generated freshness gate, registry.test.ts, and the read-telemetry test) all pass.

Status

Draft until the scope question in #239 is decided. Open to adjusting the naming scheme, the per-language holder shape, which client adopts first, or dropping the Rust metrics dependency in favor of holders-only.

[connor4312]

#239 (comment)