fix: bound HTTP intake and response lifetimes

fix: bound filesystem execution and preserve guarantees
feat: add bounded filesystem projection server
2026-09-30 09:23:12 +09:00 · 2026-09-30 09:09:09 +09:00 · 2026-09-30 08:53:44 +09:00 · 2026-09-30 08:53:43 +09:00 · 2026-09-30 07:59:50 +09:00 · 2026-09-30 07:50:51 +09:00
51 changed files with 11845 additions and 974 deletions
@@ -2,12 +2,83 @@
 # 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 = "bitflags"
 version = "2.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 [[package]]
 name = "bytes"
 version = "1.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 [[package]]
 name = "cfg-if"
 version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
 [[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 = "errno"
 version = "0.3.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
 "libc",
 "windows-sys",
 ]
 [[package]]
 name = "fastrand"
 version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 [[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 = "getrandom"
 version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
 dependencies = [
 "cfg-if",
 "libc",
 "r-efi",
 ]
 [[package]]
 name = "glob"
 version = "0.3.4"
@@ -20,6 +91,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 +221,51 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
 name = "libc"
 version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
 [[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 = "once_cell"
 version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 [[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"
@@ -60,6 +284,25 @@ dependencies = [
 "proc-macro2",
 ]
 [[package]]
 name = "r-efi"
 version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 [[package]]
 name = "rustix"
 version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "891efababe418670775f199f0d233d84843c227a0949a883ce15b37c78d6629d"
 dependencies = [
 "bitflags",
 "errno",
 "libc",
 "linux-raw-sys",
 "windows-sys",
 ]
 [[package]]
 name = "serde"
 version = "1.0.229"
@@ -111,6 +354,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,12 +388,36 @@ 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"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "876fef147edbcbddc8ac5cbbba92c7b86519e314e86638596c09673b2ed01e7f"
 [[package]]
 name = "tempfile"
 version = "3.27.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
 "fastrand",
 "getrandom",
 "once_cell",
 "rustix",
 "windows-sys",
 ]
 [[package]]
 name = "termcolor"
 version = "1.4.1"
@@ -148,6 +427,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 +497,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 +545,19 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
 [[package]]
 name = "wip-fs-server"
 version = "0.1.0"
 dependencies = [
 "http",
 "rustix",
 "tempfile",
 "wip-host",
 "wip-https",
 "wip-interface",
 "wip-protocol",
 ]
 [[package]]
 name = "wip-host"
 version = "0.1.0"
@@ -247,6 +567,18 @@ dependencies = [
 "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"
@@ -270,12 +602,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"
@@ -1,17 +1,3 @@
 [workspace]
-members = [
+members = ["crates/*"]
    ".",
    "crates/wip-host",
    "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" }
@@ -2,6 +2,92 @@
 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 Rust
 interface-authoring facade, a request-scoped host runtime, a bounded Linux
 filesystem projection server, and a private public-API conformance consumer. The
 repository root is not itself a package.
 ## Crate graph and responsibilities
 ```text
 wip-fs-server (request-time filesystem projection and loopback listener)
 ├── wip-https                 standard routes/codecs/envelopes/batching
 ├── wip-host                  request-scoped publication and dispatch
 └── wip-interface             macro-generated filesystem capabilities
 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-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-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, interface-qualified dispatch against one host-owned instance, and descriptor-guided argument decoding inside that same resolution boundary. | Backend atomicity, global object lookup, or network serving. |
 | `wip-fs-server` | Linux directory-handle-confined request-time projection, bounded BFS trees and file operations, standard `wip-https` dispatch/batch handling, and a loopback HTTP binary for TLS-proxy or explicit development use. | A new wire profile, implicit symlink following, non-loopback cleartext, authentication policy, or filesystem-wide preregistration. |
 | `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,42 +116,69 @@ 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,
 `&self`, named parameters, and `OperationResult<T>`. Generic traits or methods,
 associated items, custom lifetimes, inheritance, default method bodies, and
 other receiver forms are rejected at their source spans.
 ## Host publication and dispatch
 Applications use `wip-host` to register generated definitions and explicitly
@@ -83,17 +196,83 @@ 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; descriptor names and
+references are rejected. Registry references are opaque and remain outside the
-Rust type names are not used as wire identity.
+descriptor; generated descriptors contain neither those references nor Rust
 trait identity.
-Dispatch is qualified by interface reference and operation name. The host checks
+Dispatch is qualified by interface reference and operation name and targets a
-current object identity and validator policy, current interface membership,
+canonical Worldspace path. An `ObjectProvider` validates that path before
-interface validator, descriptor operation, arguments, and result while retaining
+resolution, maps malformed paths to `InvalidRequest`, then resolves a valid path
-the selected object and registered artifact. Host-private fields and backend
+exactly once inside `with_object`; the host checks the supplied object validator,
-handles are never projected by `WipObject`.
+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.
-Providers remain responsible for backend atomicity. Enter a transaction, lock,
+Application domain failures belong in a derived result union and are returned
-stable-handle scope, or conditional-update primitive before constructing and
+through `Ok`. `wip::HostError` is reserved for runtime/backend failures. A
-dispatching the request-scoped `PublishedObject`, and retain it until dispatch
+structurally malformed call is `InvalidRequest`; only argument values checked
-returns. The runtime never validates one object and then resolves a second
+after the current Interface Descriptor is fixed are `InvalidArguments`. A Host
-snapshot, but it cannot make an arbitrary external backend atomic by itself.
+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.
 ## Filesystem projection server
 [`crates/wip-fs-server`](crates/wip-fs-server) contains the practical server
 binary and its full security model, configuration, curl walkthrough, and
 resource/failure semantics. It resolves every object from current filesystem
 state, uses pinned directory-relative handles without following symlinks, omits
 non-UTF-8 backend names, performs bounded breadth-first tree discovery, and
 publishes validator-protected replacement only in explicit read-write mode.
 The built-in cleartext listener is loopback-only: production HTTPS is explicitly
 delegated to a reverse proxy, while local plain HTTP requires an opt-in flag.
 ## 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.
@@ -0,0 +1,19 @@
 [package]
 name = "wip-fs-server"
 version = "0.1.0"
 edition = "2024"
 description = "Request-time filesystem projection server for WIP over HTTPS"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 publish = false
 [dependencies]
 http = "1"
 rustix = { version = "1.1", features = ["fs"] }
 wip-host = { path = "../wip-host" }
 wip-https = { path = "../wip-https" }
 wip-interface = { path = "../wip-interface" }
 wip-protocol = { path = "../wip-protocol" }
 [dev-dependencies]
 tempfile = "3"
@@ -0,0 +1,148 @@
 # wip-fs-server
 `wip-fs-server` projects one configured Linux filesystem directory onto WIP
 Worldspace `/` at request time. It does not register the filesystem contents or
 keep one object instance per entry. It uses `wip-host` for publication and typed
 operation dispatch and uses the standard `wip-https` routes, JSON codecs,
 envelopes, batching, and HTTP status mapping.
 ## Security model
 - The effective root is opened once as a directory capability. Root path
  components must be real directories (symlink components are rejected), and the
  displayed effective root is read back from that same pinned descriptor. Every
  request is resolved segment-by-segment with directory-relative, `O_NOFOLLOW`
  handles.
 - Symlinks are projected as links and are never followed. Their stored target is
  available only through the `SymlinkInspect.read_link` application operation.
 - Regular files, directories, symlinks, and unsupported entry types have distinct
  public descriptions and capability sets.
 - WIP names are Unicode. Linux names that are not valid UTF-8 are deliberately
  not published; valid UTF-8 names map byte-for-byte and therefore cannot collide.
  Unicode paths containing backend-invalid NUL bytes are likewise treated as
  unpublished rather than as backend failures.
 - No object `ref` is issued. This avoids claiming representation identity for
  hard links or path-specific names. Regular files and symlinks receive an opaque
  validator containing filesystem identity plus protected metadata; replacing a
  path therefore does not preserve its validator.
 - Protocol metadata and errors never contain the backend absolute path. Startup
  prints only the explicitly configured effective root and security-sensitive
  modes.
 - The built-in listener is cleartext and loopback-only. Production deployments
  must pass `--behind-tls-proxy` and terminate HTTPS at a trusted reverse proxy.
  Plain development HTTP requires the explicit `--development-http` flag.
 The implementation currently targets Linux because it uses `O_PATH`,
 directory-relative descriptor traversal, and `/proc/self/fd` to reopen the same
 pinned backend object without resolving the untrusted Worldspace path twice.
 ## Run
 Read-only behind a TLS-terminating reverse proxy:
 ```console
 cargo run -p wip-fs-server -- \
  --root /srv/public-files \
  --listen 127.0.0.1:8443 \
  --base-path /wip \
  --behind-tls-proxy
 ```
 Local development with the write capability deliberately enabled:
 ```console
 cargo run -p wip-fs-server -- \
  --root ./example-files \
  --listen 127.0.0.1:8080 \
  --base-path /wip \
  --development-http \
  --read-write
 ```
 The server reports the effective root, `ReadOnly`/`ReadWrite` mode, transport
 mode, endpoint, and actual listen address. It does not enumerate the root.
 ## Standard interactions
 The following examples use development HTTP for readability. The JSON is the
 standard `wip-https` profile; validators and operation `Bytes` are base64 body
 fields, never `ETag` or `If-Match` headers.
 Fetch root:
 ```console
 curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{"path":"/"}'
 ```
 Fetch a bounded tree (the root counts toward `limit`):
 ```console
 curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch_tree \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{"path":"/","depth":2,"limit":100}'
 ```
 A regular-file fetch returns the opaque read interface reference and an object
 validator. Retrieve that descriptor with:
 ```console
 curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch_interface \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{"interface":"<read-interface-from-fetch>"}'
 ```
 Then call a bounded range read:
 ```console
 curl -sS -X POST http://127.0.0.1:8080/wip/v1/call_operation \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{
    "target":{"path":"/notes.txt","validator":"<base64-validator>"},
    "interface":{"reference":"<read-interface>"},
    "operation":"read",
    "arguments":{"offset":0,"length":4096}
  }'
 ```
 In `--read-write` mode a second regular-file interface declares `replace`.
 Writes require the current object validator and return the post-write validator:
 ```console
 curl -sS -X POST http://127.0.0.1:8080/wip/v1/call_operation \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{
    "target":{"path":"/notes.txt","validator":"<base64-validator>"},
    "interface":{"reference":"<write-interface>"},
    "operation":"replace",
    "arguments":{"contents":"dXBkYXRlZA=="}
  }'
 ```
 `fetch`, `fetch_tree`, and `fetch_interface` can also be combined through the
 standard `POST /wip/v1/batch` route. `call_operation` is never batchable.
 ## Resource and failure behavior
 `ResourceLimits` bounds request/response bytes, HTTP request-head bytes, JSON
 nesting, batch items, file read/write bytes, tree depth/node count, pinned handles,
 and active connections/requests. One absolute request deadline covers header and
 body intake, dispatch, cooperative filesystem work, and response transmission;
 stalled clients are closed and cannot occupy a worker beyond that bound. Workers
 accept connections directly, so the listener never moves more than the configured
 concurrency into active userspace service. Advisory file-lock acquisition uses a
 nonblocking loop and checks the same deadline/cancellation rather than allowing a
 contended lock to stall a worker. Tree traversal is breadth-first and opens only
 requested entries. Once a limit or depth boundary is reached it reads only far
 enough to
 prove whether an additional visible child exists, so `truncated` is true only
 when something was actually omitted. I/O failure and cancellation remain errors,
 not clean exhaustion.
 Whole-file replacement compares the request validator against the identity and
 state of the same pinned file handle used for the write. Failures before mutation
 carry a `NotCommitted` guarantee and map to `Internal` or
 `ResourceLimitExceeded`; a failure after truncation/write begins maps to
 `OperationOutcomeUnknown`. The server and Clients do not automatically retry
 side-effecting operations.
@@ -0,0 +1,43 @@
 //! Filesystem capability interfaces published by the projection.
 use wip_interface as wip;
 /// Bounded reads from a regular file.
 #[wip::interface]
 pub trait FileRead {
    /// Reads bytes from the current regular file.
    ///
    /// # Returns
    /// At most the configured read limit, beginning at `offset`.
    fn read(
        &self,
        /// Byte offset; omitted means zero.
        offset: Option<u64>,
        /// Requested byte count; omitted means the rest of the file.
        length: Option<u64>,
    ) -> wip::OperationResult<wip::Bytes>;
 }
 /// Inspection operations for a symbolic link itself.
 #[wip::interface]
 pub trait SymlinkInspect {
    /// Reads the link payload without following it.
    ///
    /// # Returns
    /// The platform path bytes stored in the symbolic link.
    fn read_link(&self) -> wip::OperationResult<wip::Bytes>;
 }
 /// Explicitly enabled mutation of a regular file.
 #[wip::interface]
 pub trait FileWrite {
    /// Replaces the current regular file contents through its pinned handle.
    ///
    /// # Returns
    /// Unit after the new bytes have been written and synchronized.
    fn replace(
        &self,
        /// Complete replacement contents.
        contents: wip::Bytes,
    ) -> wip::OperationResult<()>;
 }
@@ -0,0 +1,191 @@
 //! Request-time filesystem projection served through the standard WIP HTTPS binding.
 //!
 //! This crate deliberately keeps the boundaries visible:
 //!
 //! - [`wip_protocol`] owns logical requests and responses;
 //! - [`wip_host`] owns object publication, validators, and typed dispatch;
 //! - [`wip_https`] owns routes, JSON, envelopes, batching, and status mapping;
 //! - this crate owns the filesystem capability boundary and the real HTTP listener.
 //!
 //! TLS is terminated by an explicitly configured reverse proxy. The built-in
 //! listener accepts cleartext only on loopback, either behind that proxy or when
 //! [`TransportSecurity::DevelopmentHttp`] is deliberately selected.
 #![deny(missing_docs)]
 mod interfaces;
 mod projection;
 mod server;
 use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 use std::path::PathBuf;
 use std::time::Duration;
 pub use interfaces::{FileRead, FileWrite, SymlinkInspect};
 pub use server::{BoundServer, ServerBuildError, WipFsServer};
 /// Filesystem capabilities published by regular files.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AccessMode {
    /// Publish bounded reads only.
    ReadOnly,
    /// Also publish validator-protected whole-file replacement.
    ReadWrite,
 }
 /// How HTTPS is provided for the endpoint.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TransportSecurity {
    /// A trusted reverse proxy terminates TLS and forwards to the loopback listener.
    ReverseProxyTls,
    /// Cleartext HTTP is deliberately enabled for local development only.
    DevelopmentHttp,
 }
 /// Bounded resource policy applied by the HTTP adapter and filesystem provider.
 #[derive(Debug, Clone, Copy)]
 pub struct ResourceLimits {
    /// Standard JSON, body-size, nesting, and batch limits.
    pub wire: wip_https::Limits,
    /// Maximum bytes returned by one file read.
    pub max_file_read_bytes: usize,
    /// Maximum bytes accepted by one file replacement.
    pub max_file_write_bytes: usize,
    /// Maximum accepted `fetch_tree` depth.
    pub max_tree_depth: u32,
    /// Maximum accepted `fetch_tree` node count, including its root.
    pub max_tree_nodes: u32,
    /// Maximum simultaneously pinned projected filesystem handles.
    pub max_open_handles: usize,
    /// Maximum bytes accepted for one HTTP request head, including its terminator.
    pub max_http_header_bytes: usize,
    /// Maximum requests executing concurrently.
    pub max_concurrent_requests: usize,
    /// End-to-end deadline for HTTP intake, dispatch, and response transmission.
    pub request_timeout: Duration,
 }
 impl Default for ResourceLimits {
    fn default() -> Self {
        Self {
            wire: wip_https::Limits::new(256 * 1024, 2 * 1024 * 1024, 64, 64)
                .expect("default wire limits are nonzero"),
            max_file_read_bytes: 1024 * 1024,
            max_file_write_bytes: 1024 * 1024,
            max_tree_depth: 32,
            max_tree_nodes: 1024,
            max_open_handles: 2048,
            max_http_header_bytes: 16 * 1024,
            max_concurrent_requests: 32,
            request_timeout: Duration::from_secs(30),
        }
    }
 }
 /// Complete listener and projection configuration.
 #[derive(Debug, Clone)]
 pub struct ServerConfig {
    /// Filesystem directory projected as Worldspace `/`.
    pub root: PathBuf,
    /// Loopback socket used by the built-in cleartext listener.
    pub listen: SocketAddr,
    /// URL path prefix below which standard `v1/*` routes are mounted.
    pub endpoint_base_path: String,
    /// Read-only or explicit read-write publication mode.
    pub access: AccessMode,
    /// TLS termination or explicit development HTTP policy.
    pub transport_security: TransportSecurity,
    /// Request, operation, traversal, and concurrency bounds.
    pub limits: ResourceLimits,
 }
 impl ServerConfig {
    /// Builds a secure-by-default configuration for `root`.
    ///
    /// The listener defaults to an ephemeral loopback port, read-only access,
    /// and TLS termination delegated to a reverse proxy.
    #[must_use]
    pub fn for_root(root: impl Into<PathBuf>) -> Self {
        Self {
            root: root.into(),
            listen: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0),
            endpoint_base_path: "/wip".into(),
            access: AccessMode::ReadOnly,
            transport_security: TransportSecurity::ReverseProxyTls,
            limits: ResourceLimits::default(),
        }
    }
    pub(crate) fn validate(&self) -> Result<(), ConfigError> {
        if !self.listen.ip().is_loopback() {
            return Err(ConfigError::NonLoopbackCleartext);
        }
        if !valid_base_path(&self.endpoint_base_path) {
            return Err(ConfigError::InvalidBasePath);
        }
        if self.limits.max_file_read_bytes == 0
            || self.limits.max_file_write_bytes == 0
            || self.limits.max_tree_nodes == 0
            || self.limits.max_open_handles == 0
            || self.limits.max_http_header_bytes == 0
            || self.limits.max_concurrent_requests == 0
            || self.limits.request_timeout.is_zero()
        {
            return Err(ConfigError::ZeroLimit);
        }
        if self.limits.max_open_handles < self.limits.max_tree_nodes as usize {
            return Err(ConfigError::InsufficientHandles);
        }
        if self.limits.wire.max_response_bytes() < 512 {
            return Err(ConfigError::ResponseLimitTooSmall);
        }
        Ok(())
    }
    pub(crate) fn endpoint(&self) -> Result<wip_https::Endpoint, ConfigError> {
        let endpoint = format!("https://localhost{}", self.endpoint_base_path);
        wip_https::Endpoint::parse(&endpoint).map_err(|_| ConfigError::InvalidBasePath)
    }
 }
 /// Invalid server configuration.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ConfigError {
    /// The cleartext built-in listener was exposed beyond loopback.
    NonLoopbackCleartext,
    /// The endpoint prefix is not an absolute canonical URL path.
    InvalidBasePath,
    /// A resource limit is zero.
    ZeroLimit,
    /// Tree nodes could exhaust the configured handle ceiling by construction.
    InsufficientHandles,
    /// The response limit cannot reliably carry a bounded protocol error envelope.
    ResponseLimitTooSmall,
 }
 impl std::fmt::Display for ConfigError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(match self {
            Self::NonLoopbackCleartext => "the built-in cleartext listener must bind to loopback",
            Self::InvalidBasePath => {
                "endpoint base path must be absolute, canonical, and query-free"
            }
            Self::ZeroLimit => "all resource limits and the request timeout must be nonzero",
            Self::InsufficientHandles => "max_open_handles must cover max_tree_nodes",
            Self::ResponseLimitTooSmall => "max_response_bytes must be at least 512",
        })
    }
 }
 impl std::error::Error for ConfigError {}
 fn valid_base_path(path: &str) -> bool {
    path.starts_with('/')
        && !path.contains('?')
        && !path.contains('#')
        && !path.contains("//")
        && !path
            .split('/')
            .any(|segment| segment == "." || segment == "..")
        && (path == "/" || !path.ends_with('/'))
 }
@@ -0,0 +1,83 @@
 use std::error::Error;
 use std::net::SocketAddr;
 use std::path::PathBuf;
 use wip_fs_server::{AccessMode, ServerConfig, TransportSecurity, WipFsServer};
 fn main() -> Result<(), Box<dyn Error>> {
    let mut root: Option<PathBuf> = None;
    let mut listen: SocketAddr = "127.0.0.1:8443".parse()?;
    let mut base_path = "/wip".to_owned();
    let mut access = AccessMode::ReadOnly;
    let mut security = None;
    let mut arguments = std::env::args().skip(1);
    while let Some(argument) = arguments.next() {
        match argument.as_str() {
            "--root" => root = Some(PathBuf::from(required_value(&mut arguments, "--root")?)),
            "--listen" => listen = required_value(&mut arguments, "--listen")?.parse()?,
            "--base-path" => base_path = required_value(&mut arguments, "--base-path")?,
            "--read-write" => access = AccessMode::ReadWrite,
            "--development-http" => {
                set_security(&mut security, TransportSecurity::DevelopmentHttp)?
            }
            "--behind-tls-proxy" => {
                set_security(&mut security, TransportSecurity::ReverseProxyTls)?
            }
            "--help" | "-h" => {
                print_help();
                return Ok(());
            }
            unknown => return Err(format!("unknown argument `{unknown}`; use --help").into()),
        }
    }
    let root = root.ok_or("--root is required")?;
    let transport_security =
        security.ok_or("select exactly one of --behind-tls-proxy or --development-http")?;
    let mut config = ServerConfig::for_root(root);
    config.listen = listen;
    config.endpoint_base_path = base_path;
    config.access = access;
    config.transport_security = transport_security;
    let server = WipFsServer::new(config)?;
    let effective_root = server.effective_root().to_owned();
    let endpoint = server.endpoint().clone();
    let bound = server.bind()?;
    eprintln!(
        "wip-fs-server root={} access={access:?} transport={transport_security:?} endpoint={} listen={}",
        effective_root.display(),
        endpoint,
        bound.local_addr()
    );
    bound.serve()?;
    Ok(())
 }
 fn required_value(
    arguments: &mut impl Iterator<Item = String>,
    option: &str,
 ) -> Result<String, Box<dyn Error>> {
    arguments
        .next()
        .ok_or_else(|| format!("{option} requires a value").into())
 }
 fn set_security(
    security: &mut Option<TransportSecurity>,
    value: TransportSecurity,
 ) -> Result<(), Box<dyn Error>> {
    if security.replace(value).is_some() {
        Err("select only one transport-security mode".into())
    } else {
        Ok(())
    }
 }
 fn print_help() {
    println!(
        "Usage: wip-fs-server --root PATH [--listen 127.0.0.1:8443] \\\n         [--base-path /wip] [--read-write] \\\n         (--behind-tls-proxy | --development-http)\n\n\
         The built-in listener is cleartext and loopback-only. In production, \
         select --behind-tls-proxy and terminate HTTPS at a trusted reverse proxy."
    );
 }
@@ -0,0 +1,747 @@
 use std::io::{Read, Write};
 use std::net::{SocketAddr, TcpListener, TcpStream};
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::thread;
 use std::time::{Duration, Instant};
 use http::{Request, Response, StatusCode};
 use wip_host::{ExecutionContext, ObjectProvider};
 use wip_https::{
    BatchRequestKind, BatchResponse, BatchResponseItem, BatchSuccess, CodecError, EncodeHttpError,
    Endpoint, RequestMetadataError, ResourceLimitKind, Route, decode_batch_request,
    decode_call_operation_metadata, decode_fetch_interface_request, decode_fetch_request,
    decode_fetch_tree_request, encode_batch_error_response,
    encode_batch_resource_limit_error_response, encode_batch_response,
    encode_call_operation_response, encode_fetch_interface_response, encode_fetch_response,
    encode_fetch_tree_response, encode_protocol_error_response,
    encode_resource_limit_error_response, validate_http_request,
 };
 use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
 use crate::projection::Projection;
 use crate::{ConfigError, ServerConfig};
 /// Filesystem projection and framework-neutral standard WIP request adapter.
 pub struct WipFsServer {
    config: ServerConfig,
    endpoint: Endpoint,
    effective_root: std::path::PathBuf,
    projection: Arc<Projection>,
 }
 impl WipFsServer {
    /// Validates configuration and opens the configured directory capability.
    pub fn new(config: ServerConfig) -> Result<Self, ServerBuildError> {
        config.validate()?;
        let endpoint = config.endpoint()?;
        let projection = Projection::open(&config.root, config.access, config.limits)?;
        let effective_root = projection.effective_root()?;
        Ok(Self {
            config,
            endpoint,
            effective_root,
            projection: Arc::new(projection),
        })
    }
    /// Returns the canonical effective filesystem root opened by the server.
    #[must_use]
    pub fn effective_root(&self) -> &std::path::Path {
        &self.effective_root
    }
    /// Returns the configured transport endpoint prefix.
    #[must_use]
    pub fn endpoint(&self) -> &Endpoint {
        &self.endpoint
    }
    /// Handles one already-buffered HTTP request with the standard `wip-https` codecs.
    ///
    /// Listener integrations must enforce the same body limit while collecting bytes.
    #[must_use]
    pub fn handle_http(&self, request: Request<Vec<u8>>) -> Response<Vec<u8>> {
        self.handle_http_with_deadline(request, Instant::now() + self.config.limits.request_timeout)
    }
    fn handle_http_with_deadline(
        &self,
        request: Request<Vec<u8>>,
        deadline: Instant,
    ) -> Response<Vec<u8>> {
        let Some(route) = self.route(request.uri().path()) else {
            return empty_response(StatusCode::NOT_FOUND);
        };
        if let Err(error) = validate_http_request(&self.endpoint, route, &request) {
            return self.metadata_error(route, error);
        }
        let context = ExecutionContext::new()
            .with_deadline(deadline)
            .with_resource_budget(u64::from(self.config.limits.max_tree_nodes));
        match route {
            Route::Fetch => self.fetch(request.body(), &context),
            Route::FetchTree => self.fetch_tree(request.body(), &context),
            Route::FetchInterface => self.fetch_interface(request.body()),
            Route::CallOperation => self.call_operation(request.body(), &context),
            Route::Batch => self.batch(request.body(), &context),
        }
    }
    /// Binds the built-in bounded loopback HTTP listener.
    ///
    /// The listener is cleartext by design. Configuration must explicitly state
    /// whether TLS is terminated by a reverse proxy or development HTTP is in use.
    pub fn bind(self) -> Result<BoundServer, ServerBuildError> {
        let listener = TcpListener::bind(self.config.listen)
            .map_err(|error| ServerBuildError::Listener(error.to_string()))?;
        listener
            .set_nonblocking(true)
            .map_err(|error| ServerBuildError::Listener(error.to_string()))?;
        let local_addr = listener
            .local_addr()
            .map_err(|error| ServerBuildError::Listener(error.to_string()))?;
        Ok(BoundServer {
            local_addr,
            service: Arc::new(self),
            listener: Arc::new(listener),
        })
    }
    fn route(&self, path: &str) -> Option<Route> {
        [
            Route::Fetch,
            Route::FetchTree,
            Route::FetchInterface,
            Route::CallOperation,
            Route::Batch,
        ]
        .into_iter()
        .find(|route| self.endpoint.route(*route).path() == path)
    }
    fn fetch(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
        let request = match decode_fetch_request(body, self.config.limits.wire) {
            Ok(request) => request,
            Err(error) => return self.codec_error(ProtocolInteraction::Fetch, error),
        };
        match self
            .projection
            .fetch_with_context(context, &request.path)
            .map_err(|error| error.protocol_error())
        {
            Ok(object) => encode_fetch_response(&request, &object, self.config.limits.wire)
                .unwrap_or_else(|error| self.read_encode_error(ProtocolInteraction::Fetch, error)),
            Err(error) => self.protocol_error(ProtocolInteraction::Fetch, &error, None),
        }
    }
    fn fetch_tree(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
        let request = match decode_fetch_tree_request(body, self.config.limits.wire) {
            Ok(request) => request,
            Err(error) => return self.codec_error(ProtocolInteraction::FetchTree, error),
        };
        match self.projection.fetch_tree(context, &request) {
            Ok(tree) => encode_fetch_tree_response(&request, &tree, self.config.limits.wire)
                .unwrap_or_else(|error| {
                    self.read_encode_error(ProtocolInteraction::FetchTree, error)
                }),
            Err(error) => self.protocol_error(ProtocolInteraction::FetchTree, &error, None),
        }
    }
    fn fetch_interface(&self, body: &[u8]) -> Response<Vec<u8>> {
        let request = match decode_fetch_interface_request(body, self.config.limits.wire) {
            Ok(request) => request,
            Err(error) => return self.codec_error(ProtocolInteraction::FetchInterface, error),
        };
        match self.projection.fetch_interface(&request) {
            Ok(interface) => {
                encode_fetch_interface_response(&request, &interface, self.config.limits.wire)
                    .unwrap_or_else(|error| {
                        self.read_encode_error(ProtocolInteraction::FetchInterface, error)
                    })
            }
            Err(error) => self.protocol_error(ProtocolInteraction::FetchInterface, &error, None),
        }
    }
    fn call_operation(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
        let metadata = match decode_call_operation_metadata(body, self.config.limits.wire) {
            Ok(metadata) => metadata,
            Err(error) => return self.codec_error(ProtocolInteraction::CallOperation, error),
        };
        let may_commit = metadata.operation == "replace";
        let decoded = std::sync::Mutex::new(None);
        let execution = self.projection.call_operation_with_context_and_decoder(
            context,
            metadata.target.clone(),
            metadata.interface.clone(),
            metadata.operation.clone(),
            |descriptor| {
                let request = metadata.decode_request(body, descriptor, self.config.limits.wire)?;
                let arguments = request.arguments.clone();
                *decoded.lock().unwrap_or_else(|error| error.into_inner()) =
                    Some((request, descriptor.clone()));
                Ok::<_, CodecError>(arguments)
            },
        );
        match execution.map_err(|error| error.protocol_error()) {
            Ok(result) => {
                let Some((request, descriptor)) = decoded
                    .into_inner()
                    .unwrap_or_else(|error| error.into_inner())
                else {
                    let error = ProtocolError {
                        code: if may_commit {
                            ProtocolErrorCode::OperationOutcomeUnknown
                        } else {
                            ProtocolErrorCode::Internal
                        },
                        message: "operation completed without response metadata".into(),
                    };
                    return self.protocol_error(ProtocolInteraction::CallOperation, &error, None);
                };
                encode_call_operation_response(
                    &request,
                    &descriptor,
                    &result,
                    self.config.limits.wire,
                )
                .unwrap_or_else(|encode_error| {
                    if !may_commit {
                        return self
                            .read_encode_error(ProtocolInteraction::CallOperation, encode_error);
                    }
                    // Replacement may already be committed, so a response
                    // encoding failure cannot carry a non-commit guarantee.
                    let error = ProtocolError {
                        code: ProtocolErrorCode::OperationOutcomeUnknown,
                        message: "operation completed but its response could not be encoded".into(),
                    };
                    self.protocol_error(ProtocolInteraction::CallOperation, &error, None)
                })
            }
            Err(error) => self.protocol_error(ProtocolInteraction::CallOperation, &error, None),
        }
    }
    fn batch(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
        let request = match decode_batch_request(body, self.config.limits.wire) {
            Ok(request) => request,
            Err(error) => return self.batch_codec_error(error),
        };
        let responses = request
            .requests
            .iter()
            .map(|item| {
                let outcome = match &item.request {
                    BatchRequestKind::Fetch(request) => self
                        .projection
                        .fetch_with_context(context, &request.path)
                        .map(BatchSuccess::Fetch)
                        .map_err(|error| error.protocol_error()),
                    BatchRequestKind::FetchTree(request) => self
                        .projection
                        .fetch_tree(context, request)
                        .map(BatchSuccess::FetchTree),
                    BatchRequestKind::FetchInterface(request) => self
                        .projection
                        .fetch_interface(request)
                        .map(BatchSuccess::FetchInterface),
                    BatchRequestKind::Invalid { error, .. } => Err(error.clone()),
                };
                BatchResponseItem {
                    id: item.id.clone(),
                    outcome,
                }
            })
            .collect();
        let response = BatchResponse { responses };
        encode_batch_response(&request, &response, self.config.limits.wire).unwrap_or_else(
            |error| match error {
                EncodeHttpError::Codec(codec) => self.batch_codec_error(codec),
                EncodeHttpError::Http(_) => self.batch_top_error(&internal_error(), None),
            },
        )
    }
    fn metadata_error(&self, route: Route, error: RequestMetadataError) -> Response<Vec<u8>> {
        match error {
            RequestMetadataError::InvalidRequest(_) => self.protocol_error(
                interaction(route),
                &ProtocolError {
                    code: ProtocolErrorCode::InvalidRequest,
                    message: "invalid HTTP request metadata".into(),
                },
                None,
            ),
            RequestMetadataError::UnsupportedMediaType => {
                empty_response(StatusCode::UNSUPPORTED_MEDIA_TYPE)
            }
            RequestMetadataError::NotAcceptable => empty_response(StatusCode::NOT_ACCEPTABLE),
        }
    }
    fn codec_error(
        &self,
        interaction: ProtocolInteraction,
        error: CodecError,
    ) -> Response<Vec<u8>> {
        if let Some(kind) = error.resource_limit_kind() {
            self.protocol_error(interaction, &resource_error(), Some(kind))
        } else {
            self.protocol_error(
                interaction,
                &ProtocolError {
                    code: ProtocolErrorCode::InvalidRequest,
                    message: "malformed WIP request".into(),
                },
                None,
            )
        }
    }
    fn batch_codec_error(&self, error: CodecError) -> Response<Vec<u8>> {
        if let Some(kind) = error.resource_limit_kind() {
            self.batch_top_error(&resource_error(), Some(kind))
        } else {
            self.batch_top_error(
                &ProtocolError {
                    code: ProtocolErrorCode::InvalidRequest,
                    message: "malformed WIP batch request".into(),
                },
                None,
            )
        }
    }
    fn read_encode_error(
        &self,
        interaction: ProtocolInteraction,
        error: EncodeHttpError,
    ) -> Response<Vec<u8>> {
        match error {
            EncodeHttpError::Codec(codec) if codec.resource_limit_kind().is_some() => {
                self.protocol_error(interaction, &resource_error(), codec.resource_limit_kind())
            }
            _ => self.protocol_error(interaction, &internal_error(), None),
        }
    }
    fn protocol_error(
        &self,
        interaction: ProtocolInteraction,
        error: &ProtocolError,
        resource_kind: Option<ResourceLimitKind>,
    ) -> Response<Vec<u8>> {
        let encoded = match resource_kind {
            Some(kind) => encode_resource_limit_error_response(
                interaction,
                error,
                kind,
                self.config.limits.wire,
            ),
            None => encode_protocol_error_response(interaction, error, self.config.limits.wire),
        };
        encoded.unwrap_or_else(|_| empty_response(StatusCode::INTERNAL_SERVER_ERROR))
    }
    fn batch_top_error(
        &self,
        error: &ProtocolError,
        resource_kind: Option<ResourceLimitKind>,
    ) -> Response<Vec<u8>> {
        let encoded = match resource_kind {
            Some(kind) => {
                encode_batch_resource_limit_error_response(error, kind, self.config.limits.wire)
            }
            None => encode_batch_error_response(error, self.config.limits.wire),
        };
        encoded.unwrap_or_else(|_| empty_response(StatusCode::INTERNAL_SERVER_ERROR))
    }
 }
 /// Bound real HTTP listener for a [`WipFsServer`].
 pub struct BoundServer {
    local_addr: SocketAddr,
    service: Arc<WipFsServer>,
    listener: Arc<TcpListener>,
 }
 impl BoundServer {
    /// Returns the actual bound loopback address, including an assigned port.
    #[must_use]
    pub fn local_addr(&self) -> SocketAddr {
        self.local_addr
    }
    /// Serves requests with a fixed worker count until `shutdown` becomes true.
    ///
    /// Workers accept connections directly, so at most
    /// `max_concurrent_requests` sockets are active in userspace. Each connection
    /// is closed after one request and shares one absolute deadline across HTTP
    /// intake, dispatch, and response transmission.
    pub fn serve_until(&self, shutdown: Arc<AtomicBool>) -> Result<(), std::io::Error> {
        let mut workers = Vec::with_capacity(self.service.config.limits.max_concurrent_requests);
        for _ in 0..self.service.config.limits.max_concurrent_requests {
            let listener = Arc::clone(&self.listener);
            let service = Arc::clone(&self.service);
            let shutdown = Arc::clone(&shutdown);
            workers.push(thread::spawn(move || {
                while !shutdown.load(Ordering::Acquire) {
                    match listener.accept() {
                        Ok((stream, _)) => serve_connection(&service, stream),
                        Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
                            thread::sleep(Duration::from_millis(5));
                        }
                        Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
                        Err(error) => return Err(error),
                    }
                }
                Ok(())
            }));
        }
        for worker in workers {
            worker
                .join()
                .map_err(|_| std::io::Error::other("HTTP worker panicked"))??;
        }
        Ok(())
    }
    /// Serves until the process is terminated.
    pub fn serve(&self) -> Result<(), std::io::Error> {
        self.serve_until(Arc::new(AtomicBool::new(false)))
    }
 }
 #[derive(Debug)]
 struct ParsedRequestHead {
    method: http::Method,
    target: String,
    headers: Vec<(http::header::HeaderName, http::HeaderValue)>,
    content_length: usize,
 }
 #[derive(Debug)]
 enum IntakeError {
    Timeout,
    HeaderTooLarge,
    PayloadTooLarge { target: String },
    BadRequest,
    Socket,
 }
 fn serve_connection(service: &WipFsServer, mut stream: TcpStream) {
    let _ = stream.set_nonblocking(false);
    let started = Instant::now();
    let deadline = started
        .checked_add(service.config.limits.request_timeout)
        .unwrap_or(started);
    let response = match read_http_request(
        &mut stream,
        service.config.limits.max_http_header_bytes,
        service.config.limits.wire.max_request_bytes(),
        deadline,
    ) {
        Ok(request) => Some(service.handle_http_with_deadline(request, deadline)),
        Err(IntakeError::HeaderTooLarge) => {
            Some(empty_response(StatusCode::REQUEST_HEADER_FIELDS_TOO_LARGE))
        }
        Err(IntakeError::PayloadTooLarge { target }) => {
            Some(payload_too_large_response(service, &target))
        }
        Err(IntakeError::BadRequest) => Some(empty_response(StatusCode::BAD_REQUEST)),
        Err(IntakeError::Timeout | IntakeError::Socket) => None,
    };
    if let Some(response) = response {
        let _ = write_http_response(&mut stream, &response, deadline);
    }
    let _ = stream.shutdown(std::net::Shutdown::Both);
 }
 fn read_http_request(
    stream: &mut TcpStream,
    maximum_header: usize,
    maximum_body: usize,
    deadline: Instant,
 ) -> Result<Request<Vec<u8>>, IntakeError> {
    let mut received = Vec::with_capacity(maximum_header.min(8 * 1024));
    let header_end = loop {
        if let Some(position) = received.windows(4).position(|window| window == b"\r\n\r\n") {
            let end = position + 4;
            if end > maximum_header {
                return Err(IntakeError::HeaderTooLarge);
            }
            break end;
        }
        if received.len() >= maximum_header {
            return Err(IntakeError::HeaderTooLarge);
        }
        let mut chunk = [0_u8; 4 * 1024];
        let available = (maximum_header - received.len()).min(chunk.len());
        let count = read_with_deadline(stream, &mut chunk[..available], deadline)?;
        if count == 0 {
            return Err(IntakeError::BadRequest);
        }
        received.extend_from_slice(&chunk[..count]);
    };
    let parsed = parse_request_head(&received[..header_end])?;
    if parsed.content_length > maximum_body {
        return Err(IntakeError::PayloadTooLarge {
            target: parsed.target,
        });
    }
    let mut body = Vec::with_capacity(parsed.content_length);
    let buffered = &received[header_end..];
    body.extend_from_slice(&buffered[..buffered.len().min(parsed.content_length)]);
    while body.len() < parsed.content_length {
        let mut chunk = [0_u8; 8 * 1024];
        let wanted = (parsed.content_length - body.len()).min(chunk.len());
        let count = read_with_deadline(stream, &mut chunk[..wanted], deadline)?;
        if count == 0 {
            return Err(IntakeError::BadRequest);
        }
        body.extend_from_slice(&chunk[..count]);
    }
    let mut builder = Request::builder().method(parsed.method).uri(parsed.target);
    for (name, value) in parsed.headers {
        builder = builder.header(name, value);
    }
    builder.body(body).map_err(|_| IntakeError::BadRequest)
 }
 fn parse_request_head(bytes: &[u8]) -> Result<ParsedRequestHead, IntakeError> {
    let text = std::str::from_utf8(bytes).map_err(|_| IntakeError::BadRequest)?;
    let mut lines = text
        .strip_suffix("\r\n\r\n")
        .ok_or(IntakeError::BadRequest)?
        .split("\r\n");
    let mut request_line = lines
        .next()
        .ok_or(IntakeError::BadRequest)?
        .split_ascii_whitespace();
    let method = request_line.next().ok_or(IntakeError::BadRequest)?;
    let target = request_line.next().ok_or(IntakeError::BadRequest)?;
    let version = request_line.next().ok_or(IntakeError::BadRequest)?;
    if request_line.next().is_some()
        || !matches!(version, "HTTP/1.0" | "HTTP/1.1")
        || !target.starts_with('/')
    {
        return Err(IntakeError::BadRequest);
    }
    let method =
        http::Method::from_bytes(method.as_bytes()).map_err(|_| IntakeError::BadRequest)?;
    let _: http::Uri = target.parse().map_err(|_| IntakeError::BadRequest)?;
    let mut headers = Vec::new();
    let mut content_length = None;
    for line in lines {
        if line.is_empty() || line.starts_with([' ', '\t']) {
            return Err(IntakeError::BadRequest);
        }
        let (name, value) = line.split_once(':').ok_or(IntakeError::BadRequest)?;
        let name = http::header::HeaderName::from_bytes(name.as_bytes())
            .map_err(|_| IntakeError::BadRequest)?;
        let value =
            http::HeaderValue::from_str(value.trim()).map_err(|_| IntakeError::BadRequest)?;
        if name == http::header::CONTENT_LENGTH {
            if content_length.is_some() {
                return Err(IntakeError::BadRequest);
            }
            content_length = Some(
                value
                    .to_str()
                    .ok()
                    .and_then(|value| value.parse::<usize>().ok())
                    .ok_or(IntakeError::BadRequest)?,
            );
        }
        if name == http::header::TRANSFER_ENCODING {
            return Err(IntakeError::BadRequest);
        }
        headers.push((name, value));
    }
    Ok(ParsedRequestHead {
        method,
        target: target.to_owned(),
        headers,
        content_length: content_length.unwrap_or(0),
    })
 }
 fn read_with_deadline(
    stream: &mut TcpStream,
    buffer: &mut [u8],
    deadline: Instant,
 ) -> Result<usize, IntakeError> {
    let remaining = deadline
        .checked_duration_since(Instant::now())
        .ok_or(IntakeError::Timeout)?;
    stream
        .set_read_timeout(Some(remaining.max(Duration::from_millis(1))))
        .map_err(|_| IntakeError::Socket)?;
    stream.read(buffer).map_err(|error| match error.kind() {
        std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock => IntakeError::Timeout,
        _ => IntakeError::Socket,
    })
 }
 fn payload_too_large_response(service: &WipFsServer, target: &str) -> Response<Vec<u8>> {
    let route = service.route(target.split('?').next().unwrap_or_default());
    route.map_or_else(
        || empty_response(StatusCode::PAYLOAD_TOO_LARGE),
        |route| {
            if route == Route::Batch {
                service.batch_top_error(
                    &resource_error(),
                    Some(ResourceLimitKind::RepresentationBytes),
                )
            } else {
                service.protocol_error(
                    interaction(route),
                    &resource_error(),
                    Some(ResourceLimitKind::RepresentationBytes),
                )
            }
        },
    )
 }
 fn write_http_response(
    stream: &mut TcpStream,
    response: &Response<Vec<u8>>,
    deadline: Instant,
 ) -> Result<(), std::io::Error> {
    let mut encoded = Vec::new();
    write!(
        encoded,
        "HTTP/1.1 {} {}\r\n",
        response.status().as_u16(),
        response.status().canonical_reason().unwrap_or("")
    )?;
    for (name, value) in response.headers() {
        if name == http::header::CONTENT_LENGTH
            || name == http::header::CONNECTION
            || name == http::header::TRANSFER_ENCODING
        {
            continue;
        }
        encoded.extend_from_slice(name.as_str().as_bytes());
        encoded.extend_from_slice(b": ");
        encoded.extend_from_slice(value.as_bytes());
        encoded.extend_from_slice(b"\r\n");
    }
    write!(
        encoded,
        "Content-Length: {}\r\nConnection: close\r\n\r\n",
        response.body().len()
    )?;
    encoded.extend_from_slice(response.body());
    write_all_with_deadline(stream, &encoded, deadline)
 }
 fn write_all_with_deadline(
    stream: &mut TcpStream,
    mut bytes: &[u8],
    deadline: Instant,
 ) -> Result<(), std::io::Error> {
    while !bytes.is_empty() {
        let remaining = deadline
            .checked_duration_since(Instant::now())
            .ok_or_else(|| {
                std::io::Error::new(std::io::ErrorKind::TimedOut, "request timed out")
            })?;
        stream.set_write_timeout(Some(remaining.max(Duration::from_millis(1))))?;
        match stream.write(bytes) {
            Ok(0) => {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::WriteZero,
                    "socket closed",
                ));
            }
            Ok(count) => bytes = &bytes[count..],
            Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
            Err(error) => return Err(error),
        }
    }
    stream.flush()
 }
 fn interaction(route: Route) -> ProtocolInteraction {
    match route {
        Route::Fetch => ProtocolInteraction::Fetch,
        Route::FetchTree => ProtocolInteraction::FetchTree,
        Route::FetchInterface => ProtocolInteraction::FetchInterface,
        Route::CallOperation => ProtocolInteraction::CallOperation,
        Route::Batch => ProtocolInteraction::Fetch,
    }
 }
 fn resource_error() -> ProtocolError {
    ProtocolError {
        code: ProtocolErrorCode::ResourceLimitExceeded,
        message: "configured resource limit exceeded".into(),
    }
 }
 fn internal_error() -> ProtocolError {
    ProtocolError {
        code: ProtocolErrorCode::Internal,
        message: "filesystem server failed".into(),
    }
 }
 fn empty_response(status: StatusCode) -> Response<Vec<u8>> {
    Response::builder()
        .status(status)
        .body(Vec::new())
        .expect("static status builds an HTTP response")
 }
 /// Failure while validating, opening, or binding the server.
 #[derive(Debug)]
 pub enum ServerBuildError {
    /// Configuration is unsafe or unbounded.
    Config(ConfigError),
    /// The root capability could not be opened.
    Io(std::io::Error),
    /// The listener could not be bound.
    Listener(String),
 }
 impl std::fmt::Display for ServerBuildError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Config(error) => write!(formatter, "invalid server configuration: {error}"),
            Self::Io(error) => write!(formatter, "filesystem root could not be opened: {error}"),
            Self::Listener(error) => write!(formatter, "HTTP listener could not be bound: {error}"),
        }
    }
 }
 impl std::error::Error for ServerBuildError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Config(error) => Some(error),
            Self::Io(error) => Some(error),
            Self::Listener(_) => None,
        }
    }
 }
 impl From<ConfigError> for ServerBuildError {
    fn from(value: ConfigError) -> Self {
        Self::Config(value)
    }
 }
 impl From<std::io::Error> for ServerBuildError {
    fn from(value: std::io::Error) -> Self {
        Self::Io(value)
    }
 }
