feat(interface): add authoring macros and codecs

Add the wip-interface facade and proc-macro implementation for typed interface descriptors, DTO value codecs, validated dispatch, metadata extraction, and span-aware compile failures.

crates/wip-interface/tests/interface.rs

@@ -0,0 +1,218 @@
+use wip_interface::wip_protocol::{NamedValue, TypeDeclaration, TypeExpr, Value};
+use wip_interface::{DispatchError, HostError, OperationResult, WipType, interface};
+
+/// Publication request.
+#[derive(Debug, Clone, PartialEq, WipType)]
+pub struct PublishRequest {
+    /// Item title.
+    pub title: String,
+}
+
+/// Application outcome, including domain failure.
+#[derive(Debug, Clone, PartialEq, WipType)]
+pub enum PublishOutcome {
+    /// The item was accepted.
+    Published(bool),
+    /// The application rejected the item.
+    Rejected(String),
+}
+
+/// Catalog editing capability.
+///
+/// The shape is implementation-independent.
+#[interface]
+pub trait Catalog {
+    /// Publishes one item.
+    ///
+    /// This operation can report a domain rejection in its application union.
+    ///
+    /// # Returns
+    /// The application publication outcome.
+    fn publish(
+        &self,
+        /// Item to publish.
+        request: PublishRequest,
+        /// Optional audit note.
+        note: Option<String>,
+    ) -> OperationResult<PublishOutcome>;
+
+    /// Checks connectivity without returning an application value.
+    fn ping(&self) -> OperationResult<()>;
+
+    /// Demonstrates a host/runtime failure.
+    ///
+    /// # Returns
+    /// A value only when the host succeeds.
+    fn host_value(&self) -> OperationResult<String>;
+}
+
+struct AcceptingCatalog;
+
+impl Catalog for AcceptingCatalog {
+    fn publish(
+        &self,
+        request: PublishRequest,
+        note: Option<String>,
+    ) -> OperationResult<PublishOutcome> {
+        assert_eq!(request.title, "example");
+        assert_eq!(note.as_deref(), Some("audit"));
+        Ok(PublishOutcome::Published(true))
+    }
+
+    fn ping(&self) -> OperationResult<()> {
+        Ok(())
+    }
+
+    fn host_value(&self) -> OperationResult<String> {
+        Err(HostError::new("backend unavailable"))
+    }
+}
+
+struct RejectingCatalog;
+
+impl Catalog for RejectingCatalog {
+    fn publish(
+        &self,
+        _request: PublishRequest,
+        _note: Option<String>,
+    ) -> OperationResult<PublishOutcome> {
+        Ok(PublishOutcome::Rejected("policy".into()))
+    }
+
+    fn ping(&self) -> OperationResult<()> {
+        Ok(())
+    }
+
+    fn host_value(&self) -> OperationResult<String> {
+        Ok("ready".into())
+    }
+}
+
+fn named(name: &str, value: Value) -> NamedValue {
+    NamedValue {
+        name: name.into(),
+        value,
+    }
+}
+
+fn publish_arguments(with_note: bool) -> Vec<NamedValue> {
+    let mut arguments = vec![named(
+        "request",
+        PublishRequest {
+            title: "example".into(),
+        }
+        .encode()
+        .unwrap(),
+    )];
+    if with_note {
+        arguments.push(named("note", Value::String("audit".into())));
+    }
+    arguments
+}
+
+#[test]
+fn descriptor_is_generated_only_from_the_trait_declaration() {
+    let first = CatalogDefinition::descriptor();
+    let second = CatalogDefinition::descriptor();
+    assert_eq!(first, second);
+    first.validate().unwrap();
+
+    assert_eq!(first.name, "Catalog");
+    assert_eq!(
+        first.documentation.as_ref().unwrap().summary,
+        "Catalog editing capability."
+    );
+    assert_eq!(
+        first.documentation.as_ref().unwrap().details.as_deref(),
+        Some("The shape is implementation-independent.")
+    );
+    assert_eq!(first.operations.len(), 3);
+
+    let publish = &first.operations[0];
+    assert_eq!(publish.name, "publish");
+    assert_eq!(publish.parameters[0].name, "request");
+    assert_eq!(
+        publish.parameters[0]
+            .documentation
+            .as_ref()
+            .unwrap()
+            .summary,
+        "Item to publish."
+    );
+    assert!(!publish.parameters[0].optional);
+    assert!(publish.parameters[1].optional);
+    assert_eq!(
+        publish
+            .returns
+            .as_ref()
+            .unwrap()
+            .documentation
+            .as_ref()
+            .unwrap()
+            .summary,
+        "The application publication outcome."
+    );
+    assert_eq!(
+        publish.returns.as_ref().unwrap().ty,
+        TypeExpr::Named("PublishOutcome".into())
+    );
+    assert!(first.operations[1].returns.is_none());
+    assert!(
+        first
+            .declarations
+            .iter()
+            .any(|declaration| matches!(declaration, TypeDeclaration::Record(_)))
+    );
+    assert!(
+        first
+            .declarations
+            .iter()
+            .any(|declaration| matches!(declaration, TypeDeclaration::Union(_)))
+    );
+
+    // Both implementation types satisfy the same generated dispatch boundary;
+    // neither can affect the descriptor shape.
+    fn accepts_definition<T: Catalog>(_: &T) {}
+    accepts_definition(&AcceptingCatalog);
+    accepts_definition(&RejectingCatalog);
+}
+
+#[test]
+fn generated_argument_decoder_and_result_encoder_round_trip() {
+    let decoded = CatalogPublishArguments::decode(publish_arguments(false)).unwrap();
+    assert_eq!(decoded.request.title, "example");
+    assert_eq!(decoded.note, None);
+
+    let encoded = CatalogPublishArguments::encode_result(PublishOutcome::Rejected("domain".into()))
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        PublishOutcome::decode(encoded).unwrap(),
+        PublishOutcome::Rejected("domain".into())
+    );
+}
+
+#[test]
+fn typed_dispatch_validates_decodes_invokes_encodes_and_validates() {
+    let value = CatalogDefinition::dispatch(&AcceptingCatalog, "publish", publish_arguments(true))
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        PublishOutcome::decode(value).unwrap(),
+        PublishOutcome::Published(true)
+    );
+
+    assert_eq!(
+        CatalogDefinition::dispatch(&AcceptingCatalog, "ping", vec![]).unwrap(),
+        None
+    );
+
+    let invalid = CatalogDefinition::dispatch(&AcceptingCatalog, "publish", vec![]).unwrap_err();
+    assert!(matches!(invalid, DispatchError::InvalidArguments(_)));
+
+    let host = CatalogDefinition::dispatch(&AcceptingCatalog, "host_value", vec![]).unwrap_err();
+    assert!(matches!(host, DispatchError::Host(error) if error.message() == "backend unavailable"));
+
+    let unknown = CatalogDefinition::dispatch(&AcceptingCatalog, "missing", vec![]).unwrap_err();
+    assert!(matches!(unknown, DispatchError::UnknownOperation(name) if name == "missing"));
+}