feat(connect-cpp): add the C++17 convenience layer and surface the C/C++ channel

[auto-wood]

What

Adds the C++17 consumer surface for the Connect C/C++ channel, and makes that channel discoverable from the
entry documentation a C++ integrator actually reads.

Convenience layer — crates/spoke-connect/bindings/cpp/include/spoke_connect.hpp: a hand-written,
header-only C++17 wrapper over the existing C ABI (spoke_connect.h, ABI revision 1 unchanged). Move-only
owning types for the C resources, a Result<T> / Error error channel, std::string_view text inputs with an
explicit owned copy, std::optional for the C optional-value convention, callback records built from
std::function and transferred through unique_ptr only after the C constructor succeeds, explicit close()
on sessions (destruction frees but never closes), and an exception-containment branch selected from the compiler
exception macros. No new exported symbol, no record-layout change, no new artifact or version-bearing manifest.

Verification — the smoke runner compiles and runs two configurations per RID (exceptions disabled and
enabled) and requires each configuration's assertion banners to match its expected list exactly, so a
banner leaked from the other configuration fails the run; the C ABI symbol/layout/callback gate's C++ probe now
also compiles the wrapper and gained a .hpp exception-syntax negative control; the Windows CI lane runs the
same gate with --self-test so the negative mutations execute on MSVC too.

Documentation — the C++ how-to pages (EN + CN) carry a runnable walkthrough composed of three copyable
blocks that reaches Established, invokes a tool and closes in the documented order on both the success and the
failure paths; the C/C++ channel is surfaced on the root READMEs, the docs home and the package quick-start; one
authoritative registry-backed / git-based channel classification replaced the three drifting counts across
CONCEPTS.md, AGENTS.md and the specs; and the two tracked C++-related specs state the shipped facts.

Verification

• node tooling/connect/cpp-symbol-check.mjs --header … --library … --self-test → 83 declarations, 83 exports, 0 missing, 0 extra; layout, callback-signature, C and C++ probes green; all four negative mutations failing
  as intended
• node tooling/connect/cpp-smoke.mjs --rid osx-arm64 → both configurations green with their exact ordered
  banners
• node tooling/docs/twin-parity.mjs → every page twinned, heading structures matching
• pnpm docs:build green; node tooling/docs/deadlink-check.mjs → 49 pages, 2 761 anchors, 0 dead
• The how-to walkthrough was extracted from the page's own blocks, built and run under both clang exception
  configurations, observing Established, a non-empty session id and the echo JSON
• Plan QC tri-review Approve with residuals; QA gate mandatory → Approve, 10/10 acceptance criteria met

Residuals

• R1 (low) — the symbol gate's C++ inclusion probe covers only the no-exceptions configuration; the
  exception-enabled path is covered by the smoke runner. Tracking: project register entries["cpp-consumer-surface"].
• R2 (low) — the committed C++ carrier provenance records a header hash for spoke_connect.h only; a
  spoke_connect.hpp fingerprint can only land at the next carrier refresh. Tracking: the same register bucket.

No blocking finding and no critical remains open.

Notes

• The committed carriers for osx-arm64 and win-x64 are unchanged; the Windows lane's run is CI-owned and was
  not executed locally.
• A linux-x64 C carrier is recorded as a deferred roadmap item with owner, trigger and done definition; it is
  not implemented here.
• The other languages' binding READMEs keep their pre-existing internal spec links; only the C++ consumer surface
  this change owns was repointed to public destinations.

[cursor]

Stale comment

Risk: high. Left a non-blocking comment and assigned reviewers. This PR adds a large C++ FFI convenience layer with transport/callback bridges, which is above the medium approval threshold, so it needs human review.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[cursor]

Stale comment

Risk: high. Left a non-blocking comment; one reviewer is already assigned. This C++ FFI convenience layer (transport and callback bridges) is above the medium approval threshold, so it needs human review. Cursor Bugbot and Cursor Security Agent were not present after the first check poll.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with no outstanding correctness or repository-rule violations identified.

Summary

The PR adds a header-only C++17 convenience layer over the existing C ABI, expands smoke and symbol validation across exception configurations and supported carriers, and documents the C/C++ distribution channel.

• Introduces move-only C++ resource wrappers, structured results, optional-value handling, callback bridges, and explicit session closure.
• Runs exact-banner smoke validation with exceptions enabled and disabled.
• Adds macOS carrier validation and ensures native-carrier changes trigger both pull-request and push workflows.
• Updates English and Chinese integration documentation, binding specifications, and channel classification.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    CPP["C++17 consumer"] --> HPP["spoke_connect.hpp<br/>header-only convenience layer"]
    HPP --> H["spoke_connect.h<br/>C ABI revision 1"]
    H --> LIB["Committed platform carrier"]
    LIB --> RUST["spoke-connect Rust facade"]
    CHECK["Symbol and layout gate"] --> H
    CHECK --> HPP
    CHECK --> LIB
    SMOKE["Exception-disabled and<br/>exception-enabled smoke"] --> HPP
    SMOKE --> LIB

Loading

_{Reviews (5) · Last reviewed commit: "Merge branch 'feat/cpp-consumer-surface-..."}

[cursor]

Stale comment

Risk: high. Left a non-blocking comment; one reviewer is already assigned. This C++ FFI convenience layer with transport and callback bridges is above the medium approval threshold, so it needs human review. Cursor Bugbot and Cursor Security Agent were not present after the first check poll.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[cursor]

Stale comment

Risk: high. Left a non-blocking comment; one reviewer is already assigned. This C++ FFI convenience layer with transport and callback bridges is above the medium approval threshold, so it needs human review. Cursor Bugbot and Cursor Security Agent were not present after the first check poll.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[cursor]

Stale comment

Risk: high. Left a non-blocking comment; reviewers were not newly assigned because one reviewer is already requested. This C++ FFI convenience layer with transport and callback bridges is above the medium approval threshold, so it needs human review.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[cursor]

Risk: high. Left a non-blocking comment; reviewers were not newly assigned because one reviewer is already requested. This C++ FFI convenience layer with transport and callback bridges is above the medium approval threshold, so it needs human review.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}