@@ -0,0 +1,478 @@
 use std::collections::BTreeMap;
 use std::io::{Read, Write};
 use std::net::{SocketAddr, TcpStream};
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::thread;
 use std::time::{Duration, Instant};
 use tempfile::tempdir;
 use wip_fs_server::{AccessMode, ServerConfig, TransportSecurity, WipFsServer};
 use wip_https::{
    BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse, BatchSuccess, DecodedResponse,
    Endpoint, JSON_CONTENT_TYPE, Limits, Route, decode_batch_request, decode_batch_response,
    decode_call_operation_response, decode_fetch_interface_response, decode_fetch_response,
    decode_fetch_tree_response, encode_batch_request, encode_call_operation_request,
    encode_fetch_interface_request, encode_fetch_request, encode_fetch_tree_request,
 };
 use wip_protocol::{
    CallOperationRequest, FetchInterfaceRequest, FetchRequest, FetchTreeRequest, InterfaceTarget,
    ProtocolErrorCode, Target, Value,
 };
 #[test]
 fn real_listener_serves_four_core_interactions_batch_and_write() {
    let temporary = tempdir().expect("temporary root");
    std::fs::write(temporary.path().join("hello.txt"), b"hello world").expect("write file");
    std::fs::create_dir(temporary.path().join("nested")).expect("create directory");
    let mut config = ServerConfig::for_root(temporary.path());
    config.access = AccessMode::ReadWrite;
    config.transport_security = TransportSecurity::DevelopmentHttp;
    let limits = config.limits.wire;
    let bound = Arc::new(
        WipFsServer::new(config)
            .expect("build server")
            .bind()
            .expect("bind"),
    );
    let address = bound.local_addr();
    let shutdown = Arc::new(AtomicBool::new(false));
    let worker = {
        let bound = Arc::clone(&bound);
        let shutdown = Arc::clone(&shutdown);
        thread::spawn(move || bound.serve_until(shutdown))
    };
    let endpoint = Endpoint::parse(&format!("https://localhost:{}/wip", address.port()))
        .expect("client endpoint");
    let file_request = FetchRequest {
        path: "/hello.txt".into(),
    };
    let response = exchange(
        address,
        encode_fetch_request(&endpoint, &file_request, limits).expect("encode fetch"),
    );
    let file =
        success(decode_fetch_response(&file_request, &response, limits).expect("decode fetch"));
    assert_eq!(file.name, "hello.txt");
    assert_eq!(file.interfaces.len(), 2);
    assert!(file.validator.is_some());
    let tree_request = FetchTreeRequest {
        path: "/".into(),
        depth: 1,
        limit: 10,
    };
    let response = exchange(
        address,
        encode_fetch_tree_request(&endpoint, &tree_request, limits).expect("encode tree"),
    );
    let tree =
        success(decode_fetch_tree_response(&tree_request, &response, limits).expect("decode tree"));
    assert!(!tree.truncated);
    assert_eq!(tree.root.children.len(), 2);
    let read_interface_request = FetchInterfaceRequest {
        interface: file.interfaces[0].clone(),
    };
    let response = exchange(
        address,
        encode_fetch_interface_request(&endpoint, &read_interface_request, limits)
            .expect("encode interface fetch"),
    );
    let read_interface = success(
        decode_fetch_interface_response(&read_interface_request, &response, limits)
            .expect("decode interface"),
    );
    assert_eq!(read_interface.descriptor.operations[0].name, "read");
    let read_request = CallOperationRequest {
        target: Target {
            path: "/hello.txt".into(),
            validator: file.validator.clone(),
        },
        interface: InterfaceTarget {
            reference: file.interfaces[0].clone(),
            validator: None,
        },
        operation: "read".into(),
        arguments: BTreeMap::from([
            ("offset".into(), Value::Integer(6)),
            ("length".into(), Value::Integer(5)),
        ]),
    };
    let response = exchange(
        address,
        encode_call_operation_request(&endpoint, &read_request, &read_interface.descriptor, limits)
            .expect("encode read call"),
    );
    let read = success(
        decode_call_operation_response(
            &read_request,
            &read_interface.descriptor,
            &response,
            limits,
        )
        .expect("decode read call"),
    );
    assert_eq!(read.result, Value::Bytes(b"world".to_vec()));
    let batch_request = BatchRequest {
        requests: vec![
            BatchRequestItem {
                id: "root".into(),
                request: BatchRequestKind::Fetch(FetchRequest { path: "/".into() }),
            },
            BatchRequestItem {
                id: "tree".into(),
                request: BatchRequestKind::FetchTree(FetchTreeRequest {
                    path: "/nested".into(),
                    depth: 1,
                    limit: 4,
                }),
            },
            BatchRequestItem {
                id: "interface".into(),
                request: BatchRequestKind::FetchInterface(read_interface_request.clone()),
            },
        ],
    };
    let response = exchange(
        address,
        encode_batch_request(&endpoint, &batch_request, limits).expect("encode batch"),
    );
    let batch =
        success(decode_batch_response(&batch_request, &response, limits).expect("decode batch"));
    assert_batch_successes(&batch);
    let write_interface_request = FetchInterfaceRequest {
        interface: file.interfaces[1].clone(),
    };
    let response = exchange(
        address,
        encode_fetch_interface_request(&endpoint, &write_interface_request, limits)
            .expect("encode write interface fetch"),
    );
    let write_interface = success(
        decode_fetch_interface_response(&write_interface_request, &response, limits)
            .expect("decode write interface"),
    );
    let write_request = CallOperationRequest {
        target: Target {
            path: "/hello.txt".into(),
            validator: file.validator,
        },
        interface: InterfaceTarget {
            reference: file.interfaces[1].clone(),
            validator: None,
        },
        operation: "replace".into(),
        arguments: BTreeMap::from([("contents".into(), Value::Bytes(b"updated".to_vec()))]),
    };
    let response = exchange(
        address,
        encode_call_operation_request(
            &endpoint,
            &write_request,
            &write_interface.descriptor,
            limits,
        )
        .expect("encode write call"),
    );
    let write = success(
        decode_call_operation_response(
            &write_request,
            &write_interface.descriptor,
            &response,
            limits,
        )
        .expect("decode write call"),
    );
    assert!(write.validator.is_some());
    assert_eq!(
        std::fs::read(temporary.path().join("hello.txt")).expect("read updated file"),
        b"updated"
    );
    shutdown.store(true, Ordering::Release);
    worker
        .join()
        .expect("join listener")
        .expect("listener exits cleanly");
 }
 #[test]
 fn stalled_request_body_times_out_and_releases_the_only_worker() {
    let temporary = tempdir().expect("temporary root");
    let mut config = ServerConfig::for_root(temporary.path());
    config.transport_security = TransportSecurity::DevelopmentHttp;
    config.limits.max_concurrent_requests = 1;
    config.limits.request_timeout = Duration::from_millis(200);
    let limits = config.limits.wire;
    let bound = Arc::new(
        WipFsServer::new(config)
            .expect("build server")
            .bind()
            .expect("bind"),
    );
    let address = bound.local_addr();
    let shutdown = Arc::new(AtomicBool::new(false));
    let worker = {
        let bound = Arc::clone(&bound);
        let shutdown = Arc::clone(&shutdown);
        thread::spawn(move || bound.serve_until(shutdown))
    };
    let mut stalled = TcpStream::connect(address).expect("connect stalled client");
    stalled
        .set_read_timeout(Some(Duration::from_secs(1)))
        .expect("set stalled read timeout");
    write!(
        stalled,
        "POST /wip/v1/fetch HTTP/1.1\r\nHost: localhost\r\nContent-Type: application/json\r\nAccept: application/json\r\nContent-Length: 100\r\n\r\n{{"
    )
    .expect("write partial request");
    stalled.flush().expect("flush partial request");
    thread::sleep(Duration::from_millis(25));
    let endpoint = Endpoint::parse(&format!("https://localhost:{}/wip", address.port()))
        .expect("client endpoint");
    let fetch = FetchRequest { path: "/".into() };
    let started = Instant::now();
    let response = exchange(
        address,
        encode_fetch_request(&endpoint, &fetch, limits).expect("encode fetch"),
    );
    let _root = success(decode_fetch_response(&fetch, &response, limits).expect("decode fetch"));
    assert!(
        started.elapsed() < Duration::from_secs(1),
        "the valid request remained starved after the intake deadline"
    );
    let mut byte = [0_u8; 1];
    match stalled.read(&mut byte) {
        Ok(0) => {}
        Err(error)
            if matches!(
                error.kind(),
                std::io::ErrorKind::ConnectionReset
                    | std::io::ErrorKind::ConnectionAborted
                    | std::io::ErrorKind::BrokenPipe
            ) => {}
        outcome => panic!("stalled connection was not closed after its deadline: {outcome:?}"),
    }
    shutdown.store(true, Ordering::Release);
    worker
        .join()
        .expect("join listener")
        .expect("listener exits cleanly");
 }
 #[test]
 fn batch_keeps_known_malformed_arguments_item_local() {
    let temporary = tempdir().expect("temporary root");
    let config = ServerConfig::for_root(temporary.path());
    let limits = config.limits.wire;
    let server = WipFsServer::new(config).expect("build server");
    let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
    let body = br#"{"requests":[{"id":"ok","method":"fetch","arguments":{"path":"/"}},{"id":"bad","method":"fetch_tree","arguments":{"path":"/","depth":"bad","limit":1}}]}"#;
    let logical = decode_batch_request(body, limits).expect("decode item-local invalid request");
    assert!(matches!(
        logical.requests[1].request,
        BatchRequestKind::Invalid { .. }
    ));
    let request = http::Request::builder()
        .method(http::Method::POST)
        .uri(endpoint.route(Route::Batch).as_str())
        .header(http::header::CONTENT_TYPE, JSON_CONTENT_TYPE)
        .header(http::header::ACCEPT, "application/json")
        .body(body.to_vec())
        .expect("build request");
    let response = server.handle_http(request);
    let batch = success(
        decode_batch_response(&logical, &response, limits).expect("decode mixed batch response"),
    );
    assert!(matches!(
        batch.responses[0].outcome,
        Ok(BatchSuccess::Fetch(_))
    ));
    assert!(batch.responses[1].outcome.is_err());
 }
 #[test]
 fn call_argument_decoding_does_not_mask_missing_target() {
    let temporary = tempdir().expect("temporary root");
    let config = ServerConfig::for_root(temporary.path());
    let server = WipFsServer::new(config).expect("build server");
    let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
    let body = br#"{"target":{"path":"/missing"},"interface":{"reference":"unknown"},"operation":"missing","arguments":{"bytes":"not-base64"}}"#;
    let request = http::Request::builder()
        .method(http::Method::POST)
        .uri(endpoint.route(Route::CallOperation).as_str())
        .header(http::header::CONTENT_TYPE, JSON_CONTENT_TYPE)
        .header(http::header::ACCEPT, "application/json")
        .body(body.to_vec())
        .expect("build request");
    let response = server.handle_http(request);
    assert_eq!(response.status(), http::StatusCode::NOT_FOUND);
    assert!(
        std::str::from_utf8(response.body())
            .expect("UTF-8 error")
            .contains("\"not_found\"")
    );
 }
 #[test]
 fn backend_invalid_unicode_path_is_not_found_not_internal() {
    let temporary = tempdir().expect("temporary root");
    let config = ServerConfig::for_root(temporary.path());
    let limits = config.limits.wire;
    let server = WipFsServer::new(config).expect("build server");
    let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
    let request = FetchRequest {
        path: "/bad\0name".into(),
    };
    let response = server
        .handle_http(encode_fetch_request(&endpoint, &request, limits).expect("encode fetch"));
    assert_eq!(response.status(), http::StatusCode::NOT_FOUND);
    match decode_fetch_response(&request, &response, limits).expect("decode missing response") {
        DecodedResponse::ProtocolFailure { error, .. } => {
            assert_eq!(error.code, ProtocolErrorCode::NotFound);
        }
        DecodedResponse::Success(_) => panic!("backend-invalid path must not resolve"),
    }
 }
 #[test]
 fn read_response_size_failure_preserves_non_commit_guarantee() {
    let temporary = tempdir().expect("temporary root");
    std::fs::write(temporary.path().join("large"), vec![b'x'; 2_000]).expect("write file");
    let mut config = ServerConfig::for_root(temporary.path());
    config.limits.wire = Limits::new(4_096, 1_024, 64, 64).expect("wire limits");
    let limits = config.limits.wire;
    let server = WipFsServer::new(config).expect("build server");
    let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
    let fetch_request = FetchRequest {
        path: "/large".into(),
    };
    let response = server.handle_http(
        encode_fetch_request(&endpoint, &fetch_request, limits).expect("encode fetch"),
    );
    let file =
        success(decode_fetch_response(&fetch_request, &response, limits).expect("decode fetch"));
    let interface_request = FetchInterfaceRequest {
        interface: file.interfaces[0].clone(),
    };
    let response = server.handle_http(
        encode_fetch_interface_request(&endpoint, &interface_request, limits)
            .expect("encode interface fetch"),
    );
    let interface = success(
        decode_fetch_interface_response(&interface_request, &response, limits)
            .expect("decode interface"),
    );
    let call = CallOperationRequest {
        target: Target {
            path: "/large".into(),
            validator: file.validator,
        },
        interface: InterfaceTarget {
            reference: file.interfaces[0].clone(),
            validator: None,
        },
        operation: "read".into(),
        arguments: BTreeMap::from([("length".into(), Value::Integer(1_500))]),
    };
    let response = server.handle_http(
        encode_call_operation_request(&endpoint, &call, &interface.descriptor, limits)
            .expect("encode read call"),
    );
    assert_eq!(response.status(), http::StatusCode::PAYLOAD_TOO_LARGE);
    match decode_call_operation_response(&call, &interface.descriptor, &response, limits)
        .expect("decode resource failure")
    {
        DecodedResponse::ProtocolFailure { error, .. } => {
            assert_eq!(error.code, ProtocolErrorCode::ResourceLimitExceeded);
        }
        DecodedResponse::Success(_) => panic!("oversized read response must fail"),
    }
 }
 fn assert_batch_successes(batch: &BatchResponse) {
    assert_eq!(batch.responses.len(), 3);
    assert!(matches!(
        batch.responses[0].outcome,
        Ok(BatchSuccess::Fetch(_))
    ));
    assert!(matches!(
        batch.responses[1].outcome,
        Ok(BatchSuccess::FetchTree(_))
    ));
    assert!(matches!(
        batch.responses[2].outcome,
        Ok(BatchSuccess::FetchInterface(_))
    ));
 }
 fn success<T>(response: DecodedResponse<T>) -> T {
    match response {
        DecodedResponse::Success(value) => value,
        DecodedResponse::ProtocolFailure { error, .. } => panic!("protocol failure: {error}"),
    }
 }
 fn exchange(address: SocketAddr, request: http::Request<Vec<u8>>) -> http::Response<Vec<u8>> {
    let mut stream = TcpStream::connect(address).expect("connect listener");
    stream
        .set_read_timeout(Some(Duration::from_secs(5)))
        .expect("set read timeout");
    let path = request
        .uri()
        .path_and_query()
        .map_or("/", |value| value.as_str());
    write!(
        stream,
        "{} {} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n",
        request.method(),
        path
    )
    .expect("write request line");
    for (name, value) in request.headers() {
        write!(
            stream,
            "{}: {}\r\n",
            name,
            value.to_str().expect("ASCII request header")
        )
        .expect("write header");
    }
    write!(stream, "Content-Length: {}\r\n\r\n", request.body().len())
        .expect("write content length");
    stream.write_all(request.body()).expect("write body");
    stream.flush().expect("flush request");
    let mut raw = Vec::new();
    stream.read_to_end(&mut raw).expect("read response");
    let split = raw
        .windows(4)
        .position(|window| window == b"\r\n\r\n")
        .expect("HTTP response header");
    let head = std::str::from_utf8(&raw[..split]).expect("UTF-8 response head");
    let mut lines = head.split("\r\n");
    let status = lines
        .next()
        .and_then(|line| line.split_whitespace().nth(1))
        .and_then(|status| status.parse::<u16>().ok())
        .expect("response status");
    let mut builder = http::Response::builder().status(status);
    for line in lines {
        let (name, value) = line.split_once(':').expect("response header");
        builder = builder.header(name, value.trim());
    }
    builder
        .body(raw[split + 4..].to_vec())
        .expect("build response")
 }
