fix(client): validate suppressed tree objects

Cargo.lock

@@ -2,12 +2,44 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "displaydoc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
 [[package]]
 name = "glob"
 version = "0.3.4"
@@ -20,6 +52,120 @@ version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 
+[[package]]
+name = "http"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0"
+
+[[package]]
+name = "icu_properties"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148"
+dependencies = [
+ "displaydoc",
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa"
+
+[[package]]
+name = "icu_provider"
+version = "2.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
 [[package]]
 name = "indexmap"
 version = "2.14.2"
@@ -36,12 +182,33 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "litemap"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
+
 [[package]]
 name = "memchr"
 version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "potential_utf"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"
+dependencies = [
+ "zerovec",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -111,6 +278,18 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "smallvec"
+version = "1.16.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9395f0f0eee849a9b707b2f06bb92a6a422090e2123bb2ef8e87a0e61892a8e"
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
 [[package]]
 name = "syn"
 version = "2.0.119"
@@ -133,6 +312,17 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "synstructure"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
 [[package]]
 name = "target-tuple"
 version = "1.0.2"
@@ -148,6 +338,16 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "tinystr"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
 [[package]]
 name = "toml"
 version = "1.1.6+spec-1.1.0"
@@ -208,6 +408,24 @@ version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
 
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -238,6 +456,35 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
 
+[[package]]
+name = "wip-client"
+version = "0.1.0"
+dependencies = [
+ "wip-https",
+ "wip-protocol",
+]
+
+[[package]]
+name = "wip-host"
+version = "0.1.0"
+dependencies = [
+ "trybuild",
+ "wip-interface",
+ "wip-protocol",
+]
+
+[[package]]
+name = "wip-https"
+version = "0.1.0"
+dependencies = [
+ "base64",
+ "http",
+ "serde",
+ "serde_json",
+ "url",
+ "wip-protocol",
+]
+
 [[package]]
 name = "wip-interface"
 version = "0.1.0"
@@ -261,12 +508,97 @@ name = "wip-protocol"
 version = "0.1.0"
 
 [[package]]
-name = "wip-rs"
+name = "wip-public-api-example"
 version = "0.1.0"
 dependencies = [
+ "wip-host",
+ "wip-interface",
  "wip-protocol",
 ]
 
+[[package]]
+name = "writeable"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+ "synstructure",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+ "synstructure",
+]
+
+[[package]]
+name = "zerotrie"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
 [[package]]
 name = "zmij"
 version = "1.0.23"

Cargo.toml

@@ -1,16 +1,3 @@
 [workspace]
-members = [
+members = ["crates/*"]
-    ".",
-    "crates/wip-interface",
-    "crates/wip-interface-macros",
-    "crates/wip-protocol",
-]
 resolver = "3"
-
-[package]
-name = "wip-rs"
-version = "0.1.0"
-edition = "2024"
-
-[dependencies]
-wip-protocol = { path = "crates/wip-protocol" }

README.md

@@ -2,6 +2,89 @@
 
 Rust building blocks for the Web Interface Protocol (WIP).
 
+The repository is a resolver-3 virtual Cargo workspace whose packages all live
+under `crates/*`. It provides a transport-independent protocol model, the
+standard framework-independent WIP over HTTPS v1 binding, a stateful
+presentation-independent client runtime, 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.
+## Crate graph and responsibilities
+
+```text
+wip-public-api-example (workspace-only executable, integration tests, doctest)
+├── wip-protocol              logical declarations, values, calls, and validation
+├── wip-https                 standard HTTPS v1 routes, JSON codecs, envelopes, and batching
+│   └── wip-protocol
+├── wip-client                stateful Known Space, lazy tree, observation, and call runtime
+│   ├── wip-https
+│   └── wip-protocol
+├── wip-interface             application DTO codecs and interface authoring facade
+│   ├── wip-protocol
+│   └── wip-interface-macros  proc-macro implementation detail
+└── wip-host                  descriptor registry, publication, and qualified dispatch
+    ├── wip-interface
+    └── wip-protocol
+```
+
+| Crate | Responsibility | Does not own |
+| --- | --- | --- |
+| `wip-protocol` | Transport-independent descriptors, object/call/result types, logical `Value`s, validation, and stable protocol error categories. | Application DTOs, implementations, persistence, or wire encoding. |
+| `wip-https` | Standard HTTPS v1 endpoint/route derivation, UTF-8 JSON codecs, direct success bodies, error/status classification, and retrieval batches. | HTTP I/O, TLS termination, authentication schemes, server frameworks, filesystem projection, or client presentation/cache policy. |
+| `wip-client` | Endpoint/security-context-isolated Known Space, normalized object and interface observations, lazy entry trees, immutable operation call contexts, stale transitions, and bounded histories. | HTTP I/O, credentials, persistent cache, automatic operation retries, or presentation widgets/events. |
+| `wip-interface` | The public `WipType`/`interface` authoring API, Rust-to-protocol codecs, generated descriptors, and typed implementation dispatch. | Object publication, backend lifetime, or transport policy. |
+| `wip-interface-macros` | Procedural-macro expansion used by `wip-interface`. It is not an application dependency. | A supported direct user API. |
+| `wip-host` | Opaque interface registration, explicit object membership, validator checks, and interface-qualified dispatch against one host-owned instance. | Backend atomicity, global object lookup, or network serving. |
+| `wip-public-api-example` | An independently compiled consumer of the protocol, authoring, and host public crates. Its DTOs and traits are application-owned; its implementation and backend handle remain host-private. | Reusable library API or a production server. |
+
+The boundary is intentional: protocol types describe what can cross a
+transport; application DTOs opt into that model with `WipType`; a host-private
+implementation owns credentials, handles, and backend state; and `wip-https`
+maps standard routes/envelopes to `CallOperationRequest` and
+`CallOperationResponse` without placing transport-specific types in descriptors
+or application traits.
+
+## End-to-end example
+
+[`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, 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 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. 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:
+
+```console
+nix develop
+cargo run --package wip-public-api-example
+```
+
+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
 
 Applications depend on `wip-interface`, normally imported as `wip`:
@@ -30,38 +113,152 @@ pub trait Messenger {
 ```
 
 The `interface` attribute and `WipType` derive are re-exported by the facade;
-users do not import `wip-interface-macros` directly. The generated
+users do not import `wip-interface-macros` or generated private support symbols.
-`MessengerDefinition` constructs an `InterfaceDescriptor`, decodes named
+The generated `MessengerDefinition` constructs an `InterfaceDescriptor`,
-arguments, encodes results, validates both boundaries, and provides typed
+decodes named arguments, encodes results, validates both boundaries, and
-dispatch for any `T: Messenger`.
+provides typed dispatch for any `T: Messenger`.
 
-### Type mapping
+### Supported Rust syntax
+
+A supported interface is a public, non-generic trait containing methods with:
+
+- exactly an immutable `&self` receiver;
+- simple named, owned parameters;
+- an explicit `wip::OperationResult<T>` return;
+- `()` only as the application return when no value is produced; and
+- direct `Option<T>` only for an omittable parameter.
+
+`WipType` derives support named-field structs, all-unit enums, and unions whose
+cases may be unit variants or variants containing exactly one unnamed payload.
+The macros reject private,
+generic, inherited, unsafe, auto, or associated-item traits; const, async,
+unsafe, extern, variadic, generic, default-bodied, or non-`&self` methods;
+borrowed/custom-lifetime values; tuple/unit/generic structs; Rust unions;
+named-field/multi-field enum variants; explicit discriminants; nested `Option`; and
+`Option` in returns, collections, entries, or union payloads. These diagnostics
+are compile-fail tested under `crates/wip-interface/tests/ui`.
+
+### Rust type mapping
 
 | Rust | Protocol |
 | --- | --- |
-| `()` as an operation result | no returned value |
+| `()` | unit / `Value::Unit` |
 | `bool` | boolean |
 | integer primitives | JavaScript-lossless integer |
 | `f32`, `f64` | finite number |
 | `String` | string |
 | `wip::Bytes` | bytes |
-| `wip::wip_protocol::JsonValue` | JSON |
+| `wip::JsonValue` | JSON interpreted over the schema-neutral `Value` tree |
-| `wip::Entry<K, V>` | entry |
+| `wip::Entry` | canonical absolute Worldspace path encoded as a string |
 | `Vec<T>` | list |
 | named-field `#[derive(wip::WipType)]` struct | named record |
-| all-unit `#[derive(wip::WipType)]` enum | named enum |
+| all-unit `#[derive(wip::WipType)]` enum | named enum encoded as a string |
-| all-newtype `#[derive(wip::WipType)]` enum | named tagged union |
+| mixed unit/newtype or all-newtype enum | named union encoded as a discriminator record |
 
-`Option<T>` is accepted only for a direct DTO field or operation parameter and
+`Option<T>` means that a direct DTO field or operation parameter may be
-means that the named value may be omitted. It is not protocol null. Domain
+omitted; it is not protocol null. JSON null remains available inside
-failures are modeled in the application result (usually a derived union) and
+`wip::JsonValue`.
-returned through `Ok`; `wip::HostError` is only for host/runtime failures.
+
+#### Migration from the pre-canonical value API
+
+The old generic `wip::Entry<K, V>` represented an application key/value pair
+and is no longer available. Use `wip::Entry::new("/canonical/path")` for a
+Worldspace entry path and place any associated application data in a record.
+`Entry` encodes as `Value::String` and validates the canonical absolute path.
+
+The semantic `Value::Json`, `Value::Entry`, `Value::Enum`, and `Value::Union`
+variants have also been removed. JSON recursively uses `Unit`, primitive,
+`List`, and `Record` values and rejects `Bytes`; enums use `String`; unions use
+a `Record` containing `$case` and, for payload-bearing cases, `value`. Unit
+operation results are represented explicitly as `Value::Unit`.
 
 Rust doc comments become descriptor metadata. For an operation, a `# Returns`
 section documents the return declaration; text before that section documents
 the operation itself.
 
-The supported interface slice is deliberately non-generic: public traits,
+## Host publication and dispatch
-`&self`, named parameters, and `OperationResult<T>`. Generic traits or methods,
+
-associated items, custom lifetimes, inheritance, default method bodies, and
+Applications use `wip-host` to register generated definitions and explicitly
-other receiver forms are rejected at their source spans.
+choose the ordered interface set for each object publication:
+
+```rust,ignore
+let mut interfaces = wip_host::InterfaceRegistry::new();
+let messenger = interfaces.register(MessengerDefinition, None)?;
+
+let published = wip_host::PublishedObject::new(request_scoped_object)
+    .expose(&messenger)?;
+let protocol_object = published.protocol_object();
+```
+
+`expose` compiles only when the object implements the generated definition's
+interface trait. Implementing a trait does not expose it automatically, empty
+interface sets are valid, insertion order is preserved, and duplicate
+references are rejected. Registry references are opaque and remain outside the
+descriptor; generated descriptors contain neither those references nor Rust
+trait identity.
+
+Dispatch is qualified by interface reference and operation name and targets a
+canonical Worldspace path. An `ObjectProvider` validates that path before
+resolution, maps malformed paths to `InvalidRequest`, then resolves a valid path
+exactly once inside `with_object`; the host checks the supplied object validator,
+current interface membership, interface validator, descriptor operation,
+operation-specific object-validator policy, arguments, and authorization in
+canonical precedence. Path and children remain provider resolution context and
+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. 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.
+
+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
+
+Enter the dev shell and run the acceptance commands exactly:
+
+```console
+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-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-client/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "wip-client"
+version = "0.1.0"
+edition = "2024"
+description = "Presentation-independent stateful WIP client runtime"
+license = "MIT OR Apache-2.0"
+
+[dependencies]
+wip-https = { path = "../wip-https" }
+wip-protocol = { path = "../wip-protocol" }

crates/wip-client/tests/adapter.rs

@@ -0,0 +1,247 @@
+use std::collections::BTreeMap;
+
+use wip_client::{
+    CallOutcome, Client, ClientErrorKind, ClientLimits, Completion, DiagnosticKind,
+    ObservationState, OutcomeUnknownReason, SecurityContext,
+};
+use wip_https::http::{Response, StatusCode};
+use wip_https::{
+    Limits, encode_fetch_interface_response, encode_fetch_response, encode_protocol_error_response,
+};
+use wip_protocol::{
+    FetchInterfaceRequest, FetchInterfaceResponse, FetchRequest, INTERFACE_FORMAT_V1,
+    InterfaceDescriptor, Object, OperationDeclaration, ParameterDeclaration, ProtocolError,
+    ProtocolErrorCode, ProtocolInteraction, ReturnDeclaration, TypeExpr, Value,
+};
+
+fn limits() -> Limits {
+    Limits::new(64 * 1024, 64 * 1024, 64, 64).unwrap()
+}
+
+fn setup() -> (Client, wip_client::SessionId) {
+    let mut client = Client::new(ClientLimits::new(2, 16, 16, 16, 16).unwrap(), limits());
+    let session = client
+        .open_session("https://example.test/wip", SecurityContext::new("subject"))
+        .unwrap();
+    (client, session)
+}
+
+fn response(status: StatusCode, body: &[u8]) -> Response<Vec<u8>> {
+    Response::builder()
+        .status(status)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(body.to_vec())
+        .unwrap()
+}
+
+fn object() -> Object {
+    Object {
+        name: "item".into(),
+        description: None,
+        interfaces: vec!["math".into()],
+        r#ref: None,
+        validator: Some(b"object-v1".to_vec()),
+    }
+}
+
+fn descriptor(format: &str) -> InterfaceDescriptor {
+    InterfaceDescriptor {
+        format: format.into(),
+        documentation: None,
+        types: vec![],
+        operations: vec![OperationDeclaration {
+            name: "calculate".into(),
+            documentation: None,
+            parameters: vec![ParameterDeclaration {
+                name: "value".into(),
+                required: true,
+                documentation: None,
+                r#type: TypeExpr::Integer,
+            }],
+            returns: ReturnDeclaration {
+                documentation: None,
+                r#type: TypeExpr::Integer,
+            },
+        }],
+    }
+}
+
+#[test]
+fn malformed_json_unknown_fields_duplicates_and_invalid_success_are_invalid_response() {
+    let cases: &[&[u8]] = &[
+        b"{not json",
+        br#"{"name":"item","interfaces":[],"unknown":true}"#,
+        br#"{"name":"item","interfaces":["math","math"]}"#,
+        br#"{"name":"wrong","interfaces":[]}"#,
+    ];
+    for body in cases {
+        let (mut client, session) = setup();
+        let request = client.prepare_fetch(&session, "/item").unwrap();
+        let error = client
+            .complete(request.id, response(StatusCode::OK, body))
+            .unwrap_err();
+        assert_eq!(error.kind, ClientErrorKind::InvalidResponse);
+        assert!(matches!(
+            client.object(&session, "/item").unwrap().state,
+            ObservationState::Error(_)
+        ));
+    }
+}
+
+#[test]
+fn disallowed_code_and_status_success_contradictions_are_invalid_response() {
+    let cases = [
+        (
+            StatusCode::NOT_FOUND,
+            br#"{"error":{"code":"interface_not_found","message":"wrong"}}"#.as_slice(),
+        ),
+        (
+            StatusCode::OK,
+            br#"{"error":{"code":"not_found","message":"wrong status"}}"#.as_slice(),
+        ),
+        (
+            StatusCode::CREATED,
+            br#"{"name":"item","interfaces":[]}"#.as_slice(),
+        ),
+    ];
+    for (status, body) in cases {
+        let (mut client, session) = setup();
+        let request = client.prepare_fetch(&session, "/item").unwrap();
+        assert_eq!(
+            client
+                .complete(request.id, response(status, body))
+                .unwrap_err()
+                .kind,
+            ClientErrorKind::InvalidResponse
+        );
+    }
+}
+
+#[test]
+fn valid_error_envelope_is_authoritative_and_status_mismatch_is_diagnostic() {
+    let (mut client, session) = setup();
+    let request = client.prepare_fetch(&session, "/item").unwrap();
+    let error = ProtocolError {
+        code: ProtocolErrorCode::NotFound,
+        message: "missing".into(),
+    };
+    let mut encoded =
+        encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
+    *encoded.status_mut() = StatusCode::IM_A_TEAPOT;
+
+    assert_eq!(
+        client.complete(request.id, encoded).unwrap(),
+        Completion::ProtocolFailure(error)
+    );
+    assert_eq!(
+        client.object(&session, "/item").unwrap().state,
+        ObservationState::Stale
+    );
+    assert_eq!(
+        client.diagnostics(&session).unwrap().back().unwrap().kind,
+        DiagnosticKind::HttpStatusMismatch
+    );
+}
+
+#[test]
+fn non_success_without_valid_envelope_remains_transport_failure() {
+    let (mut client, session) = setup();
+    let request = client.prepare_fetch(&session, "/item").unwrap();
+    let error = client
+        .complete(
+            request.id,
+            response(StatusCode::BAD_GATEWAY, b"gateway html"),
+        )
+        .unwrap_err();
+    assert_eq!(error.kind, ClientErrorKind::Transport);
+}
+
+#[test]
+fn unsupported_descriptor_format_is_distinct_from_invalid_response() {
+    let (mut client, session) = setup();
+    let request = client.prepare_interface(&session, "math").unwrap();
+    let logical = FetchInterfaceRequest {
+        interface: "math".into(),
+    };
+    let value = FetchInterfaceResponse {
+        interface: "math".into(),
+        descriptor: descriptor("future-format/2"),
+        validator: Some(b"v2".to_vec()),
+    };
+    let encoded = encode_fetch_interface_response(&logical, &value, limits()).unwrap();
+    let error = client.complete(request.id, encoded).unwrap_err();
+    assert_eq!(error.kind, ClientErrorKind::UnsupportedDescriptorFormat);
+}
+
+#[test]
+fn malformed_call_success_after_dispatch_is_outcome_unknown_and_stales_object() {
+    let (mut client, session) = setup();
+    let fetch = client.prepare_fetch(&session, "/item").unwrap();
+    client
+        .complete(
+            fetch.id,
+            encode_fetch_response(
+                &FetchRequest {
+                    path: "/item".into(),
+                },
+                &object(),
+                limits(),
+            )
+            .unwrap(),
+        )
+        .unwrap();
+    let interface = client.prepare_interface(&session, "math").unwrap();
+    client
+        .complete(
+            interface.id,
+            encode_fetch_interface_response(
+                &FetchInterfaceRequest {
+                    interface: "math".into(),
+                },
+                &FetchInterfaceResponse {
+                    interface: "math".into(),
+                    descriptor: descriptor(INTERFACE_FORMAT_V1),
+                    validator: None,
+                },
+                limits(),
+            )
+            .unwrap(),
+        )
+        .unwrap();
+    let call = client
+        .prepare_call(
+            &session,
+            "/item",
+            "math",
+            "calculate",
+            BTreeMap::from([("value".into(), Value::Integer(2))]),
+        )
+        .unwrap();
+    client.mark_dispatched(call.id).unwrap();
+
+    let completion = client
+        .complete(
+            call.id,
+            response(
+                StatusCode::OK,
+                br#"{"result":"not an integer","unknown":true}"#,
+            ),
+        )
+        .unwrap();
+    assert!(matches!(
+        completion,
+        Completion::Call(record)
+            if matches!(
+                &record.outcome,
+                CallOutcome::Unknown {
+                    reason: OutcomeUnknownReason::ResponseDecode,
+                    failure: Some(failure),
+                } if failure.kind == ClientErrorKind::InvalidResponse
+            )
+    ));
+    assert_eq!(
+        client.object(&session, "/item").unwrap().state,
+        ObservationState::Stale
+    );
+    assert_eq!(client.in_flight_len(), 0);
+}

crates/wip-host/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "wip-host"
+version = "0.1.0"
+edition = "2024"
+description = "Host-side object publication and operation dispatch for WIP"
+license = "MIT OR Apache-2.0"
+
+[dependencies]
+wip-interface = { path = "../wip-interface" }
+wip-protocol = { path = "../wip-protocol" }
+
+[dev-dependencies]
+trybuild = "1"

crates/wip-host/tests/compile_fail.rs

@@ -0,0 +1,5 @@
+#[test]
+fn rejects_exposing_an_unimplemented_interface() {
+    let tests = trybuild::TestCases::new();
+    tests.compile_fail("tests/ui/unimplemented_interface.rs");
+}

crates/wip-host/tests/host.rs

@@ -0,0 +1,985 @@
+use std::cell::Cell;
+use std::collections::BTreeMap;
+use std::rc::Rc;
+use std::time::{Duration, Instant};
+
+use wip_host::{
+    CallError, CallErrorKind, CallRequest, CancellationToken, ExecutionContext, InterfaceRef,
+    InterfaceRegistry, InterfaceTarget, ObjectProvider, OperationAttempt, ProviderResult,
+    PublishedObject, RegisteredInterface, Target, Validator, WipObject,
+};
+use wip_interface::{
+    CodecError, EffectGuarantee, HostError, OperationResult, TypeDeclaration, TypeExpr, Value,
+    WipType, interface,
+};
+use wip_protocol::ProtocolErrorCode;
+
+#[interface]
+pub trait Reader {
+    /// Returns the reader-qualified label.
+    fn label(&self) -> OperationResult<String>;
+
+    /// Adds two integers.
+    fn add(&self, left: i64, right: i64) -> OperationResult<i64>;
+
+    /// Reports a backend failure.
+    fn fail(&self) -> OperationResult<String>;
+}
+
+#[interface]
+pub trait Writer {
+    /// Returns the writer-qualified label.
+    fn label(&self) -> OperationResult<String>;
+}
+
+#[interface]
+pub trait Hidden {
+    /// Returns a hidden value.
+    fn hidden(&self) -> OperationResult<String>;
+}
+
+#[interface]
+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)]
+pub struct BadValue;
+
+impl WipType for BadValue {
+    fn type_expr() -> TypeExpr {
+        TypeExpr::Integer
+    }
+
+    fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
+
+    fn encode(self) -> Result<Value, CodecError> {
+        Ok(Value::String("not an integer".into()))
+    }
+
+    fn decode(_: Value) -> Result<Self, CodecError> {
+        Ok(Self)
+    }
+}
+
+#[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>,
+    reference: Option<String>,
+    validator: Option<Validator>,
+    require_validator: bool,
+    calls: Rc<Cell<usize>>,
+    private_backend_handle: String,
+}
+
+impl Document {
+    fn open(name: &str, reference: Option<&str>, calls: Rc<Cell<usize>>) -> Self {
+        Self {
+            name: name.into(),
+            description: Some("public document".into()),
+            reference: reference.map(str::to_owned),
+            validator: None,
+            require_validator: false,
+            calls,
+            private_backend_handle: "/private/backend/path".into(),
+        }
+    }
+
+    fn strict(name: &str, reference: &str, validator: &[u8], calls: Rc<Cell<usize>>) -> Self {
+        Self {
+            name: name.into(),
+            description: Some("public document".into()),
+            reference: Some(reference.into()),
+            validator: Some(Validator::new(validator)),
+            require_validator: true,
+            calls,
+            private_backend_handle: "secret-handle".into(),
+        }
+    }
+
+    fn record_call(&self) {
+        self.calls.set(self.calls.get() + 1);
+    }
+}
+
+impl WipObject for Document {
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn description(&self) -> Option<&str> {
+        self.description.as_deref()
+    }
+
+    fn reference(&self) -> Option<&str> {
+        self.reference.as_deref()
+    }
+
+    fn validator(&self) -> Option<&Validator> {
+        self.validator.as_ref()
+    }
+
+    fn requires_validator(&self, _: &InterfaceRef, _: &str) -> bool {
+        self.require_validator
+    }
+}
+
+impl Reader for Document {
+    fn label(&self) -> OperationResult<String> {
+        self.record_call();
+        Ok("reader".into())
+    }
+
+    fn add(&self, left: i64, right: i64) -> OperationResult<i64> {
+        self.record_call();
+        Ok(left + right)
+    }
+
+    fn fail(&self) -> OperationResult<String> {
+        self.record_call();
+        Err(HostError::internal(
+            "backend unavailable",
+            EffectGuarantee::Unknown,
+        ))
+    }
+}
+
+impl Writer for Document {
+    fn label(&self) -> OperationResult<String> {
+        self.record_call();
+        Ok("writer".into())
+    }
+}
+
+impl Hidden for Document {
+    fn hidden(&self) -> OperationResult<String> {
+        self.record_call();
+        Ok("hidden".into())
+    }
+}
+
+impl Broken for Document {
+    fn broken(&self) -> OperationResult<BadValue> {
+        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 {
+    reader: RegisteredInterface<ReaderDefinition>,
+    writer: RegisteredInterface<WriterDefinition>,
+    broken: RegisteredInterface<BrokenDefinition>,
+    calls: Rc<Cell<usize>>,
+    resolutions: Cell<usize>,
+    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 {
+    fn new(
+        reader: RegisteredInterface<ReaderDefinition>,
+        writer: RegisteredInterface<WriterDefinition>,
+        broken: RegisteredInterface<BrokenDefinition>,
+    ) -> Self {
+        Self {
+            reader,
+            writer,
+            broken,
+            calls: Rc::new(Cell::new(0)),
+            resolutions: Cell::new(0),
+            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),
+        }
+    }
+}
+
+impl ObjectProvider for TestProvider {
+    type Object = Document;
+
+    fn with_object<R>(
+        &self,
+        context: &ExecutionContext,
+        path: &str,
+        operation: impl FnOnce(&PublishedObject<Self::Object>) -> 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" => (
+                Document::strict(
+                    "document",
+                    "document-ref",
+                    b"object-v1",
+                    Rc::clone(&self.calls),
+                ),
+                2,
+            ),
+            "/open" => (
+                Document::open("open", Some("open-ref"), Rc::clone(&self.calls)),
+                2,
+            ),
+            "/left/document" | "/right/document" => (
+                Document::strict(
+                    "document",
+                    "shared-ref",
+                    b"shared-v1",
+                    Rc::clone(&self.calls),
+                ),
+                2,
+            ),
+            "/switch" => {
+                let switched = self.switched.replace(true);
+                let (reference, validator) = if switched {
+                    ("second-ref", b"second".as_slice())
+                } else {
+                    ("first-ref", b"first".as_slice())
+                };
+                (
+                    Document::strict("switch", reference, validator, Rc::clone(&self.calls)),
+                    2,
+                )
+            }
+            "/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 ProviderResult::NotFound,
+        };
+
+        let publication = PublishedObject::new(document);
+        let publication = match interfaces {
+            0 => publication,
+            2 => publication
+                .expose(&self.writer)
+                .unwrap()
+                .expose(&self.reader)
+                .unwrap(),
+            3 => publication.expose(&self.broken).unwrap(),
+            _ => unreachable!(),
+        };
+        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 {
+        self.authorization_checks
+            .set(self.authorization_checks.get() + 1);
+        !self.deny.get()
+    }
+}
+
+fn registry_and_provider() -> (
+    InterfaceRegistry,
+    TestProvider,
+    RegisteredInterface<HiddenDefinition>,
+) {
+    let mut registry = InterfaceRegistry::new();
+    let reader = registry
+        .register(ReaderDefinition, Some(Validator::new(b"schema-v1")))
+        .unwrap();
+    let writer = registry.register(WriterDefinition, None).unwrap();
+    let hidden = registry.register(HiddenDefinition, None).unwrap();
+    let broken = registry.register(BrokenDefinition, None).unwrap();
+    let provider = TestProvider::new(reader, writer, broken);
+    (registry, provider, hidden)
+}
+
+fn request(
+    path: &str,
+    object_validator: Option<&[u8]>,
+    reference: &InterfaceRef,
+    interface_validator: Option<&[u8]>,
+    operation: &str,
+    arguments: BTreeMap<String, Value>,
+) -> CallRequest {
+    CallRequest {
+        target: Target {
+            path: path.into(),
+            validator: object_validator.map(<[u8]>::to_vec),
+        },
+        interface: InterfaceTarget {
+            reference: reference.as_str().to_owned(),
+            validator: interface_validator.map(<[u8]>::to_vec),
+        },
+        operation: operation.into(),
+        arguments,
+    }
+}
+
+fn assert_failure(error: CallError, kind: CallErrorKind, code: ProtocolErrorCode) {
+    assert_eq!(error.kind(), kind);
+    assert_eq!(error.protocol_error().code, code);
+}
+
+#[test]
+fn registry_returns_atomic_canonical_observation_without_rewriting_descriptor() {
+    let (registry, provider, _) = registry_and_provider();
+    let reference = provider.reader.reference();
+
+    assert_ne!(reference.as_str(), "Reader");
+    let observation = registry.fetch_interface(reference.as_str()).unwrap();
+    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().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);
+}
+
+#[test]
+fn canonical_object_projection_supports_optional_metadata_and_ordered_sets() {
+    let (_, provider, _) = registry_and_provider();
+    let object = provider.fetch("/document").unwrap();
+
+    assert_eq!(object.name, "document");
+    assert_eq!(object.description.as_deref(), Some("public document"));
+    assert_eq!(object.r#ref.as_deref(), Some("document-ref"));
+    assert_eq!(object.validator.as_deref(), Some(b"object-v1".as_slice()));
+    assert_eq!(
+        object.interfaces,
+        vec![
+            provider.writer.reference().as_str().to_owned(),
+            provider.reader.reference().as_str().to_owned(),
+        ]
+    );
+    assert!(!format!("{object:?}").contains("secret-handle"));
+    assert!(!format!("{object:?}").contains("/document"));
+
+    let empty = provider.fetch("/empty").unwrap();
+    assert!(empty.interfaces.is_empty());
+    assert_eq!(empty.r#ref, None);
+    assert_eq!(empty.validator, None);
+}
+
+#[test]
+fn duplicate_exposure_is_rejected_and_private_state_is_not_projected() {
+    let (_, provider, _) = registry_and_provider();
+    let publication = PublishedObject::new(Document::open(
+        "duplicate",
+        None,
+        Rc::clone(&provider.calls),
+    ))
+    .expose(&provider.reader)
+    .unwrap();
+    assert_eq!(
+        publication.implementation().private_backend_handle,
+        "/private/backend/path"
+    );
+    let error = match publication.expose(&provider.reader) {
+        Ok(_) => panic!("duplicate exposure unexpectedly succeeded"),
+        Err(error) => error,
+    };
+    assert!(
+        error
+            .to_string()
+            .contains(provider.reader.reference().as_str())
+    );
+}
+
+#[test]
+fn paths_are_resolution_context_not_object_identity() {
+    let (_, provider, _) = registry_and_provider();
+
+    let left = provider.fetch("/left/document").unwrap();
+    let right = provider.fetch("/right/document").unwrap();
+    assert_eq!(left, right);
+    assert_eq!(left.r#ref.as_deref(), Some("shared-ref"));
+
+    let first = provider.fetch("/switch").unwrap();
+    let second = provider.fetch("/switch").unwrap();
+    assert_ne!(first.r#ref, second.r#ref);
+    assert_ne!(first.validator, second.validator);
+}
+
+#[test]
+fn path_dispatch_is_interface_qualified_and_resolves_once_per_call() {
+    let (_, provider, _) = registry_and_provider();
+    let before = provider.resolutions.get();
+
+    let writer = provider
+        .call_operation(request(
+            "/open",
+            None,
+            provider.writer.reference(),
+            None,
+            "label",
+            BTreeMap::new(),
+        ))
+        .unwrap();
+    let reader = provider
+        .call_operation(request(
+            "/open",
+            None,
+            provider.reader.reference(),
+            Some(b"schema-v1"),
+            "label",
+            BTreeMap::new(),
+        ))
+        .unwrap();
+
+    let strict = provider
+        .call_operation(request(
+            "/document",
+            Some(b"object-v1"),
+            provider.reader.reference(),
+            Some(b"schema-v1"),
+            "label",
+            BTreeMap::new(),
+        ))
+        .unwrap();
+
+    assert_eq!(writer.result, Value::String("writer".into()));
+    assert_eq!(reader.result, Value::String("reader".into()));
+    assert_eq!(strict.result, Value::String("reader".into()));
+    assert_eq!(strict.validator.as_deref(), Some(b"object-v1".as_slice()));
+    assert_eq!(provider.resolutions.get() - before, 3);
+    assert_eq!(provider.calls.get(), 3);
+}
+
+#[test]
+fn call_failures_follow_canonical_precedence_without_execution() {
+    let (_, provider, hidden) = registry_and_provider();
+
+    let resolutions = provider.resolutions.get();
+    for invalid_path in [
+        "relative",
+        "/trailing/",
+        "/double//segment",
+        "/dot/./segment",
+        "/parent/../segment",
+    ] {
+        assert_failure(
+            provider
+                .call_operation(request(
+                    invalid_path,
+                    Some(b"stale"),
+                    hidden.reference(),
+                    Some(b"stale"),
+                    "missing",
+                    BTreeMap::new(),
+                ))
+                .unwrap_err(),
+            CallErrorKind::InvalidRequest,
+            ProtocolErrorCode::InvalidRequest,
+        );
+    }
+    assert_eq!(provider.resolutions.get(), resolutions);
+    assert_failure(
+        provider.fetch("/invalid/").unwrap_err(),
+        CallErrorKind::InvalidRequest,
+        ProtocolErrorCode::InvalidRequest,
+    );
+    assert_eq!(provider.resolutions.get(), resolutions);
+
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/missing",
+                Some(b"stale"),
+                hidden.reference(),
+                Some(b"stale"),
+                "missing",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::NotFound,
+        ProtocolErrorCode::NotFound,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                Some(b"stale"),
+                hidden.reference(),
+                None,
+                "missing",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::ValidatorMismatch,
+        ProtocolErrorCode::ValidatorMismatch,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                Some(b"object-v1"),
+                hidden.reference(),
+                None,
+                "hidden",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::InterfaceMismatch,
+        ProtocolErrorCode::InterfaceMismatch,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                Some(b"object-v1"),
+                provider.reader.reference(),
+                None,
+                "missing",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::InterfaceValidatorRequired,
+        ProtocolErrorCode::InterfaceValidatorRequired,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                Some(b"object-v1"),
+                provider.reader.reference(),
+                Some(b"stale-schema"),
+                "missing",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::InterfaceValidatorMismatch,
+        ProtocolErrorCode::InterfaceValidatorMismatch,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                None,
+                provider.reader.reference(),
+                Some(b"schema-v1"),
+                "missing",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::OperationNotFound,
+        ProtocolErrorCode::OperationNotFound,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                None,
+                provider.reader.reference(),
+                Some(b"schema-v1"),
+                "add",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::ValidatorRequired,
+        ProtocolErrorCode::ValidatorRequired,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                Some(b"object-v1"),
+                provider.reader.reference(),
+                Some(b"schema-v1"),
+                "add",
+                BTreeMap::from([("left".into(), Value::String("wrong".into()))]),
+            ))
+            .unwrap_err(),
+        CallErrorKind::InvalidArguments,
+        ProtocolErrorCode::InvalidArguments,
+    );
+
+    provider.deny.set(true);
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/document",
+                Some(b"object-v1"),
+                provider.reader.reference(),
+                Some(b"schema-v1"),
+                "label",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::PermissionDenied,
+        ProtocolErrorCode::PermissionDenied,
+    );
+    assert_eq!(provider.authorization_checks.get(), 1);
+    assert_eq!(provider.calls.get(), 0);
+}
+
+#[test]
+fn immutable_interface_rejects_a_supplied_validator() {
+    let (_, provider, _) = registry_and_provider();
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/open",
+                None,
+                provider.writer.reference(),
+                Some(b"unexpected"),
+                "label",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::InterfaceValidatorMismatch,
+        ProtocolErrorCode::InterfaceValidatorMismatch,
+    );
+    assert_eq!(provider.calls.get(), 0);
+}
+
+#[test]
+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(
+                "/broken",
+                None,
+                provider.broken.reference(),
+                None,
+                "broken",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        CallErrorKind::OperationOutcomeUnknown,
+        ProtocolErrorCode::OperationOutcomeUnknown,
+    );
+    assert_failure(
+        provider
+            .call_operation(request(
+                "/open",
+                None,
+                provider.reader.reference(),
+                Some(b"schema-v1"),
+                "fail",
+                BTreeMap::new(),
+            ))
+            .unwrap_err(),
+        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-host/tests/ui/unimplemented_interface.rs

@@ -0,0 +1,21 @@
+use wip_host::{InterfaceRegistry, PublishedObject, WipObject};
+use wip_interface::{OperationResult, interface};
+
+#[interface]
+pub trait Search {
+    fn search(&self) -> OperationResult<String>;
+}
+
+struct Object;
+
+impl WipObject for Object {
+    fn name(&self) -> &str {
+        "object"
+    }
+}
+
+fn main() {
+    let mut registry = InterfaceRegistry::new();
+    let search = registry.register(SearchDefinition, None).unwrap();
+    let _published = PublishedObject::new(Object).expose(&search).unwrap();
+}

crates/wip-host/tests/ui/unimplemented_interface.stderr

@@ -0,0 +1,34 @@
+error[E0277]: the trait bound `Object: Search` is not satisfied
+  --> tests/ui/unimplemented_interface.rs:20:58
+   |
+20 |     let _published = PublishedObject::new(Object).expose(&search).unwrap();
+   |                                                   ------ ^^^^^^^ unsatisfied trait bound
+   |                                                   |
+   |                                                   required by a bound introduced by this call
+   |
+help: the trait `Search` is not implemented for `Object`
+  --> tests/ui/unimplemented_interface.rs:9:1
+   |
+ 9 | struct Object;
+   | ^^^^^^^^^^^^^
+help: this trait has no implementations, consider adding one
+  --> tests/ui/unimplemented_interface.rs:5:1
+   |
+ 5 | pub trait Search {
+   | ^^^^^^^^^^^^^^^^
+note: required for `SearchDefinition` to implement `InterfaceImplementation<Object>`
+  --> tests/ui/unimplemented_interface.rs:4:1
+   |
+ 4 | #[interface]
+   | ^^^^^^^^^^^^
+ 5 | pub trait Search {
+   |           ^^^^^^
+note: required by a bound in `PublishedObject::<T>::expose`
+  --> src/lib.rs
+   |
+   |     pub fn expose<D>(mut self, interface: &RegisteredInterface<D>) -> Result<Self, PublicationError>
+   |            ------ required by a bound in this associated function
+   |     where
+   |         D: InterfaceImplementation<T>,
+   |            ^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `PublishedObject::<T>::expose`
+   = note: this error originates in the attribute macro `interface` (in Nightly builds, run with -Z macro-backtrace for more info)

crates/wip-https/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "wip-https"
+version = "0.1.0"
+edition = "2024"
+description = "Framework-independent standard WIP over HTTPS v1 binding"
+license = "MIT OR Apache-2.0"
+
+[dependencies]
+base64 = "0.22"
+http = "1"
+serde = "1"
+serde_json = "1"
+url = "2"
+wip-protocol = { path = "../wip-protocol" }

crates/wip-https/src/batch.rs

@@ -0,0 +1,596 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use http::header::{ACCEPT, CONTENT_TYPE};
+use http::{Method, Request, Response, StatusCode};
+use serde_json::{Map, Value as Json};
+use wip_protocol::{
+    FetchInterfaceRequest, FetchInterfaceResponse, FetchRequest, FetchResponse, FetchTreeRequest,
+    FetchTreeResponse, INTERFACE_FORMAT_V1, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
+};
+
+use crate::response::{self, DecodedResponse};
+use crate::{
+    BodyKind, ClientResponseError, CodecError, EncodeHttpError, Endpoint, InvalidResponseKind,
+    JSON_CONTENT_TYPE, Limits, ResourceLimitKind, Route, is_json_content_type, json,
+};
+
+/// A retrieval method accepted by the standard v1 batch endpoint.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BatchMethod {
+    /// Fetch one object.
+    Fetch,
+    /// Fetch one bounded tree.
+    FetchTree,
+    /// Fetch one interface descriptor.
+    FetchInterface,
+}
+
+impl BatchMethod {
+    fn name(self) -> &'static str {
+        match self {
+            Self::Fetch => "fetch",
+            Self::FetchTree => "fetch_tree",
+            Self::FetchInterface => "fetch_interface",
+        }
+    }
+
+    fn interaction(self) -> ProtocolInteraction {
+        match self {
+            Self::Fetch => ProtocolInteraction::Fetch,
+            Self::FetchTree => ProtocolInteraction::FetchTree,
+            Self::FetchInterface => ProtocolInteraction::FetchInterface,
+        }
+    }
+}
+
+/// One retrieval interaction accepted by the standard v1 batch endpoint.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BatchRequestKind {
+    /// Fetch one object.
+    Fetch(FetchRequest),
+    /// Fetch one bounded tree.
+    FetchTree(FetchTreeRequest),
+    /// Fetch one interface descriptor.
+    FetchInterface(FetchInterfaceRequest),
+    /// A known method whose `arguments` are not a valid logical request.
+    Invalid {
+        /// Method that was successfully identified from the item envelope.
+        method: BatchMethod,
+        /// Item-local `invalid_request` to return without rejecting other items.
+        error: ProtocolError,
+    },
+}
+
+impl BatchRequestKind {
+    fn interaction(&self) -> ProtocolInteraction {
+        match self {
+            Self::Fetch(_) => ProtocolInteraction::Fetch,
+            Self::FetchTree(_) => ProtocolInteraction::FetchTree,
+            Self::FetchInterface(_) => ProtocolInteraction::FetchInterface,
+            Self::Invalid { method, .. } => method.interaction(),
+        }
+    }
+}
+
+/// One uniquely identified batch subrequest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BatchRequestItem {
+    /// Identifier used only to correlate the corresponding subresponse.
+    pub id: String,
+    /// Retrieval interaction and arguments.
+    pub request: BatchRequestKind,
+}
+
+/// A standard v1 batch request.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BatchRequest {
+    /// Independent subrequests. Identifiers must be unique.
+    pub requests: Vec<BatchRequestItem>,
+}
+
+/// Successful result of one batch item.
+#[derive(Debug, Clone, PartialEq)]
+pub enum BatchSuccess {
+    /// Successful `fetch` result.
+    Fetch(FetchResponse),
+    /// Successful `fetch_tree` result.
+    FetchTree(FetchTreeResponse),
+    /// Successful `fetch_interface` result.
+    FetchInterface(FetchInterfaceResponse),
+}
+
+/// One batch subresponse, correlated by `id` rather than array position.
+#[derive(Debug, Clone, PartialEq)]
+pub struct BatchResponseItem {
+    /// Identifier copied from its subrequest.
+    pub id: String,
+    /// Direct interaction result or canonical item-local protocol failure.
+    pub outcome: Result<BatchSuccess, ProtocolError>,
+}
+
+/// A valid standard v1 batch response.
+#[derive(Debug, Clone, PartialEq)]
+pub struct BatchResponse {
+    /// Exactly one response for each requested identifier, in any order.
+    pub responses: Vec<BatchResponseItem>,
+}
+
+fn validate_ids<'a>(ids: impl Iterator<Item = &'a str>, maximum: usize) -> Result<(), CodecError> {
+    let mut seen = BTreeSet::new();
+    let mut count = 0;
+    for id in ids {
+        count += 1;
+        if !seen.insert(id) {
+            return Err(CodecError::DuplicateBatchId { id: id.into() });
+        }
+    }
+    if count > maximum {
+        return Err(CodecError::TooManyBatchItems {
+            actual: count,
+            maximum,
+        });
+    }
+    Ok(())
+}
+
+fn request_item_to_json(item: &BatchRequestItem) -> Result<Json, CodecError> {
+    let (method, arguments) = match &item.request {
+        BatchRequestKind::Fetch(value) => ("fetch", json::fetch_request_to_json(value)),
+        BatchRequestKind::FetchTree(value) => {
+            ("fetch_tree", json::fetch_tree_request_to_json(value))
+        }
+        BatchRequestKind::FetchInterface(value) => (
+            "fetch_interface",
+            json::fetch_interface_request_to_json(value),
+        ),
+        BatchRequestKind::Invalid { .. } => {
+            return Err(CodecError::InvalidField {
+                field: "requests".into(),
+                reason: "item-local invalid requests cannot be encoded as client requests".into(),
+            });
+        }
+    };
+    Ok(serde_json::json!({"id": item.id, "method": method, "arguments": arguments}))
+}
+
+fn request_to_json(request: &BatchRequest, limits: Limits) -> Result<Json, CodecError> {
+    validate_ids(
+        request.requests.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    for item in &request.requests {
+        match &item.request {
+            BatchRequestKind::Fetch(value) => value.validate()?,
+            BatchRequestKind::FetchTree(value) => value.validate()?,
+            BatchRequestKind::FetchInterface(_) | BatchRequestKind::Invalid { .. } => {}
+        }
+    }
+    let requests = request
+        .requests
+        .iter()
+        .map(request_item_to_json)
+        .collect::<Result<Vec<_>, _>>()?;
+    Ok(serde_json::json!({"requests": requests}))
+}
+
+fn request_from_json(value: &Json, limits: Limits) -> Result<BatchRequest, CodecError> {
+    let fields = exact_object(value, "batch", &["requests"])?;
+    let values = array(required(fields, "requests")?, "requests")?;
+    if values.len() > limits.max_batch_items {
+        return Err(CodecError::TooManyBatchItems {
+            actual: values.len(),
+            maximum: limits.max_batch_items,
+        });
+    }
+    let mut requests = Vec::with_capacity(values.len());
+    for (index, value) in values.iter().enumerate() {
+        let field = format!("requests[{index}]");
+        let fields = exact_object(value, &field, &["id", "method", "arguments"])?;
+        let id = string(required(fields, "id")?, &format!("{field}.id"))?;
+        let method_name = string(required(fields, "method")?, &format!("{field}.method"))?;
+        let arguments = required(fields, "arguments")?;
+        let method = match method_name.as_str() {
+            "fetch" => BatchMethod::Fetch,
+            "fetch_tree" => BatchMethod::FetchTree,
+            "fetch_interface" => BatchMethod::FetchInterface,
+            _ => {
+                return Err(CodecError::InvalidField {
+                    field: format!("{field}.method"),
+                    reason: "batch supports only fetch, fetch_tree, and fetch_interface".into(),
+                });
+            }
+        };
+        let decoded = match method {
+            BatchMethod::Fetch => {
+                json::fetch_request_from_json(arguments).map(BatchRequestKind::Fetch)
+            }
+            BatchMethod::FetchTree => {
+                json::fetch_tree_request_from_json(arguments).map(BatchRequestKind::FetchTree)
+            }
+            BatchMethod::FetchInterface => json::fetch_interface_request_from_json(arguments)
+                .map(BatchRequestKind::FetchInterface),
+        };
+        let request = decoded.unwrap_or_else(|error| BatchRequestKind::Invalid {
+            method,
+            error: ProtocolError {
+                code: ProtocolErrorCode::InvalidRequest,
+                message: format!("invalid {} arguments: {error}", method.name()),
+            },
+        });
+        requests.push(BatchRequestItem { id, request });
+    }
+    validate_ids(
+        requests.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    Ok(BatchRequest { requests })
+}
+
+/// Encodes a batch request using `POST v1/batch`.
+pub fn encode_batch_request(
+    endpoint: &Endpoint,
+    value: &BatchRequest,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    let body = json::serialize(&request_to_json(value, limits)?, BodyKind::Request, limits)?;
+    Ok(Request::builder()
+        .method(Method::POST)
+        .uri(endpoint.route(Route::Batch).as_str())
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .header(ACCEPT, "application/json")
+        .body(body)?)
+}
+
+/// Decodes and validates a batch request body.
+pub fn decode_batch_request(body: &[u8], limits: Limits) -> Result<BatchRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    request_from_json(&value, limits)
+}
+
+fn success_to_json(success: &BatchSuccess) -> Json {
+    match success {
+        BatchSuccess::Fetch(value) => json::object_to_json(value),
+        BatchSuccess::FetchTree(value) => json::fetch_tree_response_to_json(value),
+        BatchSuccess::FetchInterface(value) => json::fetch_interface_response_to_json(value),
+    }
+}
+
+fn response_to_json(
+    request: &BatchRequest,
+    response: &BatchResponse,
+    limits: Limits,
+) -> Result<Json, CodecError> {
+    correlate(request, response, limits)?;
+    Ok(serde_json::json!({
+        "responses": response.responses.iter().map(|item| {
+            let mut fields = Map::new();
+            fields.insert("id".into(), Json::String(item.id.clone()));
+            match &item.outcome {
+                Ok(success) => { fields.insert("result".into(), success_to_json(success)); }
+                Err(error) => { fields.insert("error".into(), response::item_error_to_json(error)); }
+            }
+            Json::Object(fields)
+        }).collect::<Vec<_>>()
+    }))
+}
+
+fn correlate(
+    request: &BatchRequest,
+    response: &BatchResponse,
+    limits: Limits,
+) -> Result<(), CodecError> {
+    validate_ids(
+        request.requests.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    validate_ids(
+        response.responses.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    let requested: BTreeMap<&str, &BatchRequestKind> = request
+        .requests
+        .iter()
+        .map(|item| (item.id.as_str(), &item.request))
+        .collect();
+    for item in &response.responses {
+        let Some(kind) = requested.get(item.id.as_str()) else {
+            return Err(CodecError::UnexpectedBatchId {
+                id: item.id.clone(),
+            });
+        };
+        match (&item.outcome, *kind) {
+            (Ok(BatchSuccess::Fetch(value)), BatchRequestKind::Fetch(request)) => {
+                request.validate_response(value)?;
+            }
+            (Ok(BatchSuccess::FetchTree(value)), BatchRequestKind::FetchTree(request)) => {
+                value.validate_for(request)?;
+            }
+            (
+                Ok(BatchSuccess::FetchInterface(value)),
+                BatchRequestKind::FetchInterface(request),
+            ) => {
+                value.validate_for(request)?;
+            }
+            (
+                Err(error),
+                BatchRequestKind::Invalid {
+                    error: expected, ..
+                },
+            ) if error == expected => {}
+            (Err(error), kind)
+                if !matches!(kind, BatchRequestKind::Invalid { .. })
+                    && error.code.is_allowed_for(kind.interaction()) => {}
+            _ => {
+                return Err(CodecError::BatchInteractionMismatch {
+                    id: item.id.clone(),
+                });
+            }
+        }
+    }
+    for item in &request.requests {
+        if !response.responses.iter().any(|other| other.id == item.id) {
+            return Err(CodecError::MissingBatchId {
+                id: item.id.clone(),
+            });
+        }
+    }
+    Ok(())
+}
+
+/// Encodes a valid batch response. Item failures remain inside HTTP 200.
+pub fn encode_batch_response(
+    request: &BatchRequest,
+    value: &BatchResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    let body = json::serialize(
+        &response_to_json(request, value, limits)?,
+        BodyKind::Response,
+        limits,
+    )?;
+    Ok(Response::builder()
+        .status(StatusCode::OK)
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)?)
+}
+
+/// Encodes a top-level batch-envelope failure.
+///
+/// Item-local failures belong in [`BatchResponseItem`]. Only failures that can
+/// reject the batch envelope before item execution are accepted here. A
+/// resource-limit failure defaults to the logical-limit status; use
+/// [`encode_batch_resource_limit_error_response`] when the concrete class is
+/// known.
+pub fn encode_batch_error_response(
+    error: &ProtocolError,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    if !matches!(
+        error.code,
+        ProtocolErrorCode::InvalidRequest
+            | ProtocolErrorCode::ResourceLimitExceeded
+            | ProtocolErrorCode::Internal
+    ) {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: "code is not valid for a top-level batch failure".into(),
+        }
+        .into());
+    }
+    let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
+    Ok(Response::builder()
+        .status(response::status_for_error(error.code))
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)?)
+}
+
+/// Encodes a class-specific top-level batch `resource_limit_exceeded` failure.
+pub fn encode_batch_resource_limit_error_response(
+    error: &ProtocolError,
+    kind: ResourceLimitKind,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    if error.code != ProtocolErrorCode::ResourceLimitExceeded {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: "resource-limit encoder requires resource_limit_exceeded".into(),
+        }
+        .into());
+    }
+    let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
+    Ok(Response::builder()
+        .status(response::status_for_resource_limit(kind))
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)?)
+}
+
+fn response_from_json(
+    value: &Json,
+    request: &BatchRequest,
+    limits: Limits,
+) -> Result<BatchResponse, CodecError> {
+    let fields = exact_object(value, "batch", &["responses"])?;
+    let values = array(required(fields, "responses")?, "responses")?;
+    if values.len() > limits.max_batch_items {
+        return Err(CodecError::TooManyBatchItems {
+            actual: values.len(),
+            maximum: limits.max_batch_items,
+        });
+    }
+    let requested: BTreeMap<&str, &BatchRequestKind> = request
+        .requests
+        .iter()
+        .map(|item| (item.id.as_str(), &item.request))
+        .collect();
+    let mut responses = Vec::with_capacity(values.len());
+    for (index, value) in values.iter().enumerate() {
+        let field = format!("responses[{index}]");
+        let fields = object(value, &field)?;
+        for name in fields.keys() {
+            if !["id", "result", "error"].contains(&name.as_str()) {
+                return Err(CodecError::UnknownField {
+                    field: format!("{field}.{name}"),
+                });
+            }
+        }
+        let id = string(required(fields, "id")?, &format!("{field}.id"))?;
+        let Some(kind) = requested.get(id.as_str()) else {
+            return Err(CodecError::UnexpectedBatchId { id });
+        };
+        let outcome = match (fields.get("result"), fields.get("error")) {
+            (Some(_), Some(_)) | (None, None) => {
+                return Err(CodecError::InvalidField {
+                    field,
+                    reason: "batch item must contain exactly one of result or error".into(),
+                });
+            }
+            (None, Some(error)) => {
+                let error = response::item_error_from_json(error)?;
+                match kind {
+                    BatchRequestKind::Invalid {
+                        error: expected, ..
+                    } if error == *expected => {}
+                    BatchRequestKind::Invalid { .. } => {
+                        return Err(CodecError::BatchInteractionMismatch { id });
+                    }
+                    kind if error.code.is_allowed_for(kind.interaction()) => {}
+                    _ => return Err(CodecError::BatchInteractionMismatch { id }),
+                }
+                Err(error)
+            }
+            (Some(result), None) => Ok(match kind {
+                BatchRequestKind::Fetch(request) => {
+                    let value = json::object_from_json(result, "result")?;
+                    request.validate_response(&value)?;
+                    BatchSuccess::Fetch(value)
+                }
+                BatchRequestKind::FetchTree(request) => {
+                    let value = json::fetch_tree_response_from_json(result)?;
+                    value.validate_for(request)?;
+                    BatchSuccess::FetchTree(value)
+                }
+                BatchRequestKind::FetchInterface(request) => {
+                    let value = json::fetch_interface_response_from_json(result)?;
+                    value.validate_for(request)?;
+                    BatchSuccess::FetchInterface(value)
+                }
+                BatchRequestKind::Invalid { .. } => {
+                    return Err(CodecError::BatchInteractionMismatch { id });
+                }
+            }),
+        };
+        responses.push(BatchResponseItem { id, outcome });
+    }
+    let response = BatchResponse { responses };
+    correlate(request, &response, limits)?;
+    Ok(response)
+}
+
+/// Decodes a batch response, including item-local failures within HTTP 200.
+pub fn decode_batch_response<B: AsRef<[u8]>>(
+    request: &BatchRequest,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<BatchResponse>, ClientResponseError> {
+    let valid_content_type = value
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(is_json_content_type);
+    if !valid_content_type {
+        if value.status().is_success() {
+            return Err(ClientResponseError::invalid(
+                InvalidResponseKind::InvalidBatch,
+                "missing or non-UTF-8 application/json Content-Type",
+            ));
+        }
+        return Err(response::transport_failure(value.status()));
+    }
+    let decoded = response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::Fetch,
+        limits,
+        |json| response_from_json(json, request, limits),
+    )
+    .map_err(|error| match error {
+        ClientResponseError::InvalidResponse { detail, .. } => {
+            ClientResponseError::invalid(InvalidResponseKind::InvalidBatch, detail)
+        }
+        other => other,
+    })?;
+    if let DecodedResponse::ProtocolFailure { error, .. } = &decoded
+        && !matches!(
+            error.code,
+            ProtocolErrorCode::InvalidRequest
+                | ProtocolErrorCode::ResourceLimitExceeded
+                | ProtocolErrorCode::Internal
+        )
+    {
+        return Err(ClientResponseError::invalid(
+            InvalidResponseKind::InvalidBatch,
+            "protocol code is not valid for a top-level batch failure",
+        ));
+    }
+    if let DecodedResponse::Success(success) = &decoded {
+        for item in &success.responses {
+            if let Ok(BatchSuccess::FetchInterface(interface)) = &item.outcome
+                && interface.descriptor.format != INTERFACE_FORMAT_V1
+            {
+                return Err(ClientResponseError::UnsupportedDescriptorFormat {
+                    format: interface.descriptor.format.clone(),
+                });
+            }
+        }
+    }
+    Ok(decoded)
+}
+
+fn object<'a>(value: &'a Json, field: &str) -> Result<&'a Map<String, Json>, CodecError> {
+    value.as_object().ok_or_else(|| CodecError::InvalidField {
+        field: field.into(),
+        reason: "expected object".into(),
+    })
+}
+
+fn exact_object<'a>(
+    value: &'a Json,
+    field: &str,
+    allowed: &[&str],
+) -> Result<&'a Map<String, Json>, CodecError> {
+    let fields = object(value, field)?;
+    for name in fields.keys() {
+        if !allowed.contains(&name.as_str()) {
+            return Err(CodecError::UnknownField {
+                field: format!("{field}.{name}"),
+            });
+        }
+    }
+    Ok(fields)
+}
+
+fn required<'a>(fields: &'a Map<String, Json>, name: &str) -> Result<&'a Json, CodecError> {
+    fields
+        .get(name)
+        .ok_or_else(|| CodecError::MissingField { field: name.into() })
+}
+
+fn string(value: &Json, field: &str) -> Result<String, CodecError> {
+    value
+        .as_str()
+        .map(str::to_owned)
+        .ok_or_else(|| CodecError::InvalidField {
+            field: field.into(),
+            reason: "expected string".into(),
+        })
+}
+
+fn array<'a>(value: &'a Json, field: &str) -> Result<&'a [Json], CodecError> {
+    value
+        .as_array()
+        .map(Vec::as_slice)
+        .ok_or_else(|| CodecError::InvalidField {
+            field: field.into(),
+            reason: "expected array".into(),
+        })
+}

crates/wip-https/src/codec.rs

@@ -0,0 +1,661 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+use http::header::{ACCEPT, CONTENT_TYPE};
+use http::{HeaderMap, Method, Request, Response, StatusCode};
+use wip_protocol::{
+    CallOperationRequest, CallOperationResponse, FetchInterfaceRequest, FetchInterfaceResponse,
+    FetchRequest, FetchResponse, FetchTreeRequest, FetchTreeResponse, INTERFACE_FORMAT_V1,
+    InterfaceDescriptor, InterfaceTarget, ProtocolError, ProtocolInteraction, Target,
+};
+
+use crate::response::{self, DecodedResponse};
+use crate::{
+    BodyKind, ClientResponseError, CodecError, Endpoint, InvalidResponseKind, JSON_CONTENT_TYPE,
+    Limits, ResourceLimitKind, Route, json,
+};
+
+fn request(
+    endpoint: &Endpoint,
+    route: Route,
+    body: Vec<u8>,
+) -> Result<Request<Vec<u8>>, http::Error> {
+    Request::builder()
+        .method(Method::POST)
+        .uri(endpoint.route(route).as_str())
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .header(ACCEPT, "application/json")
+        .body(body)
+}
+
+fn response(status: StatusCode, body: Vec<u8>) -> Result<Response<Vec<u8>>, http::Error> {
+    Response::builder()
+        .status(status)
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)
+}
+
+fn require_response_content_type<B>(response: &Response<B>) -> Result<(), ClientResponseError> {
+    let valid = response
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(is_json_content_type);
+    if valid {
+        Ok(())
+    } else if response.status().is_success() {
+        Err(ClientResponseError::invalid(
+            InvalidResponseKind::InvalidSuccessBody,
+            "missing or non-UTF-8 application/json Content-Type",
+        ))
+    } else {
+        Err(response::transport_failure(response.status()))
+    }
+}
+
+fn is_utf8_charset(value: &str) -> bool {
+    let value = value.trim();
+    value.eq_ignore_ascii_case("utf-8")
+        || value
+            .strip_prefix('"')
+            .and_then(|value| value.strip_suffix('"'))
+            .is_some_and(|value| value.eq_ignore_ascii_case("utf-8"))
+}
+
+/// Returns whether a Content-Type value denotes UTF-8 `application/json`.
+///
+/// The charset parameter is optional because JSON exchanged by this binding is
+/// always UTF-8; when present, its value must be `utf-8`. Other parameters are
+/// rejected so intermediaries cannot silently select another representation.
+#[must_use]
+pub fn is_json_content_type(value: &str) -> bool {
+    let mut parts = value.split(';');
+    if !parts
+        .next()
+        .is_some_and(|media| media.trim().eq_ignore_ascii_case("application/json"))
+    {
+        return false;
+    }
+    let mut saw_charset = false;
+    for parameter in parts {
+        let Some((name, value)) = parameter.trim().split_once('=') else {
+            return false;
+        };
+        if !name.trim().eq_ignore_ascii_case("charset") || !is_utf8_charset(value) || saw_charset {
+            return false;
+        }
+        saw_charset = true;
+    }
+    true
+}
+
+fn accepts_json(headers: &HeaderMap) -> bool {
+    let mut present = false;
+    let mut best_match: Option<((u8, u8), f32)> = None;
+    for value in headers.get_all(ACCEPT) {
+        present = true;
+        let Ok(value) = value.to_str() else {
+            continue;
+        };
+        for range in value.split(',') {
+            let mut parts = range.split(';');
+            let media_range = parts.next().unwrap_or_default().trim();
+            let mut quality = 1.0_f32;
+            let mut saw_quality = false;
+            let mut saw_charset = false;
+            let mut media_parameter_count = 0;
+            let mut valid = true;
+            for parameter in parts {
+                let parameter = parameter.trim();
+                let (name, value) = parameter
+                    .split_once('=')
+                    .map_or((parameter, None), |(name, value)| {
+                        (name.trim(), Some(value))
+                    });
+                if name.is_empty() {
+                    valid = false;
+                    break;
+                }
+                if saw_quality {
+                    // Parameters after q are Accept extensions and do not
+                    // constrain the selected representation.
+                    continue;
+                }
+                if name.eq_ignore_ascii_case("q") {
+                    let Some(value) = value else {
+                        valid = false;
+                        break;
+                    };
+                    saw_quality = true;
+                    match value.trim().parse::<f32>() {
+                        Ok(value) if (0.0..=1.0).contains(&value) => quality = value,
+                        _ => {
+                            valid = false;
+                            break;
+                        }
+                    }
+                } else {
+                    let Some(value) = value else {
+                        valid = false;
+                        break;
+                    };
+                    if !name.eq_ignore_ascii_case("charset")
+                        || !is_utf8_charset(value)
+                        || saw_charset
+                    {
+                        valid = false;
+                        break;
+                    }
+                    saw_charset = true;
+                    media_parameter_count += 1;
+                }
+            }
+            let media_specificity = if media_range.eq_ignore_ascii_case("application/json") {
+                Some(2)
+            } else if media_range.eq_ignore_ascii_case("application/*") {
+                Some(1)
+            } else if media_range == "*/*" {
+                Some(0)
+            } else {
+                None
+            };
+            if valid && let Some(media_specificity) = media_specificity {
+                let specificity = (media_specificity, media_parameter_count);
+                match best_match {
+                    Some((best_specificity, _)) if best_specificity > specificity => {}
+                    Some((best_specificity, best_quality)) if best_specificity == specificity => {
+                        best_match = Some((specificity, best_quality.max(quality)));
+                    }
+                    _ => best_match = Some((specificity, quality)),
+                }
+            }
+        }
+    }
+    if present {
+        best_match.is_some_and(|(_, quality)| quality > 0.0)
+    } else {
+        true
+    }
+}
+
+/// A failure while validating inbound HTTP request metadata.
+#[derive(Debug)]
+pub enum RequestMetadataError {
+    /// The method or route does not match the selected WIP interaction.
+    InvalidRequest(CodecError),
+    /// The request body does not use UTF-8 `application/json`.
+    UnsupportedMediaType,
+    /// The request's `Accept` metadata excludes `application/json`.
+    NotAcceptable,
+}
+
+impl RequestMetadataError {
+    /// Returns the HTTP status for this metadata failure.
+    #[must_use]
+    pub const fn status(&self) -> StatusCode {
+        match self {
+            Self::InvalidRequest(_) => StatusCode::BAD_REQUEST,
+            Self::UnsupportedMediaType => StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            Self::NotAcceptable => StatusCode::NOT_ACCEPTABLE,
+        }
+    }
+}
+
+impl Display for RequestMetadataError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidRequest(error) => error.fmt(formatter),
+            Self::UnsupportedMediaType => {
+                formatter.write_str("expected UTF-8 application/json Content-Type")
+            }
+            Self::NotAcceptable => formatter.write_str("request does not accept application/json"),
+        }
+    }
+}
+
+impl Error for RequestMetadataError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::InvalidRequest(error) => Some(error),
+            Self::UnsupportedMediaType | Self::NotAcceptable => None,
+        }
+    }
+}
+
+/// Validates mandatory HTTP metadata for an inbound WIP request.
+///
+/// Both absolute-form and origin-form request URIs are accepted, but the path
+/// must exactly equal the selected endpoint route and a query is forbidden.
+/// Unsupported content negotiation is reported as a Transport Binding metadata
+/// failure rather than a Core `invalid_request`.
+pub fn validate_http_request<B>(
+    endpoint: &Endpoint,
+    route: Route,
+    value: &Request<B>,
+) -> Result<(), RequestMetadataError> {
+    if value.method() != Method::POST {
+        return Err(RequestMetadataError::InvalidRequest(
+            CodecError::InvalidField {
+                field: "method".into(),
+                reason: "standard WIP routes require POST".into(),
+            },
+        ));
+    }
+    let expected = endpoint.route(route);
+    if value.uri().path() != expected.path() || value.uri().query().is_some() {
+        return Err(RequestMetadataError::InvalidRequest(
+            CodecError::InvalidField {
+                field: "route".into(),
+                reason: "request URI does not match the selected standard route".into(),
+            },
+        ));
+    }
+    let valid_content_type = value
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(is_json_content_type);
+    if !valid_content_type {
+        return Err(RequestMetadataError::UnsupportedMediaType);
+    }
+    if !accepts_json(value.headers()) {
+        return Err(RequestMetadataError::NotAcceptable);
+    }
+    Ok(())
+}
+
+/// Encodes a `fetch` HTTP request.
+pub fn encode_fetch_request(
+    endpoint: &Endpoint,
+    value: &FetchRequest,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    value.validate().map_err(CodecError::from)?;
+    let body = json::serialize(
+        &json::fetch_request_to_json(value),
+        BodyKind::Request,
+        limits,
+    )?;
+    Ok(request(endpoint, Route::Fetch, body)?)
+}
+
+/// Decodes a `fetch` request body.
+pub fn decode_fetch_request(body: &[u8], limits: Limits) -> Result<FetchRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    json::fetch_request_from_json(&value)
+}
+
+/// Encodes a `fetch_tree` HTTP request.
+pub fn encode_fetch_tree_request(
+    endpoint: &Endpoint,
+    value: &FetchTreeRequest,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    value.validate().map_err(CodecError::from)?;
+    let body = json::serialize(
+        &json::fetch_tree_request_to_json(value),
+        BodyKind::Request,
+        limits,
+    )?;
+    Ok(request(endpoint, Route::FetchTree, body)?)
+}
+
+/// Decodes a `fetch_tree` request body.
+pub fn decode_fetch_tree_request(
+    body: &[u8],
+    limits: Limits,
+) -> Result<FetchTreeRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    json::fetch_tree_request_from_json(&value)
+}
+
+/// Encodes a `fetch_interface` HTTP request.
+pub fn encode_fetch_interface_request(
+    endpoint: &Endpoint,
+    value: &FetchInterfaceRequest,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    let body = json::serialize(
+        &json::fetch_interface_request_to_json(value),
+        BodyKind::Request,
+        limits,
+    )?;
+    Ok(request(endpoint, Route::FetchInterface, body)?)
+}
+
+/// Decodes a `fetch_interface` request body.
+pub fn decode_fetch_interface_request(
+    body: &[u8],
+    limits: Limits,
+) -> Result<FetchInterfaceRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    json::fetch_interface_request_from_json(&value)
+}
+
+/// Descriptor-independent fields needed to resolve a `call_operation` request.
+///
+/// A Host decodes this metadata first, fixes the current interface descriptor,
+/// then passes the same body and descriptor to [`decode_call_operation_request`].
+/// This preserves canonical path/interface/operation lookup and error precedence
+/// without treating unvalidated argument JSON as a logical [`wip_protocol::Value`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CallOperationMetadata {
+    /// Path and optional object-state precondition.
+    pub target: Target,
+    /// Interface reference and optional interface precondition.
+    pub interface: InterfaceTarget,
+    /// Operation name used to select a declaration.
+    pub operation: String,
+}
+
+impl CallOperationMetadata {
+    /// Decodes the descriptor-bound request and verifies that routing metadata
+    /// still matches the values used to resolve `descriptor`.
+    pub fn decode_request(
+        &self,
+        body: &[u8],
+        descriptor: &InterfaceDescriptor,
+        limits: Limits,
+    ) -> Result<CallOperationRequest, CodecError> {
+        let request = decode_call_operation_request(body, descriptor, limits)?;
+        if request.target != self.target
+            || request.interface != self.interface
+            || request.operation != self.operation
+        {
+            return Err(CodecError::InvalidField {
+                field: "request".into(),
+                reason: "call metadata changed after descriptor resolution".into(),
+            });
+        }
+        Ok(request)
+    }
+}
+
+/// Decodes descriptor-independent `call_operation` routing metadata.
+pub fn decode_call_operation_metadata(
+    body: &[u8],
+    limits: Limits,
+) -> Result<CallOperationMetadata, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    let (target, interface, operation) = json::call_request_metadata_from_json(&value)?;
+    Ok(CallOperationMetadata {
+        target,
+        interface,
+        operation,
+    })
+}
+
+/// Encodes a descriptor-bound `call_operation` HTTP request.
+pub fn encode_call_operation_request(
+    endpoint: &Endpoint,
+    value: &CallOperationRequest,
+    descriptor: &InterfaceDescriptor,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    let value = json::call_request_to_json(value, descriptor)?;
+    let body = json::serialize(&value, BodyKind::Request, limits)?;
+    Ok(request(endpoint, Route::CallOperation, body)?)
+}
+
+/// Decodes a descriptor-bound `call_operation` request body.
+pub fn decode_call_operation_request(
+    body: &[u8],
+    descriptor: &InterfaceDescriptor,
+    limits: Limits,
+) -> Result<CallOperationRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    json::call_request_from_json(&value, descriptor)
+}
+
+/// Encodes a successful `fetch` response as a direct body with HTTP 200.
+pub fn encode_fetch_response(
+    request_value: &FetchRequest,
+    value: &FetchResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    request_value
+        .validate_response(value)
+        .map_err(CodecError::from)?;
+    let body = json::serialize(&json::object_to_json(value), BodyKind::Response, limits)?;
+    Ok(response(StatusCode::OK, body)?)
+}
+
+/// Decodes and classifies a `fetch` client response.
+pub fn decode_fetch_response<B: AsRef<[u8]>>(
+    request_value: &FetchRequest,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<FetchResponse>, ClientResponseError> {
+    require_response_content_type(value)?;
+    response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::Fetch,
+        limits,
+        |json| {
+            let object = json::object_from_json(json, "response")?;
+            request_value.validate_response(&object)?;
+            Ok(object)
+        },
+    )
+}
+
+/// Encodes a successful `fetch_tree` response as a direct body with HTTP 200.
+pub fn encode_fetch_tree_response(
+    request_value: &FetchTreeRequest,
+    value: &FetchTreeResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    value
+        .validate_for(request_value)
+        .map_err(CodecError::from)?;
+    let body = json::serialize(
+        &json::fetch_tree_response_to_json(value),
+        BodyKind::Response,
+        limits,
+    )?;
+    Ok(response(StatusCode::OK, body)?)
+}
+
+/// Decodes and classifies a `fetch_tree` client response.
+pub fn decode_fetch_tree_response<B: AsRef<[u8]>>(
+    request_value: &FetchTreeRequest,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<FetchTreeResponse>, ClientResponseError> {
+    require_response_content_type(value)?;
+    response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::FetchTree,
+        limits,
+        |json| {
+            let tree = json::fetch_tree_response_from_json(json)?;
+            tree.validate_for(request_value)?;
+            Ok(tree)
+        },
+    )
+}
+
+/// Encodes a successful `fetch_interface` response as a direct body with HTTP 200.
+pub fn encode_fetch_interface_response(
+    request_value: &FetchInterfaceRequest,
+    value: &FetchInterfaceResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    value
+        .validate_for(request_value)
+        .map_err(CodecError::from)?;
+    let body = json::serialize(
+        &json::fetch_interface_response_to_json(value),
+        BodyKind::Response,
+        limits,
+    )?;
+    Ok(response(StatusCode::OK, body)?)
+}
+
+/// Decodes and classifies a `fetch_interface` client response.
+pub fn decode_fetch_interface_response<B: AsRef<[u8]>>(
+    request_value: &FetchInterfaceRequest,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<FetchInterfaceResponse>, ClientResponseError> {
+    require_response_content_type(value)?;
+    let decoded = response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::FetchInterface,
+        limits,
+        |json| {
+            let interface = json::fetch_interface_response_from_json(json)?;
+            interface.validate_for(request_value)?;
+            Ok(interface)
+        },
+    )?;
+    if let DecodedResponse::Success(success) = &decoded
+        && success.descriptor.format != INTERFACE_FORMAT_V1
+    {
+        return Err(ClientResponseError::UnsupportedDescriptorFormat {
+            format: success.descriptor.format.clone(),
+        });
+    }
+    Ok(decoded)
+}
+
+/// Encodes a successful `call_operation` response as a direct body with HTTP 200.
+pub fn encode_call_operation_response(
+    request_value: &CallOperationRequest,
+    descriptor: &InterfaceDescriptor,
+    value: &CallOperationResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    let json = json::call_response_to_json(value, descriptor, &request_value.operation)?;
+    let body = json::serialize(&json, BodyKind::Response, limits)?;
+    Ok(response(StatusCode::OK, body)?)
+}
+
+/// Decodes and classifies a descriptor-bound `call_operation` client response.
+pub fn decode_call_operation_response<B: AsRef<[u8]>>(
+    request_value: &CallOperationRequest,
+    descriptor: &InterfaceDescriptor,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<CallOperationResponse>, ClientResponseError> {
+    require_response_content_type(value)?;
+    response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::CallOperation,
+        limits,
+        |json| json::call_response_from_json(json, descriptor, &request_value.operation),
+    )
+}
+
+fn validate_protocol_error(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+) -> Result<(), CodecError> {
+    if !error.code.is_allowed_for(interaction) {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: format!(
+                "code `{}` is not allowed for {interaction:?}",
+                response::error_code_name(error.code)
+            ),
+        });
+    }
+    Ok(())
+}
+
+fn encode_protocol_error_with_status(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+    status: StatusCode,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    validate_protocol_error(interaction, error)?;
+    let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
+    Ok(response(status, body)?)
+}
+
+/// Encodes a canonical Host error envelope using its standard HTTP status.
+///
+/// The code must be allowed for `interaction`. This API accepts only
+/// [`ProtocolError`], so client-local `InvalidResponse` and
+/// `UnsupportedDescriptorFormat` classifications cannot be emitted as Host
+/// error envelopes. Resource-limit errors use the logical-limit status; callers
+/// that know the concrete limit class should use
+/// [`encode_resource_limit_error_response`].
+pub fn encode_protocol_error_response(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    encode_protocol_error_with_status(
+        interaction,
+        error,
+        response::status_for_error(error.code),
+        limits,
+    )
+}
+
+/// Encodes a `resource_limit_exceeded` envelope with its class-specific status.
+pub fn encode_resource_limit_error_response(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+    kind: ResourceLimitKind,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    if error.code != wip_protocol::ProtocolErrorCode::ResourceLimitExceeded {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: "resource-limit encoder requires resource_limit_exceeded".into(),
+        }
+        .into());
+    }
+    encode_protocol_error_with_status(
+        interaction,
+        error,
+        response::status_for_resource_limit(kind),
+        limits,
+    )
+}
+
+/// Failure while building an outbound framework-neutral HTTP message.
+#[derive(Debug)]
+pub enum EncodeHttpError {
+    /// JSON or protocol encoding failed.
+    Codec(CodecError),
+    /// The framework-neutral HTTP message builder rejected the URI or headers.
+    Http(http::Error),
+}
+
+impl std::fmt::Display for EncodeHttpError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Codec(error) => error.fmt(formatter),
+            Self::Http(error) => error.fmt(formatter),
+        }
+    }
+}
+
+impl std::error::Error for EncodeHttpError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Codec(error) => Some(error),
+            Self::Http(error) => Some(error),
+        }
+    }
+}
+
+impl From<CodecError> for EncodeHttpError {
+    fn from(value: CodecError) -> Self {
+        Self::Codec(value)
+    }
+}
+
+impl From<http::Error> for EncodeHttpError {
+    fn from(value: http::Error) -> Self {
+        Self::Http(value)
+    }
+}

crates/wip-https/src/endpoint.rs

@@ -0,0 +1,156 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+use url::Url;
+
+/// The media type emitted for every WIP request and every response with a body.
+pub const JSON_CONTENT_TYPE: &str = "application/json; charset=utf-8";
+
+/// A fixed standard WIP over HTTPS v1 route.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Route {
+    /// Fetch one object.
+    Fetch,
+    /// Fetch a bounded object tree.
+    FetchTree,
+    /// Fetch an interface descriptor.
+    FetchInterface,
+    /// Call one operation.
+    CallOperation,
+    /// Package independent retrieval interactions.
+    Batch,
+}
+
+impl Route {
+    /// Returns the RFC 3986 relative reference used below an endpoint prefix.
+    #[must_use]
+    pub const fn relative_reference(self) -> &'static str {
+        match self {
+            Self::Fetch => "v1/fetch",
+            Self::FetchTree => "v1/fetch_tree",
+            Self::FetchInterface => "v1/fetch_interface",
+            Self::CallOperation => "v1/call_operation",
+            Self::Batch => "v1/batch",
+        }
+    }
+}
+
+/// A canonical absolute HTTPS base URL whose path always ends in `/`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Endpoint(Url);
+
+impl Endpoint {
+    /// Parses and canonicalizes an endpoint.
+    ///
+    /// The input must be an absolute HTTPS URL without a query or fragment. Its
+    /// path is an endpoint prefix, not a Worldspace path. A trailing slash is
+    /// appended when absent so RFC 3986 relative-reference resolution preserves
+    /// the final prefix segment.
+    pub fn parse(input: &str) -> Result<Self, EndpointError> {
+        let mut url = Url::parse(input).map_err(EndpointError::InvalidUrl)?;
+        if url.scheme() != "https" {
+            return Err(EndpointError::NotHttps);
+        }
+        if url.cannot_be_a_base() || url.host_str().is_none() {
+            return Err(EndpointError::NotAbsoluteBase);
+        }
+        if url.query().is_some() {
+            return Err(EndpointError::HasQuery);
+        }
+        if url.fragment().is_some() {
+            return Err(EndpointError::HasFragment);
+        }
+        if !url.path().ends_with('/') {
+            let path = format!("{}/", url.path());
+            url.set_path(&path);
+        }
+        Ok(Self(url))
+    }
+
+    /// Returns the canonical base URL.
+    #[must_use]
+    pub fn as_url(&self) -> &Url {
+        &self.0
+    }
+
+    /// Resolves one fixed v1 route below this endpoint prefix.
+    #[must_use]
+    pub fn route(&self, route: Route) -> Url {
+        self.0
+            .join(route.relative_reference())
+            .expect("fixed relative WIP routes are valid URL references")
+    }
+
+    /// Recognizes an exact standard route below this endpoint.
+    ///
+    /// Query strings, fragments, additional path segments, and Worldspace paths
+    /// are not route components and therefore never match.
+    #[must_use]
+    pub fn recognize(&self, candidate: &Url) -> Option<Route> {
+        const ROUTES: [Route; 5] = [
+            Route::Fetch,
+            Route::FetchTree,
+            Route::FetchInterface,
+            Route::CallOperation,
+            Route::Batch,
+        ];
+        if candidate.query().is_some() || candidate.fragment().is_some() {
+            return None;
+        }
+        ROUTES
+            .into_iter()
+            .find(|route| self.route(*route) == *candidate)
+    }
+}
+
+impl Display for Endpoint {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        self.0.fmt(formatter)
+    }
+}
+
+impl TryFrom<&str> for Endpoint {
+    type Error = EndpointError;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        Self::parse(value)
+    }
+}
+
+/// Why an endpoint is not a valid standard WIP HTTPS base.
+#[derive(Debug)]
+pub enum EndpointError {
+    /// URL parsing failed.
+    InvalidUrl(url::ParseError),
+    /// The URL scheme is not `https`.
+    NotHttps,
+    /// The URL is not a hierarchical absolute URL with an authority.
+    NotAbsoluteBase,
+    /// A query component was supplied.
+    HasQuery,
+    /// A fragment component was supplied.
+    HasFragment,
+}
+
+impl Display for EndpointError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidUrl(error) => write!(formatter, "invalid endpoint URL: {error}"),
+            Self::NotHttps => formatter.write_str("WIP endpoint must use HTTPS"),
+            Self::NotAbsoluteBase => {
+                formatter.write_str("WIP endpoint must be an absolute base URL")
+            }
+            Self::HasQuery => formatter.write_str("WIP endpoint must not contain a query"),
+            Self::HasFragment => formatter.write_str("WIP endpoint must not contain a fragment"),
+        }
+    }
+}
+
+impl Error for EndpointError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::InvalidUrl(error) => Some(error),
+            _ => None,
+        }
+    }
+}

crates/wip-https/src/error.rs

@@ -0,0 +1,255 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+/// Caller-selected hard limits applied before or while decoding JSON.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Limits {
+    /// Largest accepted request body in bytes.
+    pub(crate) max_request_bytes: usize,
+    /// Largest accepted response body in bytes.
+    pub(crate) max_response_bytes: usize,
+    /// Largest accepted JSON container nesting depth.
+    pub(crate) max_nesting: usize,
+    /// Largest accepted number of batch items.
+    pub(crate) max_batch_items: usize,
+}
+
+impl Limits {
+    /// Creates a nonzero limit set.
+    pub fn new(
+        max_request_bytes: usize,
+        max_response_bytes: usize,
+        max_nesting: usize,
+        max_batch_items: usize,
+    ) -> Result<Self, LimitConfigurationError> {
+        if max_request_bytes == 0 {
+            return Err(LimitConfigurationError::ZeroRequestBytes);
+        }
+        if max_response_bytes == 0 {
+            return Err(LimitConfigurationError::ZeroResponseBytes);
+        }
+        if max_nesting == 0 {
+            return Err(LimitConfigurationError::ZeroNesting);
+        }
+        if max_batch_items == 0 {
+            return Err(LimitConfigurationError::ZeroBatchItems);
+        }
+        Ok(Self {
+            max_request_bytes,
+            max_response_bytes,
+            max_nesting,
+            max_batch_items,
+        })
+    }
+
+    /// Returns the request body byte limit.
+    #[must_use]
+    pub const fn max_request_bytes(self) -> usize {
+        self.max_request_bytes
+    }
+
+    /// Returns the response body byte limit.
+    #[must_use]
+    pub const fn max_response_bytes(self) -> usize {
+        self.max_response_bytes
+    }
+
+    /// Returns the JSON container nesting limit.
+    #[must_use]
+    pub const fn max_nesting(self) -> usize {
+        self.max_nesting
+    }
+
+    /// Returns the batch item count limit.
+    #[must_use]
+    pub const fn max_batch_items(self) -> usize {
+        self.max_batch_items
+    }
+}
+
+/// Why a [`Limits`] configuration is not bounded.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LimitConfigurationError {
+    /// Request-byte limit was zero.
+    ZeroRequestBytes,
+    /// Response-byte limit was zero.
+    ZeroResponseBytes,
+    /// Nesting limit was zero.
+    ZeroNesting,
+    /// Batch-item limit was zero.
+    ZeroBatchItems,
+}
+
+impl Display for LimitConfigurationError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        formatter.write_str(match self {
+            Self::ZeroRequestBytes => "request byte limit must be nonzero",
+            Self::ZeroResponseBytes => "response byte limit must be nonzero",
+            Self::ZeroNesting => "nesting limit must be nonzero",
+            Self::ZeroBatchItems => "batch item limit must be nonzero",
+        })
+    }
+}
+
+impl Error for LimitConfigurationError {}
+
+/// Whether a body is being decoded as a request or response.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BodyKind {
+    /// An inbound server request.
+    Request,
+    /// An inbound client response.
+    Response,
+}
+
+/// The class of a resource limit exceeded by a wire representation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResourceLimitKind {
+    /// A request or response representation exceeded its byte-size limit.
+    RepresentationBytes,
+    /// A logical limit such as nesting depth, batch count, or collection size was exceeded.
+    Logical,
+}
+
+/// A malformed or locally disallowed wire representation.
+#[derive(Debug)]
+pub enum CodecError {
+    /// The body exceeds its configured byte limit.
+    BodyTooLarge {
+        /// Actual body size.
+        actual: usize,
+        /// Configured maximum.
+        maximum: usize,
+    },
+    /// JSON syntax is invalid.
+    InvalidJson(serde_json::Error),
+    /// A JSON container exceeds the configured nesting depth.
+    NestingTooDeep {
+        /// Configured maximum.
+        maximum: usize,
+    },
+    /// A required field is absent.
+    MissingField {
+        /// Field name.
+        field: String,
+    },
+    /// An undeclared field is present.
+    UnknownField {
+        /// Field name.
+        field: String,
+    },
+    /// A field has an invalid JSON type or semantic representation.
+    InvalidField {
+        /// Field name or value location.
+        field: String,
+        /// Stable human-readable reason.
+        reason: String,
+    },
+    /// An optional field was represented by JSON null rather than omission.
+    NullOptionalField {
+        /// Field name.
+        field: String,
+    },
+    /// Base64 is not canonical RFC 4648 Section 4 encoding.
+    InvalidBase64 {
+        /// Field name or value location.
+        field: String,
+    },
+    /// Logical protocol validation rejected the decoded representation.
+    ProtocolValidation(wip_protocol::ValidationError),
+    /// The batch exceeds its configured item count.
+    TooManyBatchItems {
+        /// Actual item count.
+        actual: usize,
+        /// Configured maximum.
+        maximum: usize,
+    },
+    /// Batch item identifiers are not unique.
+    DuplicateBatchId {
+        /// Repeated identifier.
+        id: String,
+    },
+    /// A response contains a batch identifier that was not requested.
+    UnexpectedBatchId {
+        /// Unexpected identifier.
+        id: String,
+    },
+    /// A response omitted a requested batch identifier.
+    MissingBatchId {
+        /// Missing identifier.
+        id: String,
+    },
+    /// A batch item result does not match its requested interaction.
+    BatchInteractionMismatch {
+        /// Item identifier.
+        id: String,
+    },
+}
+
+impl CodecError {
+    /// Classifies this failure when it represents a canonical resource limit.
+    #[must_use]
+    pub const fn resource_limit_kind(&self) -> Option<ResourceLimitKind> {
+        match self {
+            Self::BodyTooLarge { .. } => Some(ResourceLimitKind::RepresentationBytes),
+            Self::NestingTooDeep { .. } | Self::TooManyBatchItems { .. } => {
+                Some(ResourceLimitKind::Logical)
+            }
+            _ => None,
+        }
+    }
+}
+
+impl Display for CodecError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::BodyTooLarge { actual, maximum } => {
+                write!(formatter, "body has {actual} bytes; maximum is {maximum}")
+            }
+            Self::InvalidJson(error) => write!(formatter, "invalid JSON: {error}"),
+            Self::NestingTooDeep { maximum } => {
+                write!(formatter, "JSON nesting exceeds maximum {maximum}")
+            }
+            Self::MissingField { field } => write!(formatter, "missing field `{field}`"),
+            Self::UnknownField { field } => write!(formatter, "unknown field `{field}`"),
+            Self::InvalidField { field, reason } => {
+                write!(formatter, "invalid field `{field}`: {reason}")
+            }
+            Self::NullOptionalField { field } => {
+                write!(
+                    formatter,
+                    "optional field `{field}` must be omitted instead of null"
+                )
+            }
+            Self::InvalidBase64 { field } => {
+                write!(formatter, "field `{field}` is not canonical base64")
+            }
+            Self::ProtocolValidation(error) => error.fmt(formatter),
+            Self::TooManyBatchItems { actual, maximum } => {
+                write!(formatter, "batch has {actual} items; maximum is {maximum}")
+            }
+            Self::DuplicateBatchId { id } => write!(formatter, "duplicate batch id `{id}`"),
+            Self::UnexpectedBatchId { id } => write!(formatter, "unexpected batch id `{id}`"),
+            Self::MissingBatchId { id } => write!(formatter, "missing batch id `{id}`"),
+            Self::BatchInteractionMismatch { id } => {
+                write!(formatter, "batch result does not match request `{id}`")
+            }
+        }
+    }
+}
+
+impl Error for CodecError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::InvalidJson(error) => Some(error),
+            Self::ProtocolValidation(error) => Some(error),
+            _ => None,
+        }
+    }
+}
+
+impl From<wip_protocol::ValidationError> for CodecError {
+    fn from(value: wip_protocol::ValidationError) -> Self {
+        Self::ProtocolValidation(value)
+    }
+}

crates/wip-https/src/lib.rs

@@ -0,0 +1,67 @@
+//! Framework-independent standard WIP over HTTPS v1 binding.
+//!
+//! This crate owns endpoint and route derivation, UTF-8 JSON encoding, canonical
+//! success and error response handling, HTTP status mapping, descriptor-guided
+//! operation-value conversion, and retrieval batching. It deliberately performs
+//! no I/O and depends on no server framework, TLS implementation, filesystem
+//! projection, client cache, or presentation layer.
+//!
+//! Logical values remain owned by [`wip_protocol`]. Validators and `Bytes` are
+//! encoded in JSON bodies using canonical RFC 4648 Section 4 base64; this crate
+//! does not infer WIP validator semantics from `ETag` or `If-Match`.
+//!
+//! ```
+//! use wip_https::{Endpoint, Limits, encode_fetch_request};
+//! use wip_protocol::FetchRequest;
+//!
+//! let endpoint = Endpoint::parse("https://example.test/api/wip")?;
+//! let limits = Limits::new(64 * 1024, 1024 * 1024, 64, 100)?;
+//! let request = encode_fetch_request(
+//!     &endpoint,
+//!     &FetchRequest { path: "/items/123".into() },
+//!     limits,
+//! )?;
+//! assert_eq!(request.uri(), "https://example.test/api/wip/v1/fetch");
+//! assert_eq!(request.method(), http::Method::POST);
+//! # Ok::<(), Box<dyn std::error::Error>>(())
+//! ```
+
+#![deny(missing_docs)]
+
+mod batch;
+mod codec;
+mod endpoint;
+mod error;
+mod json;
+mod response;
+
+pub use batch::{
+    BatchMethod, BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse,
+    BatchResponseItem, BatchSuccess, decode_batch_request, decode_batch_response,
+    encode_batch_error_response, encode_batch_request, encode_batch_resource_limit_error_response,
+    encode_batch_response,
+};
+pub use codec::{
+    CallOperationMetadata, EncodeHttpError, RequestMetadataError, decode_call_operation_metadata,
+    decode_call_operation_request, decode_call_operation_response, decode_fetch_interface_request,
+    decode_fetch_interface_response, decode_fetch_request, decode_fetch_response,
+    decode_fetch_tree_request, decode_fetch_tree_response, encode_call_operation_request,
+    encode_call_operation_response, encode_fetch_interface_request,
+    encode_fetch_interface_response, encode_fetch_request, encode_fetch_response,
+    encode_fetch_tree_request, encode_fetch_tree_response, encode_protocol_error_response,
+    encode_resource_limit_error_response, is_json_content_type, validate_http_request,
+};
+pub use endpoint::{Endpoint, EndpointError, JSON_CONTENT_TYPE, Route};
+pub use error::{BodyKind, CodecError, LimitConfigurationError, Limits, ResourceLimitKind};
+pub use response::{
+    ClientResponseError, DecodedResponse, InvalidResponseKind, StatusMismatch,
+    TransportBindingFailure, TransportFailureKind, error_code_name, status_for_error,
+    status_for_resource_limit,
+};
+
+/// Framework-neutral HTTP types used by this binding's public API.
+pub use http;
+/// URL type used by [`Endpoint`].
+pub use url;
+/// Transport-independent logical protocol model used by this binding.
+pub use wip_protocol;

crates/wip-https/src/response.rs

@@ -0,0 +1,365 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+use http::StatusCode;
+use serde_json::{Map, Value as Json};
+use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
+
+use crate::{BodyKind, CodecError, Limits, ResourceLimitKind, json};
+
+/// A successfully classified client response.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DecodedResponse<T> {
+    /// A successful direct response body.
+    Success(T),
+    /// A canonical Host protocol failure.
+    ProtocolFailure {
+        /// The authoritative protocol error decoded from the envelope.
+        error: ProtocolError,
+        /// A diagnostic when the HTTP status differs from the canonical mapping.
+        status_mismatch: Option<StatusMismatch>,
+    },
+}
+
+/// Diagnostic evidence that HTTP metadata disagrees with a valid error envelope.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct StatusMismatch {
+    /// Status received from the peer.
+    pub actual: StatusCode,
+    /// Canonical status for the envelope's protocol code.
+    pub expected: StatusCode,
+}
+
+/// Class of non-protocol HTTP failure returned without a valid WIP envelope.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TransportFailureKind {
+    /// HTTP 401, commonly emitted by authentication infrastructure.
+    AuthenticationRequired,
+    /// HTTP 403, commonly emitted by endpoint policy or infrastructure.
+    EndpointForbidden,
+    /// Another non-success HTTP response without a WIP error envelope.
+    HttpStatus,
+}
+
+/// A non-success HTTP response that is not a valid WIP protocol failure.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TransportBindingFailure {
+    /// HTTP status returned by the peer or intermediary.
+    pub status: StatusCode,
+    /// Coarse classification which does not invent a protocol error code.
+    pub kind: TransportFailureKind,
+}
+
+/// Why a response violates the WIP v1 response contract.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum InvalidResponseKind {
+    /// A 2xx response contained an error envelope.
+    ErrorEnvelopeOnSuccessStatus,
+    /// A non-2xx response contained a valid success body.
+    SuccessBodyOnErrorStatus,
+    /// A valid error envelope used a code forbidden for the interaction.
+    DisallowedProtocolCode,
+    /// A valid success body used a 2xx status other than canonical HTTP 200.
+    NonCanonicalSuccessStatus,
+    /// A 2xx body was malformed or semantically invalid.
+    InvalidSuccessBody,
+    /// A batch response did not correlate exactly with its request.
+    InvalidBatch,
+}
+
+/// A local failure while classifying or validating a peer response.
+#[derive(Debug)]
+pub enum ClientResponseError {
+    /// The HTTP exchange failed outside the protocol envelope.
+    TransportBinding(TransportBindingFailure),
+    /// The peer supplied a contradictory or invalid WIP response.
+    InvalidResponse {
+        /// Stable response-failure category.
+        kind: InvalidResponseKind,
+        /// Bounded diagnostic from local decoding.
+        detail: String,
+    },
+    /// The descriptor is structurally valid but uses an unsupported format.
+    UnsupportedDescriptorFormat {
+        /// Format identifier received from the Host.
+        format: String,
+    },
+}
+
+impl ClientResponseError {
+    pub(crate) fn invalid(kind: InvalidResponseKind, detail: impl Into<String>) -> Self {
+        Self::InvalidResponse {
+            kind,
+            detail: detail.into(),
+        }
+    }
+}
+
+impl Display for ClientResponseError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::TransportBinding(failure) => write!(
+                formatter,
+                "transport binding failure ({:?}, HTTP {})",
+                failure.kind, failure.status
+            ),
+            Self::InvalidResponse { kind, detail } => {
+                write!(formatter, "invalid WIP response ({kind:?}): {detail}")
+            }
+            Self::UnsupportedDescriptorFormat { format } => {
+                write!(
+                    formatter,
+                    "unsupported interface descriptor format `{format}`"
+                )
+            }
+        }
+    }
+}
+
+impl Error for ClientResponseError {}
+
+/// Returns the canonical HTTP status for a wire-level protocol error.
+///
+/// [`ProtocolErrorCode::ResourceLimitExceeded`] defaults to the logical-limit
+/// status. Use [`status_for_resource_limit`] when the concrete limit class is
+/// known.
+#[must_use]
+pub const fn status_for_error(code: ProtocolErrorCode) -> StatusCode {
+    match code {
+        ProtocolErrorCode::InvalidRequest => StatusCode::BAD_REQUEST,
+        ProtocolErrorCode::NotFound | ProtocolErrorCode::InterfaceNotFound => StatusCode::NOT_FOUND,
+        ProtocolErrorCode::InterfaceMismatch => StatusCode::CONFLICT,
+        ProtocolErrorCode::OperationNotFound => StatusCode::NOT_FOUND,
+        ProtocolErrorCode::InvalidArguments => StatusCode::UNPROCESSABLE_ENTITY,
+        ProtocolErrorCode::ValidatorRequired | ProtocolErrorCode::InterfaceValidatorRequired => {
+            StatusCode::PRECONDITION_REQUIRED
+        }
+        ProtocolErrorCode::ValidatorMismatch | ProtocolErrorCode::InterfaceValidatorMismatch => {
+            StatusCode::PRECONDITION_FAILED
+        }
+        ProtocolErrorCode::PermissionDenied => StatusCode::FORBIDDEN,
+        ProtocolErrorCode::ResourceLimitExceeded => StatusCode::UNPROCESSABLE_ENTITY,
+        ProtocolErrorCode::Internal | ProtocolErrorCode::OperationOutcomeUnknown => {
+            StatusCode::INTERNAL_SERVER_ERROR
+        }
+    }
+}
+
+/// Returns the canonical HTTP status for a concrete resource-limit class.
+#[must_use]
+pub const fn status_for_resource_limit(kind: ResourceLimitKind) -> StatusCode {
+    match kind {
+        ResourceLimitKind::RepresentationBytes => StatusCode::PAYLOAD_TOO_LARGE,
+        ResourceLimitKind::Logical => StatusCode::UNPROCESSABLE_ENTITY,
+    }
+}
+
+fn status_matches_error(status: StatusCode, code: ProtocolErrorCode) -> bool {
+    match code {
+        ProtocolErrorCode::ResourceLimitExceeded => {
+            status == StatusCode::PAYLOAD_TOO_LARGE || status == StatusCode::UNPROCESSABLE_ENTITY
+        }
+        _ => status == status_for_error(code),
+    }
+}
+
+/// Returns the stable snake-case wire spelling of a protocol code.
+#[must_use]
+pub const fn error_code_name(code: ProtocolErrorCode) -> &'static str {
+    match code {
+        ProtocolErrorCode::InvalidRequest => "invalid_request",
+        ProtocolErrorCode::NotFound => "not_found",
+        ProtocolErrorCode::InterfaceNotFound => "interface_not_found",
+        ProtocolErrorCode::InterfaceMismatch => "interface_mismatch",
+        ProtocolErrorCode::OperationNotFound => "operation_not_found",
+        ProtocolErrorCode::InvalidArguments => "invalid_arguments",
+        ProtocolErrorCode::ValidatorRequired => "validator_required",
+        ProtocolErrorCode::ValidatorMismatch => "validator_mismatch",
+        ProtocolErrorCode::InterfaceValidatorRequired => "interface_validator_required",
+        ProtocolErrorCode::InterfaceValidatorMismatch => "interface_validator_mismatch",
+        ProtocolErrorCode::PermissionDenied => "permission_denied",
+        ProtocolErrorCode::ResourceLimitExceeded => "resource_limit_exceeded",
+        ProtocolErrorCode::Internal => "internal",
+        ProtocolErrorCode::OperationOutcomeUnknown => "operation_outcome_unknown",
+    }
+}
+
+fn error_code_from_name(name: &str) -> Option<ProtocolErrorCode> {
+    Some(match name {
+        "invalid_request" => ProtocolErrorCode::InvalidRequest,
+        "not_found" => ProtocolErrorCode::NotFound,
+        "interface_not_found" => ProtocolErrorCode::InterfaceNotFound,
+        "interface_mismatch" => ProtocolErrorCode::InterfaceMismatch,
+        "operation_not_found" => ProtocolErrorCode::OperationNotFound,
+        "invalid_arguments" => ProtocolErrorCode::InvalidArguments,
+        "validator_required" => ProtocolErrorCode::ValidatorRequired,
+        "validator_mismatch" => ProtocolErrorCode::ValidatorMismatch,
+        "interface_validator_required" => ProtocolErrorCode::InterfaceValidatorRequired,
+        "interface_validator_mismatch" => ProtocolErrorCode::InterfaceValidatorMismatch,
+        "permission_denied" => ProtocolErrorCode::PermissionDenied,
+        "resource_limit_exceeded" => ProtocolErrorCode::ResourceLimitExceeded,
+        "internal" => ProtocolErrorCode::Internal,
+        "operation_outcome_unknown" => ProtocolErrorCode::OperationOutcomeUnknown,
+        _ => return None,
+    })
+}
+
+pub(crate) fn error_to_json(error: &ProtocolError) -> Json {
+    serde_json::json!({
+        "error": {
+            "code": error_code_name(error.code),
+            "message": error.message,
+        }
+    })
+}
+
+pub(crate) fn item_error_to_json(error: &ProtocolError) -> Json {
+    serde_json::json!({
+        "code": error_code_name(error.code),
+        "message": error.message,
+    })
+}
+
+pub(crate) fn item_error_from_json(value: &Json) -> Result<ProtocolError, CodecError> {
+    let fields = value
+        .as_object()
+        .ok_or_else(|| invalid_field("error", "expected object"))?;
+    exact(fields, &["code", "message"], "error")?;
+    let code_name = required_string(fields, "code")?;
+    let code = error_code_from_name(code_name)
+        .ok_or_else(|| invalid_field("error.code", "unknown protocol error code"))?;
+    let message = required_string(fields, "message")?.to_owned();
+    Ok(ProtocolError { code, message })
+}
+
+fn envelope_error_from_json(value: &Json) -> Result<Option<ProtocolError>, CodecError> {
+    let Some(fields) = value.as_object() else {
+        return Ok(None);
+    };
+    if fields.len() != 1 || !fields.contains_key("error") {
+        return Ok(None);
+    }
+    item_error_from_json(&fields["error"]).map(Some)
+}
+
+fn exact(fields: &Map<String, Json>, allowed: &[&str], parent: &str) -> Result<(), CodecError> {
+    for name in fields.keys() {
+        if !allowed.contains(&name.as_str()) {
+            return Err(CodecError::UnknownField {
+                field: format!("{parent}.{name}"),
+            });
+        }
+    }
+    for name in allowed {
+        if !fields.contains_key(*name) {
+            return Err(CodecError::MissingField {
+                field: format!("{parent}.{name}"),
+            });
+        }
+    }
+    Ok(())
+}
+
+fn required_string<'a>(fields: &'a Map<String, Json>, name: &str) -> Result<&'a str, CodecError> {
+    fields
+        .get(name)
+        .and_then(Json::as_str)
+        .ok_or_else(|| invalid_field(&format!("error.{name}"), "expected string"))
+}
+
+fn invalid_field(field: &str, reason: &str) -> CodecError {
+    CodecError::InvalidField {
+        field: field.into(),
+        reason: reason.into(),
+    }
+}
+
+pub(crate) fn decode<T>(
+    status: StatusCode,
+    body: &[u8],
+    interaction: ProtocolInteraction,
+    limits: Limits,
+    success: impl FnOnce(&Json) -> Result<T, CodecError>,
+) -> Result<DecodedResponse<T>, ClientResponseError> {
+    let value = match json::parse(body, BodyKind::Response, limits) {
+        Ok(value) => value,
+        Err(_) if !status.is_success() => {
+            return Err(transport_failure(status));
+        }
+        Err(error) => {
+            return Err(ClientResponseError::invalid(
+                InvalidResponseKind::InvalidSuccessBody,
+                error.to_string(),
+            ));
+        }
+    };
+
+    match envelope_error_from_json(&value) {
+        Ok(Some(error)) => {
+            if status.is_success() {
+                return Err(ClientResponseError::invalid(
+                    InvalidResponseKind::ErrorEnvelopeOnSuccessStatus,
+                    "protocol error envelope carried by a success status",
+                ));
+            }
+            if !error.code.is_allowed_for(interaction) {
+                return Err(ClientResponseError::invalid(
+                    InvalidResponseKind::DisallowedProtocolCode,
+                    format!(
+                        "code `{}` is not allowed for {interaction:?}",
+                        error_code_name(error.code)
+                    ),
+                ));
+            }
+            let expected = status_for_error(error.code);
+            let status_mismatch =
+                (!status_matches_error(status, error.code)).then_some(StatusMismatch {
+                    actual: status,
+                    expected,
+                });
+            Ok(DecodedResponse::ProtocolFailure {
+                error,
+                status_mismatch,
+            })
+        }
+        Err(_) if !status.is_success() => Err(transport_failure(status)),
+        Err(error) => Err(ClientResponseError::invalid(
+            InvalidResponseKind::InvalidSuccessBody,
+            error.to_string(),
+        )),
+        Ok(None) if status == StatusCode::OK => success(&value)
+            .map(DecodedResponse::Success)
+            .map_err(|error| {
+                ClientResponseError::invalid(
+                    InvalidResponseKind::InvalidSuccessBody,
+                    error.to_string(),
+                )
+            }),
+        Ok(None) if status.is_success() => match success(&value) {
+            Ok(_) => Err(ClientResponseError::invalid(
+                InvalidResponseKind::NonCanonicalSuccessStatus,
+                format!("success body carried by non-canonical HTTP {status}"),
+            )),
+            Err(error) => Err(ClientResponseError::invalid(
+                InvalidResponseKind::InvalidSuccessBody,
+                error.to_string(),
+            )),
+        },
+        Ok(None) => match success(&value) {
+            Ok(_) => Err(ClientResponseError::invalid(
+                InvalidResponseKind::SuccessBodyOnErrorStatus,
+                "valid success body carried by a non-success status",
+            )),
+            Err(_) => Err(transport_failure(status)),
+        },
+    }
+}
+
+pub(crate) fn transport_failure(status: StatusCode) -> ClientResponseError {
+    let kind = match status {
+        StatusCode::UNAUTHORIZED => TransportFailureKind::AuthenticationRequired,
+        StatusCode::FORBIDDEN => TransportFailureKind::EndpointForbidden,
+        _ => TransportFailureKind::HttpStatus,
+    };
+    ClientResponseError::TransportBinding(TransportBindingFailure { status, kind })
+}

