feat(truapi): add testing API and versioned wiring

Adds the canonical testing module (api/testing.rs) and its v01/v02/versioned
wiring used by the Rust host runtime and generated clients.

Author: pgherveou

js/packages/truapi/src/client.test.ts

@@ -86,8 +86,6 @@ describe("generated client transport", () => {
         expectedFrame.set(expectedPayload, str.enc("p:1").length + 1);
 
         expect(toHex(fixture.sent[0])).toBe(toHex(expectedFrame));
-        expect(transport.truapiVersion).toBe(1);
-        expect(transport.codecVersion).toBe(1);
     });
 
     it("uses the transport codec version for generated handshake calls", () => {

js/packages/truapi/src/scale.ts

@@ -9,12 +9,12 @@ import {
   Bytes,
   Enum,
   Struct,
-  _void,
   createCodec,
   createDecoder,
   enhanceCodec,
-  str as scaleStr,
+  str,
   u8,
+  _void,
   type Codec,
 } from "scale-ts";
 import {
@@ -123,49 +123,23 @@ export function TaggedUnion<O extends TaggedUnionCodecs>(
   return Enum(inner) as unknown as Codec<TaggedUnionValue<O>>;
 }
 
-/**
- * Wire codec for Rust `CallError<D>`, projected to the public domain error `D`.
- *
- * Generated TypeScript APIs expose only the domain error union in
- * `ResultAsync<Ok, D>`. The Rust host still wraps that value in
- * `CallError::Domain` on the wire so framework errors can share the response
- * channel. Encoding always emits `Domain`; decoding returns the inner domain
- * value and throws for framework-level failures that have no public `D` shape.
- */
-export function CallError<D>(domain: Codec<D>): Codec<D> {
-  type WireCallError =
-    | { tag: "Domain"; value: D }
-    | { tag: "Denied"; value?: undefined }
-    | { tag: "Unsupported"; value?: undefined }
-    | { tag: "MalformedFrame"; value: { reason: string } }
-    | { tag: "HostFailure"; value: { reason: string } };
+/** Public TS value for Rust's derived `CallError<D>` enum. */
+export type CallErrorValue<D> =
+  | { tag: "Domain"; value: D }
+  | { tag: "Denied"; value?: undefined }
+  | { tag: "Unsupported"; value?: undefined }
+  | { tag: "MalformedFrame"; value: { reason: string } }
+  | { tag: "HostFailure"; value: { reason: string } };
 
-  const wire = Enum({
+/** SCALE codec for Rust's derived `CallError<D>` enum. */
+export function CallError<D>(domain: Codec<D>): Codec<CallErrorValue<D>> {
+  return TaggedUnion({
     Domain: domain,
     Denied: _void,
     Unsupported: _void,
-    MalformedFrame: Struct({ reason: scaleStr }),
-    HostFailure: Struct({ reason: scaleStr }),
-  }) as unknown as Codec<WireCallError>;
-
-  return enhanceCodec(
-    wire,
-    (value: D): WireCallError => ({ tag: "Domain", value }),
-    (value: WireCallError): D => {
-      switch (value.tag) {
-        case "Domain":
-          return value.value;
-        case "Denied":
-          throw new Error("Host denied the request");
-        case "Unsupported":
-          throw new Error("Host does not support this request");
-        case "MalformedFrame":
-          throw new Error(`Malformed request frame: ${value.value.reason}`);
-        case "HostFailure":
-          throw new Error(`Host failure: ${value.value.reason}`);
-      }
-    },
-  );
+    MalformedFrame: Struct({ reason: str }),
+    HostFailure: Struct({ reason: str }),
+  }) as Codec<CallErrorValue<D>>;
 }
 
 type TaggedUnionCodecs = {

rust/crates/truapi-codegen/src/rustdoc.rs

@@ -294,6 +294,9 @@ pub fn extract_api(krate: &Crate) -> Result<ApiDefinition> {
         }
 
         for candidate in candidates {
+            if should_skip_type_candidate(&name, &candidate) {
+                continue;
+            }
             let item = krate
                 .index
                 .get(&candidate.item_id)
@@ -393,18 +396,24 @@ fn should_skip_type_name(name: &str) -> bool {
             | "CancellationToken"
             | "FrameworkOnlyError"
             | "Infallible"
+            | "LatestOf"
             | "RequestId"
             | "RuntimeFailure"
             | "RuntimeFailureKind"
     )
 }
 
+fn should_skip_type_candidate(name: &str, candidate: &ItemCandidate) -> bool {
+    should_skip_type_name(name) || candidate.path.iter().any(|segment| segment == "latest")
+}
+
 fn build_name_context(type_candidates: &BTreeMap<String, Vec<ItemCandidate>>) -> NameContext {
     let mut ctx = NameContext::default();
     for (simple_name, candidates) in type_candidates {
-        if should_skip_type_name(simple_name) {
-            continue;
-        }
+        let candidates = candidates
+            .iter()
+            .filter(|candidate| !should_skip_type_candidate(simple_name, candidate))
+            .collect::<Vec<_>>();
         let has_conflict = candidates.len() > 1;
         for candidate in candidates {
             let output_name = if has_conflict {

rust/crates/truapi-codegen/src/ts.rs

@@ -1901,6 +1901,12 @@ fn codec_expr_mode(
             _ => bail!("Unsupported primitive type `{name}` in TypeScript codec generation"),
         },
         TypeRef::Named { name, args } => {
+            if name == "CallError" && args.len() == 1 {
+                return Ok(format!(
+                    "S.CallError({})",
+                    codec_expr_mode(&args[0], qualified, ctx, mode)?
+                ));
+            }
             let resolved = resolve_named(name, mode);
             let target = if qualified {
                 qualify_named(&resolved, mode)
@@ -1975,6 +1981,12 @@ fn ts_type_with_named(ty: &TypeRef, qualified: bool, mode: NameMode) -> Result<S
             _ => bail!("Unsupported primitive type `{name}` in TypeScript type generation"),
         },
         TypeRef::Named { name, args } => {
+            if name == "CallError" && args.len() == 1 {
+                return Ok(format!(
+                    "S.CallErrorValue<{}>",
+                    ts_type_with_named(&args[0], qualified, mode)?
+                ));
+            }
             let resolved = resolve_named(name, mode);
             let target = if qualified {
                 qualify_named(&resolved, mode)

rust/crates/truapi/src/api/mod.rs rust/crates/truapi/src/api.rsrust/crates/truapi/src/api/mod.rs renamed to rust/crates/truapi/src/api.rs

@@ -14,6 +14,8 @@ pub mod resource_allocation;
 pub mod signing;
 pub mod statement_store;
 pub mod system;
+#[cfg(debug_assertions)]
+pub mod testing;
 pub mod theme;
 
 pub use account::Account;
@@ -30,9 +32,12 @@ pub use resource_allocation::ResourceAllocation;
 pub use signing::Signing;
 pub use statement_store::StatementStore;
 pub use system::System;
+#[cfg(debug_assertions)]
+pub use testing::Testing;
 pub use theme::Theme;
 
 /// The unified TrUAPI contract.
+#[cfg(debug_assertions)]
 pub trait TrUApi:
     Account
     + Chain
@@ -48,12 +53,59 @@ pub trait TrUApi:
     + Signing
     + StatementStore
     + System
+    + Testing
     + Theme
     + Send
     + Sync
 {
 }
 
+#[cfg(not(debug_assertions))]
+pub trait TrUApi:
+    Account
+    + Chain
+    + Chat
+    + CoinPayment
+    + Entropy
+    + LocalStorage
+    + Notifications
+    + Payment
+    + Permissions
+    + Preimage
+    + ResourceAllocation
+    + Signing
+    + StatementStore
+    + System
+    + Theme
+    + Send
+    + Sync
+{
+}
+
+#[cfg(debug_assertions)]
+impl<T> TrUApi for T where
+    T: Account
+        + Chain
+        + Chat
+        + CoinPayment
+        + Entropy
+        + LocalStorage
+        + Notifications
+        + Payment
+        + Permissions
+        + Preimage
+        + ResourceAllocation
+        + Signing
+        + StatementStore
+        + System
+        + Testing
+        + Theme
+        + Send
+        + Sync
+{
+}
+
+#[cfg(not(debug_assertions))]
 impl<T> TrUApi for T where
     T: Account
         + Chain

rust/crates/truapi/src/api/statement_store.rs

@@ -6,7 +6,8 @@ use crate::versioned::statement_store::{
     RemoteStatementStoreCreateProofAuthorizedResponse, RemoteStatementStoreCreateProofError,
     RemoteStatementStoreCreateProofRequest, RemoteStatementStoreCreateProofResponse,
     RemoteStatementStoreSubmitError, RemoteStatementStoreSubmitRequest,
-    RemoteStatementStoreSubscribeItem, RemoteStatementStoreSubscribeRequest,
+    RemoteStatementStoreSubscribeError, RemoteStatementStoreSubscribeItem,
+    RemoteStatementStoreSubscribeRequest,
 };
 use crate::wire;
 use crate::{CallContext, CallError, Subscription};
@@ -56,8 +57,11 @@ pub trait StatementStore: Send + Sync {
         &self,
         _cx: &CallContext,
         _request: RemoteStatementStoreSubscribeRequest,
-    ) -> Subscription<RemoteStatementStoreSubscribeItem> {
-        Subscription::empty()
+    ) -> Result<
+        Subscription<RemoteStatementStoreSubscribeItem>,
+        CallError<RemoteStatementStoreSubscribeError>,
+    > {
+        Err(CallError::unavailable())
     }
 
     /// Create a proof for a statement.

rust/crates/truapi/src/api/testing.rs

@@ -0,0 +1,63 @@
+//! Debug-only API used to verify wire-version and framework-error handling.
+
+use crate::v01;
+use crate::v02;
+use crate::versioned::testing::{
+    TestingVersionProbeError, TestingVersionProbeRequest, TestingVersionProbeResponse,
+};
+use crate::wire;
+use crate::{CallContext, CallError};
+
+/// Development-only probes for generated client/runtime compatibility.
+pub trait Testing: Send + Sync {
+    /// Echo the request version back to the caller.
+    ///
+    /// ```ts
+    /// const result = await truapi.testing.versionProbe({
+    ///   message: "hello from V2",
+    ///   marker: 42,
+    /// });
+    /// assert(result.isOk(), "testing version probe failed:", result);
+    /// console.log("testing version probe:", result.value);
+    /// ```
+    #[wire(request_id = 164)]
+    async fn version_probe(
+        &self,
+        _cx: &CallContext,
+        request: TestingVersionProbeRequest,
+    ) -> Result<TestingVersionProbeResponse, CallError<TestingVersionProbeError>> {
+        match request {
+            TestingVersionProbeRequest::V1(inner) => Ok(TestingVersionProbeResponse::V1(
+                v01::TestingVersionProbeResponse {
+                    received_version: 1,
+                    message: inner.message,
+                },
+            )),
+            TestingVersionProbeRequest::V2(inner) => Ok(TestingVersionProbeResponse::V2(
+                v02::TestingVersionProbeResponse {
+                    received_version: 2,
+                    message: inner.message,
+                    marker: inner.marker,
+                },
+            )),
+        }
+    }
+
+    /// Echo a framework/domain error on the public response channel.
+    ///
+    /// ```ts
+    /// const result = await truapi.testing.echoError({
+    ///   error: { tag: "HostFailure", value: { reason: "forced by test" } },
+    /// });
+    /// assert(result.isErr(), "expected host failure");
+    /// console.log("echo error:", result.error);
+    /// ```
+    #[wire(request_id = 166)]
+    async fn echo_error(
+        &self,
+        _cx: &CallContext,
+        request: v01::EchoErrorRequest,
+    ) -> Result<(), CallError<v01::TestingVersionProbeError>> {
+        Err(request.error)
+    }
+}