@@ -1,6 +1,5 @@
 use wip_host::{InterfaceRegistry, PublishedObject, WipObject};
 use wip_interface::{OperationResult, interface};
 use wip_protocol::ObjectId;
 #[interface]
 pub trait Search {
@@ -10,8 +9,8 @@ pub trait Search {
 struct Object;
 impl WipObject for Object {
-    fn id(&self) -> ObjectId {
+    fn name(&self) -> &str {
-        ObjectId("object".into())
+        "object"
    }
 }
@@ -1,27 +1,27 @@
 error[E0277]: the trait bound `Object: Search` is not satisfied
-  --> tests/ui/unimplemented_interface.rs:21:58
+  --> tests/ui/unimplemented_interface.rs:20:58
   |
-21 |     let _published = PublishedObject::new(Object).expose(&search).unwrap();
+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:10:1
+  --> tests/ui/unimplemented_interface.rs:9:1
   |
-10 | struct Object;
+ 9 | struct Object;
   | ^^^^^^^^^^^^^
 help: this trait has no implementations, consider adding one
  --> tests/ui/unimplemented_interface.rs:6:1
   |
 6 | pub trait Search {
   | ^^^^^^^^^^^^^^^^
 note: required for `SearchDefinition` to implement `InterfaceImplementation<Object>`
  --> tests/ui/unimplemented_interface.rs:5:1
   |
- 5 | #[interface]
+ 5 | pub trait Search {
   | ^^^^^^^^^^^^^^^^
 note: required for `SearchDefinition` to implement `InterfaceImplementation<Object>`
  --> tests/ui/unimplemented_interface.rs:4:1
   |
 4 | #[interface]
   | ^^^^^^^^^^^^
- 6 | pub trait Search {
+ 5 | pub trait Search {
   |           ^^^^^^
 note: required by a bound in `PublishedObject::<T>::expose`
  --> src/lib.rs
@@ -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" }
@@ -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(),
        })
 }
@@ -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)
    }
 }
@@ -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,
        }
    }
 }
