feat: model operation outcome guarantees

Cargo.toml

@@ -1,22 +1,3 @@
 [workspace]
-members = [
-    ".",
-    "crates/wip-host",
-    "crates/wip-interface",
-    "crates/wip-interface-macros",
-    "crates/wip-protocol",
-]
+members = ["crates/*"]
 resolver = "3"
-
-[package]
-name = "wip-public-api-example"
-version = "0.1.0"
-edition = "2024"
-description = "End-to-end example of the public WIP Rust APIs"
-license = "MIT OR Apache-2.0"
-publish = false
-
-[dependencies]
-wip-host = { path = "crates/wip-host" }
-wip-interface = { path = "crates/wip-interface" }
-wip-protocol = { path = "crates/wip-protocol" }

README.md

@@ -2,9 +2,12 @@
 
 Rust building blocks for the Web Interface Protocol (WIP).
 
-The repository currently provides a transport-independent protocol model, a
-Rust interface-authoring facade, and a request-scoped host runtime. HTTP and
-other transport bindings are intentionally outside the supported slice.
+The repository is a resolver-3 virtual Cargo workspace whose packages all live
+under `crates/*`. It provides a transport-independent protocol model, a Rust
+interface-authoring facade, a request-scoped host runtime, and a private
+public-API conformance consumer. The repository root is not itself a package.
+HTTP and other transport bindings are intentionally outside the supported
+slice.
 
 ## Crate graph and responsibilities
 
@@ -36,19 +39,26 @@ or application traits.
 
 ## End-to-end example
 
-[`src/lib.rs`](src/lib.rs) is the complete public-API example and
-[`src/main.rs`](src/main.rs) runs it. It demonstrates all of the following:
+[`crates/wip-public-api-example/src/lib.rs`](crates/wip-public-api-example/src/lib.rs)
+is the complete public-API example and
+[`crates/wip-public-api-example/src/main.rs`](crates/wip-public-api-example/src/main.rs)
+runs it. It demonstrates all of the following:
 
-1. public application DTOs derived as `WipType` records and unions;
+1. public application DTOs derived as `WipType` records, enums, and unions,
+   including canonical entry paths and schema-opaque JSON;
 2. two public traits declared with `#[wip::interface]`;
 3. a private host struct implementing both traits;
-4. explicit publication of both interfaces on one object;
-5. registry observation and validation of generated descriptors;
-6. calls made with interface references, operation names, and `Value` arguments;
+4. explicit publication of both interfaces as an ordered set on one object;
+5. separate observation of opaque interface references, descriptors, and
+   descriptor validators;
+6. calls qualified by `target.path`, object validator, interface reference and
+   validator, operation, and schema-neutral `Value` arguments;
 7. validated result values decoded back to the typed application result;
 8. independent dispatch of the same `status` operation name on both interfaces;
-9. a domain rejection returned as data and a backend failure returned as a host
-   error.
+9. distinct domain rejection, rollback-confirmed and outcome-unknown
+   host/backend failures, `PermissionDenied`, stale validator recovery, interface
+   membership, and lookup failure codes; and
+10. canonical failure precedence when several request fields are invalid.
 
 Run it inside the development shell:
 
@@ -57,10 +67,17 @@ nix develop
 cargo run --package wip-public-api-example
 ```
 
-The normal integration test is in [`tests/end_to_end.rs`](tests/end_to_end.rs).
-Unit tests beside the example additionally cover every host dispatch failure,
-invalid arguments and results, interface membership, validators, and
-same-named operations.
+The public-only conformance suite is in
+[`crates/wip-public-api-example/tests/end_to_end.rs`](crates/wip-public-api-example/tests/end_to_end.rs).
+It covers canonical object/descriptor shape, ordered interfaces,
+schema-neutral record/enum/union/entry/JSON values, fully qualified calls, and
+the distinct domain, host, authorization, validator-recovery, and interface
+failure classes. Exhaustive public type construction and matching make legacy
+ObjectId, descriptor `name`, and semantic `Value` variants compile-time
+regressions. Unit tests in the public crates additionally cover every host
+dispatch failure, `InvalidRequest` versus descriptor-bound `InvalidArguments`,
+invalid local responses, validators, same-named operations, and exhaustive
+per-interaction protocol error-code sets.
 
 ## Interface authoring
 
@@ -185,19 +202,39 @@ are never projected by `WipObject`; host-private fields and backend handles are
 also excluded.
 
 Application domain failures belong in a derived result union and are returned
-through `Ok`. `wip::HostError` is reserved for runtime/backend failures. Invalid
-arguments are rejected before invocation; malformed encoded results are
-reported as `InvalidResult` and never returned as application data. Validator,
-membership, authorization, and result failures retain their distinct canonical
-protocol error codes.
+through `Ok`. `wip::HostError` is reserved for runtime/backend failures. A
+structurally malformed call is `InvalidRequest`; only argument values checked
+after the current Interface Descriptor is fixed are `InvalidArguments`. A Host
+must never return a wire `InvalidResult`: Clients keep invalid Object,
+Descriptor, operation-result, and error responses as local `InvalidResponse`
+failures, while unsupported descriptor formats remain local
+`UnsupportedDescriptorFormat` failures.
 
-Providers remain responsible for backend atomicity. Enter a transaction, lock,
-stable-handle scope, or conditional-update primitive before invoking the
-`with_object` callback, and retain it until the callback returns. Mutable
-operations must make validator comparison and backend commit atomic and return a
-validator for the committed state. The runtime never validates one object and
-then resolves a second snapshot, but it cannot make an arbitrary external
-backend atomic by itself.
+For operation calls, `Internal` and `ResourceLimitExceeded` guarantee that the
+operation did not run or that its effects were rolled back.
+`OperationOutcomeUnknown` is the only protocol code that makes no such
+guarantee, so Clients must not automatically retry it. `wip::HostError`
+therefore requires both a `HostErrorKind` and an `EffectGuarantee`; implementation
+panic, result encoding, and result validation default to an unknown outcome.
+Host-private diagnostics are bounded locally but never copied into protocol
+messages.
+
+`ExecutionContext` carries a runtime-neutral cancellation token, monotonic
+deadline, and optional Host-defined resource budget through resolution and
+execution. Cancellation and deadlines are cooperative: the runtime checks them
+immediately before typed invocation, while providers enforce them during backend
+work. A pre-invocation limit failure is `ResourceLimitExceeded`; after invocation
+it is safe to use that code only when non-commit or rollback is confirmed.
+
+Providers remain responsible for backend atomicity. `with_object` returns a typed
+`ProviderResult`, and `execute_operation` receives an `OperationAttempt` that
+separates `NotStarted` from `Started`. A transactional provider holds its
+transaction across the callback, commits successful attempts, and may call
+`OperationAttempt::confirm_rollback` only after every operation effect has been
+rolled back. Without that proof, post-invocation failures remain
+`OperationOutcomeUnknown`. Mutable operations must still make validator
+comparison and backend commit atomic and return a validator describing the state
+that becomes committed.
 
 ## Validation
 
@@ -208,10 +245,14 @@ nix develop
 cargo fmt --all -- --check
 cargo check --workspace --all-targets
 cargo test --workspace --all-targets
+cargo test --workspace --doc
 cargo clippy --workspace --all-targets -- -D warnings
+RUSTDOCFLAGS='-D warnings' cargo doc --workspace --no-deps
+cargo run --package wip-public-api-example
+git diff --check
 ```
 
-`cargo test --workspace --all-targets` includes the public example integration
-test, runtime failure tests, and `trybuild` compile-fail suites. Run
-`cargo test --workspace --doc` when validating the checked rustdoc examples
-separately.
+`cargo test --workspace --all-targets` includes the public-only conformance
+consumer, runtime failure tests, and `trybuild` compile-fail suites. The separate
+doctest, rustdoc, executable, and whitespace checks are all required acceptance
+steps.

crates/wip-host/src/lib.rs

@@ -18,11 +18,14 @@
 //!
 //! A provider is responsible for entering a backend transaction, lock,
 //! stable-handle scope, or conditional-update primitive before invoking the
-//! callback and retaining it until the callback returns. The runtime does not
-//! reopen the path or select another implementation after checking validators,
-//! but cannot make an arbitrary external backend atomic on its own. Mutable
-//! operations must make object-validator comparison and backend commit atomic;
-//! the validator returned after dispatch must describe the committed state.
+//! operation callback and retaining it through commit or rollback. The typed
+//! [`OperationAttempt`] boundary distinguishes pre-dispatch rejection from started
+//! execution. Only an implementation-supplied non-commit guarantee or a
+//! provider-confirmed rollback allows a post-invocation failure to become
+//! `Internal` or `ResourceLimitExceeded`; every other outcome is
+//! `OperationOutcomeUnknown`. Mutable operations must make object-validator
+//! comparison and backend commit atomic, and the validator returned after dispatch
+//! must describe the state that becomes committed.
 
 #![deny(missing_docs)]
 
@@ -31,19 +34,23 @@ use std::collections::{BTreeMap, HashMap, HashSet};
 use std::error::Error;
 use std::fmt::{self, Display, Formatter};
 use std::marker::PhantomData;
+use std::panic::{AssertUnwindSafe, catch_unwind};
 use std::sync::Arc;
-use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::time::Instant;
 
 use wip_interface::DispatchError;
-pub use wip_interface::{InterfaceDefinition, InterfaceImplementation};
+pub use wip_interface::{
+    EffectGuarantee, HostError, HostErrorKind, InterfaceDefinition, InterfaceImplementation,
+};
 pub use wip_protocol;
 pub use wip_protocol::{
     CallOperationRequest as CallRequest, CallOperationResponse as CallResult, InterfaceTarget,
     Target,
 };
 use wip_protocol::{
-    FetchInterfaceResponse, InterfaceDescriptor, Object, ProtocolError, ProtocolErrorCode,
-    ValidationError, Value,
+    FetchInterfaceRequest, FetchInterfaceResponse, InterfaceDescriptor, Object, ProtocolError,
+    ProtocolErrorCode, ValidationError, Value,
 };
 
 /// Opaque bytes used as a conditional execution precondition.
@@ -64,6 +71,122 @@ impl Validator {
     }
 }
 
+/// Runtime-neutral cooperative cancellation signal.
+///
+/// Clones observe the same atomic state, so transports, providers, and worker
+/// runtimes can share the token without depending on a particular async runtime.
+#[derive(Debug, Clone, Default)]
+pub struct CancellationToken(Arc<AtomicBool>);
+
+impl CancellationToken {
+    /// Creates a cancellation token in the active state.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Requests cooperative cancellation.
+    pub fn cancel(&self) {
+        self.0.store(true, Ordering::Release);
+    }
+
+    /// Returns whether cancellation has been requested.
+    #[must_use]
+    pub fn is_cancelled(&self) -> bool {
+        self.0.load(Ordering::Acquire)
+    }
+}
+
+/// Execution controls propagated through object resolution and operation dispatch.
+///
+/// Cancellation and deadlines are checked immediately before typed implementation
+/// invocation. Providers also receive the complete context and remain responsible
+/// for enforcing controls while backend work is in progress. `resource_budget` is
+/// an opaque Host-defined work-unit ceiling; this crate deliberately does not
+/// prescribe an async runtime or accounting mechanism.
+#[derive(Debug, Clone)]
+pub struct ExecutionContext {
+    cancellation: CancellationToken,
+    deadline: Option<Instant>,
+    resource_budget: Option<u64>,
+}
+
+impl Default for ExecutionContext {
+    fn default() -> Self {
+        Self {
+            cancellation: CancellationToken::new(),
+            deadline: None,
+            resource_budget: None,
+        }
+    }
+}
+
+impl ExecutionContext {
+    /// Creates an execution context without a deadline or resource budget.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Uses `cancellation` as this call's cooperative cancellation signal.
+    #[must_use]
+    pub fn with_cancellation(mut self, cancellation: CancellationToken) -> Self {
+        self.cancellation = cancellation;
+        self
+    }
+
+    /// Sets the monotonic deadline for this call.
+    #[must_use]
+    pub fn with_deadline(mut self, deadline: Instant) -> Self {
+        self.deadline = Some(deadline);
+        self
+    }
+
+    /// Sets an opaque Host-defined work-unit ceiling for this call.
+    #[must_use]
+    pub fn with_resource_budget(mut self, resource_budget: u64) -> Self {
+        self.resource_budget = Some(resource_budget);
+        self
+    }
+
+    /// Returns the shared cooperative cancellation token.
+    #[must_use]
+    pub fn cancellation(&self) -> &CancellationToken {
+        &self.cancellation
+    }
+
+    /// Returns the monotonic deadline, if one was supplied.
+    #[must_use]
+    pub fn deadline(&self) -> Option<Instant> {
+        self.deadline
+    }
+
+    /// Returns the opaque Host-defined work-unit ceiling, if one was supplied.
+    #[must_use]
+    pub fn resource_budget(&self) -> Option<u64> {
+        self.resource_budget
+    }
+
+    fn preflight(&self) -> Result<(), CallError> {
+        if self.cancellation.is_cancelled() {
+            return Err(CallError::new(
+                CallErrorKind::ResourceLimitExceeded,
+                "operation was cancelled before execution",
+            ));
+        }
+        if self
+            .deadline
+            .is_some_and(|deadline| Instant::now() >= deadline)
+        {
+            return Err(CallError::new(
+                CallErrorKind::ResourceLimitExceeded,
+                "operation deadline elapsed before execution",
+            ));
+        }
+        Ok(())
+    }
+}
+
 /// Opaque host-assigned reference to one registered interface artifact.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct InterfaceRef(String);