crates/wip-https/tests/batch.rs

@@ -0,0 +1,353 @@
+use wip_https::http::StatusCode;
+use wip_https::wip_protocol::{
+    FetchInterfaceRequest, FetchInterfaceResponse, FetchRequest, INTERFACE_FORMAT_V1,
+    InterfaceDescriptor, Object, ProtocolError, ProtocolErrorCode,
+};
+use wip_https::{
+    BatchMethod, BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse,
+    BatchResponseItem, BatchSuccess, ClientResponseError, DecodedResponse, Endpoint,
+    InvalidResponseKind, Limits, ResourceLimitKind, decode_batch_request, decode_batch_response,
+    encode_batch_error_response, encode_batch_request, encode_batch_resource_limit_error_response,
+    encode_batch_response,
+};
+
+fn limits() -> Limits {
+    Limits::new(100_000, 100_000, 64, 4).unwrap()
+}
+
+fn request() -> BatchRequest {
+    BatchRequest {
+        requests: vec![
+            BatchRequestItem {
+                id: "object".into(),
+                request: BatchRequestKind::Fetch(FetchRequest {
+                    path: "/item".into(),
+                }),
+            },
+            BatchRequestItem {
+                id: "interface".into(),
+                request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
+                    interface: "interface-v1".into(),
+                }),
+            },
+        ],
+    }
+}
+
+#[test]
+fn batch_round_trips_by_unique_id_with_item_failures_and_validators() {
+    let request = request();
+    let endpoint = Endpoint::parse("https://example.test/wip").unwrap();
+    let encoded_request = encode_batch_request(&endpoint, &request, limits()).unwrap();
+    assert_eq!(encoded_request.uri().path(), "/wip/v1/batch");
+    assert_eq!(encoded_request.headers()["accept"], "application/json");
+    assert_eq!(
+        decode_batch_request(encoded_request.body(), limits()).unwrap(),
+        request
+    );
+
+    let response = BatchResponse {
+        responses: vec![
+            BatchResponseItem {
+                id: "interface".into(),
+                outcome: Err(ProtocolError {
+                    code: ProtocolErrorCode::InterfaceNotFound,
+                    message: "gone".into(),
+                }),
+            },
+            BatchResponseItem {
+                id: "object".into(),
+                outcome: Ok(BatchSuccess::Fetch(Object {
+                    name: "item".into(),
+                    description: None,
+                    interfaces: vec![],
+                    r#ref: None,
+                    validator: Some(vec![0, 1, 2, 255]),
+                })),
+            },
+        ],
+    };
+    let encoded = encode_batch_response(&request, &response, limits()).unwrap();
+    assert_eq!(encoded.status(), StatusCode::OK);
+    assert!(
+        std::str::from_utf8(encoded.body())
+            .unwrap()
+            .contains("AAEC/w==")
+    );
+    assert_eq!(
+        decode_batch_response(&request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(response)
+    );
+}
+
+#[test]
+fn batch_interface_validator_round_trips_in_item_body() {
+    let request = BatchRequest {
+        requests: vec![BatchRequestItem {
+            id: "interface".into(),
+            request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
+                interface: "interface-v1".into(),
+            }),
+        }],
+    };
+    let response = BatchResponse {
+        responses: vec![BatchResponseItem {
+            id: "interface".into(),
+            outcome: Ok(BatchSuccess::FetchInterface(FetchInterfaceResponse {
+                interface: "interface-v1".into(),
+                descriptor: InterfaceDescriptor {
+                    format: INTERFACE_FORMAT_V1.into(),
+                    documentation: None,
+                    types: vec![],
+                    operations: vec![],
+                },
+                validator: Some(vec![255, 254, 253]),
+            })),
+        }],
+    };
+    let encoded = encode_batch_response(&request, &response, limits()).unwrap();
+    assert!(
+        std::str::from_utf8(encoded.body())
+            .unwrap()
+            .contains("//79")
+    );
+    assert_eq!(
+        decode_batch_response(&request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(response)
+    );
+}
+
+#[test]
+fn malformed_known_method_arguments_are_item_local() {
+    let body = br#"{
+        "requests": [
+            {"id":"valid","method":"fetch","arguments":{"path":"/item"}},
+            {"id":"invalid","method":"fetch_tree","arguments":{"path":"/","depth":"deep","limit":1}}
+        ]
+    }"#;
+    let decoded = decode_batch_request(body, limits()).unwrap();
+    assert!(matches!(
+        decoded.requests[0].request,
+        BatchRequestKind::Fetch(_)
+    ));
+    let invalid = match &decoded.requests[1].request {
+        BatchRequestKind::Invalid { method, error } => {
+            assert_eq!(*method, BatchMethod::FetchTree);
+            assert_eq!(error.code, ProtocolErrorCode::InvalidRequest);
+            error.clone()
+        }
+        other => panic!("expected item-local invalid request, got {other:?}"),
+    };
+
+    let response = BatchResponse {
+        responses: vec![
+            BatchResponseItem {
+                id: "valid".into(),
+                outcome: Ok(BatchSuccess::Fetch(Object {
+                    name: "item".into(),
+                    description: None,
+                    interfaces: vec![],
+                    r#ref: None,
+                    validator: None,
+                })),
+            },
+            BatchResponseItem {
+                id: "invalid".into(),
+                outcome: Err(invalid),
+            },
+        ],
+    };
+    let encoded = encode_batch_response(&decoded, &response, limits()).unwrap();
+    assert_eq!(encoded.status(), StatusCode::OK);
+    assert_eq!(
+        decode_batch_response(&decoded, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(response)
+    );
+}
+
+#[test]
+fn invalid_batch_envelopes_are_rejected_at_top_level() {
+    assert!(decode_batch_request(br#"{}"#, limits()).is_err());
+
+    let malformed_item = br#"{
+        "requests": [
+            {"id":"item","method":"fetch","arguments":{"path":"/"},"extra":true}
+        ]
+    }"#;
+    assert!(decode_batch_request(malformed_item, limits()).is_err());
+
+    let duplicate = br#"{
+        "requests": [
+            {"id":"same","method":"fetch","arguments":{"path":"/a"}},
+            {"id":"same","method":"fetch","arguments":{"path":"/b"}}
+        ]
+    }"#;
+    assert!(decode_batch_request(duplicate, limits()).is_err());
+
+    let operation = br#"{
+        "requests": [
+            {"id":"call","method":"call_operation","arguments":{}}
+        ]
+    }"#;
+    assert!(decode_batch_request(operation, limits()).is_err());
+
+    let too_many = Limits::new(100_000, 100_000, 64, 1).unwrap();
+    assert!(decode_batch_request(duplicate, too_many).is_err());
+}
+
+#[test]
+fn batch_resource_limits_use_413_or_422_and_never_429() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::ResourceLimitExceeded,
+        message: "bounded".into(),
+    };
+    for (kind, status) in [
+        (
+            ResourceLimitKind::RepresentationBytes,
+            StatusCode::PAYLOAD_TOO_LARGE,
+        ),
+        (ResourceLimitKind::Logical, StatusCode::UNPROCESSABLE_ENTITY),
+    ] {
+        let encoded = encode_batch_resource_limit_error_response(&error, kind, limits()).unwrap();
+        assert_eq!(encoded.status(), status);
+        assert_ne!(encoded.status(), StatusCode::TOO_MANY_REQUESTS);
+        assert_eq!(
+            decode_batch_response(&request(), &encoded, limits()).unwrap(),
+            DecodedResponse::ProtocolFailure {
+                error: error.clone(),
+                status_mismatch: None,
+            }
+        );
+    }
+}
+
+#[test]
+fn batch_success_body_requires_exactly_http_200() {
+    let request = request();
+    let response = BatchResponse {
+        responses: vec![
+            BatchResponseItem {
+                id: "object".into(),
+                outcome: Ok(BatchSuccess::Fetch(Object {
+                    name: "item".into(),
+                    description: None,
+                    interfaces: vec![],
+                    r#ref: None,
+                    validator: None,
+                })),
+            },
+            BatchResponseItem {
+                id: "interface".into(),
+                outcome: Err(ProtocolError {
+                    code: ProtocolErrorCode::InterfaceNotFound,
+                    message: "gone".into(),
+                }),
+            },
+        ],
+    };
+    let encoded = encode_batch_response(&request, &response, limits()).unwrap();
+    for status in [StatusCode::CREATED, StatusCode::ACCEPTED] {
+        let mut noncanonical = encoded.clone();
+        *noncanonical.status_mut() = status;
+        assert!(matches!(
+            decode_batch_response(&request, &noncanonical, limits()).unwrap_err(),
+            ClientResponseError::InvalidResponse { .. }
+        ));
+    }
+}
+
+#[test]
+fn top_level_batch_errors_use_the_batch_allowed_code_set() {
+    let invalid = ProtocolError {
+        code: ProtocolErrorCode::InvalidRequest,
+        message: "bad envelope".into(),
+    };
+    let encoded = encode_batch_error_response(&invalid, limits()).unwrap();
+    assert_eq!(
+        decode_batch_response(&request(), &encoded, limits()).unwrap(),
+        DecodedResponse::ProtocolFailure {
+            error: invalid,
+            status_mismatch: None,
+        }
+    );
+
+    let not_found = wip_https::http::Response::builder()
+        .status(StatusCode::NOT_FOUND)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(br#"{"error":{"code":"not_found","message":"not a batch failure"}}"#.to_vec())
+        .unwrap();
+    assert!(matches!(
+        decode_batch_response(&request(), &not_found, limits()).unwrap_err(),
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidBatch,
+            ..
+        }
+    ));
+}
+
+#[test]
+fn unsupported_batch_descriptor_waits_for_envelope_correlation() {
+    let duplicate = wip_https::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(
+            br#"{"responses":[{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2","future":true}}},{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"}}}]}"#
+                .to_vec(),
+        )
+        .unwrap();
+    assert!(matches!(
+        decode_batch_response(&request(), &duplicate, limits()).unwrap_err(),
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidBatch,
+            ..
+        }
+    ));
+
+    let missing = wip_https::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(
+            br#"{"responses":[{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"}}}]}"#
+                .to_vec(),
+        )
+        .unwrap();
+    assert!(matches!(
+        decode_batch_response(&request(), &missing, limits()).unwrap_err(),
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidBatch,
+            ..
+        }
+    ));
+
+    let request = BatchRequest {
+        requests: vec![BatchRequestItem {
+            id: "interface".into(),
+            request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
+                interface: "interface-v1".into(),
+            }),
+        }],
+    };
+    assert!(matches!(
+        decode_batch_response(&request, &missing, limits()).unwrap_err(),
+        ClientResponseError::UnsupportedDescriptorFormat { format }
+            if format == "wip-interface/2"
+    ));
+}
+
+#[test]
+fn batch_response_must_have_exactly_the_requested_ids() {
+    let request = request();
+    let missing = BatchResponse {
+        responses: vec![BatchResponseItem {
+            id: "object".into(),
+            outcome: Ok(BatchSuccess::Fetch(Object {
+                name: "item".into(),
+                description: None,
+                interfaces: vec![],
+                r#ref: None,
+                validator: None,
+            })),
+        }],
+    };
+    assert!(encode_batch_response(&request, &missing, limits()).is_err());
+}