@@ -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)
    }
 }
@@ -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;
@@ -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 })
 }
@@ -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());
 }
@@ -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,
            ..
        }
    ));
 }
@@ -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(_)
    ));
 }
@@ -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());
 }
@@ -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,9 +168,11 @@ 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),*],
                }
            }
@@ -174,9 +182,12 @@ fn expand_interface(attribute: TokenStream2, item: ItemTrait) -> syn::Result<Tok
            fn dispatch(
                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();
@@ -201,9 +212,12 @@ 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,
            > {
                <Self as ::wip_interface::InterfaceImplementation<T>>::dispatch(
@@ -470,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,
@@ -490,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;
@@ -507,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)
        }
    };
@@ -525,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,)*
                };
@@ -539,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
@@ -559,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(),
            })
        }
    };
@@ -625,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)?
        }
    }
 }
@@ -698,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(
@@ -726,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,
            }
        }
    });
@@ -744,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)?,
-                });
+                );
            }
        }
    });
@@ -773,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(
@@ -783,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)*
                }
@@ -802,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),
@@ -814,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,)*
                        };
@@ -849,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
@@ -869,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",
        ))
    }
 }
@@ -885,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,
            }
@@ -905,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(
@@ -915,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,
@@ -938,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),
                    ),
                )
@@ -948,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(
@@ -977,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),
        });
    }