@@ -88,14 +211,26 @@ pub struct InterfaceObservation {
 }
 
 impl InterfaceObservation {
-    /// Converts this host observation to the canonical protocol response.
-    #[must_use]
-    pub fn protocol_response(&self) -> FetchInterfaceResponse {
-        FetchInterfaceResponse {
+    /// Converts this host observation to a validated canonical protocol response.
+    ///
+    /// A Host-side response construction failure is returned as `Internal`; it is
+    /// never emitted as a successful response for a Client to reinterpret as a
+    /// local validation error.
+    pub fn protocol_response(&self) -> Result<FetchInterfaceResponse, ProtocolError> {
+        let response = FetchInterfaceResponse {
             interface: self.reference.0.clone(),
             descriptor: self.descriptor.clone(),
             validator: self.validator.as_ref().map(|validator| validator.0.clone()),
-        }
+        };
+        response
+            .validate_for(&FetchInterfaceRequest {
+                interface: self.reference.0.clone(),
+            })
+            .map_err(|_| ProtocolError {
+                code: ProtocolErrorCode::Internal,
+                message: "Host produced an invalid interface response".into(),
+            })?;
+        Ok(response)
     }
 }
 
@@ -397,26 +532,29 @@ impl<T: WipObject> PublishedObject<T> {
 
     fn dispatch_resolved(
         &self,
+        context: &ExecutionContext,
         request: CallRequest,
         authorize: impl FnOnce(&T, &InterfaceRef, &str) -> bool,
-    ) -> Result<CallResult, CallError> {
+    ) -> OperationAttempt {
+        let pre_dispatch_failure =
+            |kind, message: &str| OperationAttempt::NotStarted(CallError::new(kind, message));
         let current_object_validator = self.implementation.validator();
         if let Some(supplied) = request.target.validator.as_deref()
             && current_object_validator.map(Validator::as_bytes) != Some(supplied)
         {
-            return Err(CallError::new(
+            return pre_dispatch_failure(
                 CallErrorKind::ValidatorMismatch,
                 "object validator does not match current object state",
-            ));
+            );
         }
 
         let Some(bound) = self.interfaces.iter().find(|bound| {
             bound.artifact.reference.as_str() == request.interface.reference.as_str()
         }) else {
-            return Err(CallError::new(
+            return pre_dispatch_failure(
                 CallErrorKind::InterfaceMismatch,
                 "interface is not a member of the current object publication",
-            ));
+            );
         };
 
         match (
@@ -424,16 +562,16 @@ impl<T: WipObject> PublishedObject<T> {
             request.interface.validator.as_deref(),
         ) {
             (Some(_), None) => {
-                return Err(CallError::new(
+                return pre_dispatch_failure(
                     CallErrorKind::InterfaceValidatorRequired,
                     "registered interface requires a validator",
-                ));
+                );
             }
             (expected, Some(actual)) if expected.map(Validator::as_bytes) != Some(actual) => {
-                return Err(CallError::new(
+                return pre_dispatch_failure(
                     CallErrorKind::InterfaceValidatorMismatch,
                     "interface validator does not match the registered descriptor",
-                ));
+                );
             }
             _ => {}
         }
@@ -445,10 +583,10 @@ impl<T: WipObject> PublishedObject<T> {
             .iter()
             .any(|operation| operation.name == request.operation)
         {
-            return Err(CallError::new(
+            return pre_dispatch_failure(
                 CallErrorKind::OperationNotFound,
-                format!("operation `{}` is not declared", request.operation),
-            ));
+                &format!("operation `{}` is not declared", request.operation),
+            );
         }
 
         if request.target.validator.is_none()
@@ -456,45 +594,67 @@ impl<T: WipObject> PublishedObject<T> {
                 .implementation
                 .requires_validator(&bound.artifact.reference, &request.operation)
         {
-            return Err(CallError::new(
+            return pre_dispatch_failure(
                 CallErrorKind::ValidatorRequired,
                 "this operation requires an object validator",
-            ));
+            );
         }
 
-        bound
+        if let Err(error) = bound
             .artifact
             .descriptor
             .validate_arguments(&request.operation, &request.arguments)
-            .map_err(|error| CallError::new(CallErrorKind::InvalidArguments, error.to_string()))?;
+        {
+            return pre_dispatch_failure(CallErrorKind::InvalidArguments, &error.to_string());
+        }
 
         if !authorize(
             &self.implementation,
             &bound.artifact.reference,
             &request.operation,
         ) {
-            return Err(CallError::new(
+            return pre_dispatch_failure(
                 CallErrorKind::PermissionDenied,
                 "operation is not permitted for this caller",
-            ));
+            );
         }
 
-        let value = (bound.dispatch)(&self.implementation, &request.operation, request.arguments)
-            .map_err(CallError::from_dispatch)?;
+        if let Err(error) = context.preflight() {
+            return OperationAttempt::NotStarted(error);
+        }
 
-        bound
+        let value =
+            match (bound.dispatch)(&self.implementation, &request.operation, request.arguments) {
+                Ok(value) => value,
+                Err(
+                    error @ (DispatchError::UnknownOperation(_)
+                    | DispatchError::InvalidArguments(_)
+                    | DispatchError::Decode(_)),
+                ) => return OperationAttempt::NotStarted(CallError::from_pre_dispatch(error)),
+                Err(error) => {
+                    return OperationAttempt::Started(Err(OperationFailure::from_dispatch(error)));
+                }
+            };
+
+        if bound
             .artifact
             .descriptor
             .validate_result(&request.operation, &value)
-            .map_err(|error| CallError::new(CallErrorKind::InvalidResult, error.to_string()))?;
+            .is_err()
+        {
+            return OperationAttempt::Started(Err(OperationFailure::internal(
+                EffectGuarantee::Unknown,
+                "operation implementation produced an invalid result",
+            )));
+        }
 
-        Ok(CallResult {
+        OperationAttempt::Started(Ok(CallResult {
             result: value,
             validator: self
                 .implementation
                 .validator()
                 .map(|validator| validator.0.clone()),
-        })
+        }))
     }
 
     /// Consumes the publication and returns its host-private implementation.
@@ -504,24 +664,158 @@ impl<T: WipObject> PublishedObject<T> {
     }
 }
 
+/// A post-invocation failure awaiting final provider effect disposition.
+///
+/// Providers may upgrade an unknown failure with [`confirm_rollback`](Self::confirm_rollback)
+/// only after the backend transaction has definitely rolled back. Diagnostics are
+/// intentionally generic and safe for protocol exposure.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OperationFailure {
+    kind: HostErrorKind,
+    effect_guarantee: EffectGuarantee,
+    message: String,
+}
+
+impl OperationFailure {
+    fn internal(effect_guarantee: EffectGuarantee, message: impl Into<String>) -> Self {
+        Self {
+            kind: HostErrorKind::Internal,
+            effect_guarantee,
+            message: bounded_message(message.into()),
+        }
+    }
+
+    fn from_dispatch(error: DispatchError) -> Self {
+        match error {
+            DispatchError::Host(error) => Self {
+                kind: error.kind(),
+                effect_guarantee: error.effect_guarantee(),
+                message: match error.kind() {
+                    HostErrorKind::Internal => "operation implementation failed".into(),
+                    HostErrorKind::ResourceLimitExceeded => {
+                        "operation resource limit was exceeded".into()
+                    }
+                },
+            },
+            DispatchError::Panic => Self::internal(
+                EffectGuarantee::Unknown,
+                "operation implementation panicked",
+            ),
+            DispatchError::Encode(_) => Self::internal(
+                EffectGuarantee::Unknown,
+                "operation result could not be encoded",
+            ),
+            DispatchError::InvalidResult(_) => Self::internal(
+                EffectGuarantee::Unknown,
+                "operation implementation produced an invalid result",
+            ),
+            DispatchError::UnknownOperation(_)
+            | DispatchError::InvalidArguments(_)
+            | DispatchError::Decode(_) => {
+                unreachable!("pre-dispatch failures are classified before OperationFailure")
+            }
+        }
+    }
+
+    /// Returns the Host failure category used when effects are not committed.
+    #[must_use]
+    pub fn kind(&self) -> HostErrorKind {
+        self.kind
+    }
+
+    /// Returns the current effect guarantee.
+    #[must_use]
+    pub fn effect_guarantee(&self) -> EffectGuarantee {
+        self.effect_guarantee
+    }
+
+    /// Confirms that the provider rolled back all operation effects.
+    ///
+    /// Calling this method is a semantic assertion by the provider and must occur
+    /// only after its atomic backend boundary has completed rollback.
+    #[must_use]
+    pub fn confirm_rollback(mut self) -> Self {
+        self.effect_guarantee = EffectGuarantee::NotCommitted;
+        self
+    }
+}
+
+/// Dispatch progress returned to the provider's atomic execution boundary.
+#[derive(Debug)]
+pub enum OperationAttempt {
+    /// A canonical precondition failed and typed implementation code did not run.
+    NotStarted(CallError),
+    /// Typed implementation invocation began, with either a result or a typed
+    /// post-invocation failure.
+    Started(Result<CallResult, OperationFailure>),
+}
+
+impl OperationAttempt {
+    /// Marks a post-invocation failure as fully rolled back.
+    ///
+    /// Successful attempts and pre-dispatch failures are returned unchanged.
+    #[must_use]
+    pub fn confirm_rollback(self) -> Self {
+        match self {
+            Self::Started(Err(error)) => Self::Started(Err(error.confirm_rollback())),
+            other => other,
+        }
+    }
+}
+
+/// Result of one provider resolution or execution boundary.
+#[derive(Debug)]
+pub enum ProviderResult<T> {
+    /// The path resolved and the provider callback completed.
+    Found(T),
+    /// The path is not currently published to this caller.
+    NotFound,
+    /// Provider or backend execution failed.
+    ///
+    /// During `call_operation`, the embedded effect guarantee determines whether
+    /// the failure is safe to expose as `Internal`/`ResourceLimitExceeded` or must
+    /// become `OperationOutcomeUnknown`.
+    Failure(HostError),
+}
+
 /// A request-scoped Worldspace resolver and execution boundary.
 ///
 /// `with_object` must resolve the current object at `path` exactly once and pass
 /// a publication that pins its current interface set, implementations, and
-/// backend target for the duration of `operation`. Implementations may hold a
-/// transaction or lock around the callback. Returning `None` means the path is
-/// not published to the caller. The borrowed publication cannot escape the
-/// callback, so the default call path cannot outlive that provider boundary.
+/// backend target for the duration of `operation`. The execution context is the
+/// runtime-neutral carrier for cancellation, deadline, and resource controls.
+/// The borrowed publication cannot escape the callback.
+///
+/// Providers that can roll back mutable operations should override
+/// [`ObjectProvider::execute_operation`], hold their transaction across the
+/// callback, and call [`OperationAttempt::confirm_rollback`] only after rollback
+/// succeeds. The default boundary conservatively preserves unknown outcomes.
 pub trait ObjectProvider {
     /// Host-private object type produced by this provider.
     type Object: WipObject;
 
-    /// Runs an operation against the single object snapshot resolved at `path`.
+    /// Runs a callback against the single object snapshot resolved at `path`.
     fn with_object<R>(
         &self,
+        context: &ExecutionContext,
         path: &str,
         operation: impl FnOnce(&PublishedObject<Self::Object>) -> R,
-    ) -> Option<R>;
+    ) -> ProviderResult<R>;
+
+    /// Runs one operation attempt inside the provider's atomic backend boundary.
+    ///
+    /// The default implementation delegates to [`ObjectProvider::with_object`]
+    /// and therefore does not add a rollback guarantee. Transactional providers
+    /// can override this method, inspect the returned [`OperationAttempt`], roll
+    /// back a failed started attempt, and return its confirmed form.
+    fn execute_operation(
+        &self,
+        context: &ExecutionContext,
+        path: &str,
+        operation: impl FnOnce(&PublishedObject<Self::Object>) -> OperationAttempt,
+    ) -> ProviderResult<OperationAttempt> {
+        self.with_object(context, path, operation)
+    }
 
     /// Decides whether a declared operation may execute for the current caller.
     ///
@@ -540,16 +834,43 @@ pub trait ObjectProvider {
 
     /// Fetches the canonical object projection currently published at `path`.
     fn fetch(&self, path: &str) -> Result<Object, CallError> {
+        self.fetch_with_context(&ExecutionContext::default(), path)
+    }
+
+    /// Fetches an object while propagating runtime execution controls.
+    fn fetch_with_context(
+        &self,
+        context: &ExecutionContext,
+        path: &str,
+    ) -> Result<Object, CallError> {
         wip_protocol::validate_path(path)
             .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
-        self.with_object(path, PublishedObject::protocol_object)
-            .ok_or_else(|| CallError::new(CallErrorKind::NotFound, "target path is not published"))
-            .and_then(|object| {
-                object.validate_at_path(path).map_err(|error| {
-                    CallError::new(CallErrorKind::InvalidResult, error.to_string())
-                })?;
-                Ok(object)
-            })
+        let resolved = catch_unwind(AssertUnwindSafe(|| {
+            self.with_object(context, path, PublishedObject::protocol_object)
+        }))
+        .map_err(|_| {
+            CallError::new(
+                CallErrorKind::Internal,
+                "provider panicked while fetching an object",
+            )
+        })?;
+        let object = match resolved {
+            ProviderResult::Found(object) => object,
+            ProviderResult::NotFound => {
+                return Err(CallError::new(
+                    CallErrorKind::NotFound,
+                    "target path is not published",
+                ));
+            }
+            ProviderResult::Failure(error) => return Err(CallError::from_read_failure(error)),
+        };
+        object.validate_at_path(path).map_err(|_| {
+            CallError::new(
+                CallErrorKind::Internal,
+                "Host produced an invalid object response",
+            )
+        })?;
+        Ok(object)
     }
 
     /// Resolves and executes a canonical path-targeted operation request.
@@ -559,17 +880,47 @@ pub trait ObjectProvider {
     /// supplied object validator mismatch, membership, interface validator
     /// requirement and mismatch, operation existence, object validator
     /// requirement, arguments, then authorization. No failed precondition
-    /// invokes the provider callback or typed implementation.
+    /// invokes typed implementation code.
     fn call_operation(&self, request: CallRequest) -> Result<CallResult, CallError> {
+        self.call_operation_with_context(&ExecutionContext::default(), request)
+    }
+
+    /// Executes an operation while propagating cancellation, deadline, and
+    /// resource-budget controls to the provider and runtime preflight check.
+    fn call_operation_with_context(
+        &self,
+        context: &ExecutionContext,
+        request: CallRequest,
+    ) -> Result<CallResult, CallError> {
         wip_protocol::validate_path(&request.target.path)
             .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
         let path = request.target.path.clone();
-        self.with_object(&path, |publication| {
-            publication.dispatch_resolved(request, |object, interface, operation| {
-                self.authorize(&path, object, interface, operation)
+        let execution = catch_unwind(AssertUnwindSafe(|| {
+            self.execute_operation(context, &path, |publication| {
+                publication.dispatch_resolved(context, request, |object, interface, operation| {
+                    self.authorize(&path, object, interface, operation)
+                })
             })
-        })
-        .ok_or_else(|| CallError::new(CallErrorKind::NotFound, "target path is not published"))?
+        }));
+
+        let execution = execution.map_err(|_| {
+            CallError::from_operation_failure(OperationFailure::internal(
+                EffectGuarantee::Unknown,
+                "provider execution panicked",
+            ))
+        })?;
+        match execution {
+            ProviderResult::Found(OperationAttempt::NotStarted(error)) => Err(error),
+            ProviderResult::Found(OperationAttempt::Started(Ok(result))) => Ok(result),
+            ProviderResult::Found(OperationAttempt::Started(Err(error))) => {
+                Err(CallError::from_operation_failure(error))
+            }
+            ProviderResult::NotFound => Err(CallError::new(
+                CallErrorKind::NotFound,
+                "target path is not published",
+            )),
+            ProviderResult::Failure(error) => Err(CallError::from_host_failure(error)),
+        }
     }
 }
 
@@ -594,7 +945,7 @@ impl Display for PublicationError {
 
 impl Error for PublicationError {}
 
-/// Stable host dispatch failure kind.
+/// Stable Host dispatch failure kind.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum CallErrorKind {
     /// The request is structurally invalid.
@@ -607,8 +958,13 @@ pub enum CallErrorKind {
     OperationNotFound,
     /// Supplied named values do not satisfy the operation declaration.
     InvalidArguments,
-    /// The encoded implementation result violates its declaration.
-    InvalidResult,
+    /// A bounded cancellation, deadline, or resource limit was exceeded and the
+    /// operation effects are guaranteed not committed.
+    ResourceLimitExceeded,
+    /// The Host failed and operation effects are guaranteed not committed.
+    Internal,
+    /// The Host cannot guarantee whether operation effects were committed.
+    OperationOutcomeUnknown,
     /// This operation requires a validator and the call omitted it.
     ValidatorRequired,
     /// The supplied object validator is stale or belongs to another object.
@@ -619,11 +975,9 @@ pub enum CallErrorKind {
     InterfaceValidatorMismatch,
     /// The operation is declared but not authorized for the caller.
     PermissionDenied,
-    /// The typed implementation reported a host/backend failure.
-    Implementation,
 }
 
-/// A dispatch failure with a stable kind and non-normative diagnostic.
+/// A dispatch failure with a stable kind and bounded non-normative diagnostic.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CallError {
     kind: CallErrorKind,
@@ -634,11 +988,11 @@ impl CallError {
     fn new(kind: CallErrorKind, message: impl Into<String>) -> Self {
         Self {
             kind,
-            message: message.into(),
+            message: bounded_message(message.into()),
         }
     }
 
-    fn from_dispatch(error: DispatchError) -> Self {
+    fn from_pre_dispatch(error: DispatchError) -> Self {
         match error {
             DispatchError::UnknownOperation(operation) => Self::new(
                 CallErrorKind::OperationNotFound,
@@ -647,34 +1001,63 @@ impl CallError {
             DispatchError::InvalidArguments(error) => {
                 Self::new(CallErrorKind::InvalidArguments, error.to_string())
             }
-            DispatchError::Decode(error) => {
-                Self::new(CallErrorKind::InvalidArguments, error.to_string())
-            }
-            DispatchError::Host(error) => {
-                Self::new(CallErrorKind::Implementation, error.to_string())
-            }
-            DispatchError::Encode(error) => {
-                Self::new(CallErrorKind::InvalidResult, error.to_string())
-            }
-            DispatchError::InvalidResult(error) => {
-                Self::new(CallErrorKind::InvalidResult, error.to_string())
+            DispatchError::Decode(_) => Self::new(
+                CallErrorKind::InvalidArguments,
+                "operation arguments could not be decoded",
+            ),
+            DispatchError::Host(_)
+            | DispatchError::Panic
+            | DispatchError::Encode(_)
+            | DispatchError::InvalidResult(_) => {
+                unreachable!("post-invocation failure used as a pre-dispatch failure")
             }
         }
     }
 
+    fn from_read_failure(error: HostError) -> Self {
+        match error.kind() {
+            HostErrorKind::Internal => Self::new(
+                CallErrorKind::Internal,
+                "provider failed while fetching data",
+            ),
+            HostErrorKind::ResourceLimitExceeded => Self::new(
+                CallErrorKind::ResourceLimitExceeded,
+                "provider resource limit was exceeded while fetching data",
+            ),
+        }
+    }
+
+    fn from_host_failure(error: HostError) -> Self {
+        let kind = classified_host_kind(error.kind(), error.effect_guarantee());
+        let message = match error.kind() {
+            HostErrorKind::Internal => "provider execution failed",
+            HostErrorKind::ResourceLimitExceeded => {
+                "provider execution resource limit was exceeded"
+            }
+        };
+        Self::new(kind, message)
+    }
+
+    fn from_operation_failure(error: OperationFailure) -> Self {
+        Self::new(
+            classified_host_kind(error.kind, error.effect_guarantee),
+            error.message,
+        )
+    }
+
     /// Returns the stable failure kind.
     #[must_use]
     pub fn kind(&self) -> CallErrorKind {
         self.kind
     }
 
-    /// Returns the human-readable diagnostic.
+    /// Returns the bounded protocol-safe human-readable diagnostic.
     #[must_use]
     pub fn message(&self) -> &str {
         &self.message
     }
 
-    /// Maps this host failure to the canonical protocol error taxonomy.
+    /// Maps this Host failure to the canonical protocol error taxonomy.
     #[must_use]
     pub fn protocol_error(&self) -> ProtocolError {
         let code = match self.kind {
@@ -683,7 +1066,9 @@ impl CallError {
             CallErrorKind::InterfaceMismatch => ProtocolErrorCode::InterfaceMismatch,
             CallErrorKind::OperationNotFound => ProtocolErrorCode::OperationNotFound,
             CallErrorKind::InvalidArguments => ProtocolErrorCode::InvalidArguments,
-            CallErrorKind::InvalidResult => ProtocolErrorCode::InvalidResult,
+            CallErrorKind::ResourceLimitExceeded => ProtocolErrorCode::ResourceLimitExceeded,
+            CallErrorKind::Internal => ProtocolErrorCode::Internal,
+            CallErrorKind::OperationOutcomeUnknown => ProtocolErrorCode::OperationOutcomeUnknown,
             CallErrorKind::ValidatorRequired => ProtocolErrorCode::ValidatorRequired,
             CallErrorKind::ValidatorMismatch => ProtocolErrorCode::ValidatorMismatch,
             CallErrorKind::InterfaceValidatorRequired => {
@@ -693,7 +1078,6 @@ impl CallError {
                 ProtocolErrorCode::InterfaceValidatorMismatch
             }
             CallErrorKind::PermissionDenied => ProtocolErrorCode::PermissionDenied,
-            CallErrorKind::Implementation => ProtocolErrorCode::Internal,
         };
         ProtocolError {
             code,
@@ -702,6 +1086,30 @@ impl CallError {
     }
 }
 
+fn classified_host_kind(kind: HostErrorKind, effect_guarantee: EffectGuarantee) -> CallErrorKind {
+    match effect_guarantee {
+        EffectGuarantee::Unknown => CallErrorKind::OperationOutcomeUnknown,
+        EffectGuarantee::NotCommitted => match kind {
+            HostErrorKind::Internal => CallErrorKind::Internal,
+            HostErrorKind::ResourceLimitExceeded => CallErrorKind::ResourceLimitExceeded,
+        },
+    }
+}
+
+const MAX_PROTOCOL_MESSAGE_BYTES: usize = 512;
+
+fn bounded_message(mut message: String) -> String {
+    if message.len() <= MAX_PROTOCOL_MESSAGE_BYTES {
+        return message;
+    }
+    let mut end = MAX_PROTOCOL_MESSAGE_BYTES;
+    while !message.is_char_boundary(end) {
+        end -= 1;
+    }
+    message.truncate(end);
+    message
+}
+
 impl Display for CallError {
     fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
         write!(

crates/wip-host/tests/host.rs

@@ -1,13 +1,16 @@
 use std::cell::Cell;
 use std::collections::BTreeMap;
 use std::rc::Rc;
+use std::time::{Duration, Instant};
 
 use wip_host::{
-    CallError, CallErrorKind, CallRequest, InterfaceRef, InterfaceRegistry, InterfaceTarget,
-    ObjectProvider, PublishedObject, RegisteredInterface, Target, Validator, WipObject,
+    CallError, CallErrorKind, CallRequest, CancellationToken, ExecutionContext, InterfaceRef,
+    InterfaceRegistry, InterfaceTarget, ObjectProvider, OperationAttempt, ProviderResult,
+    PublishedObject, RegisteredInterface, Target, Validator, WipObject,
 };
 use wip_interface::{
-    CodecError, HostError, OperationResult, TypeDeclaration, TypeExpr, Value, WipType, interface,
+    CodecError, EffectGuarantee, HostError, OperationResult, TypeDeclaration, TypeExpr, Value,
+    WipType, interface,
 };
 use wip_protocol::ProtocolErrorCode;
 
@@ -39,6 +42,24 @@ pub trait Hidden {
 pub trait Broken {
     /// Returns a deliberately invalid encoded value.
     fn broken(&self) -> OperationResult<BadValue>;
+
+    /// Produces a result codec failure after implementation invocation.
+    fn encode_failure(&self) -> OperationResult<EncodeFailure>;
+
+    /// Panics after implementation invocation begins.
+    fn panic_after_call(&self) -> OperationResult<String>;
+
+    /// Reports an internal failure without an effect guarantee.
+    fn unknown_internal(&self) -> OperationResult<String>;
+
+    /// Reports an internal failure with a non-commit guarantee.
+    fn safe_internal(&self) -> OperationResult<String>;
+
+    /// Reports a resource failure without an effect guarantee.
+    fn unknown_resource(&self) -> OperationResult<String>;
+
+    /// Reports a resource failure with a non-commit guarantee.
+    fn safe_resource(&self) -> OperationResult<String>;
 }
 
 #[derive(Debug)]
@@ -60,6 +81,25 @@ impl WipType for BadValue {
     }
 }
 
+#[derive(Debug)]
+pub struct EncodeFailure;
+
+impl WipType for EncodeFailure {
+    fn type_expr() -> TypeExpr {
+        TypeExpr::String
+    }
+
+    fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
+
+    fn encode(self) -> Result<Value, CodecError> {
+        Err(CodecError::new("private://backend/result could not encode"))
+    }
+
+    fn decode(_: Value) -> Result<Self, CodecError> {
+        Ok(Self)
+    }
+}
+
 struct Document {
     name: String,
     description: Option<String>,
@@ -135,7 +175,10 @@ impl Reader for Document {
 
     fn fail(&self) -> OperationResult<String> {
         self.record_call();
-        Err(HostError::new("backend unavailable"))
+        Err(HostError::internal(
+            "backend unavailable",
+            EffectGuarantee::Unknown,
+        ))
     }
 }
 
@@ -158,6 +201,48 @@ impl Broken for Document {
         self.record_call();
         Ok(BadValue)
     }
+
+    fn encode_failure(&self) -> OperationResult<EncodeFailure> {
+        self.record_call();
+        Ok(EncodeFailure)
+    }
+
+    fn panic_after_call(&self) -> OperationResult<String> {
+        self.record_call();
+        panic!("private://backend panic with credential=secret")
+    }
+
+    fn unknown_internal(&self) -> OperationResult<String> {
+        self.record_call();
+        Err(HostError::internal(
+            "private://backend/path credential=secret",
+            EffectGuarantee::Unknown,
+        ))
+    }
+
+    fn safe_internal(&self) -> OperationResult<String> {
+        self.record_call();
+        Err(HostError::internal(
+            "private://backend/path credential=secret",
+            EffectGuarantee::NotCommitted,
+        ))
+    }
+
+    fn unknown_resource(&self) -> OperationResult<String> {
+        self.record_call();
+        Err(HostError::resource_limit(
+            "private scheduler deadline details",
+            EffectGuarantee::Unknown,
+        ))
+    }
+
+    fn safe_resource(&self) -> OperationResult<String> {
+        self.record_call();
+        Err(HostError::resource_limit(
+            "private scheduler deadline details",
+            EffectGuarantee::NotCommitted,
+        ))
+    }
 }
 
 struct TestProvider {
@@ -169,6 +254,11 @@ struct TestProvider {
     authorization_checks: Cell<usize>,
     deny: Cell<bool>,
     switched: Cell<bool>,
+    confirm_rollback: Cell<bool>,
+    provider_failure: Cell<Option<(bool, EffectGuarantee)>>,
+    observed_budget: Cell<Option<u64>>,
+    observed_deadline: Cell<Option<Instant>>,
+    observed_cancelled: Cell<bool>,
 }
 
 impl TestProvider {
@@ -186,6 +276,11 @@ impl TestProvider {
             authorization_checks: Cell::new(0),
             deny: Cell::new(false),
             switched: Cell::new(false),
+            confirm_rollback: Cell::new(false),
+            provider_failure: Cell::new(None),
+            observed_budget: Cell::new(None),
+            observed_deadline: Cell::new(None),
+            observed_cancelled: Cell::new(false),
         }
     }
 }
@@ -195,9 +290,14 @@ impl ObjectProvider for TestProvider {
 
     fn with_object<R>(
         &self,
+        context: &ExecutionContext,
         path: &str,
         operation: impl FnOnce(&PublishedObject<Self::Object>) -> R,
-    ) -> Option<R> {
+    ) -> ProviderResult<R> {
+        self.observed_budget.set(context.resource_budget());
+        self.observed_deadline.set(context.deadline());
+        self.observed_cancelled
+            .set(context.cancellation().is_cancelled());
         self.resolutions.set(self.resolutions.get() + 1);
         let (document, interfaces) = match path {
             "/document" => (
@@ -235,11 +335,15 @@ impl ObjectProvider for TestProvider {
                 )
             }
             "/empty" => (Document::open("empty", None, Rc::clone(&self.calls)), 0),
+            "/invalid-object" => (
+                Document::open("wrong-name", None, Rc::clone(&self.calls)),
+                0,
+            ),
             "/broken" => (
                 Document::open("broken", Some("broken-ref"), Rc::clone(&self.calls)),
                 3,
             ),
-            _ => return None,
+            _ => return ProviderResult::NotFound,
         };
 
         let publication = PublishedObject::new(document);
@@ -253,7 +357,32 @@ impl ObjectProvider for TestProvider {
             3 => publication.expose(&self.broken).unwrap(),
             _ => unreachable!(),
         };
-        Some(operation(&publication))
+        ProviderResult::Found(operation(&publication))
+    }
+
+    fn execute_operation(
+        &self,
+        context: &ExecutionContext,
+        path: &str,
+        operation: impl FnOnce(&PublishedObject<Self::Object>) -> OperationAttempt,
+    ) -> ProviderResult<OperationAttempt> {
+        let result = self.with_object(context, path, operation);
+        if let Some((resource, guarantee)) = self.provider_failure.get() {
+            let error = if resource {
+                HostError::resource_limit("private provider scheduler state", guarantee)
+            } else {
+                HostError::internal("private provider transaction path", guarantee)
+            };
+            return ProviderResult::Failure(error);
+        }
+        if self.confirm_rollback.get() {
+            match result {
+                ProviderResult::Found(attempt) => ProviderResult::Found(attempt.confirm_rollback()),
+                other => other,
+            }
+        } else {
+            result
+        }
     }
 
     fn authorize(&self, _: &str, _: &Document, _: &InterfaceRef, _: &str) -> bool {
@@ -316,12 +445,21 @@ fn registry_returns_atomic_canonical_observation_without_rewriting_descriptor()
     assert_eq!(observation.reference, *reference);
     assert_eq!(observation.descriptor, ReaderDefinition::descriptor());
     assert_eq!(observation.validator, Some(Validator::new(b"schema-v1")));
-    let response = observation.protocol_response();
+    let response = observation.protocol_response().unwrap();
     assert_eq!(response.interface, reference.as_str());
     assert_eq!(response.descriptor, ReaderDefinition::descriptor());
     assert_eq!(response.validator.as_deref(), Some(b"schema-v1".as_slice()));
     response.descriptor.validate().unwrap();
 
+    let mut invalid_observation = registry.fetch_interface(reference.as_str()).unwrap();
+    let duplicate_operation = invalid_observation.descriptor.operations[0].clone();
+    invalid_observation
+        .descriptor
+        .operations
+        .push(duplicate_operation);
+    let invalid_response = invalid_observation.protocol_response().unwrap_err();
+    assert_eq!(invalid_response.code, ProtocolErrorCode::Internal);
+
     let error = registry.fetch_interface("unknown").unwrap_err();
     assert_eq!(error.code, ProtocolErrorCode::InterfaceNotFound);
 }
@@ -624,9 +762,15 @@ fn immutable_interface_rejects_a_supplied_validator() {
 }
 
 #[test]
-fn invalid_results_and_backend_failures_keep_distinct_protocol_codes() {
+fn invalid_host_responses_and_uncertain_operation_failures_use_canonical_codes() {
     let (_, provider, _) = registry_and_provider();
 
+    assert_failure(
+        provider.fetch("/invalid-object").unwrap_err(),
+        CallErrorKind::Internal,
+        ProtocolErrorCode::Internal,
+    );
+
     assert_failure(
         provider
             .call_operation(request(
@@ -638,8 +782,8 @@ fn invalid_results_and_backend_failures_keep_distinct_protocol_codes() {
                 BTreeMap::new(),
             ))
             .unwrap_err(),
-        CallErrorKind::InvalidResult,
-        ProtocolErrorCode::InvalidResult,
+        CallErrorKind::OperationOutcomeUnknown,
+        ProtocolErrorCode::OperationOutcomeUnknown,
     );
     assert_failure(
         provider
@@ -652,7 +796,190 @@ fn invalid_results_and_backend_failures_keep_distinct_protocol_codes() {
                 BTreeMap::new(),
             ))
             .unwrap_err(),
-        CallErrorKind::Implementation,
-        ProtocolErrorCode::Internal,
+        CallErrorKind::OperationOutcomeUnknown,
+        ProtocolErrorCode::OperationOutcomeUnknown,
     );
 }
+
+fn call_broken(provider: &TestProvider, operation: &str) -> CallError {
+    provider
+        .call_operation(request(
+            "/broken",
+            None,
+            provider.broken.reference(),
+            None,
+            operation,
+            BTreeMap::new(),
+        ))
+        .unwrap_err()
+}
+
+#[test]
+fn typed_implementation_failures_map_only_with_a_non_commit_guarantee() {
+    let (_, provider, _) = registry_and_provider();
+
+    let unknown_internal = call_broken(&provider, "unknown_internal");
+    assert_failure(
+        unknown_internal.clone(),
+        CallErrorKind::OperationOutcomeUnknown,
+        ProtocolErrorCode::OperationOutcomeUnknown,
+    );
+    assert!(!unknown_internal.message().contains("private://"));
+    assert!(
+        !unknown_internal
+            .protocol_error()
+            .message
+            .contains("credential")
+    );
+
+    assert_failure(
+        call_broken(&provider, "safe_internal"),
+        CallErrorKind::Internal,
+        ProtocolErrorCode::Internal,
+    );
+    assert_failure(
+        call_broken(&provider, "unknown_resource"),
+        CallErrorKind::OperationOutcomeUnknown,
+        ProtocolErrorCode::OperationOutcomeUnknown,
+    );
+    assert_failure(
+        call_broken(&provider, "safe_resource"),
+        CallErrorKind::ResourceLimitExceeded,
+        ProtocolErrorCode::ResourceLimitExceeded,
+    );
+}
+
+#[test]
+fn post_invocation_result_and_panic_failures_require_provider_rollback() {
+    for operation in ["broken", "encode_failure", "panic_after_call"] {
+        let (_, provider, _) = registry_and_provider();
+        let error = call_broken(&provider, operation);
+        assert_failure(
+            error.clone(),
+            CallErrorKind::OperationOutcomeUnknown,
+            ProtocolErrorCode::OperationOutcomeUnknown,
+        );
+        assert!(!error.message().contains("private://"));
+        assert!(!error.message().contains("credential"));
+
+        provider.confirm_rollback.set(true);
+        assert_failure(
+            call_broken(&provider, operation),
+            CallErrorKind::Internal,
+            ProtocolErrorCode::Internal,
+        );
+    }
+}
+
+#[test]
+fn provider_failures_after_invocation_use_the_provider_effect_guarantee() {
+    let (_, provider, _) = registry_and_provider();
+
+    provider
+        .provider_failure
+        .set(Some((false, EffectGuarantee::Unknown)));
+    assert_failure(
+        call_broken(&provider, "safe_internal"),
+        CallErrorKind::OperationOutcomeUnknown,
+        ProtocolErrorCode::OperationOutcomeUnknown,
+    );
+
+    provider
+        .provider_failure
+        .set(Some((false, EffectGuarantee::NotCommitted)));
+    let internal = call_broken(&provider, "unknown_internal");
+    assert_failure(
+        internal.clone(),
+        CallErrorKind::Internal,
+        ProtocolErrorCode::Internal,
+    );
+    assert!(!internal.message().contains("transaction"));
+
+    provider
+        .provider_failure
+        .set(Some((true, EffectGuarantee::Unknown)));
+    assert_failure(
+        call_broken(&provider, "safe_resource"),
+        CallErrorKind::OperationOutcomeUnknown,
+        ProtocolErrorCode::OperationOutcomeUnknown,
+    );
+
+    provider
+        .provider_failure
+        .set(Some((true, EffectGuarantee::NotCommitted)));
+    assert_failure(
+        call_broken(&provider, "unknown_resource"),
+        CallErrorKind::ResourceLimitExceeded,
+        ProtocolErrorCode::ResourceLimitExceeded,
+    );
+}
+
+#[test]
+fn execution_context_is_propagated_and_preflight_prevents_invocation() {
+    let (_, provider, _) = registry_and_provider();
+    let deadline = Instant::now() + Duration::from_secs(60);
+    let context = ExecutionContext::new()
+        .with_deadline(deadline)
+        .with_resource_budget(17);
+
+    provider
+        .call_operation_with_context(
+            &context,
+            request(
+                "/open",
+                None,
+                provider.reader.reference(),
+                Some(b"schema-v1"),
+                "label",
+                BTreeMap::new(),
+            ),
+        )
+        .unwrap();
+    assert_eq!(provider.observed_deadline.get(), Some(deadline));
+    assert_eq!(provider.observed_budget.get(), Some(17));
+    assert!(!provider.observed_cancelled.get());
+
+    let calls = provider.calls.get();
+    let cancellation = CancellationToken::new();
+    cancellation.cancel();
+    let cancelled = ExecutionContext::new().with_cancellation(cancellation);
+    assert_failure(
+        provider
+            .call_operation_with_context(
+                &cancelled,
+                request(
+                    "/open",
+                    None,
+                    provider.reader.reference(),
+                    Some(b"schema-v1"),
+                    "label",
+                    BTreeMap::new(),
+                ),
+            )
+            .unwrap_err(),
+        CallErrorKind::ResourceLimitExceeded,
+        ProtocolErrorCode::ResourceLimitExceeded,
+    );
+    assert_eq!(provider.calls.get(), calls);
+    assert!(provider.observed_cancelled.get());
+
+    let expired = ExecutionContext::new().with_deadline(Instant::now() - Duration::from_secs(1));
+    assert_failure(
+        provider
+            .call_operation_with_context(
+                &expired,
+                request(
+                    "/open",
+                    None,
+                    provider.reader.reference(),
+                    Some(b"schema-v1"),
+                    "label",
+                    BTreeMap::new(),
+                ),
+            )
+            .unwrap_err(),
+        CallErrorKind::ResourceLimitExceeded,
+        ProtocolErrorCode::ResourceLimitExceeded,
+    );
+    assert_eq!(provider.calls.get(), calls);
+}

crates/wip-interface-macros/src/lib.rs

@@ -647,14 +647,17 @@ fn dispatch_arm(operation: &Operation) -> TokenStream2 {
             .map_err(::wip_interface::DispatchError::InvalidArguments)?;
             let decoded = #arguments_ident::decode(arguments)
                 .map_err(::wip_interface::DispatchError::Decode)?;
-            let result = implementation.#method_ident(#(#arguments),*)
-                .map_err(::wip_interface::DispatchError::Host)?;
-            let encoded = #arguments_ident::encode_result(result)
-                .map_err(::wip_interface::DispatchError::Encode)?;
-            descriptor
-                .validate_result(#operation_name, &encoded)
-                .map_err(::wip_interface::DispatchError::InvalidResult)?;
-            ::std::result::Result::Ok(encoded)
+            ::std::panic::catch_unwind(::std::panic::AssertUnwindSafe(|| {
+                let result = implementation.#method_ident(#(#arguments),*)
+                    .map_err(::wip_interface::DispatchError::Host)?;
+                let encoded = #arguments_ident::encode_result(result)
+                    .map_err(::wip_interface::DispatchError::Encode)?;
+                descriptor
+                    .validate_result(#operation_name, &encoded)
+                    .map_err(::wip_interface::DispatchError::InvalidResult)?;
+                ::std::result::Result::Ok(encoded)
+            }))
+            .map_err(|_| ::wip_interface::DispatchError::Panic)?
         }
     }
 }

crates/wip-interface/src/lib.rs

@@ -46,8 +46,10 @@
 //! `Option<T>` is supported only directly as a record field or operation
 //! parameter. It means omission, not a null value. A domain failure belongs in
 //! an application return enum/union and is returned as `Ok(value)`.
-//! [`HostError`] is reserved for host/runtime failure, so the required
-//! [`OperationResult`] convention keeps those two failure classes distinct.
+//! [`HostError`] is reserved for host/runtime failure and requires an explicit
+//! [`HostErrorKind`] plus [`EffectGuarantee`]. The required [`OperationResult`]
+//! convention therefore keeps domain failures separate from runtime failures and
+//! makes outcome uncertainty visible to Host dispatch.
 //!
 //! # Migration to canonical values
 //!
@@ -139,29 +141,107 @@ pub trait InterfaceImplementation<T>: InterfaceDefinition {
 /// `Err(HostError)` means the host or runtime could not perform the operation.
 pub type OperationResult<T> = Result<T, HostError>;
 
-/// A host/runtime failure, kept separate from the operation's application
+/// Whether an operation failure proves that no effects were committed.
+///
+/// This guarantee is consumed by Host dispatch when choosing a protocol failure:
+/// only [`NotCommitted`](Self::NotCommitted) failures may become `Internal` or
+/// `ResourceLimitExceeded`; [`Unknown`](Self::Unknown) failures must become
+/// `OperationOutcomeUnknown`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EffectGuarantee {
+    /// The operation was not invoked, or every effect was rolled back.
+    NotCommitted,
+    /// The operation may have committed effects.
+    Unknown,
+}
+
+/// Host/runtime failure category used when effects are known not to be committed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum HostErrorKind {
+    /// The Host or backend encountered an internal failure.
+    Internal,
+    /// A cancellation, deadline, or bounded resource limit was exceeded.
+    ResourceLimitExceeded,
+}
+
+/// A typed host/runtime failure, kept separate from the operation's application
 /// return type.
+///
+/// The effect guarantee is mandatory. Host runtimes must ignore the diagnostic
+/// when producing a wire response; it is bounded here for local observability but
+/// can still contain backend-private information.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct HostError {
+    kind: HostErrorKind,
+    effect_guarantee: EffectGuarantee,
     message: String,
 }
 
 impl HostError {
-    /// Creates a host failure with a human-readable diagnostic.
+    /// Creates an internal Host failure with an explicit effect guarantee.
     #[must_use]
-    pub fn new(message: impl Into<String>) -> Self {
+    pub fn internal(message: impl Into<String>, effect_guarantee: EffectGuarantee) -> Self {
+        Self::new(HostErrorKind::Internal, effect_guarantee, message)
+    }
+
+    /// Creates a resource-limit Host failure with an explicit effect guarantee.
+    #[must_use]
+    pub fn resource_limit(message: impl Into<String>, effect_guarantee: EffectGuarantee) -> Self {
+        Self::new(
+            HostErrorKind::ResourceLimitExceeded,
+            effect_guarantee,
+            message,
+        )
+    }
+
+    fn new(
+        kind: HostErrorKind,
+        effect_guarantee: EffectGuarantee,
+        message: impl Into<String>,
+    ) -> Self {
         Self {
-            message: message.into(),
+            kind,
+            effect_guarantee,
+            message: bounded_diagnostic(message.into()),
         }
     }
 
-    /// Returns the diagnostic message.
+    /// Returns the typed Host failure category.
+    #[must_use]
+    pub fn kind(&self) -> HostErrorKind {
+        self.kind
+    }
+
+    /// Returns the operation-effect guarantee attached by the implementation.
+    #[must_use]
+    pub fn effect_guarantee(&self) -> EffectGuarantee {
+        self.effect_guarantee
+    }
+
+    /// Returns the bounded local diagnostic message.
+    ///
+    /// Host runtimes must not place this value in protocol responses because it
+    /// can contain backend paths, credentials, or other private details.
     #[must_use]
     pub fn message(&self) -> &str {
         &self.message
     }
 }
 
+const MAX_DIAGNOSTIC_BYTES: usize = 512;
+
+fn bounded_diagnostic(mut message: String) -> String {
+    if message.len() <= MAX_DIAGNOSTIC_BYTES {
+        return message;
+    }
+    let mut end = MAX_DIAGNOSTIC_BYTES;
+    while !message.is_char_boundary(end) {
+        end -= 1;
+    }
+    message.truncate(end);
+    message
+}
+
 impl Display for HostError {
     fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
         formatter.write_str(&self.message)
@@ -241,12 +321,59 @@ pub enum DispatchError {
     Decode(CodecError),
     /// The implementation reported a host/runtime failure.
     Host(HostError),
+    /// The implementation panicked after invocation began.
+    ///
+    /// Panic payloads are deliberately discarded because they can contain
+    /// backend-private diagnostics.
+    Panic,
     /// The Rust result could not be encoded.
     Encode(CodecError),
     /// The encoded result did not match the generated declaration.
     InvalidResult(wip_protocol::ValidationError),
 }
 
+/// Whether generated dispatch failed before or after typed implementation
+/// invocation began.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DispatchPhase {
+    /// Typed implementation code was not invoked.
+    BeforeInvocation,
+    /// Typed implementation invocation began, so effects require an explicit
+    /// non-commit or rollback guarantee.
+    AfterInvocation,
+}
+
+impl DispatchError {
+    /// Returns the execution phase in which this dispatch failure occurred.
+    #[must_use]
+    pub fn phase(&self) -> DispatchPhase {
+        match self {
+            Self::UnknownOperation(_) | Self::InvalidArguments(_) | Self::Decode(_) => {
+                DispatchPhase::BeforeInvocation
+            }
+            Self::Host(_) | Self::Panic | Self::Encode(_) | Self::InvalidResult(_) => {
+                DispatchPhase::AfterInvocation
+            }
+        }
+    }
+
+    /// Returns a post-invocation effect guarantee when the implementation
+    /// supplied one.
+    ///
+    /// Panic, encode, and result-validation failures default to `Unknown` until
+    /// a provider confirms rollback. Pre-invocation failures return `None`.
+    #[must_use]
+    pub fn effect_guarantee(&self) -> Option<EffectGuarantee> {
+        match self {
+            Self::UnknownOperation(_) | Self::InvalidArguments(_) | Self::Decode(_) => None,
+            Self::Host(error) => Some(error.effect_guarantee()),
+            Self::Panic | Self::Encode(_) | Self::InvalidResult(_) => {
+                Some(EffectGuarantee::Unknown)
+            }
+        }
+    }
+}
+
 impl Display for DispatchError {
     fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
         match self {
@@ -256,6 +383,7 @@ impl Display for DispatchError {
             Self::InvalidArguments(error) => write!(formatter, "invalid arguments: {error}"),
             Self::Decode(error) => write!(formatter, "argument decoding failed: {error}"),
             Self::Host(error) => write!(formatter, "host operation failed: {error}"),
+            Self::Panic => formatter.write_str("operation implementation panicked"),
             Self::Encode(error) => write!(formatter, "result encoding failed: {error}"),
             Self::InvalidResult(error) => write!(formatter, "invalid operation result: {error}"),
         }
@@ -265,7 +393,7 @@ impl Display for DispatchError {
 impl Error for DispatchError {
     fn source(&self) -> Option<&(dyn Error + 'static)> {
         match self {
-            Self::UnknownOperation(_) => None,
+            Self::UnknownOperation(_) | Self::Panic => None,
             Self::InvalidArguments(error) | Self::InvalidResult(error) => Some(error),
             Self::Decode(error) | Self::Encode(error) => Some(error),
             Self::Host(error) => Some(error),

crates/wip-interface/tests/interface.rs

@@ -1,7 +1,10 @@
 use std::collections::BTreeMap;
 
 use wip_interface::wip_protocol::{INTERFACE_FORMAT_V1, TypeExpr, Value};
-use wip_interface::{DispatchError, HostError, OperationResult, WipType, interface};
+use wip_interface::{
+    DispatchError, DispatchPhase, EffectGuarantee, HostError, HostErrorKind, OperationResult,
+    WipType, interface,
+};
 
 /// Publication request.
 #[derive(Debug, Clone, PartialEq, WipType)]
@@ -66,7 +69,10 @@ impl Catalog for AcceptingCatalog {
     }
 
     fn host_value(&self) -> OperationResult<String> {
-        Err(HostError::new("backend unavailable"))
+        Err(HostError::internal(
+            "backend unavailable",
+            EffectGuarantee::Unknown,
+        ))
     }
 }
 
@@ -90,6 +96,26 @@ impl Catalog for RejectingCatalog {
     }
 }
 
+struct PanickingCatalog;
+
+impl Catalog for PanickingCatalog {
+    fn publish(
+        &self,
+        _request: PublishRequest,
+        _note: Option<String>,
+    ) -> OperationResult<PublishOutcome> {
+        panic!("private panic payload")
+    }
+
+    fn ping(&self) -> OperationResult<()> {
+        panic!("private panic payload")
+    }
+
+    fn host_value(&self) -> OperationResult<String> {
+        panic!("private panic payload")
+    }
+}
+
 fn publish_arguments(with_note: bool) -> BTreeMap<String, Value> {
     let mut arguments = BTreeMap::from([(
         "request".into(),
@@ -203,16 +229,41 @@ fn typed_dispatch_validates_decodes_invokes_encodes_and_validates() {
     let invalid =
         CatalogDefinition::dispatch(&AcceptingCatalog, "publish", BTreeMap::new()).unwrap_err();
     assert!(matches!(invalid, DispatchError::InvalidArguments(_)));
+    assert_eq!(invalid.phase(), DispatchPhase::BeforeInvocation);
+    assert_eq!(invalid.effect_guarantee(), None);
 
     let host =
         CatalogDefinition::dispatch(&AcceptingCatalog, "host_value", BTreeMap::new()).unwrap_err();
-    assert!(matches!(host, DispatchError::Host(error) if error.message() == "backend unavailable"));
+    assert!(
+        matches!(&host, DispatchError::Host(error) if error.message() == "backend unavailable")
+    );
+    assert_eq!(host.phase(), DispatchPhase::AfterInvocation);
+    assert_eq!(host.effect_guarantee(), Some(EffectGuarantee::Unknown));
+
+    let panic =
+        CatalogDefinition::dispatch(&PanickingCatalog, "host_value", BTreeMap::new()).unwrap_err();
+    assert!(matches!(panic, DispatchError::Panic));
+    assert_eq!(panic.phase(), DispatchPhase::AfterInvocation);
+    assert_eq!(panic.effect_guarantee(), Some(EffectGuarantee::Unknown));
+    assert!(!panic.to_string().contains("private panic payload"));
 
     let unknown =
         CatalogDefinition::dispatch(&AcceptingCatalog, "missing", BTreeMap::new()).unwrap_err();
     assert!(matches!(unknown, DispatchError::UnknownOperation(name) if name == "missing"));
 }
 
+#[test]
+fn host_errors_require_a_typed_kind_and_effect_guarantee() {
+    let internal = HostError::internal("x".repeat(4_096), EffectGuarantee::NotCommitted);
+    assert_eq!(internal.kind(), HostErrorKind::Internal);
+    assert_eq!(internal.effect_guarantee(), EffectGuarantee::NotCommitted);
+    assert!(internal.message().len() <= 512);
+
+    let resource = HostError::resource_limit("deadline", EffectGuarantee::Unknown);
+    assert_eq!(resource.kind(), HostErrorKind::ResourceLimitExceeded);
+    assert_eq!(resource.effect_guarantee(), EffectGuarantee::Unknown);
+}
+
 /// Operations whose distinct source names normalize to the same PascalCase.
 #[interface]
 pub trait DistinctOperations {

crates/wip-protocol/src/error.rs

@@ -223,10 +223,29 @@ impl Display for ValidationError {
 
 impl Error for ValidationError {}
 
-/// Stable protocol failure code returned by a host or produced by a client.
+/// One core interaction whose failure codes form a closed set.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProtocolInteraction {
+    /// Fetch one object by its Worldspace path.
+    Fetch,
+    /// Fetch a bounded tree of objects.
+    FetchTree,
+    /// Fetch one interface descriptor by its opaque reference.
+    FetchInterface,
+    /// Invoke one operation on a path-targeted object.
+    CallOperation,
+}
+
+/// Stable protocol failure code returned by a host.
+///
+/// This is the complete wire-level code set. A Client treats a malformed success
+/// or failure response, including a code disallowed for its interaction, as a
+/// Client-local `InvalidResponse`. An unsupported descriptor format is likewise
+/// a Client-local `UnsupportedDescriptorFormat`; neither condition is a code a
+/// Host can return.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ProtocolErrorCode {
-    /// The request is structurally invalid.
+    /// The request is structurally invalid before an operation descriptor is fixed.
     InvalidRequest,
     /// The target object is not published.
     NotFound,
@@ -236,10 +255,8 @@ pub enum ProtocolErrorCode {
     InterfaceMismatch,
     /// The selected operation is not declared by the current interface.
     OperationNotFound,
-    /// Supplied operation arguments are invalid.
+    /// Supplied arguments do not match the fixed operation declaration.
     InvalidArguments,
-    /// A host result does not satisfy the declaration.
-    InvalidResult,
     /// The operation requires an object validator and none was supplied.
     ValidatorRequired,
     /// The supplied object validator does not match current state.
@@ -251,9 +268,88 @@ pub enum ProtocolErrorCode {
     /// A published operation is not permitted for the caller.
     PermissionDenied,
     /// A bounded protocol resource limit was exceeded.
+    ///
+    /// For `call_operation`, the Host guarantees that the operation was not run
+    /// or that all of its effects were rolled back.
     ResourceLimitExceeded,
-    /// The host encountered an internal failure.
+    /// The Host encountered an internal failure.
+    ///
+    /// For `call_operation`, the Host guarantees that the operation was not run
+    /// or that all of its effects were rolled back.
     Internal,
+    /// The Host cannot guarantee that the operation was not run or rolled back.
+    ///
+    /// A Client must not automatically retry because the operation may have
+    /// committed effects even though no success response was available.
+    OperationOutcomeUnknown,
+}
+
+impl ProtocolErrorCode {
+    /// Every canonical wire-level error code.
+    pub const ALL: [Self; 14] = [
+        Self::InvalidRequest,
+        Self::NotFound,
+        Self::InterfaceNotFound,
+        Self::InterfaceMismatch,
+        Self::OperationNotFound,
+        Self::InvalidArguments,
+        Self::ValidatorRequired,
+        Self::ValidatorMismatch,
+        Self::InterfaceValidatorRequired,
+        Self::InterfaceValidatorMismatch,
+        Self::PermissionDenied,
+        Self::ResourceLimitExceeded,
+        Self::Internal,
+        Self::OperationOutcomeUnknown,
+    ];
+
+    /// Whether a Host may return this code for `interaction`.
+    ///
+    /// `false` identifies an invalid error response; it does not turn that
+    /// response into another wire-level protocol failure.
+    #[must_use]
+    pub const fn is_allowed_for(self, interaction: ProtocolInteraction) -> bool {
+        use ProtocolErrorCode::{
+            InterfaceMismatch, InterfaceNotFound, InterfaceValidatorMismatch,
+            InterfaceValidatorRequired, Internal, InvalidArguments, InvalidRequest, NotFound,
+            OperationNotFound, OperationOutcomeUnknown, PermissionDenied, ResourceLimitExceeded,
+            ValidatorMismatch, ValidatorRequired,
+        };
+        use ProtocolInteraction::{CallOperation, Fetch, FetchInterface, FetchTree};
+
+        match (interaction, self) {
+            (_, InvalidRequest | ResourceLimitExceeded | Internal) => true,
+            (Fetch | FetchTree, NotFound) => true,
+            (FetchInterface, InterfaceNotFound) => true,
+            (
+                CallOperation,
+                NotFound
+                | InterfaceMismatch
+                | OperationNotFound
+                | InvalidArguments
+                | ValidatorRequired
+                | ValidatorMismatch
+                | InterfaceValidatorRequired
+                | InterfaceValidatorMismatch
+                | PermissionDenied
+                | OperationOutcomeUnknown,
+            ) => true,
+            (
+                _,
+                NotFound
+                | InterfaceNotFound
+                | InterfaceMismatch
+                | OperationNotFound
+                | InvalidArguments
+                | ValidatorRequired
+                | ValidatorMismatch
+                | InterfaceValidatorRequired
+                | InterfaceValidatorMismatch
+                | PermissionDenied
+                | OperationOutcomeUnknown,
+            ) => false,
+        }
+    }
 }
 
 /// Transport-independent protocol failure.

crates/wip-protocol/src/lib.rs

@@ -16,7 +16,20 @@
 //! | `fetch_interface` | [`FetchInterfaceRequest`] / [`FetchInterfaceResponse`] |
 //! | Object and interface call preconditions | [`Target`] / [`InterfaceTarget`] |
 //! | `call_operation` | [`CallOperationRequest`] / [`CallOperationResponse`] |
-//! | Stable failure taxonomy | [`ProtocolErrorCode`] / [`ProtocolError`] |
+//! | Stable Host failure taxonomy | [`ProtocolErrorCode`] / [`ProtocolError`] |
+//! | Per-interaction allowed failure codes | [`ProtocolInteraction`] / [`ProtocolErrorCode::is_allowed_for`] |
+//!
+//! [`ProtocolErrorCode`] is a closed set of Host-returned wire failures. After a
+//! Client receives a response, an invalid Object, Descriptor, operation result,
+//! malformed error, or error code disallowed by [`ProtocolInteraction`] is a
+//! Client-local `InvalidResponse`, not another wire error. A descriptor whose
+//! `format` is not supported is a Client-local `UnsupportedDescriptorFormat`.
+//!
+//! For `call_operation`, [`ProtocolErrorCode::Internal`] and
+//! [`ProtocolErrorCode::ResourceLimitExceeded`] guarantee that the operation did
+//! not run or that all effects were rolled back. Only
+//! [`ProtocolErrorCode::OperationOutcomeUnknown`] means the Host cannot make that
+//! guarantee; Clients must not automatically retry it.
 //!
 //! Paths, object refs, interface refs, and validators remain separate concepts.
 //! They are represented by ordinary protocol strings/bytes in the corresponding
@@ -35,8 +48,8 @@ mod model;
 mod validation;
 
 pub use error::{
-    NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ValidationError,
-    ValidationErrorKind, ValueKind,
+    NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
+    ValidationError, ValidationErrorKind, ValueKind,
 };
 pub use model::{
     CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,

crates/wip-protocol/src/model.rs

@@ -379,6 +379,9 @@ impl FetchRequest {
     }
 
     /// Validates an object returned for this request.
+    ///
+    /// Failure means the Client received an invalid success response; it is not a
+    /// Host-returned [`crate::ProtocolErrorCode`].
     pub fn validate_response(&self, response: &FetchResponse) -> Result<(), ValidationError> {
         response.validate_at_path(&self.path)
     }
@@ -393,6 +396,9 @@ impl FetchTreeRequest {
 
 impl FetchTreeResponse {
     /// Validates tree shape, names, depth, and node limit for `request`.
+    ///
+    /// Failure means the Client received an invalid success response; it is not a
+    /// Host-returned [`crate::ProtocolErrorCode`].
     pub fn validate_for(&self, request: &FetchTreeRequest) -> Result<(), ValidationError> {
         crate::validation::validate_fetch_tree_response(self, request)
     }
@@ -400,6 +406,11 @@ impl FetchTreeResponse {
 
 impl FetchInterfaceResponse {
     /// Validates request correspondence and descriptor semantics.
+    ///
+    /// Failure means the Client received an invalid success response; it is not a
+    /// Host-returned [`crate::ProtocolErrorCode`]. Descriptor format support is a
+    /// separate Client concern: an otherwise valid descriptor with an unsupported
+    /// `format` is a Client-local `UnsupportedDescriptorFormat`.
     pub fn validate_for(&self, request: &FetchInterfaceRequest) -> Result<(), ValidationError> {
         crate::validation::validate_fetch_interface_response(self, request)
     }
@@ -414,6 +425,9 @@ impl CallOperationRequest {
 
 impl CallOperationResponse {
     /// Validates this result against the named operation in `descriptor`.
+    ///
+    /// Failure means the Client received an invalid success response; it is not a
+    /// Host-returned [`crate::ProtocolErrorCode`].
     pub fn validate_for(
         &self,
         descriptor: &InterfaceDescriptor,

crates/wip-protocol/tests/validation.rs

@@ -5,8 +5,8 @@ use wip_protocol::{
     FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
     INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, NameNamespace,
     Object, ObjectTreeNode, OperationDeclaration, ParameterDeclaration, PathSegment, ProtocolError,
-    ProtocolErrorCode, ProtocolResult, ReturnDeclaration, Target, TypeDeclaration, TypeExpr,
-    UnionCase, ValidationErrorKind, Value, ValueKind,
+    ProtocolErrorCode, ProtocolInteraction, ProtocolResult, ReturnDeclaration, Target,
+    TypeDeclaration, TypeExpr, UnionCase, ValidationErrorKind, Value, ValueKind,
 };
 
 fn record(entries: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
@@ -729,24 +729,26 @@ fn fetch_tree_dtos_validate_names_depth_limit_and_siblings() {
 }
 
 #[test]
-fn protocol_result_and_every_canonical_error_code_are_available() {
-    let codes = [
-        ProtocolErrorCode::InvalidRequest,
-        ProtocolErrorCode::NotFound,
-        ProtocolErrorCode::InterfaceNotFound,
-        ProtocolErrorCode::InterfaceMismatch,
-        ProtocolErrorCode::OperationNotFound,
-        ProtocolErrorCode::InvalidArguments,
-        ProtocolErrorCode::InvalidResult,
-        ProtocolErrorCode::ValidatorRequired,
-        ProtocolErrorCode::ValidatorMismatch,
-        ProtocolErrorCode::InterfaceValidatorRequired,
-        ProtocolErrorCode::InterfaceValidatorMismatch,
-        ProtocolErrorCode::PermissionDenied,
-        ProtocolErrorCode::ResourceLimitExceeded,
-        ProtocolErrorCode::Internal,
-    ];
-    assert_eq!(codes.len(), 14);
+fn protocol_result_exposes_the_exact_canonical_wire_error_codes() {
+    assert_eq!(
+        ProtocolErrorCode::ALL,
+        [
+            ProtocolErrorCode::InvalidRequest,
+            ProtocolErrorCode::NotFound,
+            ProtocolErrorCode::InterfaceNotFound,
+            ProtocolErrorCode::InterfaceMismatch,
+            ProtocolErrorCode::OperationNotFound,
+            ProtocolErrorCode::InvalidArguments,
+            ProtocolErrorCode::ValidatorRequired,
+            ProtocolErrorCode::ValidatorMismatch,
+            ProtocolErrorCode::InterfaceValidatorRequired,
+            ProtocolErrorCode::InterfaceValidatorMismatch,
+            ProtocolErrorCode::PermissionDenied,
+            ProtocolErrorCode::ResourceLimitExceeded,
+            ProtocolErrorCode::Internal,
+            ProtocolErrorCode::OperationOutcomeUnknown,
+        ]
+    );
 
     let failure: ProtocolResult<()> = ProtocolResult::Failure(ProtocolError {
         code: ProtocolErrorCode::InvalidArguments,
@@ -758,3 +760,127 @@ fn protocol_result_and_every_canonical_error_code_are_available() {
         ProtocolResult::Success(Value::Unit)
     );
 }
+
+fn assert_allowed_codes(interaction: ProtocolInteraction, expected: &[ProtocolErrorCode]) {
+    let actual: Vec<_> = ProtocolErrorCode::ALL
+        .into_iter()
+        .filter(|code| code.is_allowed_for(interaction))
+        .collect();
+    assert_eq!(actual, expected);
+
+    for code in ProtocolErrorCode::ALL {
+        assert_eq!(
+            code.is_allowed_for(interaction),
+            expected.contains(&code),
+            "unexpected {code:?} validity for {interaction:?}"
+        );
+    }
+}
+
+#[test]
+fn fetch_error_codes_are_exhaustive() {
+    assert_allowed_codes(
+        ProtocolInteraction::Fetch,
+        &[
+            ProtocolErrorCode::InvalidRequest,
+            ProtocolErrorCode::NotFound,
+            ProtocolErrorCode::ResourceLimitExceeded,
+            ProtocolErrorCode::Internal,
+        ],
+    );
+}
+
+#[test]
+fn fetch_tree_error_codes_are_exhaustive() {
+    assert_allowed_codes(
+        ProtocolInteraction::FetchTree,
+        &[
+            ProtocolErrorCode::InvalidRequest,
+            ProtocolErrorCode::NotFound,
+            ProtocolErrorCode::ResourceLimitExceeded,
+            ProtocolErrorCode::Internal,
+        ],
+    );
+}
+
+#[test]
+fn fetch_interface_error_codes_are_exhaustive() {
+    assert_allowed_codes(
+        ProtocolInteraction::FetchInterface,
+        &[
+            ProtocolErrorCode::InvalidRequest,
+            ProtocolErrorCode::InterfaceNotFound,
+            ProtocolErrorCode::ResourceLimitExceeded,
+            ProtocolErrorCode::Internal,
+        ],
+    );
+}
+
+#[test]
+fn call_operation_error_codes_are_exhaustive() {
+    assert_allowed_codes(
+        ProtocolInteraction::CallOperation,
+        &[
+            ProtocolErrorCode::InvalidRequest,
+            ProtocolErrorCode::NotFound,
+            ProtocolErrorCode::InterfaceMismatch,
+            ProtocolErrorCode::OperationNotFound,
+            ProtocolErrorCode::InvalidArguments,
+            ProtocolErrorCode::ValidatorRequired,
+            ProtocolErrorCode::ValidatorMismatch,
+            ProtocolErrorCode::InterfaceValidatorRequired,
+            ProtocolErrorCode::InterfaceValidatorMismatch,
+            ProtocolErrorCode::PermissionDenied,
+            ProtocolErrorCode::ResourceLimitExceeded,
+            ProtocolErrorCode::Internal,
+            ProtocolErrorCode::OperationOutcomeUnknown,
+        ],
+    );
+}
+
+#[test]
+fn invalid_success_payloads_remain_client_local_validation_failures() {
+    let fetch = FetchRequest {
+        path: "/articles/one".into(),
+    };
+    assert!(matches!(
+        fetch.validate_response(&object("other")).unwrap_err().kind,
+        ValidationErrorKind::ObjectNameMismatch { .. }
+    ));
+
+    let interface_request = FetchInterfaceRequest {
+        interface: "catalog-v1".into(),
+    };
+    let mut invalid_descriptor = descriptor();
+    invalid_descriptor
+        .operations
+        .push(invalid_descriptor.operations[0].clone());
+    assert!(matches!(
+        FetchInterfaceResponse {
+            interface: interface_request.interface.clone(),
+            descriptor: invalid_descriptor,
+            validator: None,
+        }
+        .validate_for(&interface_request)
+        .unwrap_err()
+        .kind,
+        ValidationErrorKind::DuplicateName {
+            namespace: NameNamespace::Operation,
+            ..
+        }
+    ));
+
+    assert!(matches!(
+        CallOperationResponse {
+            result: Value::String("not a boolean".into()),
+            validator: None,
+        }
+        .validate_for(&descriptor(), "publish")
+        .unwrap_err()
+        .kind,
+        ValidationErrorKind::TypeMismatch {
+            expected: ValueKind::Boolean,
+            actual: ValueKind::String,
+        }
+    ));
+}

crates/wip-public-api-example/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "wip-public-api-example"
+version = "0.1.0"
+edition = "2024"
+description = "Public-only end-to-end conformance consumer for the WIP Rust APIs"
+license = "MIT OR Apache-2.0"
+publish = false
+
+[dependencies]
+wip-host = { path = "../wip-host" }
+wip-interface = { path = "../wip-interface" }
+wip-protocol = { path = "../wip-protocol" }

crates/wip-public-api-example/src/lib.rs

@@ -0,0 +1,541 @@
+//! Public-only conformance consumer for the WIP Rust crates.
+//!
+//! # Architectural boundary
+//!
+//! This package is an ordinary application consumer. Its direct dependencies are
+//! the public `wip-protocol`, `wip-interface`, and `wip-host` crates; it neither
+//! imports workspace-private modules nor depends on `wip-interface-macros`.
+//! `wip-protocol` owns transport-independent DTOs and schema-neutral values,
+//! while this package owns its application DTOs and interface traits. The
+//! request-scoped implementation, backend handle, authorization policy, and
+//! publication wiring remain host-private. A transport binding would translate
+//! its own wire routes and envelopes to the protocol call DTOs; no HTTP type is
+//! part of an application trait or interface descriptor.
+//!
+//! # Breaking migration exercised here
+//!
+//! The canonical API targets operations by `target.path` rather than a mandatory
+//! object identifier. Object `ref` and object/interface validators are separate,
+//! optional observation fields. Interface references are opaque values observed
+//! separately from descriptors, and descriptors contain neither a Rust trait
+//! name nor an opaque-reference `name` field. Application records, enums,
+//! unions, entry paths, and JSON all encode through the schema-neutral [`Value`]
+//! variants: entries and enums are strings, unions are discriminator records,
+//! and JSON recursively uses ordinary records/lists/primitives. The former
+//! `Entry<K, V>` and semantic `Value::Entry`, `Value::Enum`, `Value::Union`, and
+//! `Value::Json` forms are intentionally unsupported.
+//!
+//! # Supported authoring subset
+//!
+//! Public, non-generic traits use immutable `&self` receivers, owned named
+//! parameters, and explicit `wip::OperationResult<T>` returns. Derived DTOs are
+//! named-field records, all-unit enums, or unions with unit and single-payload
+//! cases. A direct `Option<T>` means field/argument omission, never protocol
+//! null. See `wip-interface` for the complete rejected-syntax list.
+
+#![deny(missing_docs)]
+
+use std::collections::BTreeMap;
+use std::error::Error;
+use std::io;
+
+use wip_host::{
+    CallErrorKind, CallRequest, ExecutionContext, InterfaceRef, InterfaceRegistry, InterfaceTarget,
+    ObjectProvider, ProviderResult, PublishedObject, RegisteredInterface, Target, Validator,
+    WipObject,
+};
+use wip_interface as wip;
+use wip_interface::WipType;
+use wip_protocol::{ProtocolError, ProtocolErrorCode, Value};
+
+const OBJECT_PATH: &str = "/article-service";
+const OBJECT_VALIDATOR: &[u8] = b"object-v1";
+const CATALOG_VALIDATOR: &[u8] = b"catalog-v1";
+
+/// Publication visibility represented as a protocol enum string.
+#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
+pub enum Visibility {
+    /// Visible to every authorized caller.
+    Public,
+    /// Visible only inside the application domain.
+    Private,
+}
+
+/// An application-owned request DTO mapped to a protocol record.
+#[derive(Debug, Clone, PartialEq, wip::WipType)]
+pub struct PublishRequest {
+    /// Title of the article to publish.
+    pub title: String,
+    /// Optional article body; omission is distinct from JSON null.
+    pub body: Option<String>,
+    /// Canonical Worldspace path to the source entry.
+    pub source: wip::Entry,
+    /// Application enum represented by a schema-neutral string.
+    pub visibility: Visibility,
+    /// Schema-opaque JSON represented by ordinary protocol values.
+    pub metadata: wip::JsonValue,
+}
+
+/// The application domain result of a publication attempt.
+#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
+pub enum PublishOutcome {
+    /// Publication succeeded and returned its application identifier.
+    Published(String),
+    /// An application policy rejected the publication.
+    Rejected(String),
+}
+
+/// Article publication operations.
+#[wip::interface]
+pub trait Catalog {
+    /// Publishes an article or reports an application-domain rejection.
+    ///
+    /// # Returns
+    /// The typed application outcome.
+    fn publish(
+        &self,
+        /// Application publication request.
+        request: PublishRequest,
+    ) -> wip::OperationResult<PublishOutcome>;
+
+    /// Returns the catalog-qualified status.
+    fn status(&self) -> wip::OperationResult<String>;
+
+    /// Demonstrates a rollback-confirmed host/backend failure.
+    fn backend_status(&self) -> wip::OperationResult<String>;
+
+    /// Demonstrates a host/backend failure with an unknown operation outcome.
+    fn uncertain_backend_status(&self) -> wip::OperationResult<String>;
+
+    /// Demonstrates denial after every structural precondition succeeds.
+    fn restricted_status(&self) -> wip::OperationResult<String>;
+}
+
+/// Audit operations exposed by the same object.
+#[wip::interface]
+pub trait Audit {
+    /// Returns the audit-qualified status.
+    fn status(&self) -> wip::OperationResult<String>;
+}
+
+/// A registered but deliberately unexposed interface.
+#[wip::interface]
+pub trait Diagnostics {
+    /// Returns host-private diagnostics when explicitly exposed.
+    fn diagnostics(&self) -> wip::OperationResult<String>;
+}
+
+/// Observable outcomes from the complete public-API scenario.
+#[derive(Debug, Clone, PartialEq)]
+pub struct DemoReport {
+    /// Path-segment name from the canonical object projection.
+    pub object_name: String,
+    /// Optional object identity, distinct from the resolution path.
+    pub object_reference: Option<String>,
+    /// Optional object-state validator.
+    pub object_validator: Option<Vec<u8>>,
+    /// Opaque interface references published by the object, in exposure order.
+    pub published_interfaces: Vec<String>,
+    /// Opaque reference assigned to the catalog descriptor.
+    pub catalog_interface_reference: String,
+    /// Opaque reference assigned to the audit descriptor.
+    pub audit_interface_reference: String,
+    /// Descriptor format observed separately for the catalog reference.
+    pub catalog_descriptor_format: String,
+    /// Descriptor format observed separately for the audit reference.
+    pub audit_descriptor_format: String,
+    /// Typed successful application result decoded from a validated [`Value`].
+    pub published: PublishOutcome,
+    /// Typed application-domain rejection decoded from a validated [`Value`].
+    pub rejected: PublishOutcome,
+    /// Result of the catalog-qualified `status` operation.
+    pub catalog_status: String,
+    /// Result of the audit-qualified `status` operation.
+    pub audit_status: String,
+    /// Stable failure kind produced by the deliberate host/backend failure.
+    pub host_failure: CallErrorKind,
+    /// Protocol failure whose operation effects are guaranteed not committed.
+    pub protocol_failure: ProtocolError,
+    /// Protocol failure whose operation effects cannot be proven absent.
+    pub unknown_protocol_failure: ProtocolError,
+    /// Authorization failure after a fully qualified valid request.
+    pub permission_failure: ProtocolErrorCode,
+    /// Recovery signal for a stale object validator.
+    pub validator_failure: ProtocolErrorCode,
+    /// Failure for a known but unexposed interface reference.
+    pub interface_mismatch: ProtocolErrorCode,
+    /// Failure for an unknown interface observation reference.
+    pub interface_not_found: ProtocolErrorCode,
+    /// First failure for a request with an invalid path and later invalid fields.
+    pub precedence_failure: ProtocolErrorCode,
+}
+
+/// Runs the complete end-to-end conformance example.
+///
+/// The provider resolves the current object from a Worldspace path for each
+/// call. Interface observations remain separate from object projection, and all
+/// successful calls carry independent object and interface validators.
+///
+/// # Errors
+///
+/// Returns an error if registration, observation, path resolution, dispatch, or
+/// application-value decoding fails unexpectedly.
+pub fn run() -> Result<DemoReport, Box<dyn Error>> {
+    let mut registry = InterfaceRegistry::new();
+    let catalog = registry.register(CatalogDefinition, Some(Validator::new(CATALOG_VALIDATOR)))?;
+    let audit = registry.register(AuditDefinition, None)?;
+    let diagnostics = registry.register(DiagnosticsDefinition, None)?;
+    let provider = ApplicationProvider {
+        catalog: catalog.clone(),
+        audit: audit.clone(),
+    };
+
+    let object = provider.fetch(OBJECT_PATH)?;
+    let catalog_response = registry
+        .fetch_interface(
+            object
+                .interfaces
+                .first()
+                .ok_or_else(|| io::Error::other("catalog interface was not published"))?,
+        )?
+        .protocol_response()?;
+    let audit_response = registry
+        .fetch_interface(
+            object
+                .interfaces
+                .get(1)
+                .ok_or_else(|| io::Error::other("audit interface was not published"))?,
+        )?
+        .protocol_response()?;
+
+    let published = dispatch_publish(
+        &provider,
+        catalog.reference(),
+        PublishRequest {
+            title: "Public APIs".into(),
+            body: Some("protocol values in, validated values out".into()),
+            source: wip::Entry::new("/drafts/public-apis")?,
+            visibility: Visibility::Public,
+            metadata: wip::JsonValue::Object(vec![wip::JsonMember {
+                name: "reviewed".into(),
+                value: wip::JsonValue::Boolean(true),
+            }]),
+        },
+    )?;
+    let rejected = dispatch_publish(
+        &provider,
+        catalog.reference(),
+        PublishRequest {
+            title: String::new(),
+            body: None,
+            source: wip::Entry::new("/drafts/untitled")?,
+            visibility: Visibility::Private,
+            metadata: wip::JsonValue::Null,
+        },
+    )?;
+    let catalog_status = dispatch_string(
+        &provider,
+        request(
+            OBJECT_PATH,
+            catalog.reference(),
+            Some(CATALOG_VALIDATOR),
+            "status",
+            BTreeMap::new(),
+        ),
+    )?;
+    let audit_status = dispatch_string(
+        &provider,
+        request(
+            OBJECT_PATH,
+            audit.reference(),
+            None,
+            "status",
+            BTreeMap::new(),
+        ),
+    )?;
+
+    let host_error = provider
+        .call_operation(request(
+            OBJECT_PATH,
+            catalog.reference(),
+            Some(CATALOG_VALIDATOR),
+            "backend_status",
+            BTreeMap::new(),
+        ))
+        .expect_err("backend_status must model a host failure");
+    ensure_kind(&host_error, CallErrorKind::Internal)?;
+    let protocol_failure = host_error.protocol_error();
+
+    let unknown_protocol_failure = provider
+        .call_operation(request(
+            OBJECT_PATH,
+            catalog.reference(),
+            Some(CATALOG_VALIDATOR),
+            "uncertain_backend_status",
+            BTreeMap::new(),
+        ))
+        .expect_err("uncertain_backend_status must preserve an unknown outcome")
+        .protocol_error();
+
+    let permission_failure = provider
+        .call_operation(request(
+            OBJECT_PATH,
+            catalog.reference(),
+            Some(CATALOG_VALIDATOR),
+            "restricted_status",
+            BTreeMap::new(),
+        ))
+        .expect_err("restricted_status must be denied")
+        .protocol_error()
+        .code;
+
+    let validator_failure = provider
+        .call_operation(CallRequest {
+            target: Target {
+                path: OBJECT_PATH.into(),
+                validator: Some(b"stale-object".to_vec()),
+            },
+            interface: InterfaceTarget {
+                reference: diagnostics.reference().as_str().to_owned(),
+                validator: Some(b"stale-interface".to_vec()),
+            },
+            operation: "missing".into(),
+            arguments: BTreeMap::from([("unknown".into(), Value::Unit)]),
+        })
+        .expect_err("the stale object validator must fail first")
+        .protocol_error()
+        .code;
+
+    let interface_mismatch = provider
+        .call_operation(request(
+            OBJECT_PATH,
+            diagnostics.reference(),
+            None,
+            "diagnostics",
+            BTreeMap::new(),
+        ))
+        .expect_err("registered but unexposed interface must not dispatch")
+        .protocol_error()
+        .code;
+
+    let interface_not_found = registry
+        .fetch_interface("missing-interface")
+        .expect_err("unknown interface references must not resolve")
+        .code;
+
+    let precedence_failure = provider
+        .call_operation(CallRequest {
+            target: Target {
+                path: "relative/path".into(),
+                validator: Some(b"stale-object".to_vec()),
+            },
+            interface: InterfaceTarget {
+                reference: diagnostics.reference().as_str().to_owned(),
+                validator: Some(b"stale-interface".to_vec()),
+            },
+            operation: "missing".into(),
+            arguments: BTreeMap::from([("unknown".into(), Value::Unit)]),
+        })
+        .expect_err("invalid path must have canonical precedence")
+        .protocol_error()
+        .code;
+
+    Ok(DemoReport {
+        object_name: object.name,
+        object_reference: object.r#ref,
+        object_validator: object.validator,
+        published_interfaces: object.interfaces,
+        catalog_interface_reference: catalog.reference().as_str().to_owned(),
+        audit_interface_reference: audit.reference().as_str().to_owned(),
+        catalog_descriptor_format: catalog_response.descriptor.format,
+        audit_descriptor_format: audit_response.descriptor.format,
+        published,
+        rejected,
+        catalog_status,
+        audit_status,
+        host_failure: host_error.kind(),
+        protocol_failure,
+        unknown_protocol_failure,
+        permission_failure,
+        validator_failure,
+        interface_mismatch,
+        interface_not_found,
+        precedence_failure,
+    })
+}
+
+fn ensure_kind(error: &wip_host::CallError, expected: CallErrorKind) -> Result<(), io::Error> {
+    if error.kind() == expected {
+        Ok(())
+    } else {
+        Err(io::Error::other(format!(
+            "unexpected host failure kind: {:?}",
+            error.kind()
+        )))
+    }
+}
+
+fn dispatch_publish(
+    provider: &ApplicationProvider,
+    catalog: &InterfaceRef,
+    request_value: PublishRequest,
+) -> Result<PublishOutcome, Box<dyn Error>> {
+    let encoded_request = request_value.encode()?;
+    let result = provider.call_operation(request(
+        OBJECT_PATH,
+        catalog,
+        Some(CATALOG_VALIDATOR),
+        "publish",
+        BTreeMap::from([("request".into(), encoded_request)]),
+    ))?;
+    Ok(PublishOutcome::decode(result.result)?)
+}
+
+fn dispatch_string(
+    provider: &ApplicationProvider,
+    request: CallRequest,
+) -> Result<String, Box<dyn Error>> {
+    let result = provider.call_operation(request)?;
+    Ok(String::decode(result.result)?)
+}
+
+fn request(
+    path: &str,
+    interface: &InterfaceRef,
+    interface_validator: Option<&[u8]>,
+    operation: &str,
+    arguments: BTreeMap<String, Value>,
+) -> CallRequest {
+    CallRequest {
+        target: Target {
+            path: path.into(),
+            validator: Some(OBJECT_VALIDATOR.to_vec()),
+        },
+        interface: InterfaceTarget {
+            reference: interface.as_str().to_owned(),
+            validator: interface_validator.map(<[u8]>::to_vec),
+        },
+        operation: operation.into(),
+        arguments,
+    }
+}
+
+struct ApplicationProvider {
+    catalog: RegisteredInterface<CatalogDefinition>,
+    audit: RegisteredInterface<AuditDefinition>,
+}
+
+impl ObjectProvider for ApplicationProvider {
+    type Object = ApplicationService;
+
+    fn with_object<R>(
+        &self,
+        _context: &ExecutionContext,
+        path: &str,
+        operation: impl FnOnce(&PublishedObject<Self::Object>) -> R,
+    ) -> ProviderResult<R> {
+        if path != OBJECT_PATH {
+            return ProviderResult::NotFound;
+        }
+        let publication = PublishedObject::new(ApplicationService::new())
+            .expose(&self.catalog)
+            .expect("ApplicationService implements Catalog")
+            .expose(&self.audit)
+            .expect("ApplicationService implements Audit");
+        ProviderResult::Found(operation(&publication))
+    }
+
+    fn authorize(
+        &self,
+        _: &str,
+        _: &ApplicationService,
+        _: &InterfaceRef,
+        operation: &str,
+    ) -> bool {
+        operation != "restricted_status"
+    }
+}
+
+struct ApplicationService {
+    object_validator: Validator,
+    backend_connection: String,
+}
+
+impl ApplicationService {
+    fn new() -> Self {
+        Self {
+            object_validator: Validator::new(OBJECT_VALIDATOR),
+            backend_connection: "private://article-database".into(),
+        }
+    }
+}
+
+impl WipObject for ApplicationService {
+    fn name(&self) -> &str {
+        "article-service"
+    }
+
+    fn description(&self) -> Option<&str> {
+        Some("Article publication service")
+    }
+
+    fn reference(&self) -> Option<&str> {
+        Some("article-service-instance")
+    }
+
+    fn validator(&self) -> Option<&Validator> {
+        Some(&self.object_validator)
+    }
+
+    fn requires_validator(&self, _: &InterfaceRef, _: &str) -> bool {
+        true
+    }
+}
+
+impl Catalog for ApplicationService {
+    fn publish(&self, request: PublishRequest) -> wip::OperationResult<PublishOutcome> {
+        if request.title.trim().is_empty() {
+            Ok(PublishOutcome::Rejected("a title is required".into()))
+        } else {
+            Ok(PublishOutcome::Published("article-1".into()))
+        }
+    }
+
+    fn status(&self) -> wip::OperationResult<String> {
+        Ok("catalog-ready".into())
+    }
+
+    fn backend_status(&self) -> wip::OperationResult<String> {
+        if self.backend_connection.starts_with("private://") {
+            Err(wip::HostError::internal(
+                "backend unavailable",
+                wip::EffectGuarantee::NotCommitted,
+            ))
+        } else {
+            Ok("backend-ready".into())
+        }
+    }
+
+    fn uncertain_backend_status(&self) -> wip::OperationResult<String> {
+        Err(wip::HostError::internal(
+            "backend commit acknowledgement unavailable",
+            wip::EffectGuarantee::Unknown,
+        ))
+    }
+
+    fn restricted_status(&self) -> wip::OperationResult<String> {
+        Ok("authorization hook should prevent this call".into())
+    }
+}
+
+impl Audit for ApplicationService {
+    fn status(&self) -> wip::OperationResult<String> {
+        Ok("audit-ready".into())
+    }
+}
+
+impl Diagnostics for ApplicationService {
+    fn diagnostics(&self) -> wip::OperationResult<String> {
+        Ok("host-private".into())
+    }
+}

crates/wip-public-api-example/tests/end_to_end.rs

@@ -0,0 +1,246 @@
+use std::collections::BTreeMap;
+
+use wip_host::CallErrorKind;
+use wip_interface::{Entry, JsonMember, JsonValue, WipType};
+use wip_protocol::{INTERFACE_FORMAT_V1, InterfaceDescriptor, Object, ProtocolErrorCode, Value};
+use wip_public_api_example::{CatalogDefinition, PublishOutcome, PublishRequest, Visibility, run};
+
+#[test]
+fn public_crates_support_the_complete_qualified_end_to_end_scenario() {
+    let report = run().unwrap();
+
+    assert_eq!(report.object_name, "article-service");
+    assert_eq!(
+        report.object_reference.as_deref(),
+        Some("article-service-instance")
+    );
+    assert_eq!(
+        report.object_validator.as_deref(),
+        Some(b"object-v1".as_slice())
+    );
+    assert_eq!(
+        report.published_interfaces,
+        [
+            report.catalog_interface_reference.clone(),
+            report.audit_interface_reference.clone(),
+        ],
+        "interfaces must retain explicit publication order"
+    );
+    assert_ne!(
+        report.catalog_interface_reference, report.audit_interface_reference,
+        "interfaces form an ordered set of distinct opaque references"
+    );
+    assert_eq!(report.catalog_descriptor_format, INTERFACE_FORMAT_V1);
+    assert_eq!(report.audit_descriptor_format, INTERFACE_FORMAT_V1);
+    assert_eq!(
+        report.published,
+        PublishOutcome::Published("article-1".into())
+    );
+    assert_eq!(
+        report.rejected,
+        PublishOutcome::Rejected("a title is required".into())
+    );
+    assert_eq!(report.catalog_status, "catalog-ready");
+    assert_eq!(report.audit_status, "audit-ready");
+}
+
+#[test]
+fn domain_host_permission_and_validator_failures_remain_distinct() {
+    let report = run().unwrap();
+
+    assert!(matches!(report.rejected, PublishOutcome::Rejected(_)));
+    assert_eq!(report.host_failure, CallErrorKind::Internal);
+    assert_eq!(report.protocol_failure.code, ProtocolErrorCode::Internal);
+    assert_eq!(
+        report.unknown_protocol_failure.code,
+        ProtocolErrorCode::OperationOutcomeUnknown
+    );
+    assert_eq!(
+        report.permission_failure,
+        ProtocolErrorCode::PermissionDenied
+    );
+    assert_eq!(
+        report.validator_failure,
+        ProtocolErrorCode::ValidatorMismatch,
+        "validator recovery signals must not collapse to InvalidRequest"
+    );
+}
+
+#[test]
+fn interface_mismatch_is_not_interface_not_found() {
+    let report = run().unwrap();
+
+    assert_eq!(
+        report.interface_mismatch,
+        ProtocolErrorCode::InterfaceMismatch
+    );
+    assert_eq!(
+        report.interface_not_found,
+        ProtocolErrorCode::InterfaceNotFound
+    );
+    assert_ne!(report.interface_mismatch, report.interface_not_found);
+}
+
+#[test]
+fn invalid_path_keeps_canonical_failure_precedence() {
+    let report = run().unwrap();
+
+    assert_eq!(report.precedence_failure, ProtocolErrorCode::InvalidRequest);
+    assert_ne!(report.precedence_failure, report.validator_failure);
+    assert_ne!(report.precedence_failure, report.interface_mismatch);
+}
+
+#[test]
+fn object_fields_keep_path_context_and_optional_ref_separate() {
+    // Listing every field makes this test fail to compile if a mandatory
+    // ObjectId is reintroduced into the canonical object DTO.
+    let object = Object {
+        name: "article".into(),
+        description: None,
+        interfaces: vec!["catalog-ref".into(), "audit-ref".into()],
+        r#ref: None,
+        validator: None,
+    };
+
+    object.validate_at_path("/library/article").unwrap();
+    assert_eq!(object.name, "article");
+    assert_eq!(object.r#ref, None);
+    assert_eq!(object.interfaces, ["catalog-ref", "audit-ref"]);
+}
+
+#[test]
+fn interface_reference_is_observed_separately_from_descriptor_fields() {
+    // An exact destructuring pattern is compile-time coverage that the
+    // descriptor has no trait-name or opaque-reference `name` field.
+    let InterfaceDescriptor {
+        format,
+        documentation,
+        types,
+        operations,
+    } = CatalogDefinition::descriptor();
+
+    assert_eq!(format, INTERFACE_FORMAT_V1);
+    assert!(documentation.is_some());
+    assert!(!types.is_empty());
+    assert_eq!(
+        operations
+            .iter()
+            .map(|operation| operation.name.as_str())
+            .collect::<Vec<_>>(),
+        [
+            "publish",
+            "status",
+            "backend_status",
+            "uncertain_backend_status",
+            "restricted_status",
+        ]
+    );
+}
+
+#[test]
+fn application_record_enum_union_entry_and_json_use_schema_neutral_values() {
+    let request = PublishRequest {
+        title: "Canonical values".into(),
+        body: None,
+        source: Entry::new("/drafts/canonical-values").unwrap(),
+        visibility: Visibility::Public,
+        metadata: JsonValue::Object(vec![
+            JsonMember {
+                name: "tags".into(),
+                value: JsonValue::Array(vec![JsonValue::String("wip".into()), JsonValue::Null]),
+            },
+            JsonMember {
+                name: "ready".into(),
+                value: JsonValue::Boolean(true),
+            },
+        ]),
+    };
+
+    let encoded = request.encode().unwrap();
+    assert_schema_neutral(&encoded);
+    let Value::Record(fields) = encoded else {
+        panic!("derived DTO record must use Value::Record")
+    };
+    assert_eq!(
+        fields.get("title"),
+        Some(&Value::String("Canonical values".into()))
+    );
+    assert!(!fields.contains_key("body"));
+    assert_eq!(
+        fields.get("source"),
+        Some(&Value::String("/drafts/canonical-values".into()))
+    );
+    assert_eq!(
+        fields.get("visibility"),
+        Some(&Value::String("Public".into()))
+    );
+    assert_eq!(
+        fields.get("metadata"),
+        Some(&Value::Record(BTreeMap::from([
+            ("ready".into(), Value::Boolean(true)),
+            (
+                "tags".into(),
+                Value::List(vec![Value::String("wip".into()), Value::Unit])
+            ),
+        ])))
+    );
+
+    let outcome = PublishOutcome::Rejected("policy".into()).encode().unwrap();
+    assert_schema_neutral(&outcome);
+    assert_eq!(
+        outcome,
+        Value::Record(BTreeMap::from([
+            ("$case".into(), Value::String("Rejected".into())),
+            ("value".into(), Value::String("policy".into())),
+        ]))
+    );
+}
+
+#[test]
+fn entry_is_a_validated_canonical_absolute_path_string() {
+    let entry = Entry::new("/articles/one").unwrap();
+    assert_eq!(
+        entry.encode().unwrap(),
+        Value::String("/articles/one".into())
+    );
+
+    for invalid in [
+        "articles/one",
+        "/articles/",
+        "/articles//one",
+        "/articles/./one",
+        "/articles/../one",
+    ] {
+        assert!(
+            Entry::new(invalid).is_err(),
+            "accepted invalid path {invalid}"
+        );
+        assert!(
+            Entry::decode(Value::String(invalid.into())).is_err(),
+            "decoded invalid path {invalid}"
+        );
+    }
+}
+
+fn assert_schema_neutral(value: &Value) {
+    // This exhaustive match is a compile-time regression guard: reintroducing
+    // semantic Entry/Enum/Union/Json variants makes the consumer non-exhaustive.
+    match value {
+        Value::Unit
+        | Value::Boolean(_)
+        | Value::Integer(_)
+        | Value::Number(_)
+        | Value::String(_)
+        | Value::Bytes(_) => {}
+        Value::Record(fields) => {
+            for value in fields.values() {
+                assert_schema_neutral(value);
+            }
+        }
+        Value::List(values) => {
+            for value in values {
+                assert_schema_neutral(value);
+            }
+        }
+    }
+}

src/lib.rs

@@ -1,360 +0,0 @@
-//! End-to-end use of the public WIP protocol, interface, and host APIs.
-//!
-//! This workspace package defines application DTOs and interfaces with
-//! `wip-interface`, keeps its implementation private, publishes it through a
-//! request-scoped `wip-host` provider, and crosses the call boundary only with
-//! canonical `wip-protocol` values and path targets.
-
-#![deny(missing_docs)]
-
-use std::collections::BTreeMap;
-use std::error::Error;
-use std::io;
-
-use wip_host::{
-    CallErrorKind, CallRequest, InterfaceRef, InterfaceRegistry, InterfaceTarget, ObjectProvider,
-    PublishedObject, RegisteredInterface, Target, Validator, WipObject,
-};
-use wip_interface as wip;
-use wip_interface::WipType;
-use wip_protocol::ProtocolError;
-
-const OBJECT_PATH: &str = "/article-service";
-const OBJECT_VALIDATOR: &[u8] = b"object-v1";
-const CATALOG_VALIDATOR: &[u8] = b"catalog-v1";
-
-/// An application-owned request DTO mapped to a protocol record.
-#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
-pub struct PublishRequest {
-    /// Title of the article to publish.
-    pub title: String,
-    /// Optional article body; omission is distinct from JSON null.
-    pub body: Option<String>,
-}
-
-/// The application domain result of a publication attempt.
-#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
-pub enum PublishOutcome {
-    /// Publication succeeded and returned its application identifier.
-    Published(String),
-    /// An application policy rejected the publication.
-    Rejected(String),
-}
-
-/// Article publication operations.
-#[wip::interface]
-pub trait Catalog {
-    /// Publishes an article or reports an application-domain rejection.
-    ///
-    /// # Returns
-    /// The typed application outcome.
-    fn publish(
-        &self,
-        /// Application publication request.
-        request: PublishRequest,
-    ) -> wip::OperationResult<PublishOutcome>;
-
-    /// Returns the catalog-qualified status.
-    fn status(&self) -> wip::OperationResult<String>;
-
-    /// Demonstrates a host/backend failure rather than a domain result.
-    fn backend_status(&self) -> wip::OperationResult<String>;
-}
-
-/// Audit operations exposed by the same object.
-#[wip::interface]
-pub trait Audit {
-    /// Returns the audit-qualified status.
-    fn status(&self) -> wip::OperationResult<String>;
-}
-
-/// A registered but deliberately unexposed interface.
-#[wip::interface]
-pub trait Diagnostics {
-    /// Returns host-private diagnostics when explicitly exposed.
-    fn diagnostics(&self) -> wip::OperationResult<String>;
-}
-
-/// Observable outcomes from the complete public-API scenario.
-#[derive(Debug, Clone, PartialEq)]
-pub struct DemoReport {
-    /// Opaque interface references published by the object, in exposure order.
-    pub published_interfaces: Vec<String>,
-    /// Descriptor format observed for the catalog interface.
-    pub catalog_descriptor_format: String,
-    /// Descriptor format observed for the audit interface.
-    pub audit_descriptor_format: String,
-    /// Typed successful application result decoded from a validated `Value`.
-    pub published: PublishOutcome,
-    /// Typed application-domain rejection decoded from a validated `Value`.
-    pub rejected: PublishOutcome,
-    /// Result of the catalog-qualified `status` operation.
-    pub catalog_status: String,
-    /// Result of the audit-qualified `status` operation.
-    pub audit_status: String,
-    /// Stable failure kind produced by the deliberate host/backend failure.
-    pub host_failure: CallErrorKind,
-    /// A protocol-level failure built from the host failure.
-    pub protocol_failure: ProtocolError,
-}
-
-/// Runs the complete end-to-end example.
-///
-/// The provider resolves the current object from a Worldspace path for each
-/// call. Interface observations remain separate from object projection, and all
-/// calls carry independent object and interface validators.
-///
-/// # Errors
-///
-/// Returns an error if registration, observation, path resolution, dispatch, or
-/// application-value decoding fails unexpectedly.
-pub fn run() -> Result<DemoReport, Box<dyn Error>> {
-    let mut registry = InterfaceRegistry::new();
-    let catalog = registry.register(CatalogDefinition, Some(Validator::new(CATALOG_VALIDATOR)))?;
-    let audit = registry.register(AuditDefinition, None)?;
-    let _diagnostics = registry.register(DiagnosticsDefinition, None)?;
-    let provider = ApplicationProvider {
-        catalog: catalog.clone(),
-        audit: audit.clone(),
-    };
-
-    let object = provider.fetch(OBJECT_PATH)?;
-    let catalog_observation = registry.fetch_interface(
-        object
-            .interfaces
-            .first()
-            .ok_or_else(|| io::Error::other("catalog interface was not published"))?,
-    )?;
-    let audit_observation = registry.fetch_interface(
-        object
-            .interfaces
-            .get(1)
-            .ok_or_else(|| io::Error::other("audit interface was not published"))?,
-    )?;
-
-    let published = dispatch_publish(
-        &provider,
-        catalog.reference(),
-        PublishRequest {
-            title: "Public APIs".into(),
-            body: Some("protocol values in, validated values out".into()),
-        },
-    )?;
-    let rejected = dispatch_publish(
-        &provider,
-        catalog.reference(),
-        PublishRequest {
-            title: String::new(),
-            body: None,
-        },
-    )?;
-    let catalog_status = dispatch_string(
-        &provider,
-        request(
-            catalog.reference(),
-            Some(CATALOG_VALIDATOR),
-            "status",
-            BTreeMap::new(),
-        ),
-    )?;
-    let audit_status = dispatch_string(
-        &provider,
-        request(audit.reference(), None, "status", BTreeMap::new()),
-    )?;
-
-    let host_error = provider
-        .call_operation(request(
-            catalog.reference(),
-            Some(CATALOG_VALIDATOR),
-            "backend_status",
-            BTreeMap::new(),
-        ))
-        .unwrap_err();
-    if host_error.kind() != CallErrorKind::Implementation {
-        return Err(io::Error::other(format!(
-            "unexpected host failure kind: {:?}",
-            host_error.kind()
-        ))
-        .into());
-    }
-    let protocol_failure = host_error.protocol_error();
-
-    Ok(DemoReport {
-        published_interfaces: object.interfaces,
-        catalog_descriptor_format: catalog_observation.descriptor.format,
-        audit_descriptor_format: audit_observation.descriptor.format,
-        published,
-        rejected,
-        catalog_status,
-        audit_status,
-        host_failure: host_error.kind(),
-        protocol_failure,
-    })
-}
-
-fn dispatch_publish(
-    provider: &ApplicationProvider,
-    catalog: &InterfaceRef,
-    request_value: PublishRequest,
-) -> Result<PublishOutcome, Box<dyn Error>> {
-    let encoded_request = request_value.encode()?;
-    let result = provider.call_operation(request(
-        catalog,
-        Some(CATALOG_VALIDATOR),
-        "publish",
-        BTreeMap::from([("request".into(), encoded_request)]),
-    ))?;
-    Ok(PublishOutcome::decode(result.result)?)
-}
-
-fn dispatch_string(
-    provider: &ApplicationProvider,
-    request: CallRequest,
-) -> Result<String, Box<dyn Error>> {
-    let result = provider.call_operation(request)?;
-    Ok(String::decode(result.result)?)
-}
-
-fn request(
-    interface: &InterfaceRef,
-    interface_validator: Option<&[u8]>,
-    operation: &str,
-    arguments: BTreeMap<String, wip_protocol::Value>,
-) -> CallRequest {
-    CallRequest {
-        target: Target {
-            path: OBJECT_PATH.into(),
-            validator: Some(OBJECT_VALIDATOR.to_vec()),
-        },
-        interface: InterfaceTarget {
-            reference: interface.as_str().to_owned(),
-            validator: interface_validator.map(<[u8]>::to_vec),
-        },
-        operation: operation.into(),
-        arguments,
-    }
-}
-
-struct ApplicationProvider {
-    catalog: RegisteredInterface<CatalogDefinition>,
-    audit: RegisteredInterface<AuditDefinition>,
-}
-
-impl ObjectProvider for ApplicationProvider {
-    type Object = ApplicationService;
-
-    fn with_object<R>(
-        &self,
-        path: &str,
-        operation: impl FnOnce(&PublishedObject<Self::Object>) -> R,
-    ) -> Option<R> {
-        if path != OBJECT_PATH {
-            return None;
-        }
-        let publication = PublishedObject::new(ApplicationService::new())
-            .expose(&self.catalog)
-            .expect("ApplicationService implements Catalog")
-            .expose(&self.audit)
-            .expect("ApplicationService implements Audit");
-        Some(operation(&publication))
-    }
-}
-
-struct ApplicationService {
-    object_validator: Validator,
-    backend_connection: String,
-}
-
-impl ApplicationService {
-    fn new() -> Self {
-        Self {
-            object_validator: Validator::new(OBJECT_VALIDATOR),
-            backend_connection: "private://article-database".into(),
-        }
-    }
-}
-
-impl WipObject for ApplicationService {
-    fn name(&self) -> &str {
-        "article-service"
-    }
-
-    fn description(&self) -> Option<&str> {
-        Some("Article publication service")
-    }
-
-    fn reference(&self) -> Option<&str> {
-        Some("article-service-instance")
-    }
-
-    fn validator(&self) -> Option<&Validator> {
-        Some(&self.object_validator)
-    }
-
-    fn requires_validator(&self, _: &InterfaceRef, _: &str) -> bool {
-        true
-    }
-}
-
-impl Catalog for ApplicationService {
-    fn publish(&self, request: PublishRequest) -> wip::OperationResult<PublishOutcome> {
-        if request.title.trim().is_empty() {
-            Ok(PublishOutcome::Rejected("a title is required".into()))
-        } else {
-            Ok(PublishOutcome::Published("article-1".into()))
-        }
-    }
-
-    fn status(&self) -> wip::OperationResult<String> {
-        Ok("catalog-ready".into())
-    }
-
-    fn backend_status(&self) -> wip::OperationResult<String> {
-        if self.backend_connection.starts_with("private://") {
-            Err(wip::HostError::new("backend unavailable"))
-        } else {
-            Ok("backend-ready".into())
-        }
-    }
-}
-
-impl Audit for ApplicationService {
-    fn status(&self) -> wip::OperationResult<String> {
-        Ok("audit-ready".into())
-    }
-}
-
-impl Diagnostics for ApplicationService {
-    fn diagnostics(&self) -> wip::OperationResult<String> {
-        Ok("host-private".into())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use wip_protocol::ProtocolErrorCode;
-
-    #[test]
-    fn unexposed_interfaces_are_membership_failures() {
-        let mut registry = InterfaceRegistry::new();
-        let catalog = registry.register(CatalogDefinition, None).unwrap();
-        let audit = registry.register(AuditDefinition, None).unwrap();
-        let diagnostics = registry.register(DiagnosticsDefinition, None).unwrap();
-        let provider = ApplicationProvider { catalog, audit };
-
-        let error = provider
-            .call_operation(request(
-                diagnostics.reference(),
-                None,
-                "diagnostics",
-                BTreeMap::new(),
-            ))
-            .unwrap_err();
-        assert_eq!(error.kind(), CallErrorKind::InterfaceMismatch);
-        assert_eq!(
-            error.protocol_error().code,
-            ProtocolErrorCode::InterfaceMismatch
-        );
-    }
-}

tests/end_to_end.rs

@@ -1,24 +0,0 @@
-use wip_host::CallErrorKind;
-use wip_protocol::{INTERFACE_FORMAT_V1, ProtocolErrorCode};
-use wip_public_api_example::{PublishOutcome, run};
-
-#[test]
-fn public_crates_support_the_complete_end_to_end_scenario() {
-    let report = run().unwrap();
-
-    assert_eq!(report.published_interfaces.len(), 2);
-    assert_eq!(report.catalog_descriptor_format, INTERFACE_FORMAT_V1);
-    assert_eq!(report.audit_descriptor_format, INTERFACE_FORMAT_V1);
-    assert_eq!(
-        report.published,
-        PublishOutcome::Published("article-1".into())
-    );
-    assert_eq!(
-        report.rejected,
-        PublishOutcome::Rejected("a title is required".into())
-    );
-    assert_eq!(report.catalog_status, "catalog-ready");
-    assert_eq!(report.audit_status, "audit-ready");
-    assert_eq!(report.host_failure, CallErrorKind::Implementation);
-    assert_eq!(report.protocol_failure.code, ProtocolErrorCode::Internal);
-}