[ilyam8]

Summary

Phase 6 (guardrails), documentation. No behavior change, no exported API change.

• Package documentation. The package had none. doc.go covers the client's lifecycle, concurrency, request
  attempts and timeouts, the order of the hooks, SNMPv3 engine discovery and the Reports that resend or end a request,
  walks, the Go type of each value type when decoded and encoded, the malformed messages the decoder accepts, in-place
  decoding and value aliasing, the password-to-key cache, and the two trap paths, with the known bugs a caller meets
  in each (among them the malformed messages that make the decoders panic).
• Exported docs. Every exported identifier of the root package is documented, and the docs that had drifted from
  the code are corrected: the GoSNMP fields (a per-attempt Timeout without a default, Retries, AppOpts by key
  presence, Control, LocalAddr; unexported fields moved to the end), the request methods and their limits,
  Handler pointing at the GoSNMP methods instead of drifting copies, NewHandler, SnmpPDU, Asn1BER, PDUType,
  SnmpPacket, UsmSecurityParameters, UnmarshalTrap, MarshalMsg, SnmpEncodePacket, SnmpDecodePacket,
  PasswordCaching, the security parameters table, Check and the error group. SnmpVersion.String moves to
  packet.go, the Asn* constants to value.go.
• Known bugs. Each pinned bug now has a "Known bug" note where it happens: the trap digest checks (another security
  model, the table path's level taken from the message, privacy not required), the table path's panic on a header
  that fails early, keys-only users on a new engine ID, the msgID drawn by the client's version, the PDU type error
  text, ConnectIPv4/ConnectIPv6 appending their suffix on every call, Connect reseeding the IDs, the HMAC-96
  long-key cut, the 32-bit Uinteger32 decode, and the FIPS 140-only panics. Unpinned bugs in functions whose docs
  changed are pinned first and named: SnmpVersion.String of an unknown version, Partition with a partition size
  of 0, ToBigInt of a large uint, the empty-key signing of SnmpEncodePacket, the keys an empty passphrase
  derives without an error, and a user configured with keys instead of passphrases accepting a trap from another
  engine ID signed with the empty key, which anyone can compute (the Netdata Agent's trap receiver requires
  passphrases, so it is not exposed).
• Stale comments, among them the discovery note (every authenticated level fails for want of a key, not only
  authPriv), the request ID "uses all 32 bits", At "returns false", the BER package "decodes", and authenticate
  after its rename to sign.
• README and examples. Correct example paths and an exact copy of examples/example, every example listed, no
  g.MAX_OIDS (it does not exist), no upstream first-person text or alouca/gosnmp migration notes, the types Set
  takes, a pointer to the package documentation instead of a BER list that named types the decoder does not decode,
  documentation addresses, and coverage commands that work with current Go.

Validation

• The new pins pass on the code before these changes.
• Two independent reviews checked every changed statement against the code; their findings (five false statements,
  the keys-only trap acceptance among the gaps) are corrected, and a focused follow-up review checked the
  corrections.
• Apart from comments, the only changes are the two moves, the field order and a typo in an example's message
  (comment-free declarations of both trees compared); go generate leaves the generated files unchanged.
• Engine, FIPS 140-only, codec and USM goldens unchanged.
• go test -race, FIPS 140-only, golangci-lint, cross-builds, govulncheck: pass locally.