@@ -1009,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(
@@ -1060,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)*
                }
@@ -1088,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) {
@@ -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.
@@ -103,8 +131,8 @@ pub trait InterfaceImplementation<T>: InterfaceDefinition {
    fn dispatch(
        implementation: &T,
        operation: &str,
-        arguments: Vec<NamedValue>,
+        arguments: BTreeMap<String, Value>,
-    ) -> Result<Option<Value>, DispatchError>;
+    ) -> Result<Value, DispatchError>;
 }
 /// Result convention required for generated interface operations.
@@ -113,29 +141,107 @@ pub trait InterfaceImplementation<T>: InterfaceDefinition {
 /// `Err(HostError)` means the host or runtime could not perform the operation.
 pub type OperationResult<T> = Result<T, HostError>;
-/// A host/runtime failure, kept separate from the operation's application
+/// Whether an operation failure proves that no effects were committed.
 ///
 /// This guarantee is consumed by Host dispatch when choosing a protocol failure:
 /// only [`NotCommitted`](Self::NotCommitted) failures may become `Internal` or
 /// `ResourceLimitExceeded`; [`Unknown`](Self::Unknown) failures must become
 /// `OperationOutcomeUnknown`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum EffectGuarantee {
    /// The operation was not invoked, or every effect was rolled back.
    NotCommitted,
    /// The operation may have committed effects.
    Unknown,
 }
 /// Host/runtime failure category used when effects are known not to be committed.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum HostErrorKind {
    /// The Host or backend encountered an internal failure.
    Internal,
    /// A cancellation, deadline, or bounded resource limit was exceeded.
    ResourceLimitExceeded,
 }
 /// A typed host/runtime failure, kept separate from the operation's application
 /// return type.
 ///
 /// The effect guarantee is mandatory. Host runtimes must ignore the diagnostic
 /// when producing a wire response; it is bounded here for local observability but
 /// can still contain backend-private information.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct HostError {
    kind: HostErrorKind,
    effect_guarantee: EffectGuarantee,
    message: String,
 }
 impl HostError {
-    /// Creates a host failure with a human-readable diagnostic.
+    /// Creates an internal Host failure with an explicit effect guarantee.
    #[must_use]
-    pub fn new(message: impl Into<String>) -> Self {
+    pub fn internal(message: impl Into<String>, effect_guarantee: EffectGuarantee) -> Self {
        Self::new(HostErrorKind::Internal, effect_guarantee, message)
    }
    /// Creates a resource-limit Host failure with an explicit effect guarantee.
    #[must_use]
    pub fn resource_limit(message: impl Into<String>, effect_guarantee: EffectGuarantee) -> Self {
        Self::new(
            HostErrorKind::ResourceLimitExceeded,
            effect_guarantee,
            message,
        )
    }
    fn new(
        kind: HostErrorKind,
        effect_guarantee: EffectGuarantee,
        message: impl Into<String>,
    ) -> Self {
        Self {
-            message: message.into(),
+            kind,
            effect_guarantee,
            message: bounded_diagnostic(message.into()),
        }
    }
-    /// Returns the diagnostic message.
+    /// Returns the typed Host failure category.
    #[must_use]
    pub fn kind(&self) -> HostErrorKind {
        self.kind
    }
    /// Returns the operation-effect guarantee attached by the implementation.
    #[must_use]
    pub fn effect_guarantee(&self) -> EffectGuarantee {
        self.effect_guarantee
    }
    /// Returns the bounded local diagnostic message.
    ///
    /// Host runtimes must not place this value in protocol responses because it
    /// can contain backend paths, credentials, or other private details.
    #[must_use]
    pub fn message(&self) -> &str {
        &self.message
    }
 }
 const MAX_DIAGNOSTIC_BYTES: usize = 512;
 fn bounded_diagnostic(mut message: String) -> String {
    if message.len() <= MAX_DIAGNOSTIC_BYTES {
        return message;
    }
    let mut end = MAX_DIAGNOSTIC_BYTES;
    while !message.is_char_boundary(end) {
        end -= 1;
    }
    message.truncate(end);
    message
 }
 impl Display for HostError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        formatter.write_str(&self.message)
@@ -215,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 {
@@ -230,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}"),
        }
