[jeremy]

Tracking card: hey-sdk Rust: public API governance. First of two: this one states the policy and adopts the lint table; #166 applies #[non_exhaustive] and carries the migration note. Merge order: this PR, then #166 (stacked on this branch; GitHub retargets it to main on merge). Both are kept rebased on main and converged together.

Policy (bar section H). Three documents, one decision:

• rust/hey-sdk/README.md gains a Versioning section: pre-1.0 semver (0.MINOR breaking, 0.x.PATCH additive), the MSRV (1.88, stated as rust-version, moved only when a dependency or language feature requires it, as a minor release with a release-notes line, never required above stable minus eight), and How types evolve — the request-construction policy. Request-side types (bodies, *Params, Config, the resilience configs, ExchangeRequest/RefreshRequest) are built literally, keep Default and ..Default::default(), and are never #[non_exhaustive], so a field added to one is a 0.MINOR. Response-side types and open enums are #[non_exhaustive], so a field or variant added there is a 0.x.PATCH. A type on both sides is request-side. Closed enums stay exhaustive. The generator applies the rule by reachability from request bodies, not by name. Enums, when the model declares them, are emitted with Unknown(String) so an undeclared value survives a read-modify-write; until then the generator invents none.
• CONTRIBUTING.md gains a Versioning section pointing at the policy and asking a PR to say which side a touched type is on.
• AGENTS.md (Rust section) gains Lints and How the generated surface evolves, the generator-facing statement of the same rule.

Lints (bar section G), the fleet table from the cross-repo Rust devex standard, verbatim in both rust/hey-sdk/Cargo.toml and rust/generator/Cargo.toml: missing_docs, unreachable_pub, unexpected_cfgs with check-cfg(docsrs), clippy all + pedantic at warn with the four reasoned allowances (module_name_repetitions, must_use_candidate, missing_errors_doc, missing_panics_doc); -D warnings stays in CI, not in the table. rust/clippy.toml carries msrv = "1.88", the argument and type-complexity thresholds and avoid-breaking-exported-api. One local deviation from the standard, recorded here: unsafe_code is deny in the table rather than forbid, with #![forbid(unsafe_code)] in lib.rs holding the library to the stronger form — tests/config.rs has to call env::set_var, which is unsafe under edition 2024, and forbid in the table cannot be lifted for that one test. lib.rs also carries #![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used))], which reaches the library and nothing under tests/; the ~106 unwrap/expect hits in src triaged as: 20 Mutex::lock().unwrap() → unwrap_or_else(PoisonError::into_inner) (a poisoned lock still holds usable state and must not take the client down), two provably-infallible sites kept behind a targeted allow with the reason on the line (ReqwestClient::default building reqwest from its defaults; Match::operation on a match that always carries a route), the rest inside #[cfg(test)].

Generated code is not lint-gated: every file the generator writes now starts with #![allow(missing_docs, unreachable_pub, clippy::all, clippy::pedantic)] (the model chooses its names and shapes), which replaces the per-file too_many_arguments allowance. Regenerated; rs-check-drift green.

Docs. Every public item in hand-written code now has rustdoc, written in the crate's voice (what a thing means, not "gets the X"): 13 module lines in lib.rs, every undocumented field, variant, method and constant across the core modules, the client, OAuth, observability, resilience and the 27 service modules. Every integration test crate says what it covers.

Pedantic fixes, behavior identical, no public signature changed (avoid-breaking-exported-api holds): impl<'a> X<'a> → impl X<'_> across the services, #[must_use] on the Self-returning builders, try_from where a cast could lose bits, if let … else for single-arm matches, identical match arms merged, clone_from, Option<&str> over &Option<String> on a private helper, private field/function renames where a name repeated the type. Ten targeted #[allow]s remain, each with its reason on the line (listed in the diff by #[allow). One thing worth a reader's eye: oauth::expires_at reads expires_in through i64::try_from(..).ok()?, so a value past i64::MAX yields None where it used to wrap negative into an already-past instant.

client.rs (Lane A is changing its retry and tracing code concurrently): the non-doc lines changed are the 13 #[must_use] attributes on ClientBuilder, one #[allow(clippy::too_many_lines)] on attempt, a match → if let in url_for, the nonminimal_bool one-liner in the cache check (is_none_or), and u64::try_from(millis).unwrap_or(u64::MAX) in wait. Everything else there is /// text.

