feat: migrate protocol and HTTP to structured interface references

T-20: identify interfaces by exact scope/name pairs; add optional opaque scope_ref metadata and separate shape validation from path-dependent scope compatibility. Preserve call error precedence, strict JSON, validators and transport boundaries. Mechanically migrate consumers and document API/wire compatibility and deferred lifecycle semantics.

Validation: cargo fmt --all --check; git diff --check; cargo check --workspace --all-targets; cargo test -p wip-protocol -p wip-http; cargo test --workspace (221 passing tests including doctests); cargo test --workspace --all-targets; nix develop --command cargo clippy --workspace --all-targets -- -D warnings; RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps. All pass. cargo/rustc 1.95.0; development-shell Clippy/rustc 1.97.1.

crates/wip-http/tests/codecs.rs

@@ -4,9 +4,9 @@ use wip_http::http::StatusCode;
 use wip_http::wip_protocol::{
     CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
     FetchInterfaceResponse, FieldDeclaration, INTERFACE_FORMAT_V1, InterfaceDescriptor,
-    InterfaceTarget, MAX_SAFE_INTEGER, Object, ObjectObservation, ObserveRequest,
-    OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target, TypeDeclaration,
-    TypeExpr, UnionCase, Value,
+    InterfaceReference, InterfaceTarget, MAX_SAFE_INTEGER, Object, ObjectObservation,
+    ObserveRequest, OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target,
+    TypeDeclaration, TypeExpr, UnionCase, Value,
 };
 use wip_http::{
     ClientResponseError, CodecError, DecodedResponse, Endpoint, InvalidResponseKind, Limits,
@@ -25,11 +25,18 @@ fn endpoint() -> Endpoint {
     Endpoint::parse("https://example.test/wip").unwrap()
 }
 
+fn reference(scope: &str, name: &str) -> InterfaceReference {
+    InterfaceReference {
+        scope: scope.into(),
+        name: name.into(),
+    }
+}
+
 fn object(name: &str, validator: &[u8]) -> Object {
     Object {
         name: name.into(),
         description: Some("description".into()),
-        interfaces: vec!["interface-v1".into()],
+        interfaces: vec![reference("/", "interface-v1")],
         r#ref: Some(format!("object:{name}")),
         validator: Some(validator.to_vec()),
     }
@@ -152,7 +159,8 @@ fn call_request() -> CallOperationRequest {
             validator: Some(vec![0, 1, 2, 255]),
         },
         interface: InterfaceTarget {
-            reference: "interface-v1".into(),
+            reference: reference("/", "interface-v1"),
+            scope_ref: None,
             validator: Some(vec![9, 8, 7]),
         },
         operation: "everything".into(),
@@ -206,7 +214,7 @@ fn every_single_interaction_request_accepts_json() {
     let fetch_interface = encode_fetch_interface_request(
         &endpoint(),
         &FetchInterfaceRequest {
-            interface: "interface-v1".into(),
+            interface: reference("/", "interface-v1"),
         },
         limits(),
     )
@@ -286,7 +294,7 @@ fn observe_and_interface_round_trip_nested_logical_models() {
     );
 
     let interface_request = FetchInterfaceRequest {
-        interface: "interface-v1".into(),
+        interface: reference("/", "interface-v1"),
     };
     let encoded_request =
         encode_fetch_interface_request(&endpoint(), &interface_request, limits()).unwrap();
@@ -296,6 +304,7 @@ fn observe_and_interface_round_trip_nested_logical_models() {
     );
     let interface = FetchInterfaceResponse {
         interface: interface_request.interface.clone(),
+        scope_ref: None,
         descriptor: descriptor(),
         validator: Some(vec![4, 5, 6, 255]),
     };
@@ -383,7 +392,7 @@ fn malformed_unknown_null_and_noncanonical_base64_are_rejected() {
     let descriptor = descriptor();
     let body = serde_json::to_vec(&serde_json::json!({
         "target": {"path": "/items/123", "validator": null},
-        "interface": {"reference": "interface-v1"},
+        "interface": {"reference": {"scope": "/", "name": "interface-v1"}},
         "operation": "everything",
         "arguments": {}
     }))
@@ -443,10 +452,11 @@ fn caller_limits_remain_local_codec_failures() {
 #[test]
 fn unsupported_descriptor_format_is_client_local() {
     let request = FetchInterfaceRequest {
-        interface: "interface-v1".into(),
+        interface: reference("/", "interface-v1"),
     };
     let mut interface = FetchInterfaceResponse {
         interface: request.interface.clone(),
+        scope_ref: None,
         descriptor: descriptor(),
         validator: None,
     };
@@ -462,7 +472,7 @@ fn unsupported_descriptor_format_is_client_local() {
         .status(StatusCode::OK)
         .header("content-type", "application/json; charset=utf-8")
         .body(
-            br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2","future_shape":true}}"#
+            br#"{"interface":{"scope":"/","name":"interface-v1"},"descriptor":{"format":"wip-interface/2","future_shape":true}}"#
                 .to_vec(),
         )
         .unwrap();
@@ -473,8 +483,8 @@ fn unsupported_descriptor_format_is_client_local() {
     ));
 
     for malformed in [
-        br#"{"interface":"wrong","descriptor":{"format":"wip-interface/2"}}"#.as_slice(),
-        br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"},"validator":null}"#
+        br#"{"interface":{"scope":"/","name":"wrong"},"descriptor":{"format":"wip-interface/2"}}"#.as_slice(),
+        br#"{"interface":{"scope":"/","name":"interface-v1"},"descriptor":{"format":"wip-interface/2"},"validator":null}"#
             .as_slice(),
     ] {
         let response = wip_http::http::Response::builder()