@@ -239,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),
@@ -266,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 {
@@ -441,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>) {
@@ -513,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
@@ -551,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};
@@ -591,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.
@@ -618,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.
@@ -654,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
        }
    }
 }
@@ -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
    );
 }
 #[test]
 fn enums_are_strings_and_unions_are_discriminated_records() {
    for color in [Color::Red, Color::Blue] {
        let encoded = color.clone().encode().unwrap();
-        let decoded = Color::decode(encoded).unwrap();
+        assert!(matches!(encoded, Value::String(_)));
-        assert_eq!(decoded, color);
+        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());
 }
@@ -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()));
@@ -0,0 +1,8 @@
 use wip_interface::interface;
 #[interface]
 pub trait AsyncOperation {
    async fn status(&self) -> wip_interface::OperationResult<String>;
 }
 fn main() {}
@@ -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>;
  |     ^^^^^
@@ -0,0 +1,10 @@
 use wip_interface::interface;
 #[interface]
 pub trait DefaultMethod {
    fn status(&self) -> wip_interface::OperationResult<String> {
        Ok(String::new())
    }
 }
 fn main() {}
@@ -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 | |     }
  | |_____^
@@ -0,0 +1,8 @@
 use wip_interface::WipType;
 #[derive(WipType)]
 struct GenericDto<T> {
    value: T,
 }
 fn main() {}