crates/wip-https/tests/codecs.rs

@@ -0,0 +1,508 @@
+use std::collections::BTreeMap;
+
+use wip_https::http::StatusCode;
+use wip_https::wip_protocol::{
+    CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
+    FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
+    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, Object,
+    ObjectTreeNode, OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target,
+    TypeDeclaration, TypeExpr, UnionCase, Value,
+};
+use wip_https::{
+    ClientResponseError, CodecError, DecodedResponse, Endpoint, InvalidResponseKind, Limits,
+    ResourceLimitKind, decode_call_operation_metadata, decode_call_operation_request,
+    decode_call_operation_response, decode_fetch_interface_request,
+    decode_fetch_interface_response, decode_fetch_request, decode_fetch_response,
+    decode_fetch_tree_request, decode_fetch_tree_response, encode_call_operation_request,
+    encode_call_operation_response, encode_fetch_interface_request,
+    encode_fetch_interface_response, encode_fetch_request, encode_fetch_response,
+    encode_fetch_tree_request, encode_fetch_tree_response,
+};
+
+fn limits() -> Limits {
+    Limits::new(1_000_000, 1_000_000, 100, 100).unwrap()
+}
+
+fn endpoint() -> Endpoint {
+    Endpoint::parse("https://example.test/wip").unwrap()
+}
+
+fn object(name: &str, validator: &[u8]) -> Object {
+    Object {
+        name: name.into(),
+        description: Some("description".into()),
+        interfaces: vec!["interface-v1".into()],
+        r#ref: Some(format!("object:{name}")),
+        validator: Some(validator.to_vec()),
+    }
+}
+
+fn descriptor() -> InterfaceDescriptor {
+    InterfaceDescriptor {
+        format: INTERFACE_FORMAT_V1.into(),
+        documentation: Some(Documentation {
+            summary: "Codec fixture".into(),
+            details: None,
+        }),
+        types: vec![TypeDeclaration {
+            name: "Pair".into(),
+            documentation: None,
+            definition: TypeExpr::Record {
+                fields: vec![
+                    FieldDeclaration {
+                        name: "required".into(),
+                        required: true,
+                        documentation: None,
+                        r#type: TypeExpr::String,
+                    },
+                    FieldDeclaration {
+                        name: "optional".into(),
+                        required: false,
+                        documentation: None,
+                        r#type: TypeExpr::String,
+                    },
+                    FieldDeclaration {
+                        name: "optional_json".into(),
+                        required: false,
+                        documentation: None,
+                        r#type: TypeExpr::Json,
+                    },
+                ],
+            },
+        }],
+        operations: vec![OperationDeclaration {
+            name: "everything".into(),
+            documentation: None,
+            parameters: vec![
+                parameter("unit", TypeExpr::Unit),
+                parameter("boolean", TypeExpr::Boolean),
+                parameter("integer", TypeExpr::Integer),
+                parameter("number", TypeExpr::Number),
+                parameter("string", TypeExpr::String),
+                parameter("bytes", TypeExpr::Bytes),
+                parameter("entry", TypeExpr::Entry),
+                parameter(
+                    "list",
+                    TypeExpr::List {
+                        items: Box::new(TypeExpr::Integer),
+                    },
+                ),
+                parameter(
+                    "record",
+                    TypeExpr::Named {
+                        name: "Pair".into(),
+                    },
+                ),
+                parameter(
+                    "enum",
+                    TypeExpr::Enum {
+                        cases: vec![EnumCase {
+                            name: "ready".into(),
+                            documentation: None,
+                        }],
+                    },
+                ),
+                parameter(
+                    "union",
+                    TypeExpr::Union {
+                        cases: vec![
+                            UnionCase {
+                                name: "empty".into(),
+                                documentation: None,
+                                payload: None,
+                            },
+                            UnionCase {
+                                name: "found".into(),
+                                documentation: None,
+                                payload: Some(TypeExpr::Entry),
+                            },
+                        ],
+                    },
+                ),
+                parameter("json", TypeExpr::Json),
+            ],
+            returns: ReturnDeclaration {
+                documentation: None,
+                r#type: TypeExpr::Bytes,
+            },
+        }],
+    }
+}
+
+fn parameter(name: &str, r#type: TypeExpr) -> ParameterDeclaration {
+    ParameterDeclaration {
+        name: name.into(),
+        required: true,
+        documentation: None,
+        r#type,
+    }
+}
+
+fn record(fields: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
+    Value::Record(
+        fields
+            .into_iter()
+            .map(|(name, value)| (name.into(), value))
+            .collect(),
+    )
+}
+
+fn call_request() -> CallOperationRequest {
+    CallOperationRequest {
+        target: Target {
+            path: "/items/123".into(),
+            validator: Some(vec![0, 1, 2, 255]),
+        },
+        interface: InterfaceTarget {
+            reference: "interface-v1".into(),
+            validator: Some(vec![9, 8, 7]),
+        },
+        operation: "everything".into(),
+        arguments: BTreeMap::from([
+            ("unit".into(), Value::Unit),
+            ("boolean".into(), Value::Boolean(true)),
+            ("integer".into(), Value::Integer(MAX_SAFE_INTEGER)),
+            ("number".into(), Value::Number(1.5)),
+            ("string".into(), Value::String("text".into())),
+            ("bytes".into(), Value::Bytes(vec![0, 1, 2, 255])),
+            ("entry".into(), Value::String("/items/123".into())),
+            (
+                "list".into(),
+                Value::List(vec![Value::Integer(1), Value::Integer(2)]),
+            ),
+            (
+                "record".into(),
+                record([("required", Value::String("present".into()))]),
+            ),
+            ("enum".into(), Value::String("ready".into())),
+            (
+                "union".into(),
+                record([
+                    ("$case", Value::String("found".into())),
+                    ("value", Value::String("/items/123".into())),
+                ]),
+            ),
+            (
+                "json".into(),
+                record([
+                    ("null", Value::Unit),
+                    ("number", Value::Integer(2)),
+                    ("path_like", Value::String("/not-an-entry".into())),
+                ]),
+            ),
+        ]),
+    }
+}
+
+#[test]
+fn every_single_interaction_request_accepts_json() {
+    let fetch =
+        encode_fetch_request(&endpoint(), &FetchRequest { path: "/".into() }, limits()).unwrap();
+    let fetch_tree = encode_fetch_tree_request(
+        &endpoint(),
+        &FetchTreeRequest {
+            path: "/".into(),
+            depth: 1,
+            limit: 1,
+        },
+        limits(),
+    )
+    .unwrap();
+    let fetch_interface = encode_fetch_interface_request(
+        &endpoint(),
+        &FetchInterfaceRequest {
+            interface: "interface-v1".into(),
+        },
+        limits(),
+    )
+    .unwrap();
+    let call = encode_call_operation_request(&endpoint(), &call_request(), &descriptor(), limits())
+        .unwrap();
+
+    for request in [fetch, fetch_tree, fetch_interface, call] {
+        assert_eq!(request.headers()["accept"], "application/json");
+    }
+}
+
+#[test]
+fn fetch_round_trips_direct_body_and_body_validator() {
+    let request = FetchRequest {
+        path: "/items/123".into(),
+    };
+    let encoded_request = encode_fetch_request(&endpoint(), &request, limits()).unwrap();
+    assert_eq!(encoded_request.uri().path(), "/wip/v1/fetch");
+    assert_eq!(
+        decode_fetch_request(encoded_request.body(), limits()).unwrap(),
+        request
+    );
+
+    let expected = object("123", &[0, 1, 2, 255]);
+    let encoded = encode_fetch_response(&request, &expected, limits()).unwrap();
+    assert_eq!(encoded.status(), StatusCode::OK);
+    assert_eq!(
+        decode_fetch_response(&request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(expected)
+    );
+    assert!(encoded.headers().get("etag").is_none());
+}
+
+#[test]
+fn tree_and_interface_round_trip_nested_logical_models() {
+    let tree_request = FetchTreeRequest {
+        path: "/items".into(),
+        depth: 1,
+        limit: 2,
+    };
+    let encoded_request = encode_fetch_tree_request(&endpoint(), &tree_request, limits()).unwrap();
+    assert_eq!(
+        decode_fetch_tree_request(encoded_request.body(), limits()).unwrap(),
+        tree_request
+    );
+    let tree = FetchTreeResponse {
+        root: ObjectTreeNode {
+            object: object("items", b"root-validator"),
+            children: vec![ObjectTreeNode {
+                object: object("123", b"child-validator"),
+                children: vec![],
+            }],
+        },
+        truncated: false,
+    };
+    let encoded = encode_fetch_tree_response(&tree_request, &tree, limits()).unwrap();
+    assert_eq!(
+        decode_fetch_tree_response(&tree_request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(tree)
+    );
+
+    let interface_request = FetchInterfaceRequest {
+        interface: "interface-v1".into(),
+    };
+    let encoded_request =
+        encode_fetch_interface_request(&endpoint(), &interface_request, limits()).unwrap();
+    assert_eq!(
+        decode_fetch_interface_request(encoded_request.body(), limits()).unwrap(),
+        interface_request
+    );
+    let interface = FetchInterfaceResponse {
+        interface: interface_request.interface.clone(),
+        descriptor: descriptor(),
+        validator: Some(vec![4, 5, 6, 255]),
+    };
+    let encoded =
+        encode_fetch_interface_response(&interface_request, &interface, limits()).unwrap();
+    assert_eq!(
+        decode_fetch_interface_response(&interface_request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(interface)
+    );
+}
+
+#[test]
+fn descriptor_guided_values_and_validators_round_trip_both_directions() {
+    let descriptor = descriptor();
+    let request = call_request();
+    let encoded =
+        encode_call_operation_request(&endpoint(), &request, &descriptor, limits()).unwrap();
+    let body = std::str::from_utf8(encoded.body()).unwrap();
+    assert!(body.contains("AAEC/w=="));
+    let metadata = decode_call_operation_metadata(encoded.body(), limits()).unwrap();
+    assert_eq!(metadata.target, request.target);
+    assert_eq!(metadata.interface, request.interface);
+    assert_eq!(metadata.operation, request.operation);
+    assert_eq!(
+        metadata
+            .decode_request(encoded.body(), &descriptor, limits())
+            .unwrap(),
+        request
+    );
+    let mut changed_route = request.clone();
+    changed_route.target.path = "/items/other".into();
+    let changed =
+        encode_call_operation_request(&endpoint(), &changed_route, &descriptor, limits()).unwrap();
+    assert!(
+        metadata
+            .decode_request(changed.body(), &descriptor, limits())
+            .is_err()
+    );
+
+    let mut null_json_request = request.clone();
+    null_json_request
+        .arguments
+        .insert("json".into(), Value::Unit);
+    null_json_request.arguments.insert(
+        "record".into(),
+        record([
+            ("required", Value::String("present".into())),
+            ("optional_json", Value::Unit),
+        ]),
+    );
+    let null_json =
+        encode_call_operation_request(&endpoint(), &null_json_request, &descriptor, limits())
+            .unwrap();
+    assert_eq!(
+        decode_call_operation_request(null_json.body(), &descriptor, limits()).unwrap(),
+        null_json_request
+    );
+
+    let expected = CallOperationResponse {
+        result: Value::Bytes(vec![255, 0, 1]),
+        validator: Some(vec![3, 2, 1, 0]),
+    };
+    let encoded =
+        encode_call_operation_response(&request, &descriptor, &expected, limits()).unwrap();
+    assert!(
+        std::str::from_utf8(encoded.body())
+            .unwrap()
+            .contains("/wAB")
+    );
+    assert_eq!(
+        decode_call_operation_response(&request, &descriptor, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(expected)
+    );
+}
+
+#[test]
+fn malformed_unknown_null_and_noncanonical_base64_are_rejected() {
+    let limits = limits();
+    assert!(decode_fetch_request(br#"{"path":"/","extra":true}"#, limits).is_err());
+    assert!(decode_fetch_request(br#"{"path":"relative","path":"/"}"#, limits).is_err());
+
+    let request = call_request();
+    let descriptor = descriptor();
+    let body = serde_json::to_vec(&serde_json::json!({
+        "target": {"path": "/items/123", "validator": null},
+        "interface": {"reference": "interface-v1"},
+        "operation": "everything",
+        "arguments": {}
+    }))
+    .unwrap();
+    assert!(decode_call_operation_request(&body, &descriptor, limits).is_err());
+
+    let mut json: serde_json::Value = serde_json::from_slice(
+        encode_call_operation_request(&endpoint(), &request, &descriptor, limits)
+            .unwrap()
+            .body(),
+    )
+    .unwrap();
+    json["arguments"]["bytes"] = serde_json::Value::String("AAEC_w==".into());
+    assert!(
+        decode_call_operation_request(&serde_json::to_vec(&json).unwrap(), &descriptor, limits)
+            .is_err()
+    );
+}
+
+#[test]
+fn caller_limits_bound_bytes_and_nesting() {
+    let tiny = Limits::new(8, 8, 2, 1).unwrap();
+    let too_large = decode_fetch_request(br#"{"path":"/long"}"#, tiny).unwrap_err();
+    assert!(matches!(&too_large, CodecError::BodyTooLarge { .. }));
+    assert_eq!(
+        too_large.resource_limit_kind(),
+        Some(ResourceLimitKind::RepresentationBytes)
+    );
+
+    let nested = br#"{"path":[[["/"]]]}"#;
+    let nesting_limited = Limits::new(1024, 1024, 2, 1).unwrap();
+    let too_deep = decode_fetch_request(nested, nesting_limited).unwrap_err();
+    assert!(matches!(&too_deep, CodecError::NestingTooDeep { .. }));
+    assert_eq!(
+        too_deep.resource_limit_kind(),
+        Some(ResourceLimitKind::Logical)
+    );
+
+    let outbound_limited = Limits::new(1_000_000, 1_000_000, 1, 10).unwrap();
+    assert!(
+        encode_call_operation_request(
+            &endpoint(),
+            &call_request(),
+            &descriptor(),
+            outbound_limited,
+        )
+        .is_err()
+    );
+    assert!(
+        encode_fetch_response(
+            &FetchRequest {
+                path: "/item".into(),
+            },
+            &object("item", b"validator"),
+            outbound_limited,
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn unsupported_descriptor_format_is_client_local() {
+    let request = FetchInterfaceRequest {
+        interface: "interface-v1".into(),
+    };
+    let mut interface = FetchInterfaceResponse {
+        interface: request.interface.clone(),
+        descriptor: descriptor(),
+        validator: None,
+    };
+    interface.descriptor.format = "future-format".into();
+    let response = encode_fetch_interface_response(&request, &interface, limits()).unwrap();
+    let error = decode_fetch_interface_response(&request, &response, limits()).unwrap_err();
+    assert!(matches!(
+        error,
+        ClientResponseError::UnsupportedDescriptorFormat { .. }
+    ));
+
+    let future_shape = wip_https::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(
+            br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2","future_shape":true}}"#
+                .to_vec(),
+        )
+        .unwrap();
+    assert!(matches!(
+        decode_fetch_interface_response(&request, &future_shape, limits()).unwrap_err(),
+        ClientResponseError::UnsupportedDescriptorFormat { format }
+            if format == "wip-interface/2"
+    ));
+
+    for malformed in [
+        br#"{"interface":"wrong","descriptor":{"format":"wip-interface/2"}}"#.as_slice(),
+        br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"},"validator":null}"#
+            .as_slice(),
+    ] {
+        let response = wip_https::http::Response::builder()
+            .status(StatusCode::OK)
+            .header("content-type", "application/json; charset=utf-8")
+            .body(malformed.to_vec())
+            .unwrap();
+        assert!(matches!(
+            decode_fetch_interface_response(&request, &response, limits()).unwrap_err(),
+            ClientResponseError::InvalidResponse {
+                kind: InvalidResponseKind::InvalidSuccessBody,
+                ..
+            }
+        ));
+    }
+}
+
+#[test]
+fn invalid_success_is_classified_as_invalid_response() {
+    let response = wip_https::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(br#"{"name":"wrong","interfaces":[]}"#.to_vec())
+        .unwrap();
+    let error = decode_fetch_response(
+        &FetchRequest {
+            path: "/expected".into(),
+        },
+        &response,
+        limits(),
+    )
+    .unwrap_err();
+    assert!(matches!(
+        error,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidSuccessBody,
+            ..
+        }
+    ));
+}

crates/wip-https/tests/responses.rs

@@ -0,0 +1,304 @@
+use wip_https::http::{Response, StatusCode};
+use wip_https::wip_protocol::{
+    FetchRequest, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
+};
+use wip_https::{
+    ClientResponseError, DecodedResponse, InvalidResponseKind, Limits, ResourceLimitKind,
+    TransportFailureKind, decode_fetch_response, encode_protocol_error_response,
+    encode_resource_limit_error_response, error_code_name, is_json_content_type, status_for_error,
+    status_for_resource_limit,
+};
+
+fn limits() -> Limits {
+    Limits::new(64 * 1024, 64 * 1024, 32, 16).unwrap()
+}
+
+fn request() -> FetchRequest {
+    FetchRequest { path: "/".into() }
+}
+
+fn response(status: StatusCode, body: impl Into<Vec<u8>>) -> Response<Vec<u8>> {
+    Response::builder()
+        .status(status)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(body.into())
+        .unwrap()
+}
+
+#[test]
+fn content_type_accepts_only_utf8_json_syntax() {
+    assert!(is_json_content_type("application/json"));
+    assert!(is_json_content_type("Application/JSON; Charset=\"UTF-8\""));
+    assert!(!is_json_content_type("application/json; charset=utf-16"));
+    assert!(!is_json_content_type("application/json; charset=\"utf-8"));
+    assert!(!is_json_content_type("application/json; charset=utf-8\""));
+    assert!(!is_json_content_type("application/json; profile=other"));
+}
+
+#[test]
+fn every_protocol_code_has_stable_name_and_status() {
+    let expected = [
+        (
+            ProtocolErrorCode::InvalidRequest,
+            "invalid_request",
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            ProtocolErrorCode::NotFound,
+            "not_found",
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            ProtocolErrorCode::InterfaceNotFound,
+            "interface_not_found",
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            ProtocolErrorCode::InterfaceMismatch,
+            "interface_mismatch",
+            StatusCode::CONFLICT,
+        ),
+        (
+            ProtocolErrorCode::OperationNotFound,
+            "operation_not_found",
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            ProtocolErrorCode::InvalidArguments,
+            "invalid_arguments",
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+        (
+            ProtocolErrorCode::ValidatorRequired,
+            "validator_required",
+            StatusCode::PRECONDITION_REQUIRED,
+        ),
+        (
+            ProtocolErrorCode::ValidatorMismatch,
+            "validator_mismatch",
+            StatusCode::PRECONDITION_FAILED,
+        ),
+        (
+            ProtocolErrorCode::InterfaceValidatorRequired,
+            "interface_validator_required",
+            StatusCode::PRECONDITION_REQUIRED,
+        ),
+        (
+            ProtocolErrorCode::InterfaceValidatorMismatch,
+            "interface_validator_mismatch",
+            StatusCode::PRECONDITION_FAILED,
+        ),
+        (
+            ProtocolErrorCode::PermissionDenied,
+            "permission_denied",
+            StatusCode::FORBIDDEN,
+        ),
+        (
+            ProtocolErrorCode::ResourceLimitExceeded,
+            "resource_limit_exceeded",
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+        (
+            ProtocolErrorCode::Internal,
+            "internal",
+            StatusCode::INTERNAL_SERVER_ERROR,
+        ),
+        (
+            ProtocolErrorCode::OperationOutcomeUnknown,
+            "operation_outcome_unknown",
+            StatusCode::INTERNAL_SERVER_ERROR,
+        ),
+    ];
+    assert_eq!(expected.len(), ProtocolErrorCode::ALL.len());
+    for (code, name, status) in expected {
+        assert_eq!(error_code_name(code), name);
+        assert_eq!(status_for_error(code), status);
+    }
+}
+
+#[test]
+fn resource_limit_statuses_encode_and_decode_by_concrete_limit_class() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::ResourceLimitExceeded,
+        message: "bounded".into(),
+    };
+    let cases = [
+        (
+            ResourceLimitKind::RepresentationBytes,
+            StatusCode::PAYLOAD_TOO_LARGE,
+        ),
+        (ResourceLimitKind::Logical, StatusCode::UNPROCESSABLE_ENTITY),
+    ];
+    for (kind, status) in cases {
+        assert_eq!(status_for_resource_limit(kind), status);
+        let encoded = encode_resource_limit_error_response(
+            ProtocolInteraction::Fetch,
+            &error,
+            kind,
+            limits(),
+        )
+        .unwrap();
+        assert_eq!(encoded.status(), status);
+        assert_eq!(
+            decode_fetch_response(&request(), &encoded, limits()).unwrap(),
+            DecodedResponse::ProtocolFailure {
+                error: error.clone(),
+                status_mismatch: None,
+            }
+        );
+    }
+
+    let default =
+        encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
+    assert_eq!(default.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    assert_ne!(default.status(), StatusCode::TOO_MANY_REQUESTS);
+}
+
+#[test]
+fn rate_limit_status_without_protocol_envelope_stays_transport_failure() {
+    let response = Response::builder()
+        .status(StatusCode::TOO_MANY_REQUESTS)
+        .body(b"rate limited".to_vec())
+        .unwrap();
+    assert!(matches!(
+        decode_fetch_response(&request(), &response, limits()).unwrap_err(),
+        ClientResponseError::TransportBinding(failure)
+            if failure.status == StatusCode::TOO_MANY_REQUESTS
+                && failure.kind == TransportFailureKind::HttpStatus
+    ));
+}
+
+#[test]
+fn valid_success_body_requires_exactly_http_200() {
+    let success_body = br#"{"name":"","interfaces":[]}"#;
+    for status in [StatusCode::CREATED, StatusCode::ACCEPTED] {
+        assert!(matches!(
+            decode_fetch_response(&request(), &response(status, success_body), limits())
+                .unwrap_err(),
+            ClientResponseError::InvalidResponse {
+                kind: InvalidResponseKind::NonCanonicalSuccessStatus,
+                ..
+            }
+        ));
+    }
+}
+
+#[test]
+fn server_encoder_rejects_codes_disallowed_for_the_interaction() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::InterfaceNotFound,
+        message: "not valid for fetch".into(),
+    };
+    assert!(encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).is_err());
+}
+
+#[test]
+fn valid_envelope_code_is_authoritative_when_status_mismatches() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::NotFound,
+        message: "missing".into(),
+    };
+    let mut encoded =
+        encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
+    *encoded.status_mut() = StatusCode::IM_A_TEAPOT;
+
+    assert_eq!(
+        decode_fetch_response(&request(), &encoded, limits()).unwrap(),
+        DecodedResponse::ProtocolFailure {
+            error,
+            status_mismatch: Some(wip_https::StatusMismatch {
+                actual: StatusCode::IM_A_TEAPOT,
+                expected: StatusCode::NOT_FOUND,
+            }),
+        }
+    );
+}
+
+#[test]
+fn envelope_and_status_contradictions_are_invalid_responses() {
+    let error_body = br#"{"error":{"code":"not_found","message":"missing"}}"#;
+    let on_success =
+        decode_fetch_response(&request(), &response(StatusCode::OK, error_body), limits())
+            .unwrap_err();
+    assert!(matches!(
+        on_success,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::ErrorEnvelopeOnSuccessStatus,
+            ..
+        }
+    ));
+
+    let success_body = br#"{"name":"","interfaces":[]}"#;
+    let on_error = decode_fetch_response(
+        &request(),
+        &response(StatusCode::BAD_GATEWAY, success_body),
+        limits(),
+    )
+    .unwrap_err();
+    assert!(matches!(
+        on_error,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::SuccessBodyOnErrorStatus,
+            ..
+        }
+    ));
+}
+
+#[test]
+fn disallowed_protocol_code_is_invalid_instead_of_reclassified() {
+    let body = br#"{"error":{"code":"interface_not_found","message":"wrong interaction"}}"#;
+    let error = decode_fetch_response(&request(), &response(StatusCode::NOT_FOUND, body), limits())
+        .unwrap_err();
+    assert!(matches!(
+        error,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::DisallowedProtocolCode,
+            ..
+        }
+    ));
+}
+
+#[test]
+fn proxy_authentication_and_endpoint_failures_stay_transport_failures() {
+    let cases = [
+        (
+            StatusCode::BAD_GATEWAY,
+            TransportFailureKind::HttpStatus,
+            b"proxy failure".as_slice(),
+        ),
+        (
+            StatusCode::UNAUTHORIZED,
+            TransportFailureKind::AuthenticationRequired,
+            b"login required".as_slice(),
+        ),
+        (
+            StatusCode::FORBIDDEN,
+            TransportFailureKind::EndpointForbidden,
+            b"denied".as_slice(),
+        ),
+    ];
+    for (status, expected_kind, body) in cases {
+        let response = Response::builder()
+            .status(status)
+            .body(body.to_vec())
+            .unwrap();
+        let error = decode_fetch_response(&request(), &response, limits()).unwrap_err();
+        assert!(matches!(
+            error,
+            ClientResponseError::TransportBinding(failure)
+                if failure.status == status && failure.kind == expected_kind
+        ));
+    }
+}
+
+#[test]
+fn malformed_non_success_envelope_is_transport_binding_failure() {
+    let malformed = response(
+        StatusCode::BAD_GATEWAY,
+        br#"{"error":{"code":"not_found","message":null}}"#,
+    );
+    assert!(matches!(
+        decode_fetch_response(&request(), &malformed, limits()).unwrap_err(),
+        ClientResponseError::TransportBinding(_)
+    ));
+}

crates/wip-https/tests/routes.rs

@@ -0,0 +1,127 @@
+use wip_https::http::{Method, Request, StatusCode};
+use wip_https::{Endpoint, RequestMetadataError, Route, validate_http_request};
+
+#[test]
+fn endpoint_is_https_absolute_queryless_and_canonical() {
+    let endpoint = Endpoint::parse("https://example.test/root/prefix").unwrap();
+    assert_eq!(endpoint.to_string(), "https://example.test/root/prefix/");
+
+    let expected = [
+        (Route::Fetch, "https://example.test/root/prefix/v1/fetch"),
+        (
+            Route::FetchTree,
+            "https://example.test/root/prefix/v1/fetch_tree",
+        ),
+        (
+            Route::FetchInterface,
+            "https://example.test/root/prefix/v1/fetch_interface",
+        ),
+        (
+            Route::CallOperation,
+            "https://example.test/root/prefix/v1/call_operation",
+        ),
+        (Route::Batch, "https://example.test/root/prefix/v1/batch"),
+    ];
+    for (route, url) in expected {
+        assert_eq!(endpoint.route(route).as_str(), url);
+        assert_eq!(
+            endpoint.recognize(&wip_https::url::Url::parse(url).unwrap()),
+            Some(route)
+        );
+    }
+    assert_eq!(
+        endpoint.recognize(
+            &wip_https::url::Url::parse("https://example.test/root/prefix/v1/fetch?path=/items")
+                .unwrap()
+        ),
+        None
+    );
+}
+
+#[test]
+fn routes_never_mix_worldspace_paths_into_endpoint_prefixes() {
+    let endpoint = Endpoint::parse("https://example.test/wip/%E4%B8%96%E7%95%8C/").unwrap();
+    let route = endpoint.route(Route::Fetch);
+    assert_eq!(route.path(), "/wip/%E4%B8%96%E7%95%8C/v1/fetch");
+    assert!(!route.as_str().contains("items"));
+}
+
+#[test]
+fn inbound_http_metadata_enforces_post_route_and_json() {
+    let endpoint = Endpoint::parse("https://example.test/wip").unwrap();
+    let valid = Request::builder()
+        .method(Method::POST)
+        .uri("/wip/v1/fetch")
+        .header("content-type", "application/json; charset=utf-8")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    assert!(validate_http_request(&endpoint, Route::Fetch, &valid).is_ok());
+
+    let wrong_method = Request::builder()
+        .method(Method::GET)
+        .uri("/wip/v1/fetch")
+        .header("content-type", "application/json")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    assert!(validate_http_request(&endpoint, Route::Fetch, &wrong_method).is_err());
+
+    let wrong_route = Request::builder()
+        .method(Method::POST)
+        .uri("/wip/v1/fetch_tree")
+        .header("content-type", "application/json")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    assert!(validate_http_request(&endpoint, Route::Fetch, &wrong_route).is_err());
+
+    for accept in [
+        "text/plain, */*;q=1, application/json;q=0",
+        "application/json; charset=utf-16",
+        "application/json; profile=future",
+    ] {
+        let incompatible_accept = Request::builder()
+            .method(Method::POST)
+            .uri("/wip/v1/fetch")
+            .header("content-type", "application/json")
+            .header("accept", accept)
+            .body(Vec::<u8>::new())
+            .unwrap();
+        let error =
+            validate_http_request(&endpoint, Route::Fetch, &incompatible_accept).unwrap_err();
+        assert!(matches!(&error, RequestMetadataError::NotAcceptable));
+        assert_eq!(error.status(), StatusCode::NOT_ACCEPTABLE);
+    }
+
+    for accept in [
+        "application/json; charset=UTF-8",
+        "application/json; q=1; profile=accept-extension",
+    ] {
+        let compatible_accept = Request::builder()
+            .method(Method::POST)
+            .uri("/wip/v1/fetch")
+            .header("content-type", "application/json")
+            .header("accept", accept)
+            .body(Vec::<u8>::new())
+            .unwrap();
+        assert!(validate_http_request(&endpoint, Route::Fetch, &compatible_accept).is_ok());
+    }
+
+    let unsupported_media_type = Request::builder()
+        .method(Method::POST)
+        .uri("/wip/v1/fetch")
+        .header("content-type", "text/plain")
+        .header("accept", "application/json")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    let error =
+        validate_http_request(&endpoint, Route::Fetch, &unsupported_media_type).unwrap_err();
+    assert!(matches!(&error, RequestMetadataError::UnsupportedMediaType));
+    assert_eq!(error.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
+}
+
+#[test]
+fn invalid_endpoint_components_are_rejected() {
+    assert!(Endpoint::parse("http://example.test/wip").is_err());
+    assert!(Endpoint::parse("/relative").is_err());
+    assert!(Endpoint::parse("https://example.test/wip?q=1").is_err());
+    assert!(Endpoint::parse("https://example.test/wip#fragment").is_err());
+}

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

@@ -1,4 +1,10 @@
 //! Procedural macros backing the public `wip-interface` authoring facade.
+//!
+//! This is an implementation crate. Applications should depend on
+//! `wip-interface`, which re-exports both macros alongside the traits and types
+//! used by their generated code.
+
+#![deny(missing_docs)]
 
 use std::collections::HashSet;
 
@@ -162,14 +168,40 @@ fn expand_interface(attribute: TokenStream2, item: ItemTrait) -> syn::Result<Tok
                 #(#declaration_collectors)*
 
                 ::wip_interface::wip_protocol::InterfaceDescriptor {
-                    name: ::std::string::String::from(stringify!(#trait_ident)),
+                    format: ::std::string::String::from(
+                        ::wip_interface::wip_protocol::INTERFACE_FORMAT_V1,
+                    ),
                     documentation: #trait_doc,
-                    declarations,
+                    types: declarations,
                     operations: ::std::vec![#(#operation_declarations),*],
                 }
             }
         }
 
+        impl<T: #trait_ident> ::wip_interface::InterfaceImplementation<T> for #definition_ident {
+            fn dispatch(
+                implementation: &T,
+                operation: &str,
+                arguments: ::std::collections::BTreeMap<
+                    ::std::string::String,
+                    ::wip_interface::wip_protocol::Value,
+                >,
+            ) -> ::std::result::Result<
+                ::wip_interface::wip_protocol::Value,
+                ::wip_interface::DispatchError,
+            > {
+                let descriptor = Self::descriptor();
+                match operation {
+                    #(#dispatch_arms)*
+                    _ => ::std::result::Result::Err(
+                        ::wip_interface::DispatchError::UnknownOperation(
+                            ::std::string::String::from(operation),
+                        ),
+                    ),
+                }
+            }
+        }
+
         impl #definition_ident {
             /// Builds the interface descriptor generated from the trait declaration.
             pub fn descriptor() -> ::wip_interface::wip_protocol::InterfaceDescriptor {
@@ -180,20 +212,19 @@ fn expand_interface(attribute: TokenStream2, item: ItemTrait) -> syn::Result<Tok
             pub fn dispatch<T: #trait_ident>(
                 implementation: &T,
                 operation: &str,
-                arguments: ::std::vec::Vec<::wip_interface::wip_protocol::NamedValue>,
+                arguments: ::std::collections::BTreeMap<
+                    ::std::string::String,
+                    ::wip_interface::wip_protocol::Value,
+                >,
             ) -> ::std::result::Result<
-                ::std::option::Option<::wip_interface::wip_protocol::Value>,
+                ::wip_interface::wip_protocol::Value,
                 ::wip_interface::DispatchError,
             > {
-                let descriptor = Self::descriptor();
+                <Self as ::wip_interface::InterfaceImplementation<T>>::dispatch(
-                match operation {
+                    implementation,
-                    #(#dispatch_arms)*
+                    operation,
-                    _ => ::std::result::Result::Err(
+                    arguments,
-                        ::wip_interface::DispatchError::UnknownOperation(
+                )
-                            ::std::string::String::from(operation),
-                        ),
-                    ),
-                }
             }
         }
 
@@ -453,13 +484,18 @@ fn parse_operation_result(output: &ReturnType) -> syn::Result<Type> {
         _ => None,
     });
     let result = types.next().cloned();
-    if arguments.args.len() != 1 || result.is_none() || types.next().is_some() {
+    if arguments.args.len() != 1 || types.next().is_some() {
         return Err(Error::new_spanned(
             arguments,
             "`OperationResult` must have exactly one application result type",
         ));
     }
-    let result = result.expect("checked above");
+    let result = result.ok_or_else(|| {
+        Error::new_spanned(
+            arguments,
+            "`OperationResult` must have exactly one application result type",
+        )
+    })?;
     if direct_option(&result)?.is_some() || contains_option(&result) {
         return Err(Error::new_spanned(
             result,
@@ -473,8 +509,13 @@ fn argument_item(operation: &Operation) -> TokenStream2 {
     let arguments_ident = &operation.arguments_ident;
     let fields = operation.parameters.iter().map(|parameter| {
         let ident = &parameter.ident;
+        let name = &parameter.name;
         let ty = parameter_rust_type(parameter);
-        quote!(pub #ident: #ty)
+        let documentation = format!("Decoded `{name}` operation argument.");
+        quote!(
+            #[doc = #documentation]
+            pub #ident: #ty
+        )
     });
     let decoders = operation.parameters.iter().map(|parameter| {
         let ident = &parameter.ident;
@@ -490,12 +531,11 @@ fn argument_item(operation: &Operation) -> TokenStream2 {
     let encode_result = if operation.unit_result {
         quote! {
             let () = result;
-            ::std::result::Result::Ok(::std::option::Option::None)
+            ::std::result::Result::Ok(::wip_interface::wip_protocol::Value::Unit)
         }
     } else {
         quote! {
             <#result_ty as ::wip_interface::WipType>::encode(result)
-                .map(::std::option::Option::Some)
         }
     };
 
@@ -508,9 +548,12 @@ fn argument_item(operation: &Operation) -> TokenStream2 {
         impl #arguments_ident {
             /// Decodes named logical values into typed operation arguments.
             pub fn decode(
-                arguments: ::std::vec::Vec<::wip_interface::wip_protocol::NamedValue>,
+                arguments: ::std::collections::BTreeMap<
+                    ::std::string::String,
+                    ::wip_interface::wip_protocol::Value,
+                >,
             ) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
-                let mut decoder = ::wip_interface::__private::RecordDecoder::new(arguments)?;
+                let mut decoder = ::wip_interface::__private::RecordDecoder::new(arguments);
                 let decoded = Self {
                     #(#decoders,)*
                 };
@@ -522,7 +565,7 @@ fn argument_item(operation: &Operation) -> TokenStream2 {
             pub fn encode_result(
                 result: #result_ty,
             ) -> ::std::result::Result<
-                ::std::option::Option<::wip_interface::wip_protocol::Value>,
+                ::wip_interface::wip_protocol::Value,
                 ::wip_interface::CodecError,
             > {
                 #encode_result
@@ -542,22 +585,18 @@ fn operation_declaration(operation: &Operation) -> TokenStream2 {
         quote! {
             ::wip_interface::wip_protocol::ParameterDeclaration {
                 name: ::std::string::String::from(#parameter_name),
+                required: !#optional,
                 documentation: #parameter_doc,
-                ty: <#ty as ::wip_interface::WipType>::type_expr(),
+                r#type: <#ty as ::wip_interface::WipType>::type_expr(),
-                optional: #optional,
             }
         }
     });
-    let returns = if operation.unit_result {
-        quote!(::std::option::Option::None)
-    } else {
     let result_ty = &operation.result_ty;
     let return_doc = documentation_tokens(operation.return_documentation.as_ref());
-        quote! {
+    let returns = quote! {
-            ::std::option::Option::Some(::wip_interface::wip_protocol::ReturnDeclaration {
+        ::wip_interface::wip_protocol::ReturnDeclaration {
             documentation: #return_doc,
-                ty: <#result_ty as ::wip_interface::WipType>::type_expr(),
+            r#type: <#result_ty as ::wip_interface::WipType>::type_expr(),
-            })
         }
     };
 
@@ -608,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)?;
+            ::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_return(#operation_name, encoded.as_ref())
+                    .validate_result(#operation_name, &encoded)
                     .map_err(::wip_interface::DispatchError::InvalidResult)?;
                 ::std::result::Result::Ok(encoded)
+            }))
+            .map_err(|_| ::wip_interface::DispatchError::Panic)?
         }
     }
 }
@@ -681,7 +723,12 @@ fn derive_record(
     let mut parsed_fields = Vec::new();
     let mut names = HashSet::new();
     for field in fields {
-        let field_ident = field.ident.clone().expect("named fields have identifiers");
+        let Some(field_ident) = field.ident.clone() else {
+            return Err(Error::new_spanned(
+                field,
+                "`WipType` record fields must be named",
+            ));
+        };
         let name = source_name(&field_ident);
         if !names.insert(name.clone()) {
             return Err(Error::new(
@@ -709,9 +756,9 @@ fn derive_record(
         quote! {
             ::wip_interface::wip_protocol::FieldDeclaration {
                 name: ::std::string::String::from(#name),
+                required: !#optional,
                 documentation: #documentation,
-                ty: <#ty as ::wip_interface::WipType>::type_expr(),
+                r#type: <#ty as ::wip_interface::WipType>::type_expr(),
-                optional: #optional,
             }
         }
     });
@@ -727,18 +774,18 @@ fn derive_record(
         if field.optional {
             quote! {
                 if let ::std::option::Option::Some(value) = #field_ident {
-                    fields.push(::wip_interface::wip_protocol::NamedValue {
+                    fields.insert(
-                        name: ::std::string::String::from(#field_name),
+                        ::std::string::String::from(#field_name),
-                        value: <#ty as ::wip_interface::WipType>::encode(value)?,
+                        <#ty as ::wip_interface::WipType>::encode(value)?,
-                    });
+                    );
                 }
             }
         } else {
             quote! {
-                fields.push(::wip_interface::wip_protocol::NamedValue {
+                fields.insert(
-                    name: ::std::string::String::from(#field_name),
+                    ::std::string::String::from(#field_name),
-                    value: <#ty as ::wip_interface::WipType>::encode(#field_ident)?,
+                    <#ty as ::wip_interface::WipType>::encode(#field_ident)?,
-                });
+                );
             }
         }
     });
@@ -756,9 +803,9 @@ fn derive_record(
     Ok(quote! {
         impl ::wip_interface::WipType for #ident {
             fn type_expr() -> ::wip_interface::wip_protocol::TypeExpr {
-                ::wip_interface::wip_protocol::TypeExpr::Named(
+                ::wip_interface::wip_protocol::TypeExpr::Named {
-                    ::std::string::String::from(#type_name),
+                    name: ::std::string::String::from(#type_name),
-                )
+                }
             }
 
             fn collect_declarations(
@@ -766,13 +813,13 @@ fn derive_record(
                     ::wip_interface::wip_protocol::TypeDeclaration,
                 >,
             ) {
-                let declaration = ::wip_interface::wip_protocol::TypeDeclaration::Record(
+                let declaration = ::wip_interface::wip_protocol::TypeDeclaration {
-                    ::wip_interface::wip_protocol::RecordDeclaration {
                     name: ::std::string::String::from(#type_name),
                     documentation: #declaration_doc,
+                    definition: ::wip_interface::wip_protocol::TypeExpr::Record {
                         fields: ::std::vec![#(#field_declarations),*],
                     },
-                );
+                };
                 if ::wip_interface::__private::register_declaration(declarations, declaration) {
                     #(#dependency_collectors)*
                 }
@@ -785,7 +832,7 @@ fn derive_record(
                 ::wip_interface::CodecError,
             > {
                 let Self { #(#destructured_fields),* } = self;
-                let mut fields = ::std::vec::Vec::new();
+                let mut fields = ::std::collections::BTreeMap::new();
                 #(#encoders)*
                 ::std::result::Result::Ok(
                     ::wip_interface::wip_protocol::Value::Record(fields),
@@ -797,7 +844,7 @@ fn derive_record(
             ) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
                 match value {
                     ::wip_interface::wip_protocol::Value::Record(fields) => {
-                        let mut decoder = ::wip_interface::__private::RecordDecoder::new(fields)?;
+                        let mut decoder = ::wip_interface::__private::RecordDecoder::new(fields);
                         let decoded = Self {
                             #(#decoders,)*
                         };
@@ -832,14 +879,14 @@ fn derive_enum(
         .variants
         .iter()
         .all(|variant| matches!(variant.fields, Fields::Unit));
-    let all_payload = !data.variants.is_empty()
+    let valid_union = data.variants.iter().all(|variant| {
-        && data.variants.iter().all(|variant| {
+        matches!(variant.fields, Fields::Unit)
-            matches!(&variant.fields, Fields::Unnamed(fields) if fields.unnamed.len() == 1)
+            || matches!(&variant.fields, Fields::Unnamed(fields) if fields.unnamed.len() == 1)
     });
 
     if all_unit {
         derive_unit_enum(ident, type_name, type_documentation, data)
-    } else if all_payload {
+    } else if valid_union {
         derive_union_enum(ident, type_name, type_documentation, data)
     } else {
         let span = data
@@ -852,7 +899,7 @@ fn derive_enum(
             .map_or_else(|| data.enum_token.span, Spanned::span);
         Err(Error::new(
             span,
-            "a `WipType` enum must contain either only unit variants or only single-field tuple variants; mixed and named-field variants are unsupported",
+            "a `WipType` enum must contain unit variants and/or single-field tuple variants; named-field and multi-field variants are unsupported",
         ))
     }
 }
@@ -868,7 +915,7 @@ fn derive_unit_enum(
         let name = source_name(&variant.ident);
         let documentation = documentation_tokens(documentation(&variant.attrs).as_ref());
         quote! {
-            ::wip_interface::wip_protocol::EnumVariantDeclaration {
+            ::wip_interface::wip_protocol::EnumCase {
                 name: ::std::string::String::from(#name),
                 documentation: #documentation,
             }
@@ -888,9 +935,9 @@ fn derive_unit_enum(
     Ok(quote! {
         impl ::wip_interface::WipType for #ident {
             fn type_expr() -> ::wip_interface::wip_protocol::TypeExpr {
-                ::wip_interface::wip_protocol::TypeExpr::Named(
+                ::wip_interface::wip_protocol::TypeExpr::Named {
-                    ::std::string::String::from(#type_name),
+                    name: ::std::string::String::from(#type_name),
-                )
+                }
             }
 
             fn collect_declarations(
@@ -898,13 +945,13 @@ fn derive_unit_enum(
                     ::wip_interface::wip_protocol::TypeDeclaration,
                 >,
             ) {
-                let declaration = ::wip_interface::wip_protocol::TypeDeclaration::Enum(
+                let declaration = ::wip_interface::wip_protocol::TypeDeclaration {
-                    ::wip_interface::wip_protocol::EnumDeclaration {
                     name: ::std::string::String::from(#type_name),
                     documentation: #declaration_doc,
-                        variants: ::std::vec![#(#declarations),*],
+                    definition: ::wip_interface::wip_protocol::TypeExpr::Enum {
+                        cases: ::std::vec![#(#declarations),*],
                     },
-                );
+                };
                 let _ = ::wip_interface::__private::register_declaration(
                     declarations,
                     declaration,
@@ -921,7 +968,7 @@ fn derive_unit_enum(
                     #(#encoders,)*
                 };
                 ::std::result::Result::Ok(
-                    ::wip_interface::wip_protocol::Value::Enum(
+                    ::wip_interface::wip_protocol::Value::String(
                         ::std::string::String::from(variant),
                     ),
                 )
@@ -931,7 +978,7 @@ fn derive_unit_enum(
                 value: ::wip_interface::wip_protocol::Value,
             ) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
                 match value {
-                    ::wip_interface::wip_protocol::Value::Enum(variant) => {
+                    ::wip_interface::wip_protocol::Value::String(variant) => {
                         match variant.as_str() {
                             #(#decoders,)*
                             _ => ::std::result::Result::Err(
@@ -960,30 +1007,36 @@ fn derive_union_enum(
     struct Variant<'a> {
         ident: &'a Ident,
         name: String,
-        ty: &'a Type,
+        payload: Option<&'a Type>,
         documentation: Option<Documentation>,
     }
 
     let mut variants = Vec::new();
     for variant in &data.variants {
-        let Fields::Unnamed(fields) = &variant.fields else {
+        let payload = match &variant.fields {
-            unreachable!("enum shape was checked before union generation");
+            Fields::Unit => None,
-        };
+            Fields::Unnamed(fields) if fields.unnamed.len() == 1 => {
-        let field = fields
+                let field = fields.unnamed.first().expect("length checked");
-            .unnamed
-            .first()
-            .expect("union variants have one field");
                 if direct_option(&field.ty)?.is_some() || contains_option(&field.ty) {
                     return Err(Error::new_spanned(
                         &field.ty,
                         "`Option<T>` is only supported directly on DTO fields and operation parameters",
                     ));
                 }
-        validate_value_type(&field.ty, "union variant payload")?;
+                validate_value_type(&field.ty, "union case payload")?;
+                Some(&field.ty)
+            }
+            _ => {
+                return Err(Error::new_spanned(
+                    variant,
+                    "a `WipType` union case must be unit-like or contain exactly one unnamed payload",
+                ));
+            }
+        };
         variants.push(Variant {
             ident: &variant.ident,
             name: source_name(&variant.ident),
-            ty: &field.ty,
+            payload,
             documentation: documentation(&variant.attrs),
         });
     }
@@ -992,50 +1045,95 @@ fn derive_union_enum(
     let declarations = variants.iter().map(|variant| {
         let name = &variant.name;
         let documentation = documentation_tokens(variant.documentation.as_ref());
-        let ty = variant.ty;
+        let payload = match variant.payload {
+            Some(ty) => quote! {
+                ::std::option::Option::Some(
+                    <#ty as ::wip_interface::WipType>::type_expr(),
+                )
+            },
+            None => quote!(::std::option::Option::None),
+        };
         quote! {
-            ::wip_interface::wip_protocol::UnionVariantDeclaration {
+            ::wip_interface::wip_protocol::UnionCase {
                 name: ::std::string::String::from(#name),
                 documentation: #documentation,
-                ty: <#ty as ::wip_interface::WipType>::type_expr(),
+                payload: #payload,
             }
         }
     });
-    let dependency_collectors = variants.iter().map(|variant| {
+    let dependency_collectors = variants.iter().filter_map(|variant| {
-        let ty = variant.ty;
+        variant.payload.map(
-        quote!(<#ty as ::wip_interface::WipType>::collect_declarations(declarations);)
+            |ty| quote!(<#ty as ::wip_interface::WipType>::collect_declarations(declarations);),
+        )
     });
     let encoders = variants.iter().map(|variant| {
         let variant_ident = variant.ident;
         let name = &variant.name;
-        let ty = variant.ty;
+        match variant.payload {
-        quote! {
+            Some(ty) => quote! {
                 Self::#variant_ident(value) => {
-                ::wip_interface::wip_protocol::Value::Union {
+                    let mut fields = ::std::collections::BTreeMap::new();
-                    variant: ::std::string::String::from(#name),
+                    fields.insert(
-                    value: ::std::boxed::Box::new(
+                        ::std::string::String::from(
-                        <#ty as ::wip_interface::WipType>::encode(value)?,
+                            ::wip_interface::wip_protocol::UNION_CASE_FIELD,
                         ),
+                        ::wip_interface::wip_protocol::Value::String(
+                            ::std::string::String::from(#name),
+                        ),
+                    );
+                    fields.insert(
+                        ::std::string::String::from(
+                            ::wip_interface::wip_protocol::UNION_VALUE_FIELD,
+                        ),
+                        <#ty as ::wip_interface::WipType>::encode(value)?,
+                    );
+                    ::wip_interface::wip_protocol::Value::Record(fields)
                 }
+            },
+            None => quote! {
+                Self::#variant_ident => {
+                    let mut fields = ::std::collections::BTreeMap::new();
+                    fields.insert(
+                        ::std::string::String::from(
+                            ::wip_interface::wip_protocol::UNION_CASE_FIELD,
+                        ),
+                        ::wip_interface::wip_protocol::Value::String(
+                            ::std::string::String::from(#name),
+                        ),
+                    );
+                    ::wip_interface::wip_protocol::Value::Record(fields)
                 }
+            },
         }
     });
     let decoders = variants.iter().map(|variant| {
         let variant_ident = variant.ident;
         let name = &variant.name;
-        let ty = variant.ty;
+        match variant.payload {
-        quote! {
+            Some(ty) => quote! {
-            #name => <#ty as ::wip_interface::WipType>::decode(*value)
+                #name => {
-                .map(Self::#variant_ident)
+                    let value = decoder.required::<#ty>(
+                        ::wip_interface::wip_protocol::UNION_VALUE_FIELD,
+                    )?;
+                    decoder.finish()?;
+                    ::std::result::Result::Ok(Self::#variant_ident(value))
+                }
+            },
+            None => quote! {
+                #name => {
+                    decoder.finish()?;
+                    ::std::result::Result::Ok(Self::#variant_ident)
+                }
+            },
         }
     });
 
     Ok(quote! {
         impl ::wip_interface::WipType for #ident {
             fn type_expr() -> ::wip_interface::wip_protocol::TypeExpr {
-                ::wip_interface::wip_protocol::TypeExpr::Named(
+                ::wip_interface::wip_protocol::TypeExpr::Named {
-                    ::std::string::String::from(#type_name),
+                    name: ::std::string::String::from(#type_name),
-                )
+                }
             }
 
             fn collect_declarations(
@@ -1043,13 +1141,13 @@ fn derive_union_enum(
                     ::wip_interface::wip_protocol::TypeDeclaration,
                 >,
             ) {
-                let declaration = ::wip_interface::wip_protocol::TypeDeclaration::Union(
+                let declaration = ::wip_interface::wip_protocol::TypeDeclaration {
-                    ::wip_interface::wip_protocol::UnionDeclaration {
                     name: ::std::string::String::from(#type_name),
                     documentation: #declaration_doc,
-                        variants: ::std::vec![#(#declarations),*],
+                    definition: ::wip_interface::wip_protocol::TypeExpr::Union {
+                        cases: ::std::vec![#(#declarations),*],
                     },
-                );
+                };
                 if ::wip_interface::__private::register_declaration(declarations, declaration) {
                     #(#dependency_collectors)*
                 }
@@ -1071,26 +1169,30 @@ fn derive_union_enum(
                 value: ::wip_interface::wip_protocol::Value,
             ) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
                 match value {
-                    ::wip_interface::wip_protocol::Value::Union { variant, value } => {
+                    ::wip_interface::wip_protocol::Value::Record(fields) => {
-                        match variant.as_str() {
+                        let mut decoder =
+                            ::wip_interface::__private::RecordDecoder::new(fields);
+                        let case = decoder.required::<::std::string::String>(
+                            ::wip_interface::wip_protocol::UNION_CASE_FIELD,
+                        )?;
+                        match case.as_str() {
                             #(#decoders,)*
                             _ => ::std::result::Result::Err(
                                 ::wip_interface::__private::decode_unknown_variant(
                                     #type_name,
-                                    variant,
+                                    case,
                                 ),
                             ),
                         }
                     }
                     actual => ::std::result::Result::Err(
-                        ::wip_interface::__private::decode_type_mismatch("union", actual),
+                        ::wip_interface::__private::decode_type_mismatch("union record", actual),
                     ),
                 }
             }
         }
     })
 }
-
 fn optional_type(ty: &Type, context: &str) -> syn::Result<(bool, Type)> {
     if let Some(inner) = direct_option(ty)? {
         if contains_option(&inner) {

crates/wip-interface/src/lib.rs

@@ -30,37 +30,65 @@
 //!
 //! | Rust type | Protocol type/value |
 //! | --- | --- |
-//! | `()` as an operation result | no return declaration / no value |
+//! | `()` | `Unit` |
 //! | `bool` | `Boolean` |
 //! | signed and unsigned integer primitives | JavaScript-lossless `Integer` |
 //! | `f32`, `f64` | finite `Number` |
 //! | `String` | `String` |
 //! | [`Bytes`] | `Bytes` |
-//! | [`wip_protocol::JsonValue`] | `Json` |
+//! | [`JsonValue`] | schema-neutral `Json` value tree |
-//! | [`Entry<K, V>`] | `Entry<K, V>` |
+//! | [`Entry`] | canonical absolute Worldspace path (`Entry`) |
 //! | `Vec<T>` | `List<T>` |
 //! | a named-field struct deriving [`WipType`] | named record |
 //! | an all-unit enum deriving [`WipType`] | named enum |
-//! | an all-newtype enum deriving [`WipType`] | named tagged union |
+//! | an enum mixing unit and single-payload cases deriving [`WipType`] | named union |
 //!
 //! `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
+//! [`HostError`] is reserved for host/runtime failure and requires an explicit
-//! [`OperationResult`] convention keeps those two failure classes distinct.
+//! [`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
+//!
+//! Earlier releases exposed `Entry<K, V>` and semantic `Value::Json`,
+//! `Value::Entry`, `Value::Enum`, and `Value::Union` variants. Those forms are
+//! intentionally gone: [`Entry`] is now one validated absolute Worldspace path,
+//! while JSON, enum, and union meaning comes only from the descriptor. Codecs
+//! exchange only raw [`Value`] strings, records, lists, and primitives. Unit
+//! operation results now cross the boundary as [`Value::Unit`] rather than an
+//! absent value.
+//!
+//! # Supported interface syntax
+//!
+//! An interface is a public, non-generic trait whose operations use exactly
+//! `&self`, simple named owned parameters, and an explicit
+//! `OperationResult<T>`. `WipType` derives support named-field structs,
+//! all-unit enums as protocol enums, and enums made from any mix of unit and
+//! single-payload cases as protocol unions.
+//!
+//! The macros reject trait inheritance and associated items; const, async,
+//! unsafe, extern, variadic, generic, default-bodied, or non-`&self` methods;
+//! borrowed values and custom lifetimes; tuple, unit, or generic structs;
+//! unsupported named-field or multi-field enum variants; explicit discriminants; Rust unions;
+//! and `Option` anywhere except a direct DTO field or operation parameter.
+//! Unsupported inputs produce source-located compile errors rather than
+//! generating a partial interface.
 
 #![deny(missing_docs)]
 
+use std::collections::BTreeMap;
 use std::error::Error;
 use std::fmt::{self, Display, Formatter};
 
 pub use wip_interface_macros::{WipType, interface};
 pub use wip_protocol;
 pub use wip_protocol::{
-    Documentation, EnumDeclaration, EnumVariantDeclaration, FieldDeclaration, InterfaceDescriptor,
+    Documentation, EnumCase, FieldDeclaration, InterfaceDescriptor, MAX_SAFE_INTEGER,
-    JsonMember, JsonValue, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, NamedValue, OperationDeclaration,
+    MIN_SAFE_INTEGER, OperationDeclaration, ParameterDeclaration, ReturnDeclaration,
-    ParameterDeclaration, RecordDeclaration, ReturnDeclaration, TypeDeclaration, TypeExpr,
+    TypeDeclaration, TypeExpr, UnionCase, ValidationError, Value,
-    UnionDeclaration, UnionVariantDeclaration, ValidationError, Value,
 };
 
 /// Converts one Rust application type to and from its protocol representation.
@@ -92,35 +120,128 @@ pub trait InterfaceDefinition {
     fn descriptor() -> InterfaceDescriptor;
 }
 
+/// Typed dispatch implemented by every generated interface companion.
+///
+/// `T` must implement the Rust interface trait associated with this definition.
+/// Host runtimes use this bound when an interface is explicitly exposed, so an
+/// object that does not implement that interface is rejected at compile time.
+pub trait InterfaceImplementation<T>: InterfaceDefinition {
+    /// Validates, decodes, and dispatches one operation to `implementation`,
+    /// then encodes and validates its result.
+    fn dispatch(
+        implementation: &T,
+        operation: &str,
+        arguments: BTreeMap<String, Value>,
+    ) -> Result<Value, DispatchError>;
+}
+
 /// Result convention required for generated interface operations.
 ///
 /// `Ok(T)` is an application result, including domain-failure union cases.
 /// `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)
@@ -200,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 {
@@ -215,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}"),
         }
@@ -224,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),
@@ -251,13 +420,101 @@ impl From<Bytes> for Vec<u8> {
     }
 }
 
-/// A typed protocol key/value entry.
+/// A canonical absolute path to an entry in the current Worldspace.
-#[derive(Debug, Clone, PartialEq, Eq)]
+///
-pub struct Entry<K, V> {
+/// This replaces the pre-canonical `Entry<K, V>` key/value pair. Construct an
-    /// Entry key.
+/// entry from a path such as `/articles/1`; application data associated with
-    pub key: K,
+/// that entry belongs in an ordinary record alongside this value.
-    /// Entry value.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-    pub value: V,
+pub struct Entry(String);
+
+impl Entry {
+    /// Validates and creates an entry path.
+    pub fn new(path: impl Into<String>) -> Result<Self, CodecError> {
+        let path = path.into();
+        validate_entry_path(&path)?;
+        Ok(Self(path))
+    }
+
+    /// Returns the canonical absolute Worldspace path.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Consumes the entry and returns its path.
+    #[must_use]
+    pub fn into_string(self) -> String {
+        self.0
+    }
+}
+
+impl TryFrom<String> for Entry {
+    type Error = CodecError;
+
+    fn try_from(path: String) -> Result<Self, Self::Error> {
+        Self::new(path)
+    }
+}
+
+impl std::str::FromStr for Entry {
+    type Err = CodecError;
+
+    fn from_str(path: &str) -> Result<Self, Self::Err> {
+        Self::new(path)
+    }
+}
+
+/// One member in a [`JsonValue::Object`].
+#[derive(Debug, Clone, PartialEq)]
+pub struct JsonMember {
+    /// Member name.
+    pub name: String,
+    /// Member value.
+    pub value: JsonValue,
+}
+
+/// JSON data represented independently of any application schema.
+///
+/// Its codec uses the ordinary schema-neutral [`Value`] variants. JSON null is
+/// [`Value::Unit`], arrays are [`Value::List`], and objects are
+/// [`Value::Record`]. Protocol bytes have no JSON representation and decoding
+/// a tree containing [`Value::Bytes`] is rejected.
+#[derive(Debug, Clone, PartialEq)]
+pub enum JsonValue {
+    /// JSON null.
+    Null,
+    /// A JSON boolean.
+    Boolean(bool),
+    /// An interoperable integral JSON number.
+    Integer(i64),
+    /// A finite non-integral JSON number.
+    Number(f64),
+    /// A JSON string.
+    String(String),
+    /// A JSON array.
+    Array(Vec<JsonValue>),
+    /// A JSON object. Duplicate member names are rejected while encoding.
+    Object(Vec<JsonMember>),
+}
+
+impl WipType for () {
+    fn type_expr() -> TypeExpr {
+        TypeExpr::Unit
+    }
+
+    fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
+
+    fn encode(self) -> Result<Value, CodecError> {
+        Ok(Value::Unit)
+    }
+
+    fn decode(value: Value) -> Result<Self, CodecError> {
+        match value {
+            Value::Unit => Ok(()),
+            other => Err(CodecError::expected("unit", &other)),
+        }
+    }
 }
 
 impl WipType for bool {
@@ -426,52 +683,87 @@ impl WipType for JsonValue {
     fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
 
     fn encode(self) -> Result<Value, CodecError> {
-        validate_json(&self)?;
+        encode_json(self)
-        Ok(Value::Json(self))
     }
 
     fn decode(value: Value) -> Result<Self, CodecError> {
-        match value {
+        decode_json(value)
-            Value::Json(value) => {
-                validate_json(&value)?;
-                Ok(value)
     }
-            other => Err(CodecError::expected("json", &other)),
+}
+
+fn encode_json(value: JsonValue) -> Result<Value, CodecError> {
+    match value {
+        JsonValue::Null => Ok(Value::Unit),
+        JsonValue::Boolean(value) => Ok(Value::Boolean(value)),
+        JsonValue::Integer(value) => {
+            ensure_safe_integer(value)?;
+            Ok(Value::Integer(value))
+        }
+        JsonValue::Number(value) => {
+            ensure_finite(value)?;
+            Ok(Value::Number(value))
+        }
+        JsonValue::String(value) => Ok(Value::String(value)),
+        JsonValue::Array(values) => values
+            .into_iter()
+            .enumerate()
+            .map(|(index, value)| encode_json(value).map_err(|error| error.at(index.to_string())))
+            .collect::<Result<Vec<_>, _>>()
+            .map(Value::List),
+        JsonValue::Object(members) => {
+            let mut fields = BTreeMap::new();
+            for member in members {
+                let name = member.name;
+                let value = encode_json(member.value).map_err(|error| error.at(name.clone()))?;
+                if fields.insert(name.clone(), value).is_some() {
+                    return Err(CodecError::new(format!("duplicate JSON member `{name}`")).at(name));
+                }
+            }
+            Ok(Value::Record(fields))
         }
     }
 }
 
-fn validate_json(value: &JsonValue) -> Result<(), CodecError> {
+fn decode_json(value: Value) -> Result<JsonValue, CodecError> {
     match value {
-        JsonValue::Integer(value) => ensure_safe_integer(*value),
+        Value::Unit => Ok(JsonValue::Null),
-        JsonValue::Number(value) => ensure_finite(*value),
+        Value::Boolean(value) => Ok(JsonValue::Boolean(value)),
-        JsonValue::Array(values) => {
+        Value::Integer(value) => {
-            for (index, value) in values.iter().enumerate() {
+            ensure_safe_integer(value)?;
-                validate_json(value).map_err(|error| error.at(index.to_string()))?;
+            Ok(JsonValue::Integer(value))
         }
-            Ok(())
+        Value::Number(value) => {
+            ensure_finite(value)?;
+            Ok(JsonValue::Number(value))
         }
-        JsonValue::Object(members) => {
+        Value::String(value) => Ok(JsonValue::String(value)),
-            let mut names = std::collections::HashSet::new();
+        Value::Bytes(_) => Err(CodecError::new("bytes are not valid inside JSON")),
-            for member in members {
+        Value::List(values) => values
-                if !names.insert(member.name.as_str()) {
+            .into_iter()
-                    return Err(CodecError::new(format!(
+            .enumerate()
-                        "duplicate JSON member `{}`",
+            .map(|(index, value)| decode_json(value).map_err(|error| error.at(index.to_string())))
-                        member.name
+            .collect::<Result<Vec<_>, _>>()
-                    ))
+            .map(JsonValue::Array),
-                    .at(member.name.clone()));
+        Value::Record(fields) => fields
-                }
+            .into_iter()
-                validate_json(&member.value).map_err(|error| error.at(member.name.clone()))?;
+            .map(|(name, value)| {
-            }
+                decode_json(value)
-            Ok(())
+                    .map(|value| JsonMember {
-        }
+                        name: name.clone(),
-        JsonValue::Null | JsonValue::Boolean(_) | JsonValue::String(_) => Ok(()),
+                        value,
+                    })
+                    .map_err(|error| error.at(name))
+            })
+            .collect::<Result<Vec<_>, _>>()
+            .map(JsonValue::Object),
     }
 }
 
 impl<T: WipType> WipType for Vec<T> {
     fn type_expr() -> TypeExpr {
-        TypeExpr::List(Box::new(T::type_expr()))
+        TypeExpr::List {
+            items: Box::new(T::type_expr()),
+        }
     }
 
     fn collect_declarations(declarations: &mut Vec<TypeDeclaration>) {
@@ -498,37 +790,31 @@ impl<T: WipType> WipType for Vec<T> {
     }
 }
 
-impl<K: WipType, V: WipType> WipType for Entry<K, V> {
+impl WipType for Entry {
     fn type_expr() -> TypeExpr {
-        TypeExpr::Entry {
+        TypeExpr::Entry
-            key: Box::new(K::type_expr()),
-            value: Box::new(V::type_expr()),
-        }
     }
 
-    fn collect_declarations(declarations: &mut Vec<TypeDeclaration>) {
+    fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
-        K::collect_declarations(declarations);
-        V::collect_declarations(declarations);
-    }
 
     fn encode(self) -> Result<Value, CodecError> {
-        Ok(Value::Entry {
+        validate_entry_path(&self.0)?;
-            key: Box::new(self.key.encode().map_err(|error| error.at("key"))?),
+        Ok(Value::String(self.0))
-            value: Box::new(self.value.encode().map_err(|error| error.at("value"))?),
-        })
     }
 
     fn decode(value: Value) -> Result<Self, CodecError> {
-        let Value::Entry { key, value } = value else {
+        let Value::String(path) = value else {
-            return Err(CodecError::expected("entry", &value));
+            return Err(CodecError::expected("entry path string", &value));
         };
-        Ok(Self {
+        Self::new(path)
-            key: K::decode(*key).map_err(|error| error.at("key"))?,
-            value: V::decode(*value).map_err(|error| error.at("value"))?,
-        })
     }
 }
 
+fn validate_entry_path(path: &str) -> Result<(), CodecError> {
+    wip_protocol::validate_path(path)
+        .map_err(|error| CodecError::new(format!("invalid canonical Worldspace path: {error}")))
+}
+
 /// Implementation details used by code emitted from the facade's macros.
 ///
 /// These APIs are public only because macro expansions execute in the
@@ -536,12 +822,9 @@ impl<K: WipType, V: WipType> WipType for Entry<K, V> {
 /// and are not intended for direct use.
 #[doc(hidden)]
 pub mod __private {
-    use std::collections::HashSet;
+    use std::collections::BTreeMap;
 
-    use wip_protocol::{
+    use wip_protocol::{InterfaceDescriptor, TypeDeclaration, ValidationError, Value};
-        InterfaceDescriptor, NamedValue, ObjectId, OperationCall, OperationTarget, TypeDeclaration,
-        ValidationError, Value,
-    };
 
     use crate::{CodecError, Documentation, WipType};
 
@@ -576,16 +859,9 @@ pub mod __private {
     pub fn validate_arguments(
         descriptor: &InterfaceDescriptor,
         operation: &str,
-        arguments: &[NamedValue],
+        arguments: &BTreeMap<String, Value>,
     ) -> Result<(), ValidationError> {
-        descriptor.validate_call(&OperationCall {
+        descriptor.validate_arguments(operation, arguments)
-            target: OperationTarget {
-                object: ObjectId("<typed-dispatch>".into()),
-                interface: descriptor.name.clone(),
-                operation: operation.into(),
-            },
-            arguments: arguments.to_vec(),
-        })
     }
 
     /// Builds a codec error for a generated structural mismatch.
@@ -603,22 +879,13 @@ pub mod __private {
 
     /// Decoder for a protocol record or operation's named argument collection.
     pub struct RecordDecoder {
-        fields: Vec<NamedValue>,
+        fields: BTreeMap<String, Value>,
-        seen: HashSet<String>,
     }
 
     impl RecordDecoder {
-        /// Starts decoding record fields or named operation arguments and
+        /// Starts decoding record fields or named operation arguments.
-        /// rejects duplicate names.
+        pub fn new(fields: BTreeMap<String, Value>) -> Self {
-        pub fn new(fields: Vec<NamedValue>) -> Result<Self, CodecError> {
+            Self { fields }
-            let mut seen = HashSet::new();
-            for field in &fields {
-                if !seen.insert(field.name.clone()) {
-                    return Err(CodecError::new(format!("duplicate field `{}`", field.name))
-                        .at(field.name.clone()));
-                }
-            }
-            Ok(Self { fields, seen })
         }
 
         /// Decodes a required field.
@@ -639,23 +906,15 @@ pub mod __private {
 
         /// Rejects any fields that were not consumed by generated code.
         pub fn finish(self) -> Result<(), CodecError> {
-            if let Some(field) = self.fields.first() {
+            if let Some(name) = self.fields.keys().next() {
-                Err(CodecError::new(format!("unknown field `{}`", field.name))
+                Err(CodecError::new(format!("unknown field `{name}`")).at(name.clone()))
-                    .at(field.name.clone()))
             } else {
                 Ok(())
             }
         }
 
         fn take(&mut self, name: &str) -> Option<Value> {
-            let index = self.fields.iter().position(|field| field.name == name)?;
+            self.fields.remove(name)
-            Some(self.fields.remove(index).value)
-        }
-
-        /// Returns the set of names supplied to this decoder.
-        #[allow(dead_code)]
-        pub fn supplied_names(&self) -> &HashSet<String> {
-            &self.seen
         }
     }
 }

crates/wip-interface/tests/codecs.rs

@@ -1,8 +1,7 @@
-use wip_interface::wip_protocol::{
+use std::collections::BTreeMap;
-    EnumDeclaration, JsonMember, JsonValue, NamedValue, RecordDeclaration, TypeDeclaration,
+
-    TypeExpr, UnionDeclaration, Value,
+use wip_interface::wip_protocol::{TypeExpr, UNION_CASE_FIELD, UNION_VALUE_FIELD, Value};
-};
+use wip_interface::{Bytes, Entry, JsonMember, JsonValue, WipType};
-use wip_interface::{Bytes, Entry, WipType};
 
 /// A request record.
 #[derive(Debug, Clone, PartialEq, WipType)]
@@ -11,8 +10,8 @@ struct Request {
     title: String,
     /// Optional priority.
     priority: Option<i32>,
-    /// Related entries.
+    /// Related Worldspace entries.
-    related: Vec<Entry<String, bool>>,
+    related: Vec<Entry>,
     /// Opaque bytes.
     body: Bytes,
     /// Arbitrary metadata.
@@ -38,33 +37,53 @@ struct Receipt {
 /// Application-level publication outcome.
 #[derive(Debug, Clone, PartialEq, WipType)]
 enum PublishOutcome {
+    /// Work has not completed and carries no payload.
+    Pending,
     /// Application success.
     Published(Receipt),
     /// Domain rejection, not a host failure.
     Rejected(String),
 }
 
+fn field<'a>(record: &'a BTreeMap<String, Value>, name: &str) -> &'a Value {
+    record
+        .get(name)
+        .unwrap_or_else(|| panic!("missing `{name}`"))
+}
+
 #[test]
-fn supported_values_round_trip() {
+fn primitive_unit_record_list_entry_and_json_values_round_trip() {
+    assert_eq!(().encode().unwrap(), Value::Unit);
+    assert_eq!(<()>::decode(Value::Unit).unwrap(), ());
+    assert_eq!(<()>::type_expr(), TypeExpr::Unit);
+
     let request = Request {
         title: "hello".into(),
         priority: None,
-        related: vec![Entry {
+        related: vec![Entry::new("/articles/1").unwrap()],
-            key: "/articles/1".into(),
-            value: true,
-        }],
         body: Bytes(vec![1, 2, 3]),
         metadata: JsonValue::Object(vec![JsonMember {
             name: "source".into(),
-            value: JsonValue::String("test".into()),
+            value: JsonValue::Array(vec![JsonValue::String("test".into()), JsonValue::Null]),
         }]),
     };
 
     let encoded = request.clone().encode().unwrap();
     let Value::Record(fields) = &encoded else {
-        panic!("record derive must encode a protocol record")
+        panic!("record derive must encode a raw protocol record")
     };
-    assert!(fields.iter().all(|field| field.name != "priority"));
+    assert!(!fields.contains_key("priority"));
+    assert_eq!(
+        field(fields, "related"),
+        &Value::List(vec![Value::String("/articles/1".into())])
+    );
+    assert_eq!(
+        field(fields, "metadata"),
+        &Value::Record(BTreeMap::from([(
+            "source".into(),
+            Value::List(vec![Value::String("test".into()), Value::Unit]),
+        )]))
+    );
     assert_eq!(Request::decode(encoded).unwrap(), request);
 
     let number = 42.5_f64;
@@ -77,92 +96,136 @@ fn supported_values_round_trip() {
         f32::decode(narrow_number.encode().unwrap()).unwrap(),
         narrow_number
     );
-
-    for color in [Color::Red, Color::Blue] {
-        let encoded = color.clone().encode().unwrap();
-        let decoded = Color::decode(encoded).unwrap();
-        assert_eq!(decoded, color);
 }
 
+#[test]
+fn enums_are_strings_and_unions_are_discriminated_records() {
+    for color in [Color::Red, Color::Blue] {
+        let encoded = color.clone().encode().unwrap();
+        assert!(matches!(encoded, Value::String(_)));
+        assert_eq!(Color::decode(encoded).unwrap(), color);
+    }
+
+    let pending = PublishOutcome::Pending.encode().unwrap();
+    assert_eq!(
+        pending,
+        Value::Record(BTreeMap::from([(
+            UNION_CASE_FIELD.into(),
+            Value::String("Pending".into()),
+        )]))
+    );
+
+    let published = PublishOutcome::Published(Receipt { number: 7 })
+        .encode()
+        .unwrap();
+    let Value::Record(fields) = &published else {
+        panic!("union must encode as a record")
+    };
+    assert_eq!(
+        fields.get(UNION_CASE_FIELD),
+        Some(&Value::String("Published".into()))
+    );
+    assert!(matches!(
+        fields.get(UNION_VALUE_FIELD),
+        Some(Value::Record(_))
+    ));
+
     for outcome in [
+        PublishOutcome::Pending,
         PublishOutcome::Published(Receipt { number: 7 }),
         PublishOutcome::Rejected("policy".into()),
     ] {
         let encoded = outcome.clone().encode().unwrap();
-        let decoded = PublishOutcome::decode(encoded).unwrap();
+        assert_eq!(PublishOutcome::decode(encoded).unwrap(), outcome);
-        assert_eq!(decoded, outcome);
     }
 }
 
 #[test]
-fn derived_declarations_include_docs_optionality_and_dependencies() {
+fn derived_declarations_use_canonical_named_type_expressions() {
     let mut declarations = Vec::new();
     Request::collect_declarations(&mut declarations);
     Color::collect_declarations(&mut declarations);
     PublishOutcome::collect_declarations(&mut declarations);
 
-    let TypeDeclaration::Record(RecordDeclaration {
+    let request = declarations
-        documentation,
+        .iter()
-        fields,
+        .find(|declaration| declaration.name == "Request")
-        ..
+        .unwrap();
-    }) = &declarations[0]
+    assert_eq!(
-    else {
+        request.documentation.as_ref().unwrap().summary,
+        "A request record."
+    );
+    let TypeExpr::Record { fields } = &request.definition else {
         panic!("Request must be a record declaration")
     };
-    assert_eq!(documentation.as_ref().unwrap().summary, "A request record.");
     assert_eq!(
         fields[0].documentation.as_ref().unwrap().summary,
         "Required title."
     );
-    assert!(!fields[0].optional);
+    assert!(fields[0].required);
-    assert!(fields[1].optional);
+    assert!(!fields[1].required);
-    assert_eq!(fields[1].ty, TypeExpr::Integer);
+    assert_eq!(fields[1].r#type, TypeExpr::Integer);
     assert_eq!(
-        fields[2].ty,
+        fields[2].r#type,
-        TypeExpr::List(Box::new(TypeExpr::Entry {
+        TypeExpr::List {
-            key: Box::new(TypeExpr::String),
+            items: Box::new(TypeExpr::Entry),
-            value: Box::new(TypeExpr::Boolean),
+        }
-        }))
     );
 
     let color = declarations
         .iter()
-        .find(|declaration| declaration.name() == "Color")
+        .find(|declaration| declaration.name == "Color")
         .unwrap();
-    let TypeDeclaration::Enum(EnumDeclaration { variants, .. }) = color else {
+    let TypeExpr::Enum { cases } = &color.definition else {
         panic!("Color must be an enum declaration")
     };
     assert_eq!(
-        variants[0].documentation.as_ref().unwrap().summary,
+        cases[0].documentation.as_ref().unwrap().summary,
         "Warm red."
     );
 
     let outcome = declarations
         .iter()
-        .find(|declaration| declaration.name() == "PublishOutcome")
+        .find(|declaration| declaration.name == "PublishOutcome")
         .unwrap();
-    let TypeDeclaration::Union(UnionDeclaration { variants, .. }) = outcome else {
+    let TypeExpr::Union { cases } = &outcome.definition else {
         panic!("PublishOutcome must be a union declaration")
     };
-    assert_eq!(variants[0].ty, TypeExpr::Named("Receipt".into()));
+    assert_eq!(cases[0].payload, None);
+    assert_eq!(
+        cases[1].payload,
+        Some(TypeExpr::Named {
+            name: "Receipt".into(),
+        })
+    );
     assert!(
         declarations
             .iter()
-            .any(|declaration| declaration.name() == "Receipt")
+            .any(|declaration| declaration.name == "Receipt")
     );
 }
 
 #[test]
-fn codecs_reject_invalid_boundaries() {
+fn codecs_reject_invalid_boundaries_and_json_bytes() {
     assert!(i64::MAX.encode().is_err());
     assert!(f64::NAN.encode().is_err());
-    assert!(Request::decode(Value::Record(vec![])).is_err());
+    assert!(Request::decode(Value::Record(BTreeMap::new())).is_err());
     assert!(
-        Request::decode(Value::Record(vec![NamedValue {
+        Request::decode(Value::Record(BTreeMap::from([(
-            name: "unknown".into(),
+            "unknown".into(),
-            value: Value::String("value".into()),
+            Value::String("value".into()),
-        }]))
+        )])))
+        .is_err()
+    );
+    assert!(Color::decode(Value::String("Green".into())).is_err());
+    assert!(Entry::new("articles/1").is_err());
+    assert!(Entry::decode(Value::String("/articles/../1".into())).is_err());
+    assert!(JsonValue::decode(Value::Bytes(vec![1])).is_err());
+    assert!(
+        JsonValue::decode(Value::Record(BTreeMap::from([(
+            "nested".into(),
+            Value::List(vec![Value::Bytes(vec![1])]),
+        )])))
         .is_err()
     );
-    assert!(Color::decode(Value::Enum("Green".into())).is_err());
 }

crates/wip-interface/tests/interface.rs

@@ -1,5 +1,10 @@
-use wip_interface::wip_protocol::{NamedValue, TypeDeclaration, TypeExpr, Value};
+use std::collections::BTreeMap;
-use wip_interface::{DispatchError, HostError, OperationResult, WipType, interface};
+
+use wip_interface::wip_protocol::{INTERFACE_FORMAT_V1, TypeExpr, Value};
+use wip_interface::{
+    DispatchError, DispatchPhase, EffectGuarantee, HostError, HostErrorKind, OperationResult,
+    WipType, interface,
+};
 
 /// Publication request.
 #[derive(Debug, Clone, PartialEq, WipType)]
@@ -36,7 +41,7 @@ pub trait Catalog {
         note: Option<String>,
     ) -> OperationResult<PublishOutcome>;
 
-    /// Checks connectivity without returning an application value.
+    /// Checks connectivity without returning application data.
     fn ping(&self) -> OperationResult<()>;
 
     /// Demonstrates a host/runtime failure.
@@ -64,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,
+        ))
     }
 }
 
@@ -88,36 +96,49 @@ impl Catalog for RejectingCatalog {
     }
 }
 
-fn named(name: &str, value: Value) -> NamedValue {
+struct PanickingCatalog;
-    NamedValue {
+
-        name: name.into(),
+impl Catalog for PanickingCatalog {
-        value,
+    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) -> Vec<NamedValue> {
+fn publish_arguments(with_note: bool) -> BTreeMap<String, Value> {
-    let mut arguments = vec![named(
+    let mut arguments = BTreeMap::from([(
-        "request",
+        "request".into(),
         PublishRequest {
             title: "example".into(),
         }
         .encode()
         .unwrap(),
-    )];
+    )]);
     if with_note {
-        arguments.push(named("note", Value::String("audit".into())));
+        arguments.insert("note".into(), Value::String("audit".into()));
     }
     arguments
 }
 
 #[test]
-fn descriptor_is_generated_only_from_the_trait_declaration() {
+fn descriptor_is_canonical_and_generated_only_from_the_trait_declaration() {
     let first = CatalogDefinition::descriptor();
     let second = CatalogDefinition::descriptor();
     assert_eq!(first, second);
     first.validate().unwrap();
 
-    assert_eq!(first.name, "Catalog");
+    assert_eq!(first.format, INTERFACE_FORMAT_V1);
     assert_eq!(
         first.documentation.as_ref().unwrap().summary,
         "Catalog editing capability."
@@ -139,84 +160,110 @@ fn descriptor_is_generated_only_from_the_trait_declaration() {
             .summary,
         "Item to publish."
     );
-    assert!(!publish.parameters[0].optional);
+    assert!(publish.parameters[0].required);
-    assert!(publish.parameters[1].optional);
+    assert!(!publish.parameters[1].required);
     assert_eq!(
-        publish
+        publish.returns.documentation.as_ref().unwrap().summary,
-            .returns
-            .as_ref()
-            .unwrap()
-            .documentation
-            .as_ref()
-            .unwrap()
-            .summary,
         "The application publication outcome."
     );
     assert_eq!(
-        publish.returns.as_ref().unwrap().ty,
+        publish.returns.r#type,
-        TypeExpr::Named("PublishOutcome".into())
+        TypeExpr::Named {
+            name: "PublishOutcome".into(),
+        }
     );
-    assert!(first.operations[1].returns.is_none());
+    assert_eq!(first.operations[1].returns.r#type, TypeExpr::Unit);
     assert!(
         first
-            .declarations
+            .types
             .iter()
-            .any(|declaration| matches!(declaration, TypeDeclaration::Record(_)))
+            .any(|declaration| matches!(declaration.definition, TypeExpr::Record { .. }))
     );
     assert!(
         first
-            .declarations
+            .types
             .iter()
-            .any(|declaration| matches!(declaration, TypeDeclaration::Union(_)))
+            .any(|declaration| matches!(declaration.definition, TypeExpr::Union { .. }))
     );
 
-    // Both implementation types satisfy the same generated dispatch boundary;
+    // Both implementation types satisfy one immutable generated definition;
-    // neither can affect the descriptor shape.
+    // implementation selection cannot contribute fields to the descriptor.
     fn accepts_definition<T: Catalog>(_: &T) {}
     accepts_definition(&AcceptingCatalog);
     accepts_definition(&RejectingCatalog);
+    assert_eq!(CatalogDefinition::descriptor(), first);
 }
 
 #[test]
-fn generated_argument_decoder_and_result_encoder_round_trip() {
+fn generated_argument_decoder_and_result_encoder_use_raw_values() {
     let decoded = CatalogPublishArguments::decode(publish_arguments(false)).unwrap();
     assert_eq!(decoded.request.title, "example");
     assert_eq!(decoded.note, None);
 
-    let encoded = CatalogPublishArguments::encode_result(PublishOutcome::Rejected("domain".into()))
+    let encoded =
-        .unwrap()
+        CatalogPublishArguments::encode_result(PublishOutcome::Rejected("domain".into())).unwrap();
-        .unwrap();
     assert_eq!(
         PublishOutcome::decode(encoded).unwrap(),
         PublishOutcome::Rejected("domain".into())
     );
+    assert_eq!(
+        CatalogPingArguments::encode_result(()).unwrap(),
+        Value::Unit
+    );
 }
 
 #[test]
 fn typed_dispatch_validates_decodes_invokes_encodes_and_validates() {
-    let value = CatalogDefinition::dispatch(&AcceptingCatalog, "publish", publish_arguments(true))
+    let value =
-        .unwrap()
+        CatalogDefinition::dispatch(&AcceptingCatalog, "publish", publish_arguments(true)).unwrap();
-        .unwrap();
     assert_eq!(
         PublishOutcome::decode(value).unwrap(),
         PublishOutcome::Published(true)
     );
 
     assert_eq!(
-        CatalogDefinition::dispatch(&AcceptingCatalog, "ping", vec![]).unwrap(),
+        CatalogDefinition::dispatch(&AcceptingCatalog, "ping", BTreeMap::new()).unwrap(),
-        None
+        Value::Unit
     );
 
-    let invalid = CatalogDefinition::dispatch(&AcceptingCatalog, "publish", vec![]).unwrap_err();
+    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", vec![]).unwrap_err();
+    let host =
-    assert!(matches!(host, DispatchError::Host(error) if error.message() == "backend unavailable"));
+        CatalogDefinition::dispatch(&AcceptingCatalog, "host_value", BTreeMap::new()).unwrap_err();
+    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 unknown = CatalogDefinition::dispatch(&AcceptingCatalog, "missing", vec![]).unwrap_err();
+    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 {
@@ -245,11 +292,11 @@ fn distinct_operation_names_always_generate_distinct_public_items() {
     assert_eq!(descriptor.operations[0].name, "item");
     assert_eq!(descriptor.operations[1].name, "item_");
 
-    let first = DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item", vec![])
+    let first =
-        .unwrap()
+        DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item", BTreeMap::new())
             .unwrap();
-    let second = DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item_", vec![])
+    let second =
-        .unwrap()
+        DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item_", BTreeMap::new())
             .unwrap();
     assert_eq!(first, Value::String("item".into()));
     assert_eq!(second, Value::String("item_".into()));

crates/wip-interface/tests/ui/async_operation.rs

@@ -0,0 +1,8 @@
+use wip_interface::interface;
+
+#[interface]
+pub trait AsyncOperation {
+    async fn status(&self) -> wip_interface::OperationResult<String>;
+}
+
+fn main() {}

crates/wip-interface/tests/ui/async_operation.stderr

@@ -0,0 +1,5 @@
+error: async operations are not supported
+ --> tests/ui/async_operation.rs:5:5
+  |
+5 |     async fn status(&self) -> wip_interface::OperationResult<String>;
+  |     ^^^^^

crates/wip-interface/tests/ui/default_method.rs

@@ -0,0 +1,10 @@
+use wip_interface::interface;
+
+#[interface]
+pub trait DefaultMethod {
+    fn status(&self) -> wip_interface::OperationResult<String> {
+        Ok(String::new())
+    }
+}
+
+fn main() {}

crates/wip-interface/tests/ui/default_method.stderr

@@ -0,0 +1,8 @@
+error: WIP operation methods must not have a body
+ --> tests/ui/default_method.rs:5:64
+  |
+5 |       fn status(&self) -> wip_interface::OperationResult<String> {
+  |  ________________________________________________________________^
+6 | |         Ok(String::new())
+7 | |     }
+  | |_____^

crates/wip-interface/tests/ui/generic_dto.rs

@@ -0,0 +1,8 @@
+use wip_interface::WipType;
+
+#[derive(WipType)]
+struct GenericDto<T> {
+    value: T,
+}
+
+fn main() {}

crates/wip-interface/tests/ui/generic_dto.stderr

@@ -0,0 +1,5 @@
+error: generic DTOs are not supported by `WipType`
+ --> tests/ui/generic_dto.rs:4:18
+  |
+4 | struct GenericDto<T> {
+  |                  ^^^

crates/wip-interface/tests/ui/mixed_enum.rs

@@ -1,9 +1,9 @@
 use wip_interface::WipType;
 
 #[derive(WipType)]
-enum MixedEnum {
+enum UnsupportedEnum {
     Empty,
-    Payload(String),
+    Payload { value: String },
 }
 
 fn main() {}

crates/wip-interface/tests/ui/mixed_enum.stderr

@@ -1,5 +1,5 @@
-error: a `WipType` enum must contain either only unit variants or only single-field tuple variants; mixed and named-field variants are unsupported
+error: a `WipType` enum must contain unit variants and/or single-field tuple variants; named-field and multi-field variants are unsupported
- --> tests/ui/mixed_enum.rs:4:1
+ --> tests/ui/mixed_enum.rs:6:5
   |
-4 | enum MixedEnum {
+6 |     Payload { value: String },
-  | ^^^^
+  |     ^^^^^^^

crates/wip-interface/tests/ui/nested_option.rs

@@ -0,0 +1,8 @@
+use wip_interface::WipType;
+
+#[derive(WipType)]
+struct NestedOption {
+    values: Vec<Option<String>>,
+}
+
+fn main() {}

crates/wip-interface/tests/ui/nested_option.stderr

@@ -0,0 +1,5 @@
+error: `Option<T>` must appear directly as the DTO field type
+ --> tests/ui/nested_option.rs:5:13
+  |
+5 |     values: Vec<Option<String>>,
+  |             ^^^^^^^^^^^^^^^^^^^

crates/wip-interface/tests/ui/unsupported_type.stderr

@@ -4,16 +4,11 @@ error[E0277]: the trait bound `(std::string::String, std::string::String): WipTy
 5 |     fn load(&self, pair: (String, String)) -> OperationResult<String>;
   |                          ^^^^^^^^^^^^^^^^ the trait `WipType` is not implemented for `(std::string::String, std::string::String)`
   |
-  = help: the following other types implement trait `WipType`:
+help: the trait `WipType` is implemented for `()`
-            JsonValue
+ --> src/lib.rs
-            Vec<T>
+  |
-            bool
+  | impl WipType for () {
-            f32
+  | ^^^^^^^^^^^^^^^^^^^
-            f64
-            i128
-            i16
-            i32
-          and $N others
 
 error[E0277]: the trait bound `(std::string::String, std::string::String): WipType` is not satisfied
  --> tests/ui/unsupported_type.rs:5:26
@@ -24,16 +19,11 @@ error[E0277]: the trait bound `(std::string::String, std::string::String): WipTy
 5 |     fn load(&self, pair: (String, String)) -> OperationResult<String>;
   |                          ^^^^^^^^^^^^^^^^ the trait `WipType` is not implemented for `(std::string::String, std::string::String)`
   |
-  = help: the following other types implement trait `WipType`:
+help: the trait `WipType` is implemented for `()`
-            JsonValue
+ --> src/lib.rs
-            Vec<T>
+  |
-            bool
+  | impl WipType for () {
-            f32
+  | ^^^^^^^^^^^^^^^^^^^
-            f64
-            i128
-            i16
-            i32
-          and $N others
 note: required by a bound in `wip_interface::__private::RecordDecoder::required`
  --> src/lib.rs
   |

crates/wip-protocol/src/error.rs

@@ -8,79 +8,65 @@ pub enum NameNamespace {
     TypeDeclaration,
     /// Operations in an interface descriptor.
     Operation,
-    /// Fields in a record declaration.
+    /// Fields in an inline or named record type.
     Field,
     /// Parameters in an operation declaration.
     Parameter,
-    /// Variants in an enum declaration.
+    /// Cases in an enum type.
-    EnumVariant,
+    EnumCase,
-    /// Variants in a union declaration.
+    /// Cases in a union type.
-    UnionVariant,
+    UnionCase,
-    /// Fields supplied in a record value.
+    /// Child object names beneath one tree node.
-    RecordValueField,
+    ChildObject,
-    /// Arguments supplied in an operation call.
-    Argument,
-    /// Members in a logical JSON object.
-    JsonMember,
-    /// Descriptors in an interface observation.
-    InterfaceDescriptor,
 }
 
-/// Structural kind of a logical protocol value.
+/// Structural kind of a schema-neutral logical value.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ValueKind {
-    /// String value.
+    /// Unit value.
-    String,
+    Unit,
     /// Boolean value.
     Boolean,
     /// Integer value.
     Integer,
     /// Floating-point number value.
     Number,
+    /// String value.
+    String,
     /// Byte sequence.
     Bytes,
-    /// List value.
-    List,
-    /// Key/value entry.
-    Entry,
     /// Record value.
     Record,
-    /// Enum value.
+    /// List value.
-    Enum,
+    List,
-    /// Tagged-union value.
-    Union,
-    /// Logical JSON value.
-    Json,
 }
 
 /// A typed segment identifying a declaration or value location.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum PathSegment {
-    /// Interface descriptor.
+    /// Descriptor root.
-    Interface(String),
+    Descriptor,
     /// Named type declaration.
     Declaration(String),
     /// Operation declaration or call.
     Operation(String),
     /// Record field declaration or value.
     Field(String),
-    /// Operation parameter declaration or argument.
+    /// Operation parameter or argument.
     Parameter(String),
-    /// Enum or union variant.
+    /// Enum or union case.
-    Variant(String),
+    Case(String),
-    /// List or JSON array index.
+    /// List index.
     Index(usize),
-    /// Entry key.
-    EntryKey,
-    /// Entry value.
-    EntryValue,
     /// Operation return value.
     Return,
-    /// JSON object member.
+    /// Object at a Worldspace path.
-    JsonMember(String),
+    Object(String),
+    /// Child object in a tree response.
+    Child(String),
 }
 
-/// Machine-readable reason why protocol validation failed.
+/// Machine-readable reason why logical protocol validation failed.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ValidationErrorKind {
     /// A name occurred more than once in one namespace.
@@ -117,11 +103,15 @@ pub enum ValidationErrorKind {
         /// Missing field name.
         name: String,
     },
-    /// An enum or union value selected an undeclared variant.
+    /// An enum or union selected an undeclared case.
-    UnknownVariant {
+    UnknownCase {
-        /// Unknown variant name.
+        /// Unknown case name.
         name: String,
     },
+    /// A payload-bearing union case omitted `value`.
+    MissingUnionPayload,
+    /// A payload-free union case supplied `value`.
+    UnexpectedUnionPayload,
     /// An operation call contains an undeclared argument.
     UnknownParameter {
         /// Unknown parameter name.
@@ -132,44 +122,66 @@ pub enum ValidationErrorKind {
         /// Missing parameter name.
         name: String,
     },
-    /// An integer is outside the JavaScript-lossless range.
+    /// An operation is not declared by the descriptor.
+    UnknownOperation {
+        /// Unknown operation name.
+        name: String,
+    },
+    /// An integer is outside the interoperable safe range.
     IntegerOutOfRange {
         /// Rejected integer.
         value: i64,
     },
     /// A numeric value is NaN or infinite.
     NonFiniteNumber,
+    /// A JSON-interpreted value tree contains protocol bytes.
+    BytesInJson,
+    /// An object name is not a valid root or non-root path segment.
+    InvalidObjectName {
+        /// Rejected object name.
+        name: String,
+    },
     /// An object's ordered interface set contains a duplicate.
     DuplicateInterface {
-        /// Duplicate interface name.
+        /// Duplicate opaque interface reference.
-        name: String,
+        reference: String,
     },
-    /// An observation omits a descriptor named by its object.
+    /// A string is not a canonical absolute Worldspace path.
-    MissingInterfaceDescriptor {
+    InvalidPath {
-        /// Missing interface name.
+        /// Rejected path.
-        name: String,
+        path: String,
     },
-    /// An observation contains a descriptor not named by its object.
+    /// An object name does not match the path where it was observed.
-    UnexpectedInterfaceDescriptor {
+    ObjectNameMismatch {
-        /// Unexpected interface name.
+        /// Name required by the observation path.
-        name: String,
-    },
-    /// A call targets an interface other than the descriptor being used.
-    InterfaceMismatch {
-        /// Descriptor interface name.
         expected: String,
-        /// Call target interface name.
+        /// Name supplied by the object.
         actual: String,
     },
-    /// An operation is not declared by the interface.
+    /// Equivalent ref/validator observations disagree on object representation.
-    UnknownOperation {
+    InconsistentObjectObservation {
-        /// Unknown operation name.
+        /// Shared opaque object reference.
-        name: String,
+        reference: String,
+    },
+    /// A `fetch_tree` request used a zero limit.
+    ZeroTreeLimit,
+    /// A tree response exceeds the requested maximum depth.
+    TreeDepthExceeded {
+        /// Requested maximum depth.
+        maximum: u32,
+    },
+    /// A tree response exceeds the requested maximum node count.
+    TreeLimitExceeded {
+        /// Requested maximum node count.
+        limit: u32,
+    },
+    /// A response refers to a different interface than its request.
+    InterfaceResponseMismatch {
+        /// Requested opaque reference.
+        expected: String,
+        /// Returned opaque reference.
+        actual: String,
     },
-    /// A no-return operation produced a value.
-    UnexpectedReturnValue,
-    /// An operation with a return declaration produced no value.
-    MissingReturnValue,
 }
 
 /// A validation failure with a typed path to the failing location.
@@ -211,30 +223,152 @@ impl Display for ValidationError {
 
 impl Error for ValidationError {}
 
-/// Stable category of an error returned by a protocol host runtime.
+/// One core interaction whose failure codes form a closed set.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum ProtocolErrorCategory {
+pub enum ProtocolInteraction {
-    /// The request is structurally invalid.
+    /// Fetch one object by its Worldspace path.
-    InvalidRequest,
+    Fetch,
-    /// The target object is not published.
+    /// Fetch a bounded tree of objects.
-    ObjectNotFound,
+    FetchTree,
-    /// The target interface is not implemented by the object.
+    /// Fetch one interface descriptor by its opaque reference.
-    InterfaceNotFound,
+    FetchInterface,
-    /// The target operation is not declared by the interface.
+    /// Invoke one operation on a path-targeted object.
-    OperationNotFound,
+    CallOperation,
-    /// Supplied operation arguments are invalid.
-    InvalidArguments,
-    /// The implementation rejected the call for a domain reason.
-    OperationFailed,
-    /// The host encountered an internal failure.
-    Internal,
 }
 
-/// Transport-independent protocol failure returned by a host runtime.
+/// 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 before an operation descriptor is fixed.
+    InvalidRequest,
+    /// The target object is not published.
+    NotFound,
+    /// The interface reference is not currently published.
+    InterfaceNotFound,
+    /// The selected interface is not on the current object.
+    InterfaceMismatch,
+    /// The selected operation is not declared by the current interface.
+    OperationNotFound,
+    /// Supplied arguments do not match the fixed operation declaration.
+    InvalidArguments,
+    /// The operation requires an object validator and none was supplied.
+    ValidatorRequired,
+    /// The supplied object validator does not match current state.
+    ValidatorMismatch,
+    /// A mutable interface requires its validator and none was supplied.
+    InterfaceValidatorRequired,
+    /// The supplied interface validator does not match the descriptor.
+    InterfaceValidatorMismatch,
+    /// 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.
+    ///
+    /// 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.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProtocolError {
-    /// Stable programmatic category.
+    /// Stable programmatic code. Consumers must branch on this field.
-    pub category: ProtocolErrorCategory,
+    pub code: ProtocolErrorCode,
-    /// Human-readable diagnostic. Consumers must not branch on this text.
+    /// Bounded human-readable diagnostic. Consumers must not branch on it.
     pub message: String,
 }
+
+impl Display for ProtocolError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        write!(
+            formatter,
+            "protocol failure ({:?}): {}",
+            self.code, self.message
+        )
+    }
+}
+
+impl Error for ProtocolError {}

crates/wip-protocol/src/lib.rs

@@ -1,9 +1,45 @@
-//! Transport-independent logical types for the Web Interface Protocol (WIP).
+//! Canonical transport-independent logical types for the Web Interface Protocol.
 //!
-//! This crate deliberately models interface declarations, published objects,
+//! This crate follows the Core Model and `3-protocol.md` without assigning HTTP
-//! operation calls, and operation results without assigning them HTTP routes,
+//! routes, methods, headers, URL encodings, or JSON envelopes. The correspondence
-//! methods, headers, or JSON envelopes. A transport can encode these values,
+//! between canonical logical concepts and this crate is direct:
-//! but the encoding is outside this crate's contract.
+//!
+//! | Canonical protocol concept | Rust API |
+//! | --- | --- |
+//! | Object projection and ordered interface set | [`Object`] |
+//! | Optional object identity / state precondition | `Object::ref` / [`Object::validator`] |
+//! | Interface Descriptor | [`InterfaceDescriptor`] |
+//! | Named declaration and all schema expressions | [`TypeDeclaration`] / [`TypeExpr`] |
+//! | Schema-neutral primitive/composite value | [`Value`] |
+//! | `fetch` | [`FetchRequest`] / [`FetchResponse`] |
+//! | `fetch_tree` | [`FetchTreeRequest`] / [`FetchTreeResponse`] |
+//! | `fetch_interface` | [`FetchInterfaceRequest`] / [`FetchInterfaceResponse`] |
+//! | Object and interface call preconditions | [`Target`] / [`InterfaceTarget`] |
+//! | `call_operation` | [`CallOperationRequest`] / [`CallOperationResponse`] |
+//! | 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
+//! fields. In particular, object refs are optional, operation targeting uses a
+//! path, and this crate defines no interaction that fetches an object by ref.
+//!
+//! [`Value`] contains only the canonical raw value kinds. A descriptor interprets
+//! enum values as strings, entries as canonical-path strings, and unions as
+//! records with a `$case` string plus an optional `value` payload. JSON uses the
+//! same value tree (`Unit` is JSON null) and rejects bytes.
 
 #![deny(missing_docs)]
 
@@ -12,19 +48,33 @@ mod model;
 mod validation;
 
 pub use error::{
-    NameNamespace, PathSegment, ProtocolError, ProtocolErrorCategory, ValidationError,
+    NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
-    ValidationErrorKind, ValueKind,
+    ValidationError, ValidationErrorKind, ValueKind,
 };
 pub use model::{
-    Documentation, EnumDeclaration, EnumVariantDeclaration, FieldDeclaration, InterfaceDescriptor,
+    CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
-    InterfaceObservation, JsonMember, JsonValue, NamedValue, Object, ObjectId, OperationCall,
+    FetchInterfaceResponse, FetchRequest, FetchResponse, FetchTreeRequest, FetchTreeResponse,
-    OperationDeclaration, OperationOutcome, OperationResult, OperationTarget, ParameterDeclaration,
+    FieldDeclaration, InterfaceDescriptor, InterfaceTarget, Object, ObjectTreeNode,
-    RecordDeclaration, ReturnDeclaration, TypeDeclaration, TypeExpr, UnionDeclaration,
+    OperationDeclaration, ParameterDeclaration, ProtocolResult, ReturnDeclaration, Target,
-    UnionVariantDeclaration, Value,
+    TypeDeclaration, TypeExpr, UnionCase, Value,
 };
 
-/// Largest integer that is exactly interoperable with a JavaScript `Number`.
+/// Validates a canonical absolute Worldspace path.
+pub fn validate_path(path: &str) -> Result<(), ValidationError> {
+    validation::validate_path(path)
+}
+
+/// Canonical format identifier for the first Interface Descriptor format.
+pub const INTERFACE_FORMAT_V1: &str = "wip-interface/1";
+
+/// Discriminator field used by a union's raw record value.
+pub const UNION_CASE_FIELD: &str = "$case";
+
+/// Optional payload field used by a union's raw record value.
+pub const UNION_VALUE_FIELD: &str = "value";
+
+/// Largest integer exactly interoperable with a JavaScript `Number`.
 pub const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
 
-/// Smallest integer that is exactly interoperable with a JavaScript `Number`.
+/// Smallest integer exactly interoperable with a JavaScript `Number`.
 pub const MIN_SAFE_INTEGER: i64 = -MAX_SAFE_INTEGER;

crates/wip-protocol/src/model.rs

@@ -1,6 +1,8 @@
+use std::collections::BTreeMap;
+
 use crate::{ProtocolError, ValidationError};
 
-/// Human-readable documentation attached to a protocol declaration.
+/// Human-readable plain-text documentation attached to a protocol declaration.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct Documentation {
     /// A short, self-contained description.
@@ -9,242 +11,194 @@ pub struct Documentation {
     pub details: Option<String>,
 }
 
-/// Stable logical identity of a published object.
+/// The protocol projection currently published at one Worldspace path.
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct ObjectId(pub String);
-
-/// A published object and the ordered set of interfaces it implements.
 ///
-/// The vector order is significant. Call [`Object::validate`] before
+/// `name` is a path segment, `interfaces` is an ordered set of opaque interface
-/// publication to reject duplicate interface names.
+/// references, `r#ref` is optional object identity, and `validator` is an
+/// independent optional observation precondition. In particular, neither the
+/// path nor `r#ref` is a mandatory object identifier.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Object {
-    /// Logical object identity.
+    /// Path-segment name. The root object's name is empty.
-    pub id: ObjectId,
+    pub name: String,
-    /// Interface names in publication order.
+    /// Short public description of the object.
+    pub description: Option<String>,
+    /// Opaque interface references in host publication order.
     pub interfaces: Vec<String>,
-}
+    /// Optional opaque identity within one client-facing Worldspace.
-
+    pub r#ref: Option<String>,
-/// A complete logical observation of an object and its interface descriptors.
+    /// Optional opaque validator for the object's observed state.
-#[derive(Debug, Clone, PartialEq)]
+    pub validator: Option<Vec<u8>>,
-pub struct InterfaceObservation {
-    /// Observed object.
-    pub object: Object,
-    /// Descriptors corresponding to `object.interfaces`.
-    pub descriptors: Vec<InterfaceDescriptor>,
 }
 
 /// Transport-independent description of one interface.
-#[derive(Debug, Clone, PartialEq)]
+///
+/// Interface identity is supplied by interaction fields such as
+/// [`FetchInterfaceResponse::interface`], not embedded in the descriptor.
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InterfaceDescriptor {
-    /// Interface name.
+    /// Descriptor format version understood by clients and hosts.
-    pub name: String,
+    pub format: String,
     /// Optional interface documentation.
     pub documentation: Option<Documentation>,
-    /// Named type declarations local to this descriptor.
+    /// Named declarations local to this descriptor.
-    pub declarations: Vec<TypeDeclaration>,
+    pub types: Vec<TypeDeclaration>,
     /// Operations exposed by this interface.
     pub operations: Vec<OperationDeclaration>,
 }
 
-/// A named type declaration local to an interface descriptor.
+/// A descriptor-local named type declaration.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum TypeDeclaration {
+pub struct TypeDeclaration {
-    /// A record declaration.
-    Record(RecordDeclaration),
-    /// An enumeration declaration.
-    Enum(EnumDeclaration),
-    /// A tagged union declaration.
-    Union(UnionDeclaration),
-}
-
-impl TypeDeclaration {
-    /// Returns the descriptor-local declaration name.
-    #[must_use]
-    pub fn name(&self) -> &str {
-        match self {
-            Self::Record(declaration) => &declaration.name,
-            Self::Enum(declaration) => &declaration.name,
-            Self::Union(declaration) => &declaration.name,
-        }
-    }
-}
-
-/// Declaration of a record with named fields.
-#[derive(Debug, Clone, PartialEq)]
-pub struct RecordDeclaration {
     /// Descriptor-local type name.
     pub name: String,
-    /// Optional record documentation.
+    /// Optional type documentation.
     pub documentation: Option<Documentation>,
+    /// Definition associated with `name`.
+    pub definition: TypeExpr,
+}
+
+/// A type expression used by declarations, fields, parameters, and returns.
+///
+/// [`TypeExpr::Named`] references are resolved only within the containing
+/// descriptor. Recursive references, including recursion through lists,
+/// records, and unions, are invalid.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TypeExpr {
+    /// A value carrying no data.
+    Unit,
+    /// A boolean.
+    Boolean,
+    /// A JavaScript-lossless signed integer.
+    Integer,
+    /// A finite IEEE-754 binary64 number.
+    Number,
+    /// A Unicode string.
+    String,
+    /// An opaque byte sequence.
+    Bytes,
+    /// A schema-opaque JSON-compatible value tree.
+    Json,
+    /// A canonical absolute Worldspace path represented by a string value.
+    Entry,
+    /// A descriptor-local named declaration.
+    Named {
+        /// Referenced declaration name.
+        name: String,
+    },
+    /// A record with named fields.
+    Record {
         /// Fields in declaration order.
-    pub fields: Vec<FieldDeclaration>,
+        fields: Vec<FieldDeclaration>,
+    },
+    /// An ordered list.
+    List {
+        /// Type of every list item.
+        items: Box<TypeExpr>,
+    },
+    /// A closed set of payload-free cases represented by strings.
+    Enum {
+        /// Cases in declaration order.
+        cases: Vec<EnumCase>,
+    },
+    /// A discriminated union represented by a record.
+    Union {
+        /// Cases in declaration order.
+        cases: Vec<UnionCase>,
+    },
 }
 
 /// Declaration of a record field.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct FieldDeclaration {
     /// Field name.
     pub name: String,
+    /// Whether the field must be present.
+    pub required: bool,
     /// Optional field documentation.
     pub documentation: Option<Documentation>,
     /// Field value type.
-    pub ty: TypeExpr,
+    pub r#type: TypeExpr,
-    /// Whether the field may be omitted.
-    ///
-    /// Optionality represents absence, not a `null` value.
-    pub optional: bool,
 }
 
-/// Declaration of an enumeration.
+/// One payload-free enum case.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct EnumDeclaration {
+pub struct EnumCase {
-    /// Descriptor-local type name.
+    /// Case name.
     pub name: String,
-    /// Optional enum documentation.
+    /// Optional case documentation.
     pub documentation: Option<Documentation>,
-    /// Allowed variants in declaration order.
-    pub variants: Vec<EnumVariantDeclaration>,
 }
 
-/// Declaration of one enumeration variant.
+/// One union case with zero or one payload.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct EnumVariantDeclaration {
+pub struct UnionCase {
-    /// Variant name.
+    /// Case name.
     pub name: String,
-    /// Optional variant documentation.
+    /// Optional case documentation.
     pub documentation: Option<Documentation>,
-}
+    /// Optional payload type.
-
+    pub payload: Option<TypeExpr>,
-/// Declaration of a tagged union.
-#[derive(Debug, Clone, PartialEq)]
-pub struct UnionDeclaration {
-    /// Descriptor-local type name.
-    pub name: String,
-    /// Optional union documentation.
-    pub documentation: Option<Documentation>,
-    /// Allowed tagged variants in declaration order.
-    pub variants: Vec<UnionVariantDeclaration>,
-}
-
-/// Declaration of one tagged-union variant.
-#[derive(Debug, Clone, PartialEq)]
-pub struct UnionVariantDeclaration {
-    /// Variant tag.
-    pub name: String,
-    /// Optional variant documentation.
-    pub documentation: Option<Documentation>,
-    /// Payload type.
-    pub ty: TypeExpr,
-}
-
-/// A type expression used by fields, parameters, returns, and union payloads.
-///
-/// `Named` references are resolved only within the containing descriptor.
-/// Optional values are represented by the containing field or parameter and
-/// therefore are intentionally not a type expression.
-#[derive(Debug, Clone, PartialEq)]
-pub enum TypeExpr {
-    /// A UTF-8 string.
-    String,
-    /// A boolean.
-    Boolean,
-    /// A JavaScript-lossless integer.
-    Integer,
-    /// A finite IEEE-754 double precision number.
-    Number,
-    /// An opaque byte sequence.
-    Bytes,
-    /// An ordered sequence of values.
-    List(Box<TypeExpr>),
-    /// A key/value entry.
-    Entry {
-        /// Entry key type.
-        key: Box<TypeExpr>,
-        /// Entry value type.
-        value: Box<TypeExpr>,
-    },
-    /// A logical JSON value.
-    Json,
-    /// A descriptor-local named declaration.
-    Named(String),
 }
 
 /// Declaration of one interface operation.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OperationDeclaration {
-    /// Operation name, unique within its interface.
+    /// Operation name, unique within its descriptor.
     pub name: String,
     /// Optional operation documentation.
     pub documentation: Option<Documentation>,
     /// Parameters in declaration order.
     pub parameters: Vec<ParameterDeclaration>,
-    /// Return declaration, or `None` for an operation with no return value.
+    /// Return declaration. No-data operations return [`TypeExpr::Unit`].
-    pub returns: Option<ReturnDeclaration>,
+    pub returns: ReturnDeclaration,
 }
 
 /// Declaration of one operation parameter.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ParameterDeclaration {
     /// Parameter name.
     pub name: String,
+    /// Whether the parameter must be present.
+    pub required: bool,
     /// Optional parameter documentation.
     pub documentation: Option<Documentation>,
     /// Parameter value type.
-    pub ty: TypeExpr,
+    pub r#type: TypeExpr,
-    /// Whether the parameter may be omitted.
-    ///
-    /// Optionality represents absence, not a `null` value.
-    pub optional: bool,
 }
 
 /// Declaration of an operation return value.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ReturnDeclaration {
     /// Optional return-value documentation.
     pub documentation: Option<Documentation>,
     /// Return value type.
-    pub ty: TypeExpr,
+    pub r#type: TypeExpr,
 }
 
-/// A logical protocol value.
+/// A schema-neutral logical protocol value.
 ///
-/// There is no general `Null` variant: optional record fields and operation
+/// Enum cases, union cases, entries, and JSON are interpretations imposed by a
-/// parameters are omitted. JSON null remains available inside [`Value::Json`].
+/// descriptor. They are deliberately not variants of this enum. Record key
+/// ordering is not protocol-significant.
 #[derive(Debug, Clone, PartialEq)]
 pub enum Value {
-    /// A UTF-8 string.
+    /// A value carrying no data; it also represents JSON null under `Json`.
-    String(String),
+    Unit,
     /// A boolean.
     Boolean(bool),
-    /// An integer, validated against the JavaScript safe integer range.
+    /// A JavaScript-lossless integer.
     Integer(i64),
-    /// A number, validated to be finite.
+    /// A finite IEEE-754 binary64 number.
     Number(f64),
+    /// A Unicode string.
+    String(String),
     /// An opaque byte sequence.
     Bytes(Vec<u8>),
+    /// String-keyed fields with order-insensitive semantics.
+    Record(BTreeMap<String, Value>),
     /// An ordered sequence.
     List(Vec<Value>),
-    /// A key/value entry.
-    Entry {
-        /// Entry key.
-        key: Box<Value>,
-        /// Entry value.
-        value: Box<Value>,
-    },
-    /// Record fields. Duplicate names are invalid.
-    Record(Vec<NamedValue>),
-    /// An enum variant name.
-    Enum(String),
-    /// A tagged-union value.
-    Union {
-        /// Selected variant tag.
-        variant: String,
-        /// Variant payload.
-        value: Box<Value>,
-    },
-    /// A logical JSON value.
-    Json(JsonValue),
 }
 
 impl Value {
@@ -252,132 +206,233 @@ impl Value {
     #[must_use]
     pub fn kind(&self) -> crate::ValueKind {
         match self {
-            Self::String(_) => crate::ValueKind::String,
+            Self::Unit => crate::ValueKind::Unit,
             Self::Boolean(_) => crate::ValueKind::Boolean,
             Self::Integer(_) => crate::ValueKind::Integer,
             Self::Number(_) => crate::ValueKind::Number,
+            Self::String(_) => crate::ValueKind::String,
             Self::Bytes(_) => crate::ValueKind::Bytes,
-            Self::List(_) => crate::ValueKind::List,
-            Self::Entry { .. } => crate::ValueKind::Entry,
             Self::Record(_) => crate::ValueKind::Record,
-            Self::Enum(_) => crate::ValueKind::Enum,
+            Self::List(_) => crate::ValueKind::List,
-            Self::Union { .. } => crate::ValueKind::Union,
-            Self::Json(_) => crate::ValueKind::Json,
         }
     }
 }
 
-/// A named value used by records and operation arguments.
+/// Request for the object currently published at one path.
-#[derive(Debug, Clone, PartialEq)]
-pub struct NamedValue {
-    /// Field or parameter name.
-    pub name: String,
-    /// Associated value.
-    pub value: Value,
-}
-
-/// A transport-independent JSON value.
-#[derive(Debug, Clone, PartialEq)]
-pub enum JsonValue {
-    /// JSON null.
-    Null,
-    /// JSON boolean.
-    Boolean(bool),
-    /// JSON integer, validated against the JavaScript safe integer range.
-    Integer(i64),
-    /// JSON number, validated to be finite.
-    Number(f64),
-    /// JSON string.
-    String(String),
-    /// JSON array.
-    Array(Vec<JsonValue>),
-    /// JSON object. Duplicate member names are invalid.
-    Object(Vec<JsonMember>),
-}
-
-/// A member of a logical JSON object.
-#[derive(Debug, Clone, PartialEq)]
-pub struct JsonMember {
-    /// Member name.
-    pub name: String,
-    /// Member value.
-    pub value: JsonValue,
-}
-
-/// Logical destination of an operation call.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct OperationTarget {
+pub struct FetchRequest {
-    /// Target object.
+    /// Canonical absolute Worldspace path.
-    pub object: ObjectId,
+    pub path: String,
-    /// Target interface name.
+}
+
+/// Successful `fetch` response.
+pub type FetchResponse = Object;
+
+/// Request for a bounded breadth-first object-tree observation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FetchTreeRequest {
+    /// Canonical absolute path of the tree root.
+    pub path: String,
+    /// Maximum depth, where the requested object has depth zero.
+    pub depth: u32,
+    /// Maximum total node count, including the root. Must be nonzero.
+    pub limit: u32,
+}
+
+/// One node in a tree observation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ObjectTreeNode {
+    /// Object observed at this tree position.
+    pub object: Object,
+    /// Direct children in host-defined traversal order.
+    pub children: Vec<ObjectTreeNode>,
+}
+
+/// Successful `fetch_tree` response.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FetchTreeResponse {
+    /// Observed tree rooted at the requested path.
+    pub root: ObjectTreeNode,
+    /// Whether public indexable children were omitted by depth or limit.
+    pub truncated: bool,
+}
+
+/// Request for the current descriptor of one opaque interface reference.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FetchInterfaceRequest {
+    /// Opaque interface reference obtained from an object.
     pub interface: String,
-    /// Target operation name.
+}
+
+/// Successful `fetch_interface` response.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FetchInterfaceResponse {
+    /// Opaque interface reference corresponding to the request.
+    pub interface: String,
+    /// Current validated descriptor.
+    pub descriptor: InterfaceDescriptor,
+    /// Optional opaque validator for this descriptor observation.
+    pub validator: Option<Vec<u8>>,
+}
+
+/// Object portion of an operation target.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Target {
+    /// Canonical absolute path of the target object.
+    pub path: String,
+    /// Optional validator copied from the object observation.
+    pub validator: Option<Vec<u8>>,
+}
+
+/// Interface portion of an operation target.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InterfaceTarget {
+    /// Opaque interface reference selected from the object's interface set.
+    pub reference: String,
+    /// Optional validator copied from the interface observation.
+    pub validator: Option<Vec<u8>>,
+}
+
+/// Transport-independent request to execute one operation.
+#[derive(Debug, Clone, PartialEq)]
+pub struct CallOperationRequest {
+    /// Path and optional object-state precondition.
+    pub target: Target,
+    /// Interface reference and its independent optional precondition.
+    pub interface: InterfaceTarget,
+    /// Operation name within the selected descriptor.
     pub operation: String,
+    /// Named arguments; map iteration order has no protocol meaning.
+    pub arguments: BTreeMap<String, Value>,
 }
 
-/// A transport-independent operation call.
+/// Successful operation response.
 #[derive(Debug, Clone, PartialEq)]
-pub struct OperationCall {
+pub struct CallOperationResponse {
-    /// Logical call target.
+    /// Application result validated against the operation return declaration.
-    pub target: OperationTarget,
+    pub result: Value,
-    /// Named arguments. Optional arguments are represented by omission.
+    /// Optional validator for the object state observed after execution.
-    pub arguments: Vec<NamedValue>,
+    pub validator: Option<Vec<u8>>,
 }
 
-/// Successful or failed logical outcome of an operation.
+/// Logical outcome of any core interaction.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum OperationOutcome {
+pub enum ProtocolResult<T> {
-    /// Operation returned. `None` represents a declared no-return operation.
+    /// The interaction succeeded.
-    Returned(Option<Value>),
+    Success(T),
-    /// Operation failed with a protocol-level error.
+    /// The interaction failed at the protocol boundary.
-    Failed(ProtocolError),
+    Failure(ProtocolError),
-}
-
-/// A transport-independent operation result.
-#[derive(Debug, Clone, PartialEq)]
-pub struct OperationResult {
-    /// Target corresponding to the result.
-    pub target: OperationTarget,
-    /// Logical outcome.
-    pub outcome: OperationOutcome,
 }
 
 impl Object {
-    /// Validates ordered-set interface semantics.
+    /// Validates the object-independent name and ordered-interface-set rules.
     pub fn validate(&self) -> Result<(), ValidationError> {
         crate::validation::validate_object(self)
     }
+
+    /// Validates this object as the response observed at `path`.
+    pub fn validate_at_path(&self, path: &str) -> Result<(), ValidationError> {
+        crate::validation::validate_object_at_path(self, path)
     }
 
-impl InterfaceObservation {
+    /// Validates equal representations for a shared ref and present validator.
-    /// Validates the object, descriptor structure, and their correspondence.
+    pub fn validate_consistency_with(&self, other: &Self) -> Result<(), ValidationError> {
-    pub fn validate(&self) -> Result<(), ValidationError> {
+        crate::validation::validate_object_consistency(self, other)
-        crate::validation::validate_observation(self)
     }
 }
 
 impl InterfaceDescriptor {
-    /// Validates declaration structure, references, and absence of recursion.
+    /// Validates declaration structure, named references, and absence of cycles.
     pub fn validate(&self) -> Result<(), ValidationError> {
         crate::validation::validate_descriptor(self)
     }
 
-    /// Validates a value against a type expression in this descriptor.
+    /// Validates a raw value against a type expression in this descriptor.
-    pub fn validate_value(&self, ty: &TypeExpr, value: &Value) -> Result<(), ValidationError> {
+    pub fn validate_value(&self, r#type: &TypeExpr, value: &Value) -> Result<(), ValidationError> {
-        crate::validation::validate_root_value(self, ty, value)
+        crate::validation::validate_root_value(self, r#type, value)
     }
 
-    /// Validates a call target and arguments against this descriptor.
+    /// Validates named arguments for one declared operation.
-    pub fn validate_call(&self, call: &OperationCall) -> Result<(), ValidationError> {
+    pub fn validate_arguments(
-        crate::validation::validate_call(self, call)
-    }
-
-    /// Validates an operation's returned value against this descriptor.
-    pub fn validate_return(
         &self,
         operation: &str,
-        value: Option<&Value>,
+        arguments: &BTreeMap<String, Value>,
     ) -> Result<(), ValidationError> {
-        crate::validation::validate_return(self, operation, value)
+        crate::validation::validate_arguments(self, operation, arguments)
+    }
+
+    /// Validates one operation result against its return declaration.
+    pub fn validate_result(&self, operation: &str, result: &Value) -> Result<(), ValidationError> {
+        crate::validation::validate_result(self, operation, result)
+    }
+
+    /// Validates the path, operation, and arguments in a call request.
+    pub fn validate_call(&self, request: &CallOperationRequest) -> Result<(), ValidationError> {
+        crate::validation::validate_call(self, request)
+    }
+}
+
+impl FetchRequest {
+    /// Validates the request path.
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        crate::validation::validate_path(&self.path)
+    }
+
+    /// 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)
+    }
+}
+
+impl FetchTreeRequest {
+    /// Validates the request path and nonzero node limit.
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        crate::validation::validate_fetch_tree_request(self)
+    }
+}
+
+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)
+    }
+}
+
+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)
+    }
+}
+
+impl CallOperationRequest {
+    /// Validates this call against the descriptor selected by `interface`.
+    pub fn validate_with(&self, descriptor: &InterfaceDescriptor) -> Result<(), ValidationError> {
+        descriptor.validate_call(self)
+    }
+}
+
+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,
+        operation: &str,
+    ) -> Result<(), ValidationError> {
+        descriptor.validate_result(operation, &self.result)
     }
 }

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/src/main.rs

@@ -0,0 +1,14 @@
+use std::error::Error;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let report = wip_public_api_example::run()?;
+    println!(
+        "published {} interfaces; catalog={}, audit={}; domain={:?}; host={:?}",
+        report.published_interfaces.len(),
+        report.catalog_status,
+        report.audit_status,
+        report.rejected,
+        report.host_failure,
+    );
+    Ok(())
+}

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/main.rs

@@ -1,3 +0,0 @@
-fn main() {
-    println!("Hello, world!");
-}