Not in here (Lane C's): rustfmt.toml, rust-toolchain.toml, deny.toml, the CI matrix, Makefile targets. Not in here either: any version file (a 0.30.0 release is being cut).

Local gate on Rust 1.98.1, at the current head (rebased onto main after #165 and #170): make -C rust check (fmt, clippy --all-targets -D warnings, test — 48 suites, doc -D warnings, --no-default-features, examples, deny, publish dry run) exit 0; make rs-check-drift exit 0; make conformance-rs 195/195; cargo check -p hey-sdk on 1.88.0 with --all-features and --no-default-features both build. cargo semver-checks against main reports nothing: BulkheadConfig briefly gained Copy here and lost it again when the check named that a major (copy_impl_added).

Review. Codex CLI adversarial pass done (seven findings: six folded in 9cc320c, one declined — the dispositions are in the rebase comment below). Copilot and Codex-bot threads answered inline. Babysitting the review loop to convergence.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-10T07:32:20.792434Z	e42e451	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[Copilot]

🔵 Needs a closer look

The change set is broad (lint policy + generator + regenerated code + core crate edits), so a final human pass is warranted to confirm no subtle API/behavior regressions.

Pull request overview

This PR documents the Rust crate’s public API governance policy (versioning/MSRV and how request- vs response-side types evolve) and adopts the shared “fleet” lint configuration across rust/hey-sdk and rust/generator, with associated doc/pedantic cleanups and regenerated artifacts.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Changes:

• Add/align versioning + API evolution policy documentation across rust/hey-sdk/README.md, CONTRIBUTING.md, and AGENTS.md.
• Adopt the shared Rust + Clippy lint tables in rust/hey-sdk/Cargo.toml and rust/generator/Cargo.toml, plus add rust/clippy.toml and regenerate Rust generated sources with a consistent lint header.
• Apply rustdoc and clippy-driven refactors across the Rust crate, tests, and generator code.

File summaries

File	Description
rust/hey-sdk/tests/support/mod.rs	Restrict test support helpers to crate visibility (pub(crate)).
rust/hey-sdk/tests/services_world.rs	Add module-level rustdoc for wire-level tests.
rust/hey-sdk/tests/services_workflows.rs	Add module rustdoc; improve numeric literal readability in tests.
rust/hey-sdk/tests/services_topics.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_time_tracks.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_time_track_categories.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_stickies.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_snippets.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_search.rs	Add module rustdoc; improve numeric literal readability in fixtures/asserts.
rust/hey-sdk/tests/services_publications.rs	Add module rustdoc; improve numeric literal readability.
rust/hey-sdk/tests/services_postings.rs	Add module rustdoc; update type usage to PostingChanges; make assertion explicit.
rust/hey-sdk/tests/services_journal.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_identity.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_habits.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_folders.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_extenzions.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_designations.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_contacts.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_collections.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_collections_writes.rs	Add module rustdoc; improve numeric literal readability in IDs.
rust/hey-sdk/tests/services_clips.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_clearances.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_calendars.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_calendar_todos.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_calendar_periods.rs	Add module rustdoc; improve numeric literal readability in JSON fixture.
rust/hey-sdk/tests/services_calendar_events.rs	Add module rustdoc; improve numeric literal readability; tighten comment formatting.
rust/hey-sdk/tests/services_calendar_changes.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_bulk_replies.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_boxes.rs	Add module-level rustdoc.
rust/hey-sdk/tests/services_attachments.rs	Add module-level rustdoc.
rust/hey-sdk/tests/routes.rs	Add module-level rustdoc describing route table coverage.
rust/hey-sdk/tests/resilience.rs	Add module rustdoc; make params type explicit in one call site.
rust/hey-sdk/tests/recordings.rs	Add module rustdoc; improve numeric literal readability.
rust/hey-sdk/tests/raw.rs	Add module rustdoc; make params type explicit in one call site.
rust/hey-sdk/tests/pagination.rs	Add module rustdoc; make params type explicit in one call site.
rust/hey-sdk/tests/observability.rs	Add module rustdoc; adjust internal recorder helper and formatting.
rust/hey-sdk/tests/get_all.rs	Add module-level rustdoc.
rust/hey-sdk/tests/form.rs	Add module-level rustdoc.
rust/hey-sdk/tests/errors.rs	Add module-level rustdoc.
rust/hey-sdk/tests/dates.rs	Add module-level rustdoc.
rust/hey-sdk/tests/config.rs	Add module rustdoc; handle poisoned mutex explicitly; allow unsafe env mutation in tests with rationale.
rust/hey-sdk/tests/client_pipeline.rs	Add module rustdoc; make params types explicit; adjust query string collection.
rust/hey-sdk/tests/cache.rs	Add module-level rustdoc.
rust/hey-sdk/tests/body_limit.rs	Add module-level rustdoc.
rust/hey-sdk/tests/account_scope.rs	Add module-level rustdoc.
rust/hey-sdk/src/url.rs	Add/adjust docs and targeted clippy allow for a provably-infallible expect.
rust/hey-sdk/src/types.rs	Add rustdoc; avoid lossy casts in date arithmetic.
rust/hey-sdk/src/services/world.rs	Add rustdoc for service and client accessor; document one targeted clippy allow.
rust/hey-sdk/src/services/workflows.rs	Add rustdoc on public fields; update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/topics.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/time_tracks.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/stickies.rs	Add rustdoc on enum + helpers; strengthen integer conversions and limit handling.
rust/hey-sdk/src/services/snippets.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/search.rs	Add rustdoc on results shape; update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/publications.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/postings.rs	Add rustdoc on enums/structs; adjust helper signature; update impl lifetime style.
rust/hey-sdk/src/services/messages.rs	Add rustdoc on message/draft structs; update impl lifetime style.
rust/hey-sdk/src/services/journal.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/identity.rs	Add rustdoc on enum; update impl lifetime style.
rust/hey-sdk/src/services/habits.rs	Add rustdoc on params; update impl lifetime style.
rust/hey-sdk/src/services/extenzions.rs	Add rustdoc on structs; update impl lifetime style.
rust/hey-sdk/src/services/entries.rs	Add rustdoc on reply recipients; update impl lifetime style.
rust/hey-sdk/src/services/designations.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/contacts.rs	Add rustdoc on structs; minor perf/style refactors (clone_from, i64::to_string).
rust/hey-sdk/src/services/collections.rs	Add rustdoc; simplify optional string handling via Option<&str>.
rust/hey-sdk/src/services/clips.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/clearances.rs	Add rustdoc; minor refactor (i64::to_string).
rust/hey-sdk/src/services/calendars.rs	Add rustdoc on decoded list structs; update impl lifetime style.
rust/hey-sdk/src/services/calendar_todos.rs	Add rustdoc on update struct; update impl lifetime style.
rust/hey-sdk/src/services/calendar_periods.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/calendar_events.rs	Add extensive rustdoc; adjust optional field encoding; update impl lifetime style; simplify helpers.
rust/hey-sdk/src/services/calendar_changes.rs	Add rustdoc on cursor/changes structs; update impl lifetime style.
rust/hey-sdk/src/services/bulk_replies.rs	Update impl lifetime style (impl X<'_>).
rust/hey-sdk/src/services/boxes.rs	Add rustdoc; refactor cache read flow; update impl lifetime style.
rust/hey-sdk/src/services/attachments.rs	Update impl lifetime style; add targeted cast allow with rationale.
rust/hey-sdk/src/security.rs	Add rustdoc to is_localhost.
rust/hey-sdk/src/route.rs	Expand rustdoc across route metadata types.
rust/hey-sdk/src/resilience/rate_limit.rs	Harden mutex poisoning behavior; add docs and targeted clippy allows in tests.
rust/hey-sdk/src/resilience/mod.rs	Add rustdoc and #[must_use] on builder methods; handle mutex poisoning.
rust/hey-sdk/src/resilience/circuit_breaker.rs	Handle mutex poisoning; add docs and a targeted cast precision allow.
rust/hey-sdk/src/resilience/bulkhead.rs	Make BulkheadConfig Copy; add docs.
rust/hey-sdk/src/raw.rs	Add rustdoc for raw HTTP helpers.
rust/hey-sdk/src/pagination.rs	Rename internal cursor storage; expose value accessors; factor next-page parsing into helper.
rust/hey-sdk/src/operation.rs	Add rustdoc; add targeted allow for struct bool count.
rust/hey-sdk/src/observability.rs	Expand rustdoc on hook types; adjust test helper signature.
rust/hey-sdk/src/oauth.rs	Add rustdoc on public OAuth types; avoid lossy cast when computing expires_at.
rust/hey-sdk/src/lib.rs	Add crate-level lint attributes and expand module-level rustdoc.
rust/hey-sdk/src/http/reqwest.rs	Add targeted allow + rationale for expect in Default.
rust/hey-sdk/src/http/mod.rs	Add docs and docsrs feature annotation for reqwest export.
rust/hey-sdk/src/generated/types.rs	Add generated-file lint allow header.
rust/hey-sdk/src/generated/services/workflows.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/topics.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/time_tracks.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/stickies.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/snippets.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/search.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/publications.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/postings.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/mod.rs	Add generated-module lint allow header.
rust/hey-sdk/src/generated/services/messages.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/journal.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/identity.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/habits.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/folders.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/extenzions.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/entries.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/designations.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/contacts.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/collections.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/clips.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/clearances.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/calendars.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/calendar_todos.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/calendar_periods.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/calendar_events.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/bulk_replies.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/boxes.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/services/attachments.rs	Replace per-file allow with standard generated lint allow header.
rust/hey-sdk/src/generated/routes.rs	Add generated-file lint allow header.
rust/hey-sdk/src/generated/mod.rs	Add generated-module lint allow header.
rust/hey-sdk/src/form.rs	Add rustdoc on FormResponse::status.
rust/hey-sdk/src/error.rs	Add rustdoc on error categories + helpers; minor refactors to match lint expectations.
rust/hey-sdk/src/config.rs	Add rustdoc and #[must_use] on config builders.
rust/hey-sdk/src/client.rs	Add extensive rustdoc and #[must_use] on builder methods; small clippy-driven refactors.
rust/hey-sdk/src/cache.rs	Add rustdoc; handle poisoned mutexes; refactor hex encoding implementation.
rust/hey-sdk/src/auth.rs	Add rustdoc on auth traits/types.
rust/hey-sdk/README.md	Add “Versioning” policy section (semver rules, MSRV, type evolution rules).
rust/hey-sdk/Cargo.toml	Add fleet [lints] tables for rust + clippy.
rust/generator/src/naming.rs	Reduce visibility to pub(crate); add targeted clippy allow for input checks.
rust/generator/src/model.rs	Reduce visibility to pub(crate); harden parsing for status/retry fields; rename retry field to on.
rust/generator/src/main.rs	Pass rendered file map by reference (avoid moves/clones).
rust/generator/src/emit/types.rs	Reduce visibility to pub(crate).
rust/generator/src/emit/services.rs	Reduce visibility; rely on common generated-file header instead of per-file allow.
rust/generator/src/emit/routes.rs	Update emitted retry list source to match model (on).
rust/generator/src/emit/mod.rs	Centralize generated-file header including lint allow; refactor doc comment rendering.
rust/generator/Cargo.toml	Add fleet [lints] tables for rust + clippy.
rust/clippy.toml	Add repository clippy configuration (MSRV, thresholds, exported API checks).
CONTRIBUTING.md	Document versioning policy and request-side vs response-side guidance for PRs.
AGENTS.md	Add Rust lint + generated-surface evolution documentation for contributors.

Review details

• Files reviewed: 108/139 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 735c63a547

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jeremy]

Rebased onto main at e4ff0d7 (after #156, #152 and the v0.30.0 tag); the generator conflict with #156 resolved by taking main's refusals and re-applying the pub(crate) narrowing, then regenerating. Full local gate green again (fmt, clippy -D warnings, 47 test suites, doc -D warnings, drift, conformance 190/190).

Adversarial review (Codex CLI, gpt-6-astra at xhigh, read-only, over the hand-written diff) raised seven points; six folded in 9cc320c, one declined:

1. Error::network said "nothing reached HEY" — wrong: a timeout can follow a write HEY made. Reworded: retryable because the request can go out again, and only safe for an operation the model calls idempotent, which is the only kind the client resends. Fixed.
2. Match::operation's allow claimed an invariant public fields cannot hold. It now carries a # Panics contract (unreachable through Router::recognize; reachable only by emptying operations by hand) and the allow cites it. Fixed.
3. ReqwestClient::default claimed reqwest cannot fail to build; a TLS backend can. It carries a # Panics contract and points at the fallible constructors (with_timeout, from_builder). Fixed.
4. The env-var test's safety comment overclaimed. It now states what the lock provides: every test in that binary that reads or writes the environment holds it. Declined the suggested child-process rewrite: the test predates this PR and the lock does cover every reader in the process; a redesign belongs with the runtime contract-tests card, not a lint pass.
5. The README asserted a cargo semver-checks gate and an MSRV job that land in the CI-hardening PR, not here. Reworded to state the checks without asserting the jobs. Fixed.
6. "A response field added is a patch" was too strong: a required field with no decoding default (a DateTime) refuses yesterday's payload. The README now says so. Fixed.
7. The enum policy contradicted the request-side rule for an enum reachable from a body. Now: the literal rule is for structs; an open enum is #[non_exhaustive] on either side, since its declared variants stay constructible. README and AGENTS.md. Fixed.

[jeremy]

Rebased onto main at 1d3d047 (#164, Go-only); no conflicts, gate green (48 suites, drift, conformance 195/195). #166 rebased on top, same result.

[jeremy]

Rebased onto main at 5680b25 (after #165 and #170). The conflict was lib.rs, where #165's additions met this branch's lint table and module docs; resolved by taking both. Two things the rebase changed on this side, in e42e451: the trace helpers only the feature's macros call moved behind the feature so a --no-default-features build carries no dead code, and BulkheadConfig went back to Clone without Copy — cargo semver-checks names copy_impl_added a major, and this PR is meant to change no public signature.

Gate at e42e451: make -C rust check (48 suites) exit 0, rs-check-drift exit 0, conformance-rs 195/195, cargo check on 1.88.0 with --all-features and --no-default-features. CI green, including api-compat-rust against main. #166 is rebased on this head; merge order unchanged: this PR, then #166.