docs(rfc): add RFC 0027 method-level capability detection - #420
Draft
ryanleecode wants to merge 5 commits into
Draft
docs(rfc): add RFC 0027 method-level capability detection#420ryanleecode wants to merge 5 commits into
ryanleecode wants to merge 5 commits into
Conversation
truapi_platform::Features::feature_supported gained a doc comment stating that only Chain queries reach a platform (RFC 0027). The regenerated host-callbacks.ts golden picks that comment up verbatim. Diff reviewed hunk by hunk: one hunk, doc-only, no behavioral change.
Implements the interface-level changes RFC 0027 (method-level capability
detection) specifies, so the validate-rfc CI gate sees truapi interface
changes on this PR:
- Append HostFeatureSupportedRequest::Method { id: u8 } after Chain, so
Chain keeps SCALE variant index 0 and deployed encodings stay identical.
A host predating the variant fails to decode it and answers
CallError::MalformedFrame, the probe signal RFC 0027 relies on. Pinned
by exhaustive tests: every Method id round-trips at [0x01, id], Chain
encodes with leading 0x00.
- Rename CallError::unavailable() to CallError::unsupported() and answer
CallError::Unsupported instead of a fabricated HostFailure. 52 default
trait bodies updated; compiler-proven by the rename.
- Answer Method probes in the core funnel (host_logic::features) from the
generated WIRE_TABLE rather than forwarding to a platform; request and
subscription-start ids answer true, response/stop/interrupt/receive and
unallocated ids answer false. CLI platform returns a typed error for an
impossible Method query instead of a false answer.
- Tests: four-id-kind pinning in features.rs; wire-level proof in
wire_result_shape.rs that a Method probe is answered by the core (not
the platform) and that advertised support matches what the dispatcher
routes.
- RFC text amended where review found it underspecified: id-kind
semantics, HostFailure vs Unsupported retry distinction, constructor
rename.
- Regenerated iOS uniffi bindings carry the new enum converter.
Deviation (CONST-D1/S4): truapi_platform::Features::feature_supported
keeps a parameter type that admits Method, a state no platform can
answer. Narrowing it changes a callback signature implemented by every
in- and out-of-repo host adapter (Swift HostBridge, Kotlin HostBridge,
JS HostCallbacks), which RFC 0027 does not propose. The invariant is
enforced by the core funnel and by tests in host_logic/features.rs and
tests/wire_result_shape.rs, not by the type.
The generator now emits a host_initiated flag on every WIRE_TABLE row so the RFC 0027 capability probe can exclude host-initiated subscription ids (chat_custom_message_render) that the product-facing dispatcher never routes. Golden hunks reviewed: the host_initiated struct field plus one flag per row (true only for chat_custom_message_render), later slimmed to a one-line field doc in the slop-comment pass.
The RFC 0027 review found the probe answered true for a host-initiated subscription id the product dispatcher drops. Captured as an architecture pattern: answer probes from the product-callable subset of the wire table, flag host-initiated rows in codegen, and pin the table/registration equivalence exhaustively over all 256 ids.
ryanleecode
marked this pull request as ready for review
August 16, 2026 07:50
ryanleecode
changed the title
ryanleecode
changed the title
ryanleecode
marked this pull request as draft
August 16, 2026 07:50
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
RFC: Method-level capability detection for protocol extension
Summary
Products can now query whether a TrUAPI host serves a specific wire method before calling it, and unimplemented methods answer a typed
CallError::Unsupportedinstead of an ambiguous host failure string. Host capability answers come from the build's wire table — the same table the dispatcher routes from — so a positive probe cannot advertise a method that the host would silently drop. Host-initiated subscription ids (pushed by the host, never product-callable) answerfalse.Checklist
docs/rfcs/0027-capability-detection.mdrust/crates/truapi/rfc(applied on open)Motivation
TrUAPI methods extend faster than native host runtimes ship. A product that calls a method an older host does not have sends into a dispatcher with no handler, and the frame is dropped silently: the client transport has no request timeouts, so the call hangs forever. Products need a documented, backward-compatible way to learn whether the host will serve a method before invoking it, and unhandled calls must fail explicitly rather than hang.
Validation
Full Rust workspace build and test suite, clippy
-D warnings, nightly fmt, codegen regeneration checks, golden emit tests, TS wire-table parity, and iOS binding sync all pass. New tests pin the codec layout, every id kind's probe answer, the 256-id probe↔registration equivalence, and the wire-levelMalformedFrame/Unsupportedoutcomes.