@@ -0,0 +1,5 @@
 error: generic DTOs are not supported by `WipType`
 --> tests/ui/generic_dto.rs:4:18
  |
 4 | struct GenericDto<T> {
  |                  ^^^
@@ -1,9 +1,9 @@
 use wip_interface::WipType;
 #[derive(WipType)]
-enum MixedEnum {
+enum UnsupportedEnum {
    Empty,
-    Payload(String),
+    Payload { value: String },
 }
 fn main() {}
@@ -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 },
-  | ^^^^
+  |     ^^^^^^^
@@ -0,0 +1,8 @@
 use wip_interface::WipType;
 #[derive(WipType)]
 struct NestedOption {
    values: Vec<Option<String>>,
 }
 fn main() {}
@@ -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>>,
  |             ^^^^^^^^^^^^^^^^^^^
@@ -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
  |
@@ -223,10 +223,29 @@ impl Display for ValidationError {
 impl Error for ValidationError {}
-/// Stable protocol failure code returned by a host or produced by a client.
+/// One core interaction whose failure codes form a closed set.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ProtocolInteraction {
    /// Fetch one object by its Worldspace path.
    Fetch,
    /// Fetch a bounded tree of objects.
    FetchTree,
    /// Fetch one interface descriptor by its opaque reference.
    FetchInterface,
    /// Invoke one operation on a path-targeted object.
    CallOperation,
 }
 /// Stable protocol failure code returned by a host.
 ///
 /// This is the complete wire-level code set. A Client treats a malformed success
 /// or failure response, including a code disallowed for its interaction, as a
 /// Client-local `InvalidResponse`. An unsupported descriptor format is likewise
 /// a Client-local `UnsupportedDescriptorFormat`; neither condition is a code a
 /// Host can return.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ProtocolErrorCode {
-    /// The request is structurally invalid.
+    /// The request is structurally invalid before an operation descriptor is fixed.
    InvalidRequest,
    /// The target object is not published.
    NotFound,
@@ -236,10 +255,8 @@ pub enum ProtocolErrorCode {
    InterfaceMismatch,
    /// The selected operation is not declared by the current interface.
    OperationNotFound,
-    /// Supplied operation arguments are invalid.
+    /// Supplied arguments do not match the fixed operation declaration.
    InvalidArguments,
    /// A host result does not satisfy the declaration.
    InvalidResult,
    /// The operation requires an object validator and none was supplied.
    ValidatorRequired,
    /// The supplied object validator does not match current state.
@@ -251,9 +268,88 @@ pub enum ProtocolErrorCode {
    /// A published operation is not permitted for the caller.
    PermissionDenied,
    /// A bounded protocol resource limit was exceeded.
    ///
    /// For `call_operation`, the Host guarantees that the operation was not run
    /// or that all of its effects were rolled back.
    ResourceLimitExceeded,
-    /// The host encountered an internal failure.
+    /// The Host encountered an internal failure.
    ///
    /// For `call_operation`, the Host guarantees that the operation was not run
    /// or that all of its effects were rolled back.
    Internal,
    /// The Host cannot guarantee that the operation was not run or rolled back.
    ///
    /// A Client must not automatically retry because the operation may have
    /// committed effects even though no success response was available.
    OperationOutcomeUnknown,
 }
 impl ProtocolErrorCode {
    /// Every canonical wire-level error code.
    pub const ALL: [Self; 14] = [
        Self::InvalidRequest,
        Self::NotFound,
        Self::InterfaceNotFound,
        Self::InterfaceMismatch,
        Self::OperationNotFound,
        Self::InvalidArguments,
        Self::ValidatorRequired,
        Self::ValidatorMismatch,
        Self::InterfaceValidatorRequired,
        Self::InterfaceValidatorMismatch,
        Self::PermissionDenied,
        Self::ResourceLimitExceeded,
        Self::Internal,
        Self::OperationOutcomeUnknown,
    ];
    /// Whether a Host may return this code for `interaction`.
    ///
    /// `false` identifies an invalid error response; it does not turn that
    /// response into another wire-level protocol failure.
    #[must_use]
    pub const fn is_allowed_for(self, interaction: ProtocolInteraction) -> bool {
        use ProtocolErrorCode::{
            InterfaceMismatch, InterfaceNotFound, InterfaceValidatorMismatch,
            InterfaceValidatorRequired, Internal, InvalidArguments, InvalidRequest, NotFound,
            OperationNotFound, OperationOutcomeUnknown, PermissionDenied, ResourceLimitExceeded,
            ValidatorMismatch, ValidatorRequired,
        };
        use ProtocolInteraction::{CallOperation, Fetch, FetchInterface, FetchTree};
        match (interaction, self) {
            (_, InvalidRequest | ResourceLimitExceeded | Internal) => true,
            (Fetch | FetchTree, NotFound) => true,
            (FetchInterface, InterfaceNotFound) => true,
            (
                CallOperation,
                NotFound
                | InterfaceMismatch
                | OperationNotFound
                | InvalidArguments
                | ValidatorRequired
                | ValidatorMismatch
                | InterfaceValidatorRequired
                | InterfaceValidatorMismatch
                | PermissionDenied
                | OperationOutcomeUnknown,
            ) => true,
            (
                _,
                NotFound
                | InterfaceNotFound
                | InterfaceMismatch
                | OperationNotFound
                | InvalidArguments
                | ValidatorRequired
                | ValidatorMismatch
                | InterfaceValidatorRequired
                | InterfaceValidatorMismatch
                | PermissionDenied
                | OperationOutcomeUnknown,
            ) => false,
        }
    }
 }
 /// Transport-independent protocol failure.
@@ -264,3 +360,15 @@ pub struct ProtocolError {
    /// 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 {}
@@ -16,7 +16,20 @@
 //! | `fetch_interface` | [`FetchInterfaceRequest`] / [`FetchInterfaceResponse`] |
 //! | Object and interface call preconditions | [`Target`] / [`InterfaceTarget`] |
 //! | `call_operation` | [`CallOperationRequest`] / [`CallOperationResponse`] |
-//! | Stable failure taxonomy | [`ProtocolErrorCode`] / [`ProtocolError`] |
+//! | Stable Host failure taxonomy | [`ProtocolErrorCode`] / [`ProtocolError`] |
 //! | Per-interaction allowed failure codes | [`ProtocolInteraction`] / [`ProtocolErrorCode::is_allowed_for`] |
 //!
 //! [`ProtocolErrorCode`] is a closed set of Host-returned wire failures. After a
 //! Client receives a response, an invalid Object, Descriptor, operation result,
 //! malformed error, or error code disallowed by [`ProtocolInteraction`] is a
 //! Client-local `InvalidResponse`, not another wire error. A descriptor whose
 //! `format` is not supported is a Client-local `UnsupportedDescriptorFormat`.
 //!
 //! For `call_operation`, [`ProtocolErrorCode::Internal`] and
 //! [`ProtocolErrorCode::ResourceLimitExceeded`] guarantee that the operation did
 //! not run or that all effects were rolled back. Only
 //! [`ProtocolErrorCode::OperationOutcomeUnknown`] means the Host cannot make that
 //! guarantee; Clients must not automatically retry it.
 //!
 //! Paths, object refs, interface refs, and validators remain separate concepts.
 //! They are represented by ordinary protocol strings/bytes in the corresponding
@@ -35,8 +48,8 @@ mod model;
 mod validation;
 pub use error::{
-    NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ValidationError,
+    NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
-    ValidationErrorKind, ValueKind,
+    ValidationError, ValidationErrorKind, ValueKind,
 };
 pub use model::{
    CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
@@ -379,6 +379,9 @@ impl FetchRequest {
    }
    /// Validates an object returned for this request.
    ///
    /// Failure means the Client received an invalid success response; it is not a
    /// Host-returned [`crate::ProtocolErrorCode`].
    pub fn validate_response(&self, response: &FetchResponse) -> Result<(), ValidationError> {
        response.validate_at_path(&self.path)
    }
@@ -393,6 +396,9 @@ impl FetchTreeRequest {
 impl FetchTreeResponse {
    /// Validates tree shape, names, depth, and node limit for `request`.
    ///
    /// Failure means the Client received an invalid success response; it is not a
    /// Host-returned [`crate::ProtocolErrorCode`].
    pub fn validate_for(&self, request: &FetchTreeRequest) -> Result<(), ValidationError> {
        crate::validation::validate_fetch_tree_response(self, request)
    }
@@ -400,6 +406,11 @@ impl FetchTreeResponse {
 impl FetchInterfaceResponse {
    /// Validates request correspondence and descriptor semantics.
    ///
    /// Failure means the Client received an invalid success response; it is not a
    /// Host-returned [`crate::ProtocolErrorCode`]. Descriptor format support is a
    /// separate Client concern: an otherwise valid descriptor with an unsupported
    /// `format` is a Client-local `UnsupportedDescriptorFormat`.
    pub fn validate_for(&self, request: &FetchInterfaceRequest) -> Result<(), ValidationError> {
        crate::validation::validate_fetch_interface_response(self, request)
    }
@@ -414,6 +425,9 @@ impl CallOperationRequest {
 impl CallOperationResponse {
    /// Validates this result against the named operation in `descriptor`.
    ///
    /// Failure means the Client received an invalid success response; it is not a
    /// Host-returned [`crate::ProtocolErrorCode`].
    pub fn validate_for(
        &self,
        descriptor: &InterfaceDescriptor,
@@ -5,8 +5,8 @@ use wip_protocol::{
    FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, NameNamespace,
    Object, ObjectTreeNode, OperationDeclaration, ParameterDeclaration, PathSegment, ProtocolError,
-    ProtocolErrorCode, ProtocolResult, ReturnDeclaration, Target, TypeDeclaration, TypeExpr,
+    ProtocolErrorCode, ProtocolInteraction, ProtocolResult, ReturnDeclaration, Target,
-    UnionCase, ValidationErrorKind, Value, ValueKind,
+    TypeDeclaration, TypeExpr, UnionCase, ValidationErrorKind, Value, ValueKind,
 };
 fn record(entries: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
@@ -729,15 +729,16 @@ fn fetch_tree_dtos_validate_names_depth_limit_and_siblings() {
 }
 #[test]
-fn protocol_result_and_every_canonical_error_code_are_available() {
+fn protocol_result_exposes_the_exact_canonical_wire_error_codes() {
-    let codes = [
+    assert_eq!(
        ProtocolErrorCode::ALL,
        [
            ProtocolErrorCode::InvalidRequest,
            ProtocolErrorCode::NotFound,
            ProtocolErrorCode::InterfaceNotFound,
            ProtocolErrorCode::InterfaceMismatch,
            ProtocolErrorCode::OperationNotFound,
            ProtocolErrorCode::InvalidArguments,
        ProtocolErrorCode::InvalidResult,
            ProtocolErrorCode::ValidatorRequired,
            ProtocolErrorCode::ValidatorMismatch,
            ProtocolErrorCode::InterfaceValidatorRequired,
@@ -745,8 +746,9 @@ fn protocol_result_and_every_canonical_error_code_are_available() {
            ProtocolErrorCode::PermissionDenied,
            ProtocolErrorCode::ResourceLimitExceeded,
            ProtocolErrorCode::Internal,
-    ];
+            ProtocolErrorCode::OperationOutcomeUnknown,
-    assert_eq!(codes.len(), 14);
+        ]
    );
    let failure: ProtocolResult<()> = ProtocolResult::Failure(ProtocolError {
        code: ProtocolErrorCode::InvalidArguments,
@@ -758,3 +760,127 @@ fn protocol_result_and_every_canonical_error_code_are_available() {
        ProtocolResult::Success(Value::Unit)
    );
 }
 fn assert_allowed_codes(interaction: ProtocolInteraction, expected: &[ProtocolErrorCode]) {
    let actual: Vec<_> = ProtocolErrorCode::ALL
        .into_iter()
        .filter(|code| code.is_allowed_for(interaction))
        .collect();
    assert_eq!(actual, expected);
    for code in ProtocolErrorCode::ALL {
        assert_eq!(
            code.is_allowed_for(interaction),
            expected.contains(&code),
            "unexpected {code:?} validity for {interaction:?}"
        );
    }
 }
 #[test]
 fn fetch_error_codes_are_exhaustive() {
    assert_allowed_codes(
        ProtocolInteraction::Fetch,
        &[
            ProtocolErrorCode::InvalidRequest,
            ProtocolErrorCode::NotFound,
            ProtocolErrorCode::ResourceLimitExceeded,
            ProtocolErrorCode::Internal,
        ],
    );
 }
 #[test]
 fn fetch_tree_error_codes_are_exhaustive() {
    assert_allowed_codes(
        ProtocolInteraction::FetchTree,
        &[
            ProtocolErrorCode::InvalidRequest,
            ProtocolErrorCode::NotFound,
            ProtocolErrorCode::ResourceLimitExceeded,
            ProtocolErrorCode::Internal,
        ],
    );
 }
 #[test]
 fn fetch_interface_error_codes_are_exhaustive() {
    assert_allowed_codes(
        ProtocolInteraction::FetchInterface,
        &[
            ProtocolErrorCode::InvalidRequest,
            ProtocolErrorCode::InterfaceNotFound,
            ProtocolErrorCode::ResourceLimitExceeded,
            ProtocolErrorCode::Internal,
        ],
    );
 }
 #[test]
 fn call_operation_error_codes_are_exhaustive() {
    assert_allowed_codes(
        ProtocolInteraction::CallOperation,
        &[
            ProtocolErrorCode::InvalidRequest,
            ProtocolErrorCode::NotFound,
            ProtocolErrorCode::InterfaceMismatch,
            ProtocolErrorCode::OperationNotFound,
            ProtocolErrorCode::InvalidArguments,
            ProtocolErrorCode::ValidatorRequired,
            ProtocolErrorCode::ValidatorMismatch,
            ProtocolErrorCode::InterfaceValidatorRequired,
            ProtocolErrorCode::InterfaceValidatorMismatch,
            ProtocolErrorCode::PermissionDenied,
            ProtocolErrorCode::ResourceLimitExceeded,
            ProtocolErrorCode::Internal,
            ProtocolErrorCode::OperationOutcomeUnknown,
        ],
    );
 }
 #[test]
 fn invalid_success_payloads_remain_client_local_validation_failures() {
    let fetch = FetchRequest {
        path: "/articles/one".into(),
    };
    assert!(matches!(
        fetch.validate_response(&object("other")).unwrap_err().kind,
        ValidationErrorKind::ObjectNameMismatch { .. }
    ));
    let interface_request = FetchInterfaceRequest {
        interface: "catalog-v1".into(),
    };
    let mut invalid_descriptor = descriptor();
    invalid_descriptor
        .operations
        .push(invalid_descriptor.operations[0].clone());
    assert!(matches!(
        FetchInterfaceResponse {
            interface: interface_request.interface.clone(),
            descriptor: invalid_descriptor,
            validator: None,
        }
        .validate_for(&interface_request)
        .unwrap_err()
        .kind,
        ValidationErrorKind::DuplicateName {
            namespace: NameNamespace::Operation,
            ..
        }
    ));
    assert!(matches!(
        CallOperationResponse {
            result: Value::String("not a boolean".into()),
            validator: None,
        }
        .validate_for(&descriptor(), "publish")
        .unwrap_err()
        .kind,
        ValidationErrorKind::TypeMismatch {
            expected: ValueKind::Boolean,
            actual: ValueKind::String,
        }
    ));
 }
@@ -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" }
@@ -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())
    }
 }
@@ -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(())
 }
@@ -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);
            }
        }
    }
 }
@@ -1,3 +0,0 @@
 fn main() {
    println!("Hello, world!");
 }
Author	SHA1	Message	Date
Hare	780150d7ae	fix: bound HTTP intake and response lifetimes	2026-09-30 09:23:12 +09:00
Hare	f5034c0e4b	fix: bound filesystem execution and preserve guarantees	2026-09-30 09:09:09 +09:00
Hare	df51da3d03	feat: add bounded filesystem projection server	2026-09-30 08:53:44 +09:00
Hare	fdfaa3a685	feat(host): decode operation arguments in dispatch boundary	2026-09-30 08:53:43 +09:00
Hare	96db3dd6a8	fix: honor Accept media parameters	2026-09-30 07:59:50 +09:00
Hare	625f4c148d	fix(https): align canonical binding semantics	2026-09-30 07:50:51 +09:00
Hare	beeffae9c5	fix: validate HTTPS binding limits and response ordering	2026-09-30 06:43:02 +09:00
Hare	56923c1160	feat: implement WIP over HTTPS v1 binding	2026-09-30 06:32:04 +09:00
Hare	6de58da17d	feat: model operation outcome guarantees	2026-09-30 05:52:38 +09:00
Hare	027555eb4e	fix: align protocol error semantics	2026-09-30 05:26:34 +09:00
Hare	75119f23e5	feat(example): restore virtual workspace conformance	2026-09-29 06:51:05 +09:00
Hare	653a1171a2	fix: reject malformed host target paths	2026-09-29 06:35:10 +09:00
Hare	2efda433e7	fix: align host dispatch with canonical paths	2026-09-29 06:28:33 +09:00
Hare	2d524723a4	fix: align interface macros with canonical values	2026-09-29 06:11:07 +09:00
Hare	7f4e0e4460	fix: integrate canonical protocol model	2026-09-29 05:54:36 +09:00
Hare	0705101c97	feat(example): add public API end-to-end flow	2026-09-29 00:04:11 +09:00
Hare	5992322371	fix(interface): harden generated public API	2026-09-29 00:04:04 +09:00
Hare	d0683f0b6d	feat(host): resolve published interface references	2026-09-29 00:03:55 +09:00