feat: support typed in-process WIP clients without HTTP

fix: correct protocol name in Rust documentation
chore: prepare 0.2.0 release
2026-10-16 05:26:11 +09:00 · 2026-10-15 17:53:48 +09:00 · 2026-10-09 00:35:06 +09:00 · 2026-10-08 18:27:04 +09:00 · 2026-10-08 17:50:16 +09:00 · 2026-10-08 04:03:51 +09:00
108 changed files with 20684 additions and 4126 deletions
@@ -0,0 +1,47 @@
 # Changelog
 All notable changes to the published WIP Rust crates are documented here.
 ## Unreleased
 ## 0.2.0
 - Adds public Text View `Token`/`TokenKind`, `tokenize_object`,
  `tokenize_interface`, and delimiter-free `to_plain_text`. Direct rendering uses
  the same token generation path; HTML and terminal-color renderers are not included.
 - Makes Client Interface caches scope-lifetime-aware, invalidates observations on
  confirmed binding loss, and retains immutable contexts for in-flight calls.
 - Adds `wip-text-view`, an independent single-entity Object/Interface signature
  library with Protocol validation, typed errors, full ordered declarations,
  documentation summaries and safe Text View quoting/escapes. No path, lookup,
  cache, UI, network or Protocol wire-schema changes are required.
 - Breaking Protocol/HTTP migration from opaque Interface reference strings to
  exact `(scope, name)` records in Objects, fetches and calls, with optional
  opaque `scope_ref` metadata. Adds shape and placement-aware scope validation
  without changing routes, validators or the wire error-code set.
 - Breaking Host registration migration to explicit Scope publication lifetimes and
  local names, with coherent provider-attested scope Object binding for fetch and
  dispatch. Supplied scope_ref is checked at membership precedence; scope deletion
  retires retained tokens, while ordinary Object state updates preserve lifetime.
 - Integrates scoped references across filesystem and public consumers and the TUI.
  External FS scopes bind to visible current connected lineage, not retained
  registry artifacts. TUI labels use absolute safely quoted `::`/`#` notation;
  structured selection and Client scope invalidation prevent stale UI dispatch.
  The public example carries fetched scope refs and includes real HTTP lifetime,
  visibility and validator-precedence conformance tests with optional refs. See
  [MIGRATION.md](MIGRATION.md) for API/wire examples and provider responsibilities.
 ## 0.1.0
 Initial public release of:
 - `wip-protocol`: transport-independent WIP logical model and validation.
 - `wip-interface-macros`: procedural-macro implementation for interface and DTO declarations.
 - `wip-interface`: public Rust interface-authoring facade and typed value codecs.
 - `wip-host`: request-scoped publication, precondition validation, and qualified operation dispatch.
 - `wip-http`: framework-independent WIP over HTTP v1 routes, strict JSON codecs, and failure classification.
 - `wip-client`: stateful Known Space, interest-driven acquisition, request ownership, and operation lifecycle.
 The repository also contains non-published filesystem server, terminal client, and public-API conformance packages.
@@ -1235,28 +1235,28 @@ checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
 [[package]]
 name = "wip-client"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
- "wip-https",
+ "wip-http",
 "wip-protocol",
 ]
 [[package]]
 name = "wip-fs-server"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
 "http",
 "rustix 1.1.5",
 "tempfile",
 "wip-host",
- "wip-https",
+ "wip-http",
 "wip-interface",
 "wip-protocol",
 ]
 [[package]]
 name = "wip-host"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
 "trybuild",
 "wip-interface",
@@ -1264,8 +1264,8 @@ dependencies = [
 ]
 [[package]]
-name = "wip-https"
+name = "wip-http"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
 "base64 0.22.1",
 "http",
@@ -1277,7 +1277,7 @@ dependencies = [
 [[package]]
 name = "wip-interface"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
 "trybuild",
 "wip-interface-macros",
@@ -1286,7 +1286,7 @@ dependencies = [
 [[package]]
 name = "wip-interface-macros"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -1295,20 +1295,29 @@ dependencies = [
 [[package]]
 name = "wip-protocol"
-version = "0.1.0"
+version = "0.2.0"
 [[package]]
 name = "wip-public-api-example"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
 "wip-client",
 "wip-host",
 "wip-http",
 "wip-interface",
 "wip-protocol",
 ]
 [[package]]
 name = "wip-text-view"
 version = "0.2.0"
 dependencies = [
 "wip-protocol",
 ]
 [[package]]
 name = "wip-tui"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
 "base64 0.22.1",
 "crossterm",
@@ -1318,7 +1327,7 @@ dependencies = [
 "ureq",
 "wip-client",
 "wip-fs-server",
- "wip-https",
+ "wip-http",
 "wip-protocol",
 ]
@@ -1341,9 +1350,9 @@ dependencies = [
 [[package]]
 name = "yoke-derive"
-version = "0.8.3"
+version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
+checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -1,3 +1,20 @@
 [workspace]
 members = ["crates/*"]
 resolver = "3"
 [workspace.package]
 version = "0.2.0"
 edition = "2024"
 rust-version = "1.88"
 license = "MIT OR Apache-2.0"
 repository = "https://gitea.hareworks.net/Hare/wip-rs"
 [workspace.dependencies]
 wip-client = { version = "0.2.0", path = "crates/wip-client" }
 wip-fs-server = { version = "0.2.0", path = "crates/wip-fs-server" }
 wip-host = { version = "0.2.0", path = "crates/wip-host" }
 wip-http = { version = "0.2.0", path = "crates/wip-http" }
 wip-interface = { version = "0.2.0", path = "crates/wip-interface" }
 wip-interface-macros = { version = "0.2.0", path = "crates/wip-interface-macros" }
 wip-protocol = { version = "0.2.0", path = "crates/wip-protocol" }
 wip-text-view = { version = "0.2.0", path = "crates/wip-text-view" }
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Hare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,249 @@
 # Structured Interface reference and scope publication migration
 ## Transport-independent Client API
 The default `wip-client` feature set still exposes the HTTP-compatible
 `wip_client::Client` and `PreparedRequest`. Its constructor takes state and wire
 limits, sessions canonicalize HTTP endpoints, and `complete` consumes an HTTP
 response. Existing TUI and native HTTP consumers need no source migration; the
 wire contract is unchanged.
 For an in-process Host (including Client and Host in one WASM module), disable
 default features and use `wip_client::direct::{Client, Request, Response}`:
 ```toml
 wip-client = { version = "0.2.0", default-features = false }
 ```
 - `direct::Client::new(ClientLimits)` takes no wire limits.
 - `open_session(worldspace_identity, SecurityContext)` accepts an opaque identity,
  not a URL. Issue a separate identity per Worldspace view/Host lifetime and a
  separate security identity whenever authorization context changes. Direct and
  canonical HTTP session identities cannot alias each other's cache.
 - Preparation methods retain their names and arguments. Their result is
  `direct::PreparedRequest { id, request: Request }`, with `Observe`,
  `FetchInterface`, and `CallOperation` variants containing Protocol request DTOs.
 - Route that exact DTO to the session's Host/security context; mark calls
  dispatched before invoking the Host. Complete with the original `id` and the
  matching `Response` variant containing `Result<Protocol DTO, ProtocolError>`.
  No HTTP request, response, JSON codec, or artificial endpoint is needed.
 - Direct responses undergo the same semantic validation and state transitions
  as HTTP responses. Wrong interactions and invalid results are rejected;
  invalid call responses retain an unknown execution outcome. Retrievals may
  be explicitly refreshed, but operations are never automatically retried.
 - `ClientLimits` still bounds cache, sessions, in-flight requests, and history.
  HTTP status/envelope checks and byte/JSON nesting limits belong to the optional
  HTTP adapter. An embedding application owns DTO allocation/execution budgets.
 The `direct` module API documentation contains a runnable typed example. Run
 `cargo test -p wip-client --no-default-features` to exercise the core without an
 HTTP dependency; ordinary `cargo test -p wip-client` also runs unchanged HTTP
 regressions and direct/HTTP state parity tests.
 The 0.2.0 API/wire change follows `wip-reference` canonical Core Model,
 Protocol and WIP over HTTP at `6086f3c5ef10aa1464ce9c824750d7f667217bfd`.
 It replaces the earlier opaque Interface reference contract; HTTP routes and
 error codes have **not** changed. Peers must upgrade together: the codec does
 not accept legacy strings or display shorthand as Protocol references.
 ## Rust API
 `Object.interfaces` is now `Vec<InterfaceReference>`.
 `FetchInterfaceRequest.interface`, `FetchInterfaceResponse.interface`, and
 `InterfaceTarget.reference` all use the same record:
 ```rust
 use wip_protocol::{FetchInterfaceRequest, InterfaceReference, InterfaceTarget};
 let reference = InterfaceReference {
    scope: "/github".into(),
    name: "issue.read".into(),
 };
 reference.validate()?; // reference shape, no target Object path needed
 let fetch = FetchInterfaceRequest { interface: reference.clone() };
 let target = InterfaceTarget {
    reference,
    scope_ref: Some("opaque-scope-object-ref".into()),
    validator: None,
 };
 # Ok::<(), wip_protocol::ValidationError>(())
 ```
 Construct scope and name explicitly from your Worldspace publication context.
 There is no implicit conversion from a string, delimiter parser, normalization,
 case folding, or URL decoding. A name may contain `/`, `.`, `::`, `#`, or Unicode;
 only an empty name is invalid. Scope must be a canonical absolute Worldspace
 path: `/`, or nonempty slash-separated segments other than `.` and `..`, with
 no empty segments or trailing slash. `%2F` is ordinary field text, not an escape
 for a Worldspace path separator.
 Equality, hashing and ordering operate on both fields, independent of member
 order/JSON escape spelling. Use the record itself as a membership/cache key;
 identical names in different scopes are different references. The descriptor
 still contains only format, documentation, types and operations, not identity.
 `FetchInterfaceResponse` and `InterfaceTarget` additionally require the Rust
 field `scope_ref: Option<String>` in struct literals. Use `None` when omitted,
 not an invented identity. This is an opaque scope Object ref observation/call
 precondition, **not** a third Interface identity component or a validator.
 Host enforces scope publication lifetimes and optional scope-ref identity
 inside the provider boundary. Client caches keep the complete structured reference
 and optional fetched scope binding; confirmed scope deletion or ref replacement
 invalidates bound observations, while local eviction is not deletion evidence.
 Do not mistake registry artifact retention for publication.
 ## Validation boundaries
 - `InterfaceReference::validate()` and `FetchInterfaceRequest::validate()`
  check reference shape independently of a target Object path.
 - `Object::validate()` checks shape and duplicate `(scope, name)` pairs;
  `Object::validate_at_path()` additionally checks placement, including scope.
  `ObserveRequest::validate_response()` checks every derived node path,
  including the depth boundary. Invalid success responses are Client-local
  `InvalidResponse`, not Host-returned Protocol errors.
 - `InterfaceReference::validate_for_path(path)` checks ancestor-or-self scope
  compatibility by path segments. Root and self scope are valid; `/a` is not
  an ancestor of `/ab`. This has no indexability dependency.
 - `CallOperationRequest::validate()` checks descriptor-independent shape.
  `validate_with()` adds operation/argument checks but does not replace Host
  publication lookup. Host interface selection checks scope compatibility and
  exact membership **after** target lookup: invalid reference shape is
  `InvalidRequest`, but a valid reference outside the target's scope is
  `InterfaceMismatch`, with `NotFound` retaining precedence.
 ## HTTP wire
 All four reference positions use an exact object with required string fields:
 ```json
 {"scope":"/github","name":"issue.read"}
 ```
 For example:
 ```json
 {
  "interface": {"scope":"/github","name":"issue.read"},
  "scope_ref": "opaque-scope-object-ref",
  "descriptor": {"format":"wip-interface/1","types":[],"operations":[]}
 }
 ```
 A call uses:
 ```json
 {
  "target": {"path":"/github/issues/123"},
  "interface": {
    "reference": {"scope":"/github","name":"issue.read"},
    "scope_ref": "opaque-scope-object-ref"
  },
  "operation":"refresh",
  "arguments":{}
 }
 ```
 Unknown/duplicate members, missing fields, null fields, relative scopes, empty
 names, legacy `"interface-v1"` and shorthand `"/github::issue.read"` strings
 are rejected. Field order and JSON escaping do not affect decoded identity.
 `scope_ref` is a normal opaque string, **not Base64**; omission is allowed but
 explicit null and nonstrings are invalid. An empty string is a valid opaque
 ref. Validators remain canonical padded standard Base64.
 Descriptor-independent HTTP call metadata decoding enforces reference shape
 and the same strict JSON rules without turning scope compatibility into early
 `InvalidRequest`. Normal descriptor-bound encode/decode uses the same reference
 codec. Request violations retain the existing `400 invalid_request` boundary;
 malformed success responses retain Client-local `InvalidResponse`. Standard
 `POST v1/observe`, `v1/fetch_interface`, `v1/call_operation`, error-code/status
 mapping and Transport failure classification are unchanged.
 ## Host registration and provider migration
 Registration now requires an explicit canonical Scope and local name:
 ```rust,ignore
 let mut registry = wip_host::InterfaceRegistry::new();
 let scope = wip_host::Scope::new("/service")?;
 let api = registry.register(&scope, "catalog", CatalogDefinition, None)?;
 // INSIDE the backend transaction/lock/stable-handle boundary:
 let current = wip_host::ScopeObservation::new(&scope, &current_scope_object);
 let publication = wip_host::PublishedObject::new(current_target_object)
    .expose(&api)?
    .bind_scope(current);
 ```
 Collision keys are exact `(scope, name)` coordinates, not Rust Definition TypeId.
 The same Definition can be registered in different scopes or under different
 names. Root, self and ancestor scopes are valid, but ancestor compatibility and
 explicit target membership remain independent checks. Descriptors still have
 no publication identity fields.
 A Scope carries a private publication lifetime, not a generated Protocol ref.
 Clone it only while the same scope Object remains published: ordinary Object
 state/validator updates do not retire it. Deletion, replacement or movement
 requires retiring the old lifetime with `registry.remove_scope(&scope)` and
 creating a fresh Scope before republication, even at the same path or ref.
 Retained registration tokens cannot fetch or start calls after retirement.
 Ref-less replacement cannot be tracked by a Client identity precondition; refs
 and scope_ref remain optional, not forcibly generated.
 `ScopeObservation::new(&scope, &object)` is a provider attestation that this
 lifetime currently belongs to the Object at the scope path. Construct and attach
 it with `PublishedObject::bind_scope` inside the same coherent boundary as target
 resolution, membership, Descriptor/validator selection, implementation and
 backend handles, through dispatch and commit/rollback. A matching ref or an
 independent scope prelookup is not sufficient. The scope Object need not expose
 any interfaces. Providers own atomicity and external-writer limitations; the
 runtime checks the attached lifetime and optional scope_ref, and validates both
 arguments and results against the same frozen Descriptor. A supplied scope_ref
 mismatch, including a missing current ref, is `InterfaceMismatch` at membership
 precedence, after target existence and a supplied Object validator mismatch.
 Omission applies no scope identity precondition.
 Artifact-only `registry.fetch_interface(reference)` is removed. Prefer
 `ObjectProvider::fetch_interface(&provider, &registry, &reference)`, which resolves
 the visible scope Object with `with_object` and uses its attached current binding.
 Low-level `registry.fetch_interface(&reference, &current_observation)` requires
 the same coherent current attestation, not a cached snapshot. Fetch returns
 Descriptor, Interface validator and optional scope Object ref together; Clients
 need not additionally fetch an ancestor Object. `registry.scopes()` may repeat
 a handle for several names; do not treat it as a unique-scope iterator.
 `PublishedObject::protocol_object()` is a path-free composition projection, not
 publication authority. For current observations use `ObjectProvider::observe_object`
 or `publication.protocol_object_at(path)` inside the coherent provider boundary;
 the latter also validates compatible live scope associations and response shape.
 ## Downstream status
 The filesystem default registers local names `file.read`, `symlink.inspect` and
 `file.write` at its deployment-pinned root Scope, displayed as `/::file.read` etc.
 External compositions choose explicit Scope/local names and implement
 `Composition::scope` to attest a non-root lifetime from the exact refreshed backend
 entry in its connected lineage. The engine never independently resolves a scope
 path during dispatch. Default composition remains root-scoped; exposing non-root
 registrations requires the application's current lifetime attestation, not merely
 an artifact or matching ref/validator. All bindings are formed inside backend
 execution, with current principal lineage visibility and publication metadata.
 Retire/recreate Scope handles on deletion, replacement or movement; a pinned leaf
 alone is not evidence that a self-scope Object remains published at that path.
 The Linux deployment root remains pinned across textual root rename/replacement,
 and its ref-less default publication continues to omit scope_ref.
 The public API example self-scopes `catalog`, `audit` and `diagnostics` at
 `/article-service`, fetches through its provider, and constructs call metadata
 from the fetched structured reference and scope_ref. External-style conformance
 tests also cross real TCP HTTP for root/self-scopes, same names in different
 scopes, optional refs, stale refs, deletion/republication and validator precedence.
 The TUI stores structured references in cache keys, selections, actions, editors
 and in-flight subjects. Normal screens reuse the canonical absolute scoped
 formatter (`/scope::name#operation`, with JSON component quoting when needed).
 Labels are never parsed to reconstruct identity, and scope_ref/validators are not
 normal-screen reference labels. Client invalidation is synchronized back into UI
 observations before dispatch; re-observation is not automatic execution. Typed
 result entries are still fetched on selection, not all at once, and do not create
 inferred indexable edges. Interface authoring/macros remain descriptor-only.
@@ -1,62 +1,110 @@
 # wip-rs
-Rust building blocks for the Web Interface Protocol (WIP).
+Rust building blocks for the Worldspace Interface Protocol (WIP).
 The repository is a resolver-3 virtual Cargo workspace whose packages all live
 under `crates/*`. It provides a transport-independent protocol model, the
-standard framework-independent WIP over HTTPS v1 binding, a stateful
+standard framework-independent WIP over HTTP v1 binding, a stateful
 presentation-independent client runtime, a Rust interface-authoring facade, a
 request-scoped host runtime, a bounded Linux filesystem projection server, an
-interactive terminal client, and a private public-API conformance consumer. The
+interactive terminal client, a standalone Text View signature library, and a
 private public-API conformance consumer. The
 repository root is not itself a package.
 ## Crate graph and responsibilities
 ```text
-wip-tui (interactive Worldspace explorer and operation editor)
+Published libraries
 ├── wip-client                Known Space, request identity, validators, and calls
 ├── wip-https                 framework-neutral HTTP request/response messages
 └── wip-protocol              descriptors and logical values
-wip-fs-server (request-time filesystem projection and loopback listener)
+wip-text-view
-├── wip-https                 standard routes/codecs/envelopes/batching
+└── wip-protocol
 ├── wip-host                  request-scoped publication and dispatch
 └── wip-interface             macro-generated filesystem capabilities
-wip-public-api-example (workspace-only executable, integration tests, doctest)
+wip-client
-├── wip-protocol              logical declarations, values, calls, and validation
+├── wip-http
 ├── wip-https                 standard HTTPS v1 routes, JSON codecs, envelopes, and batching
 │   └── wip-protocol
-├── wip-client                stateful Known Space, lazy tree, observation, and call runtime
+└── wip-protocol
-│   ├── wip-https
+
 wip-host
 ├── wip-interface
 │   ├── wip-interface-macros
 │   └── wip-protocol
-├── wip-interface             application DTO codecs and interface authoring facade
+└── wip-protocol
-│   ├── wip-protocol
+
-│   └── wip-interface-macros  proc-macro implementation detail
+Workspace-only applications and conformance consumers
-└── wip-host                  descriptor registry, publication, and qualified dispatch
+
-    ├── wip-interface
+wip-tui
-    └── wip-protocol
+├── wip-client
 ├── wip-http
 └── wip-protocol
 wip-fs-server
 ├── wip-host
 ├── wip-http
 ├── wip-interface
 └── wip-protocol
 wip-public-api-example
 ├── wip-host
 ├── wip-interface
 └── wip-protocol
 ```
 | Crate | Responsibility | Does not own |
 | --- | --- | --- |
 | `wip-text-view` | Standalone, validated single-Object and single-Interface Text View signatures with full declarations, summaries and safe escapes. | Retrieval, cache, placement context, wire schema, UI layout, parsing or call-target reconstruction. |
 | `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-http` | Standard WIP over HTTP v1 endpoint/route derivation, UTF-8 JSON codecs, direct success bodies, and error/status classification. | HTTP I/O, URL scheme or TLS policy, authentication schemes, server frameworks, filesystem projection, or client presentation/cache policy. |
-| `wip-client` | Endpoint/security-context-isolated Known Space, normalized object and interface observations, lazy entry trees, immutable operation call contexts, stale transitions, and bounded histories. | HTTP I/O, credentials, persistent cache, automatic operation retries, or presentation widgets/events. |
+| `wip-client` | Endpoint/security-context-isolated Known Space, normalized object and interface observations, intent-driven object and descriptor coverage with bounded request deduplication, immutable operation call contexts, stale transitions, and bounded histories. | HTTP I/O, credentials, persistent cache, automatic operation retries, or presentation widgets/events. |
-| `wip-tui` | Keyboard-only interactive Worldspace tree, selected Entry and qualified operation panes, descriptor-driven argument editing, bounded result/diagnostic rendering, terminal lifecycle, and HTTPS I/O workers over `wip-client`. | Independent cache/validator semantics, automatic operation retries, Host internals, backend paths, or persistent state. |
+| `wip-tui` | Keyboard-only interactive Worldspace tree, selected Entry and qualified operation panes, descriptor-driven argument editing, bounded result/diagnostic rendering, terminal lifecycle, and HTTP I/O workers over `wip-client`. | Independent cache/validator semantics, automatic operation retries, Host internals, backend paths, or persistent state. |
 | `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-host` | Scoped interface registration and publication lifetimes, 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-fs-server` | Linux directory-handle-confined request-time projection, complete depth-bounded observations and bounded file operations, standard `wip-http` dispatch, and a loopback HTTP binary. | A new wire profile, implicit symlink following, non-loopback cleartext, authentication policy, TLS termination, 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. |
 ## Published crates
 The `0.2.0` release consists of these seven crates:
 - `wip-protocol`
 - `wip-interface-macros` — implementation dependency re-exported by `wip-interface`
 - `wip-interface`
 - `wip-host`
 - `wip-http`
 - `wip-client`
 - `wip-text-view`
 The [`wip-text-view`](crates/wip-text-view/README.md) library's
 `render_object(&Object)` API needs no path;
 `render_interface(&Interface)` takes one borrowed entity pairing the complete
 structured reference with its descriptor, without changing Protocol wire fields.
 Both return one complete plain-text signature or a typed error.
 The filesystem server, terminal client, and public-API example are workspace-only packages and set `publish = false`. All workspace packages require Rust 1.88 or newer and are licensed under either Apache-2.0 or MIT at your option.
 See [RELEASING.md](RELEASING.md) for the dependency-ordered crates.io procedure and [CHANGELOG.md](CHANGELOG.md) for release contents.
 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`
+implementation owns credentials, handles, and backend state; and `wip-http`
 maps standard routes/envelopes to `CallOperationRequest` and
 `CallOperationResponse` without placing transport-specific types in descriptors
 or application traits.
 ## Structured Interface references
 The 0.2.0 Protocol/HTTP API uses explicit `InterfaceReference { scope,
 name }` records and optional `scope_ref` observation/precondition metadata.
 Legacy opaque-string wire references are rejected. See [MIGRATION.md](MIGRATION.md)
 for construction examples, validation boundaries and downstream migration status.
 The filesystem default publishes `/::file.read`, `/::symlink.inspect` and
 `/::file.write`; external compositions explicitly choose Scope/local names.
 The TUI retains structured references for selection and dispatch, while normal
 screens use absolute `scope::name#operation` labels with safely quoted components.
 These labels are display-only: they are never parsed as cache keys or call targets,
 and scope refs/validators remain runtime metadata rather than normal-screen labels.
 Client scope invalidation is reflected in the UI before another explicit call.
 ## End-to-end example
 [`crates/wip-public-api-example/src/lib.rs`](crates/wip-public-api-example/src/lib.rs)
@@ -69,7 +117,7 @@ runs it. It demonstrates all of the following:
 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
+5. separate observation of structured interface references, descriptors, and
   descriptor validators;
 6. calls qualified by `target.path`, object validator, interface reference and
   validator, operation, and schema-neutral `Value` arguments;
@@ -197,25 +245,44 @@ choose the ordered interface set for each object publication:
 ```rust,ignore
 let mut interfaces = wip_host::InterfaceRegistry::new();
-let messenger = interfaces.register(MessengerDefinition, None)?;
+let scope = wip_host::Scope::new("/service")?;
 let messenger = interfaces.register(&scope, "messenger", MessengerDefinition, None)?;
 // Inside the provider coherent backend boundary, not a stale scope prelookup:
 let current = wip_host::ScopeObservation::new(&scope, &current_scope_object);
 let published = wip_host::PublishedObject::new(request_scoped_object)
-    .expose(&messenger)?;
+    .expose(&messenger)?
-let protocol_object = published.protocol_object();
+    .bind_scope(current);
 let protocol_object = published.protocol_object_at("/service/item")?;
 ```
 `expose` compiles only when the object implements the generated definition's
 interface trait. Implementing a trait does not expose it automatically, empty
 interface sets are valid, insertion order is preserved, and duplicate
-references are rejected. Registry references are opaque and remain outside the
+references are rejected. Registry collisions use exact `(scope, name)` pairs,
-descriptor; generated descriptors contain neither those references nor Rust
+not Rust Definition identity; the same Definition may be registered at multiple
-trait identity.
+coordinates. Structured references remain outside the Descriptor.
 `Scope` carries a private Object publication lifetime. Keep it for ordinary state
 updates; retire it with `remove_scope` and create a fresh Scope on deletion,
 replacement or movement, even at the same path. Providers attach a current
 `ScopeObservation` from the scope Object inside the coherent target/backend
 boundary, never from a separate prelookup. The scope Object need not expose any
 interfaces. Fetch uses `ObjectProvider::fetch_interface(&provider, &registry,
 &reference)` to observe the visible scope Object and return its optional ref,
 Descriptor and Interface validator together; retained artifacts alone are not
 publication. Calls require the current attached lifetime and check supplied
 `scope_ref` at membership precedence; omission adds no identity precondition.
 Refs, Object validators and Interface validators retain distinct responsibilities.
 See [MIGRATION.md](MIGRATION.md) for the provider atomicity and lifecycle contract.
 Dispatch is qualified by interface reference and operation name and targets a
 canonical Worldspace path. An `ObjectProvider` validates that path before
 resolution, maps malformed paths to `InvalidRequest`, then resolves a valid path
 exactly once inside `with_object`; the host checks the supplied object validator,
-current interface membership, interface validator, descriptor operation,
+current scope lifetime/optional scope_ref and 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
@@ -263,8 +330,10 @@ from Worldspace `/`, lazily expands materialized tree nodes, displays current
 object/interface/operation metadata, validates all canonical descriptor types in
 a field editor, and requires a separate confirmation action before every call.
 It uses the stateful `wip-client` runtime for request correlation, observed
-validators, stale transitions, and unknown outcomes. HTTPS is the default;
+validators, stale transitions, and unknown outcomes. One canonical `http` or
-loopback plain HTTP requires `--allow-http`. Full startup, TLS, key binding,
+`https` endpoint is used unchanged for request construction, transport, and
 cache partitioning. Scheme, TLS, certificates, authentication, and proxy policy
 belong to the HTTP implementation and deployment. Full startup, key binding,
 layout, validator, and filesystem-operation examples are in the
 [package README](crates/wip-tui/README.md).
@@ -274,10 +343,12 @@ layout, validator, and filesystem-operation examples are in the
 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
+non-UTF-8 backend names, returns complete recursive observations through the
-publishes validator-protected replacement only in explicit read-write mode.
+requested depth or a resource-limit failure, and publishes validator-protected
-The built-in cleartext listener is loopback-only: production HTTPS is explicitly
+replacement only in explicit read-write mode.
-delegated to a reverse proxy, while local plain HTTP requires an opt-in flag.
+The built-in HTTP listener is loopback-only. Externally visible URL schemes,
 TLS termination, certificates, authentication, and proxy routing are deployment
 concerns rather than separate WIP profiles.
 ## Validation
@@ -0,0 +1,78 @@
 # Releasing
 The seven public crates in the current workspace (including `wip-text-view`) use one version and must be released in dependency order. The filesystem server, terminal client, and public-API example set `publish = false` and are never uploaded.
 ## Preconditions
 1. Work from a clean `master` whose `HEAD` matches `origin/master`.
 2. Confirm the intended version in `[workspace.package]` and every internal requirement in `[workspace.dependencies]`.
 3. Confirm ownership of all seven names on crates.io.
 4. Run the complete repository validation suite:
 ```console
 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
 ```
 ## Publish order
 Before uploading anything, dry-run the exact public package set together. Cargo uses a temporary local registry for unpublished workspace dependencies during this check:
 ```console
 cargo publish --dry-run --workspace \
  --exclude wip-fs-server \
  --exclude wip-public-api-example \
  --exclude wip-tui
 ```
 Then dry-run and publish each layer before moving to a crate that depends on it:
 ```console
 cargo publish --dry-run --package wip-protocol
 cargo publish --package wip-protocol
 cargo publish --dry-run --package wip-interface-macros
 cargo publish --package wip-interface-macros
 ```
 Wait until both versions are available from the crates.io index, then continue:
 ```console
 cargo publish --dry-run --package wip-text-view
 cargo publish --package wip-text-view
 cargo publish --dry-run --package wip-interface
 cargo publish --package wip-interface
 cargo publish --dry-run --package wip-http
 cargo publish --package wip-http
 ```
 After those versions are available from the index:
 ```console
 cargo publish --dry-run --package wip-host
 cargo publish --package wip-host
 cargo publish --dry-run --package wip-client
 cargo publish --package wip-client
 ```
 Registry propagation can take time. A dependent dry-run reporting that a WIP crate is unavailable means the previous publish is not visible in the selected registry yet; do not bypass verification.
 ## Tag
 After all seven uploads resolve successfully, tag the exact published commit and push the tag:
 ```console
 git tag -a v0.2.0 -m "chore: release 0.2.0"
 git push origin v0.2.0
 ```
 Do not move or recreate a published version or its tag. Prepare a new version for any subsequent correction.
@@ -1,10 +1,26 @@
 [package]
 name = "wip-client"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
 rust-version.workspace = true
 description = "Presentation-independent stateful WIP client runtime"
-license = "MIT OR Apache-2.0"
+license.workspace = true
 repository.workspace = true
 readme = "README.md"
 documentation = "https://docs.rs/wip-client"
 [features]
 default = ["http"]
 http = ["dep:wip-http"]
 [dependencies]
-wip-https = { path = "../wip-https" }
+wip-http = { workspace = true, optional = true }
-wip-protocol = { path = "../wip-protocol" }
+wip-protocol.workspace = true
 [[test]]
 name = "adapter"
 required-features = ["http"]
 [[test]]
 name = "runtime"
 required-features = ["http"]
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Hare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,52 @@
 # wip-client
 Presentation-independent stateful runtime for Worldspace Interface Protocol (WIP) clients.
 `wip-client` manages Worldspace-view- and security-context-isolated Known Space, object and Interface Descriptor observations, bounded request ownership, supersession, out-of-order response suppression, validator recovery, and operation call contexts. Its typed logical core requires neither HTTP nor JSON. The default HTTP facade produces and consumes framework-neutral `wip-http` messages using the same logical runtime. Neither path performs network I/O or contains UI types.
 ```toml
 [dependencies]
 wip-client = "0.2.0"
 ```
 The default `http` feature preserves `wip_client::Client::new(state_limits, wire_limits)`, canonical HTTP endpoint sessions, `PreparedRequest`, and HTTP `complete`. Applications send each prepared request and return its corresponding response.
 ## Direct typed Client (no HTTP dependency)
 ```toml
 [dependencies]
 wip-client = { version = "0.2.0", default-features = false }
 wip-protocol = "0.2.0"
 ```
 Use `wip_client::direct::{Client, Request, Response}`. Construct the client with `Client::new(state_limits)` and open a session using an opaque, application-owned Worldspace view identity plus `SecurityContext`; no URL is parsed or required. Allocate different identities for different Hosts/views and when replacing a Host. Direct identities and HTTP endpoint identities occupy distinct namespaces, even when their strings match.
 The existing observation, interface acquisition, and call preparation methods return `direct::PreparedRequest { id, request }`. Dispatch the `Request::Observe`, `Request::FetchInterface`, or `Request::CallOperation` DTO to the Host, then call `complete(id, Response::<matching interaction>(result))`, where `result` is `Result<Protocol response DTO, ProtocolError>`. The prepared request must be dispatched unchanged; routing it to the session's Host/security context remains the application's responsibility. Mark calls dispatched immediately before invoking the Host.
 Typed results are **not trusted**: the runtime checks interaction correspondence, observation depth/names/paths, scoped Interface correspondence, descriptor structure and format, descriptor-bound arguments/results, and per-interaction Protocol error codes. Invalid call responses leave the outcome unknown, just as with HTTP. HTTP status/envelope classification, JSON encoding, and wire size/depth limits remain exclusive to the optional adapter; `ClientLimits` bounds retained logical state on both paths. Direct DTO allocation and execution budgets belong to the embedding application.
 See [migration guidance](../../MIGRATION.md#transport-independent-client-api) and the `direct` module's executable API example.
 ## Interface identity and scope lifetime
 Interface acquisition and call APIs use `wip_protocol::InterfaceReference { scope, name }` directly. Within an endpoint/security-context session, the complete scoped pair is the cache key and the Object membership key: equal names in different scopes remain distinct. A scope is a canonical absolute Worldspace path and must be an ancestor of, or equal to, the call target path. Root scope (`/`) and self scope are valid; clients must not rewrite either into a different reference.
 `InterfaceObservation::scope_ref` is optional opaque metadata identifying the scope Object, not a third reference component, a path, or an Interface Descriptor validator. Its absence does not prevent acquisition or calls. Calls copy the exact observed reference, optional `scope_ref`, and optional Interface Descriptor validator into `InterfaceTarget`; the target Object validator is copied separately. The `CallContext` fixes those observations, the descriptor, and the operation declaration before dispatch.
 A descriptor without an Interface Descriptor validator is immutable only within the lifetime of its scope Object, not forever at that path. Descriptors with validators are also bound to that scope lifetime. When accepted observations establish that a known scope binding has changed or been lost, dependent cached interface state is invalidated and cannot authorize a new call until explicitly reacquired. A superseded interface response must not restore an observation from the old lifetime. A previously prepared call retains its original context rather than silently adopting a new scope identity or descriptor.
 Scope binding evidence is shared across Interface names at the same scope path: a new binding learned by fetching one name retires older descriptors for the other names too. Separately observed Object refs also provide lifetime evidence even when a descriptor's `scope_ref` was omitted. This corroboration is private bounded cache state, not an invented identity, and never fills in missing call metadata. Same-lifetime descriptor validation still applies; a detected ref change or loss retires the old lifetime instead.
 Object deletion, entry-edge removal, and local cache eviction are different events. A direct observe `NotFound` confirms unavailability at the requested scope path and removes cached interfaces scoped to that path; it does not guarantee identity-wide Object deletion or unavailability through every alias. Removing one entry edge likewise does not prove that the Object was deleted or invalidate every remaining alias. Cache eviction is local loss of retained knowledge, not evidence of Host deletion. Losing a known binding at an interface's scope path nevertheless ends safe reuse of descriptors dependent on that binding, even if the same Object remains reachable elsewhere. Optional `scope_ref` can provide identity evidence, but clients do not fabricate it when it is absent.
 Without Object `ref` or `scope_ref` identity evidence, a replacement at the same scope path can be indistinguishable from the previous Object. The runtime cannot detect every ref-less replacement from path and descriptor contents alone; absence of detectable change is not proof that the scope lifetime continued.
 ## Explicit recovery and operation outcomes
 `ensure_observed` and `ensure_interface` avoid duplicate fresh or loading work; they do not automatically refresh retained stale or failed observations. Use the explicit object/children refresh APIs and `prepare_interface` to recover the observations required for a new call. An operation `InterfaceMismatch` invalidates both sides of the call's assumptions: it marks the target Object observation stale and invalidates the selected cached interface observation, so recovery requires reobserving membership and reacquiring the descriptor. Reobserving an Object and reacquiring its interface are retrievals, not a retry of an operation.
 The runtime never automatically retries an operation. Mark a call dispatched when handing it to the transport and report completion or transport failure with its original `RequestId`. A timeout, disconnect, or invalid response after dispatch can leave the outcome unknown: execution or commit cannot be ruled out. Refreshing stale state does not resolve that uncertainty and must not automatically resubmit the call; any new operation is an explicit application decision.
 See the [API documentation](https://docs.rs/wip-client) for session, acquisition, cache, and call APIs.
 Licensed under either of Apache-2.0 or MIT at your option.
@@ -0,0 +1,346 @@
 //! Optional HTTP facade. Encoding and wire classification live only here.
 use std::ops::{Deref, DerefMut};
 use wip_http::http::{Request, Response};
 use wip_http::{
    ClientResponseError, DecodedResponse, Endpoint, Limits, StatusMismatch,
    decode_call_operation_response, decode_fetch_interface_response, decode_observe_response,
    encode_call_operation_request, encode_fetch_interface_request, encode_observe_request,
 };
 use super::*;
 /// Encoded HTTP request paired with its runtime identity.
 #[derive(Debug)]
 pub struct PreparedRequest {
    /// Identity required when completing or failing this request.
    pub id: RequestId,
    /// Standard WIP over HTTP request.
    pub request: Request<Vec<u8>>,
 }
 /// HTTP-compatible facade over the typed logical client.
 ///
 /// State inspection and transport failure reporting delegate to the same core.
 /// Request encoding is performed before changing cache or in-flight state.
 #[derive(Debug)]
 pub struct Client {
    core: DirectClient,
    wire_limits: Limits,
 }
 impl Deref for Client {
    type Target = DirectClient;
    fn deref(&self) -> &Self::Target {
        &self.core
    }
 }
 impl DerefMut for Client {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.core
    }
 }
 impl Client {
    /// Creates an empty runtime with explicit state and wire bounds.
    #[must_use]
    pub fn new(limits: ClientLimits, wire_limits: Limits) -> Self {
        Self {
            core: DirectClient::new(limits),
            wire_limits,
        }
    }
    /// Returns one cached object observation.
    #[must_use]
    pub fn object(&self, session: &SessionId, path: &str) -> Option<ObjectObservation> {
        self.core.object(session, path)
    }
    /// Returns bounded Known Space in canonical path order.
    #[must_use]
    pub fn known_space(&self, session: &SessionId) -> Option<Vec<ObjectObservation>> {
        self.core.known_space(session)
    }
    /// Returns one materialized lazy-tree node.
    #[must_use]
    pub fn tree(&self, session: &SessionId, path: &str) -> Option<&TreeObservation> {
        self.core.tree(session, path)
    }
    /// Returns the descriptor observation for a complete scoped reference.
    #[must_use]
    pub fn interface(
        &self,
        session: &SessionId,
        reference: &InterfaceReference,
    ) -> Option<&InterfaceObservation> {
        self.core.interface(session, reference)
    }
    /// Returns bounded operation history from oldest to newest.
    #[must_use]
    pub fn call_history(&self, session: &SessionId) -> Option<&VecDeque<CallRecord>> {
        self.core.call_history(session)
    }
    /// Returns bounded diagnostic history from oldest to newest.
    #[must_use]
    pub fn diagnostics(&self, session: &SessionId) -> Option<&VecDeque<Diagnostic>> {
        self.core.diagnostics(session)
    }
    /// Returns the number of requests currently in flight.
    #[must_use]
    pub fn in_flight_len(&self) -> usize {
        self.core.in_flight_len()
    }
    /// Returns the immutable context of an in-flight operation.
    #[must_use]
    pub fn pending_call_context(&self, id: RequestId) -> Option<&CallContext> {
        self.core.pending_call_context(id)
    }
    /// Marks an operation as handed to the transport.
    pub fn mark_dispatched(&mut self, id: RequestId) -> Result<(), ClientError> {
        self.core.mark_dispatched(id)
    }
    /// Records a failure with no response, preserving the dispatch boundary.
    pub fn fail_transport(
        &mut self,
        id: RequestId,
        detail: impl Into<String>,
    ) -> Result<Completion, ClientError> {
        self.core.fail_transport(id, detail)
    }
    /// Records timeout or disconnect after dispatch without retrying.
    pub fn fail_dispatched_call(
        &mut self,
        id: RequestId,
        failure: DispatchedTransportFailure,
        detail: impl Into<String>,
    ) -> Result<Completion, ClientError> {
        self.core.fail_dispatched_call(id, failure, detail)
    }
    /// Opens a session isolated by canonical endpoint and security context.
    pub fn open_session(
        &mut self,
        endpoint: &str,
        security_context: SecurityContext,
    ) -> Result<SessionId, ClientError> {
        let endpoint = Endpoint::parse(endpoint).map_err(invalid_request)?;
        self.core.open_session_id(SessionId {
            endpoint: endpoint.to_string(),
            security_context,
            binding: SessionBinding::Http,
        })
    }
    /// Ensures requested coverage without duplicating fresh or loading work.
    pub fn ensure_observed(
        &mut self,
        session: &SessionId,
        path: impl Into<String>,
        depth: u32,
    ) -> Result<Option<PreparedRequest>, ClientError> {
        let path = path.into();
        wip_protocol::validate_path(&path).map_err(invalid_request)?;
        let coverage = observation_coverage(self.core.session(session)?, &path, depth);
        if coverage != ObservationCoverage::Missing
            || self.core.pending.len() >= self.core.limits.in_flight
        {
            return Ok(None);
        }
        self.refresh_observed(session, path, depth).map(Some)
    }
    /// Ensures direct children without duplicating fresh or loading work.
    pub fn ensure_children_observed(
        &mut self,
        session: &SessionId,
        path: impl Into<String>,
    ) -> Result<Option<PreparedRequest>, ClientError> {
        self.ensure_observed(session, path, 1)
    }
    /// Refreshes one object without replacing previously observed children.
    pub fn refresh_object(
        &mut self,
        session: &SessionId,
        path: impl Into<String>,
    ) -> Result<PreparedRequest, ClientError> {
        self.refresh_observed(session, path, 0)
    }
    /// Refreshes one object and its direct children.
    pub fn refresh_children(
        &mut self,
        session: &SessionId,
        path: impl Into<String>,
    ) -> Result<PreparedRequest, ClientError> {
        self.refresh_observed(session, path, 1)
    }
    /// Explicitly refreshes observation coverage, superseding older requests.
    pub fn refresh_observed(
        &mut self,
        session: &SessionId,
        path: impl Into<String>,
        depth: u32,
    ) -> Result<PreparedRequest, ClientError> {
        let endpoint = endpoint(session)?;
        let limits = self.wire_limits;
        let (id, request) = self
            .core
            .refresh_observed_with(session, path, depth, |request| {
                encode_observe_request(&endpoint, request, limits).map_err(invalid_request)
            })?;
        Ok(PreparedRequest { id, request })
    }
    /// Ensures an interface without duplicating work or evicting another descriptor.
    pub fn ensure_interface(
        &mut self,
        session: &SessionId,
        reference: InterfaceReference,
    ) -> Result<Option<PreparedRequest>, ClientError> {
        let state = self.core.session(session)?;
        if state.interfaces.contains_key(&reference)
            || state.interfaces.len() >= self.core.limits.interfaces_per_session
            || self.core.pending.len() >= self.core.limits.in_flight
        {
            return Ok(None);
        }
        self.prepare_interface(session, reference).map(Some)
    }
    /// Explicitly starts or refreshes a descriptor observation.
    pub fn prepare_interface(
        &mut self,
        session: &SessionId,
        reference: InterfaceReference,
    ) -> Result<PreparedRequest, ClientError> {
        let endpoint = endpoint(session)?;
        let limits = self.wire_limits;
        let (id, request) = self
            .core
            .prepare_interface_with(session, reference, |request| {
                encode_fetch_interface_request(&endpoint, request, limits).map_err(invalid_request)
            })?;
        Ok(PreparedRequest { id, request })
    }
    /// Constructs an operation using fresh observations and an immutable CallContext.
    pub fn prepare_call(
        &mut self,
        session: &SessionId,
        path: &str,
        interface: &InterfaceReference,
        operation: impl Into<String>,
        arguments: BTreeMap<String, Value>,
    ) -> Result<PreparedRequest, ClientError> {
        let endpoint = endpoint(session)?;
        let limits = self.wire_limits;
        let (id, request) = self.core.prepare_call_with(
            session,
            path,
            interface,
            operation,
            arguments,
            |request, descriptor| {
                encode_call_operation_request(&endpoint, request, descriptor, limits)
                    .map_err(invalid_request)
            },
        )?;
        Ok(PreparedRequest { id, request })
    }
    /// Decodes HTTP metadata and body, then validates and applies the logical result.
    pub fn complete(
        &mut self,
        id: RequestId,
        response: Response<Vec<u8>>,
    ) -> Result<Completion, ClientError> {
        let pending = self.core.pending.get(&id).ok_or_else(unknown_request)?;
        let session = pending.session().clone();
        let mut mismatch = None;
        let decoded = match pending {
            Pending::Observe { request, .. } => {
                decode_observe_response(request, &response, self.wire_limits)
                    .map(|value| LogicalResponse::Observe(unpack(value, &mut mismatch)))
            }
            Pending::Interface { request, .. } => {
                decode_fetch_interface_response(request, &response, self.wire_limits)
                    .map(|value| LogicalResponse::FetchInterface(unpack(value, &mut mismatch)))
            }
            Pending::Call { context, .. } => decode_call_operation_response(
                &context.request,
                &context.descriptor,
                &response,
                self.wire_limits,
            )
            .map(|value| LogicalResponse::CallOperation(unpack(value, &mut mismatch))),
        }
        .map_err(classify_response_error);
        let completion = self.core.complete_result(id, decoded)?;
        if !matches!(completion, Completion::StaleResponseRejected(_))
            && let Some(mismatch) = mismatch
        {
            let maximum = self.core.limits.history;
            self.core.session_mut(&session)?.push_diagnostic(
                Diagnostic {
                    request_id: id,
                    kind: DiagnosticKind::HttpStatusMismatch,
                    detail: format!(
                        "received HTTP {}; canonical status is {}",
                        mismatch.actual, mismatch.expected
                    ),
                },
                maximum,
            );
        }
        Ok(completion)
    }
 }
 fn endpoint(session: &SessionId) -> Result<Endpoint, ClientError> {
    if session.binding != SessionBinding::Http {
        return Err(invalid_request(
            "direct Worldspace session cannot be used as an HTTP endpoint",
        ));
    }
    Endpoint::parse(&session.endpoint).map_err(invalid_request)
 }
 fn unpack<T>(
    value: DecodedResponse<T>,
    mismatch: &mut Option<StatusMismatch>,
 ) -> Result<T, ProtocolError> {
    match value {
        DecodedResponse::Success(value) => Ok(value),
        DecodedResponse::ProtocolFailure {
            error,
            status_mismatch,
        } => {
            *mismatch = status_mismatch;
            Err(error)
        }
    }
 }
 fn classify_response_error(error: ClientResponseError) -> ClientError {
    let kind = match error {
        ClientResponseError::InvalidResponse { .. } => ClientErrorKind::InvalidResponse,
        ClientResponseError::UnsupportedDescriptorFormat { .. } => {
            ClientErrorKind::UnsupportedDescriptorFormat
        }
        ClientResponseError::TransportBinding(_) => ClientErrorKind::Transport,
    };
    ClientError::new(kind, error.to_string())
 }
@@ -0,0 +1,80 @@
 use super::*;
 fn invalid_response(error: impl Display) -> ClientError {
    ClientError::new(ClientErrorKind::InvalidResponse, error.to_string())
 }
 pub(super) fn invalid_request(error: impl Display) -> ClientError {
    ClientError::new(ClientErrorKind::InvalidRequest, error.to_string())
 }
 fn validate_failure<T>(
    result: Result<T, ProtocolError>,
    interaction: ProtocolInteraction,
    validate: impl FnOnce(&T) -> Result<(), ClientError>,
 ) -> Result<Result<T, ProtocolError>, ClientError> {
    match &result {
        Ok(value) => validate(value)?,
        Err(error) if !error.code.is_allowed_for(interaction) => {
            return Err(invalid_response(
                "Protocol error is forbidden for this interaction",
            ));
        }
        Err(_) => {}
    }
    Ok(result)
 }
 pub(super) fn validate_observe(
    request: &ObserveRequest,
    response: Result<LogicalResponse, ClientError>,
 ) -> Result<Result<ProtocolObjectObservation, ProtocolError>, ClientError> {
    let LogicalResponse::Observe(result) = response? else {
        return Err(invalid_response(
            "response interaction does not match Observe request",
        ));
    };
    validate_failure(result, ProtocolInteraction::Observe, |value| {
        request.validate_response(value).map_err(invalid_response)
    })
 }
 pub(super) fn validate_interface(
    request: &FetchInterfaceRequest,
    response: Result<LogicalResponse, ClientError>,
 ) -> Result<Result<FetchInterfaceResponse, ProtocolError>, ClientError> {
    let LogicalResponse::FetchInterface(result) = response? else {
        return Err(invalid_response(
            "response interaction does not match FetchInterface request",
        ));
    };
    validate_failure(result, ProtocolInteraction::FetchInterface, |value| {
        value.validate_for(request).map_err(invalid_response)?;
        if value.descriptor.format != INTERFACE_FORMAT_V1 {
            return Err(ClientError::new(
                ClientErrorKind::UnsupportedDescriptorFormat,
                format!(
                    "unsupported interface descriptor format `{}`",
                    value.descriptor.format
                ),
            ));
        }
        Ok(())
    })
 }
 pub(super) fn validate_call(
    context: &CallContext,
    response: Result<LogicalResponse, ClientError>,
 ) -> Result<Result<CallOperationResponse, ProtocolError>, ClientError> {
    let LogicalResponse::CallOperation(result) = response? else {
        return Err(invalid_response(
            "response interaction does not match CallOperation request",
        ));
    };
    validate_failure(result, ProtocolInteraction::CallOperation, |value| {
        value
            .validate_for(&context.descriptor, &context.request.operation)
            .map_err(invalid_response)
    })
 }
@@ -1,21 +1,30 @@
 fn root_reference(name: &str) -> wip_protocol::InterfaceReference {
    wip_protocol::InterfaceReference {
        scope: "/".into(),
        name: name.into(),
    }
 }
 use std::collections::BTreeMap;
 use wip_client::{
    CallOutcome, Client, ClientErrorKind, ClientLimits, Completion, DiagnosticKind,
    ObservationState, OutcomeUnknownReason, SecurityContext,
 };
-use wip_https::http::{Response, StatusCode};
+use wip_http::http::{Response, StatusCode};
-use wip_https::{
+use wip_http::{
-    Limits, encode_fetch_interface_response, encode_fetch_response, encode_protocol_error_response,
+    Limits, decode_call_operation_request, decode_fetch_interface_request,
    encode_fetch_interface_response, encode_observe_response, encode_protocol_error_response,
 };
 use wip_protocol::{
-    FetchInterfaceRequest, FetchInterfaceResponse, FetchRequest, INTERFACE_FORMAT_V1,
+    CallOperationRequest, FetchInterfaceRequest, FetchInterfaceResponse, INTERFACE_FORMAT_V1,
-    InterfaceDescriptor, Object, OperationDeclaration, ParameterDeclaration, ProtocolError,
+    InterfaceDescriptor, InterfaceReference, InterfaceTarget, Object, ObjectObservation,
-    ProtocolErrorCode, ProtocolInteraction, ReturnDeclaration, TypeExpr, Value,
+    ObserveRequest, OperationDeclaration, ParameterDeclaration, ProtocolError, ProtocolErrorCode,
    ProtocolInteraction, ReturnDeclaration, Target, TypeExpr, Value,
 };
 fn limits() -> Limits {
-    Limits::new(64 * 1024, 64 * 1024, 64, 64).unwrap()
+    Limits::new(64 * 1024, 64 * 1024, 64).unwrap()
 }
 fn setup() -> (Client, wip_client::SessionId) {
@@ -38,7 +47,7 @@ fn object() -> Object {
    Object {
        name: "item".into(),
        description: None,
-        interfaces: vec!["math".into()],
+        interfaces: vec![root_reference("math")],
        r#ref: None,
        validator: Some(b"object-v1".to_vec()),
    }
@@ -66,17 +75,363 @@ fn descriptor(format: &str) -> InterfaceDescriptor {
    }
 }
 fn reference(scope: &str, name: &str) -> InterfaceReference {
    InterfaceReference {
        scope: scope.into(),
        name: name.into(),
    }
 }
 fn observe(client: &mut Client, session: &wip_client::SessionId, path: &str, value: Object) {
    let request = client.refresh_object(session, path).unwrap();
    client
        .complete(
            request.id,
            encode_observe_response(
                &ObserveRequest {
                    path: path.into(),
                    depth: 0,
                },
                &ObjectObservation {
                    object: value,
                    children: None,
                },
                limits(),
            )
            .unwrap(),
        )
        .unwrap();
 }
 fn fetch(
    client: &mut Client,
    session: &wip_client::SessionId,
    value: FetchInterfaceResponse,
 ) -> Completion {
    let request = client
        .prepare_interface(session, value.interface.clone())
        .unwrap();
    let logical = FetchInterfaceRequest {
        interface: value.interface.clone(),
    };
    assert_eq!(
        decode_fetch_interface_request(request.request.body(), limits()).unwrap(),
        logical
    );
    client
        .complete(
            request.id,
            encode_fetch_interface_response(&logical, &value, limits()).unwrap(),
        )
        .unwrap()
 }
 #[test]
 fn observe_accepts_same_name_interfaces_in_different_scopes() {
    let (mut client, session) = setup();
    let request = client.refresh_object(&session, "/item").unwrap();
    let completion = client
        .complete(
            request.id,
            response(
                StatusCode::OK,
                br#"{"object":{"name":"item","interfaces":[{"scope":"/","name":"math"},{"scope":"/item","name":"math"}]}}"#,
            ),
        )
        .unwrap();
    let expected = vec![root_reference("math"), reference("/item", "math")];
    assert!(matches!(
        completion,
        Completion::Object(observation)
            if observation.state == ObservationState::Fresh
                && observation.object.as_ref().unwrap().interfaces == expected
    ));
    let cached = client.object(&session, "/item").unwrap();
    assert_eq!(cached.state, ObservationState::Fresh);
    assert_eq!(cached.object.unwrap().interfaces, expected);
 }
 #[test]
 fn same_name_different_scopes_have_independent_requests_and_cached_descriptors() {
    let (mut client, session) = setup();
    let root = root_reference("math");
    let scoped = reference("/area", "math");
    let root_request = client
        .ensure_interface(&session, root.clone())
        .unwrap()
        .unwrap();
    let scoped_request = client
        .ensure_interface(&session, scoped.clone())
        .unwrap()
        .unwrap();
    assert_ne!(root_request.id, scoped_request.id);
    assert_eq!(
        decode_fetch_interface_request(root_request.request.body(), limits()).unwrap(),
        FetchInterfaceRequest {
            interface: root.clone(),
        }
    );
    assert_eq!(
        decode_fetch_interface_request(scoped_request.request.body(), limits()).unwrap(),
        FetchInterfaceRequest {
            interface: scoped.clone(),
        }
    );
    for selected in [&root, &scoped] {
        assert!(
            client
                .ensure_interface(&session, selected.clone())
                .unwrap()
                .is_none()
        );
    }
    assert_eq!(client.in_flight_len(), 2);
    // Reverse completion order must not supersede the other scope's request.
    for (request, selected, documentation, scope_ref, validator) in [
        (
            scoped_request,
            &scoped,
            "area math",
            Some("area-object"),
            Some(b"area-v1".to_vec()),
        ),
        (root_request, &root, "root math", None, None),
    ] {
        let mut expected_descriptor = descriptor(INTERFACE_FORMAT_V1);
        expected_descriptor.documentation = Some(wip_protocol::Documentation {
            summary: documentation.into(),
            details: None,
        });
        let value = FetchInterfaceResponse {
            interface: selected.clone(),
            scope_ref: scope_ref.map(str::to_owned),
            descriptor: expected_descriptor.clone(),
            validator: validator.clone(),
        };
        let completion = client
            .complete(
                request.id,
                encode_fetch_interface_response(
                    &FetchInterfaceRequest {
                        interface: selected.clone(),
                    },
                    &value,
                    limits(),
                )
                .unwrap(),
            )
            .unwrap();
        assert!(matches!(completion, Completion::Interface(_)));
        let cached = client.interface(&session, selected).unwrap();
        assert_eq!(cached.reference, *selected);
        assert_eq!(cached.descriptor, Some(expected_descriptor));
        assert_eq!(cached.scope_ref, value.scope_ref);
        assert_eq!(cached.validator, validator);
        assert_eq!(cached.state, ObservationState::Fresh);
    }
    for selected in [&root, &scoped] {
        assert!(
            client
                .ensure_interface(&session, selected.clone())
                .unwrap()
                .is_none()
        );
    }
    assert_eq!(client.in_flight_len(), 0);
    assert_eq!(
        client
            .interface(&session, &root)
            .unwrap()
            .descriptor
            .as_ref()
            .unwrap()
            .documentation
            .as_ref()
            .map(|documentation| documentation.summary.as_str()),
        Some("root math")
    );
    assert_eq!(
        client
            .interface(&session, &scoped)
            .unwrap()
            .descriptor
            .as_ref()
            .unwrap()
            .documentation
            .as_ref()
            .map(|documentation| documentation.summary.as_str()),
        Some("area math")
    );
 }
 #[test]
 fn interface_completion_retains_optional_scope_ref_independently_of_validator() {
    for scope_ref in [None, Some("opaque scope identity / not a path")] {
        for validator in [None, Some(b"interface-v1".to_vec())] {
            let (mut client, session) = setup();
            let selected = reference("/area", "math");
            let expected = wip_client::InterfaceObservation {
                reference: selected.clone(),
                descriptor: Some(descriptor(INTERFACE_FORMAT_V1)),
                scope_ref: scope_ref.map(str::to_owned),
                validator: validator.clone(),
                state: ObservationState::Fresh,
            };
            let completion = fetch(
                &mut client,
                &session,
                FetchInterfaceResponse {
                    interface: selected.clone(),
                    descriptor: expected.descriptor.clone().unwrap(),
                    scope_ref: expected.scope_ref.clone(),
                    validator,
                },
            );
            assert_eq!(completion, Completion::Interface(expected.clone()));
            assert_eq!(client.interface(&session, &selected), Some(&expected));
        }
    }
 }
 #[test]
 fn call_membership_requires_the_complete_scope_and_name_pair() {
    let (mut client, session) = setup();
    let member = reference("/item", "math");
    let same_name = root_reference("math");
    let mut value = object();
    value.interfaces = vec![member.clone()];
    observe(&mut client, &session, "/item", value);
    for selected in [&member, &same_name] {
        fetch(
            &mut client,
            &session,
            FetchInterfaceResponse {
                interface: selected.clone(),
                descriptor: descriptor(INTERFACE_FORMAT_V1),
                scope_ref: None,
                validator: None,
            },
        );
    }
    let arguments = BTreeMap::from([("value".into(), Value::Integer(2))]);
    assert_eq!(
        client
            .prepare_call(
                &session,
                "/item",
                &same_name,
                "calculate",
                arguments.clone(),
            )
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidRequest
    );
    assert_eq!(client.in_flight_len(), 0);
    let call = client
        .prepare_call(&session, "/item", &member, "calculate", arguments)
        .unwrap();
    assert_eq!(
        decode_call_operation_request(
            call.request.body(),
            &descriptor(INTERFACE_FORMAT_V1),
            limits(),
        )
        .unwrap()
        .interface
        .reference,
        member
    );
 }
 #[test]
 fn calls_copy_exact_observed_references_metadata_and_validators_for_root_ancestor_and_self_scopes()
 {
    for (path, scope) in [
        ("/", "/"),
        ("/item", "/"),
        ("/item", "/item"),
        ("/area/item", "/area"),
        ("/area/item", "/area/item"),
    ] {
        for scope_ref in [None, Some("opaque scope identity / not a path")] {
            for interface_validator in [None, Some(b"interface-v1".to_vec())] {
                for object_validator in [None, Some(b"object-v1".to_vec())] {
                    let (mut client, session) = setup();
                    let selected = reference(scope, "math");
                    let expected_descriptor = descriptor(INTERFACE_FORMAT_V1);
                    let mut value = object();
                    value.name = path.rsplit('/').next().unwrap().into();
                    value.interfaces = vec![selected.clone()];
                    value.validator = object_validator.clone();
                    if path == scope {
                        value.r#ref = scope_ref.map(str::to_owned);
                    }
                    observe(&mut client, &session, path, value.clone());
                    fetch(
                        &mut client,
                        &session,
                        FetchInterfaceResponse {
                            interface: selected.clone(),
                            descriptor: expected_descriptor.clone(),
                            scope_ref: scope_ref.map(str::to_owned),
                            validator: interface_validator.clone(),
                        },
                    );
                    let expected_interface = client.interface(&session, &selected).unwrap().clone();
                    let expected_object = client.object(&session, path).unwrap();
                    let arguments = BTreeMap::from([("value".into(), Value::Integer(2))]);
                    let expected = CallOperationRequest {
                        target: Target {
                            path: path.into(),
                            validator: object_validator,
                        },
                        interface: InterfaceTarget {
                            reference: selected.clone(),
                            scope_ref: scope_ref.map(str::to_owned),
                            validator: interface_validator.clone(),
                        },
                        operation: "calculate".into(),
                        arguments: arguments.clone(),
                    };
                    let call = client
                        .prepare_call(&session, path, &selected, "calculate", arguments)
                        .unwrap();
                    assert_eq!(
                        decode_call_operation_request(
                            call.request.body(),
                            &expected_descriptor,
                            limits(),
                        )
                        .unwrap(),
                        expected
                    );
                    let context = client.pending_call_context(call.id).unwrap();
                    assert_eq!(context.request(), &expected);
                    assert_eq!(context.interface(), &expected_interface);
                    assert_eq!(context.object(), &expected_object);
                    assert_eq!(context.object().object.as_ref(), Some(&value));
                    assert_eq!(context.descriptor(), &expected_descriptor);
                    assert_eq!(context.operation(), &expected_descriptor.operations[0]);
                    assert_eq!(context.session(), &session);
                }
            }
        }
    }
 }
 #[test]
 fn malformed_json_unknown_fields_duplicates_and_invalid_success_are_invalid_response() {
    let cases: &[&[u8]] = &[
        b"{not json",
        br#"{"name":"item","interfaces":[],"unknown":true}"#,
-        br#"{"name":"item","interfaces":["math","math"]}"#,
+        br#"{"name":"item","interfaces":[{"scope":"/","name":"math"},{"scope":"/","name":"math"}]}"#,
        br#"{"name":"wrong","interfaces":[]}"#,
    ];
    for body in cases {
        let (mut client, session) = setup();
-        let request = client.prepare_fetch(&session, "/item").unwrap();
+        let request = client.refresh_observed(&session, "/item", 0).unwrap();
        let error = client
            .complete(request.id, response(StatusCode::OK, body))
            .unwrap_err();
@@ -106,7 +461,7 @@ fn disallowed_code_and_status_success_contradictions_are_invalid_response() {
    ];
    for (status, body) in cases {
        let (mut client, session) = setup();
-        let request = client.prepare_fetch(&session, "/item").unwrap();
+        let request = client.refresh_observed(&session, "/item", 0).unwrap();
        assert_eq!(
            client
                .complete(request.id, response(status, body))
@@ -120,13 +475,13 @@ fn disallowed_code_and_status_success_contradictions_are_invalid_response() {
 #[test]
 fn valid_error_envelope_is_authoritative_and_status_mismatch_is_diagnostic() {
    let (mut client, session) = setup();
-    let request = client.prepare_fetch(&session, "/item").unwrap();
+    let request = client.refresh_observed(&session, "/item", 0).unwrap();
    let error = ProtocolError {
        code: ProtocolErrorCode::NotFound,
        message: "missing".into(),
    };
    let mut encoded =
-        encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
+        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).unwrap();
    *encoded.status_mut() = StatusCode::IM_A_TEAPOT;
    assert_eq!(
@@ -144,27 +499,51 @@ fn valid_error_envelope_is_authoritative_and_status_mismatch_is_diagnostic() {
 }
 #[test]
-fn non_success_without_valid_envelope_remains_transport_failure() {
+fn resource_envelope_on_413_uses_code_and_records_canonical_422_mismatch() {
    let (mut client, session) = setup();
-    let request = client.prepare_fetch(&session, "/item").unwrap();
+    let request = client.refresh_observed(&session, "/item", 0).unwrap();
-    let error = client
+    let error = ProtocolError {
-        .complete(
+        code: ProtocolErrorCode::ResourceLimitExceeded,
-            request.id,
+        message: "logical observation limit exceeded".into(),
-            response(StatusCode::BAD_GATEWAY, b"gateway html"),
+    };
-        )
+    let mut encoded =
-        .unwrap_err();
+        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).unwrap();
-    assert_eq!(error.kind, ClientErrorKind::Transport);
+    *encoded.status_mut() = StatusCode::PAYLOAD_TOO_LARGE;
    assert_eq!(
        client.complete(request.id, encoded).unwrap(),
        Completion::ProtocolFailure(error)
    );
    assert_eq!(
        client.diagnostics(&session).unwrap().back().unwrap().kind,
        DiagnosticKind::HttpStatusMismatch
    );
 }
 #[test]
 fn non_success_without_valid_envelope_remains_transport_failure() {
    for status in [StatusCode::BAD_GATEWAY, StatusCode::PAYLOAD_TOO_LARGE] {
        let (mut client, session) = setup();
        let request = client.refresh_observed(&session, "/item", 0).unwrap();
        let error = client
            .complete(request.id, response(status, b"infrastructure failure"))
            .unwrap_err();
        assert_eq!(error.kind, ClientErrorKind::Transport);
    }
 }
 #[test]
 fn unsupported_descriptor_format_is_distinct_from_invalid_response() {
    let (mut client, session) = setup();
-    let request = client.prepare_interface(&session, "math").unwrap();
+    let request = client
        .prepare_interface(&session, root_reference("math"))
        .unwrap();
    let logical = FetchInterfaceRequest {
-        interface: "math".into(),
+        interface: root_reference("math"),
    };
    let value = FetchInterfaceResponse {
-        interface: "math".into(),
+        scope_ref: None,
        interface: root_reference("math"),
        descriptor: descriptor("future-format/2"),
        validator: Some(b"v2".to_vec()),
    };
@@ -176,30 +555,37 @@ fn unsupported_descriptor_format_is_distinct_from_invalid_response() {
 #[test]
 fn malformed_call_success_after_dispatch_is_outcome_unknown_and_stales_object() {
    let (mut client, session) = setup();
-    let fetch = client.prepare_fetch(&session, "/item").unwrap();
+    let observation = client.refresh_observed(&session, "/item", 0).unwrap();
    client
        .complete(
-            fetch.id,
+            observation.id,
-            encode_fetch_response(
+            encode_observe_response(
-                &FetchRequest {
+                &ObserveRequest {
                    path: "/item".into(),
                    depth: 0,
                },
                &ObjectObservation {
                    object: object(),
                    children: None,
                },
                &object(),
                limits(),
            )
            .unwrap(),
        )
        .unwrap();
-    let interface = client.prepare_interface(&session, "math").unwrap();
+    let interface = client
        .prepare_interface(&session, root_reference("math"))
        .unwrap();
    client
        .complete(
            interface.id,
            encode_fetch_interface_response(
                &FetchInterfaceRequest {
-                    interface: "math".into(),
+                    interface: root_reference("math"),
                },
                &FetchInterfaceResponse {
-                    interface: "math".into(),
+                    scope_ref: None,
                    interface: root_reference("math"),
                    descriptor: descriptor(INTERFACE_FORMAT_V1),
                    validator: None,
                },
@@ -212,7 +598,7 @@ fn malformed_call_success_after_dispatch_is_outcome_unknown_and_stales_object()
        .prepare_call(
            &session,
            "/item",
-            "math",
+            &root_reference("math"),
            "calculate",
            BTreeMap::from([("value".into(), Value::Integer(2))]),
        )
@@ -245,3 +631,83 @@ fn malformed_call_success_after_dispatch_is_outcome_unknown_and_stales_object()
    );
    assert_eq!(client.in_flight_len(), 0);
 }
 #[test]
 fn plain_413_after_call_dispatch_is_unknown_transport_outcome() {
    let (mut client, session) = setup();
    let observation = client.refresh_observed(&session, "/item", 0).unwrap();
    client
        .complete(
            observation.id,
            encode_observe_response(
                &ObserveRequest {
                    path: "/item".into(),
                    depth: 0,
                },
                &ObjectObservation {
                    object: object(),
                    children: None,
                },
                limits(),
            )
            .unwrap(),
        )
        .unwrap();
    let interface = client
        .prepare_interface(&session, root_reference("math"))
        .unwrap();
    client
        .complete(
            interface.id,
            encode_fetch_interface_response(
                &FetchInterfaceRequest {
                    interface: root_reference("math"),
                },
                &FetchInterfaceResponse {
                    scope_ref: None,
                    interface: root_reference("math"),
                    descriptor: descriptor(INTERFACE_FORMAT_V1),
                    validator: None,
                },
                limits(),
            )
            .unwrap(),
        )
        .unwrap();
    let call = client
        .prepare_call(
            &session,
            "/item",
            &root_reference("math"),
            "calculate",
            BTreeMap::from([("value".into(), Value::Integer(2))]),
        )
        .unwrap();
    client.mark_dispatched(call.id).unwrap();
    let completion = client
        .complete(
            call.id,
            Response::builder()
                .status(StatusCode::PAYLOAD_TOO_LARGE)
                .body(Vec::<u8>::new())
                .unwrap(),
        )
        .unwrap();
    assert!(matches!(
        completion,
        Completion::Call(record)
            if matches!(
                &record.outcome,
                CallOutcome::Unknown {
                    reason: OutcomeUnknownReason::ResponseDecode,
                    failure: Some(failure),
                } if failure.kind == ClientErrorKind::Transport
            )
    ));
    assert_eq!(
        client.object(&session, "/item").unwrap().state,
        ObservationState::Stale
    );
    assert_eq!(client.in_flight_len(), 0);
 }
@@ -0,0 +1,614 @@
 //! Public API tests: no HTTP types, codec, endpoint parser, or JSON dependency.
 use std::collections::BTreeMap;
 use wip_client::direct::{Client, PreparedRequest, Request, Response};
 use wip_client::{
    CallOutcome, ClientErrorKind, ClientLimits, Completion, DispatchedTransportFailure,
    ObservationState, OutcomeUnknownReason, SecurityContext, SessionId,
 };
 use wip_protocol::{
    CallOperationResponse, FetchInterfaceResponse, INTERFACE_FORMAT_V1, InterfaceDescriptor,
    InterfaceReference, Object, ObjectObservation, OperationDeclaration, ParameterDeclaration,
    ProtocolError, ProtocolErrorCode, ReturnDeclaration, TypeExpr, Value,
 };
 fn setup() -> (Client, SessionId) {
    let mut client = Client::new(ClientLimits::new(4, 16, 8, 8, 4).unwrap());
    let session = client
        .open_session("in-process world", SecurityContext::new("alice"))
        .unwrap();
    (client, session)
 }
 fn reference() -> InterfaceReference {
    InterfaceReference {
        scope: "/scope".into(),
        name: "math".into(),
    }
 }
 fn object(name: &str, identity: Option<&str>) -> ObjectObservation {
    ObjectObservation {
        object: Object {
            name: name.into(),
            description: None,
            interfaces: vec![reference()],
            r#ref: identity.map(str::to_owned),
            validator: None,
        },
        children: None,
    }
 }
 fn descriptor() -> InterfaceDescriptor {
    InterfaceDescriptor {
        format: INTERFACE_FORMAT_V1.into(),
        documentation: None,
        types: vec![],
        operations: vec![OperationDeclaration {
            name: "double".into(),
            documentation: None,
            parameters: vec![ParameterDeclaration {
                name: "n".into(),
                documentation: None,
                required: true,
                r#type: TypeExpr::Integer,
            }],
            returns: ReturnDeclaration {
                documentation: None,
                r#type: TypeExpr::Integer,
            },
        }],
    }
 }
 fn interface(scope_ref: Option<&str>) -> FetchInterfaceResponse {
    FetchInterfaceResponse {
        interface: reference(),
        scope_ref: scope_ref.map(str::to_owned),
        validator: None,
        descriptor: descriptor(),
    }
 }
 fn failure(code: ProtocolErrorCode) -> ProtocolError {
    ProtocolError {
        code,
        message: "test failure".into(),
    }
 }
 fn observe(client: &mut Client, session: &SessionId, path: &str, value: ObjectObservation) {
    let request = client.refresh_object(session, path).unwrap();
    assert!(
        matches!(&request.request, Request::Observe(value) if value.path == path && value.depth == 0)
    );
    client
        .complete(request.id, Response::Observe(Ok(value)))
        .unwrap();
 }
 fn ready(client: &mut Client, session: &SessionId) {
    observe(client, session, "/scope/item", object("item", None));
    let request = client.prepare_interface(session, reference()).unwrap();
    assert!(
        matches!(request.request, Request::FetchInterface(value) if value.interface == reference())
    );
    client
        .complete(request.id, Response::FetchInterface(Ok(interface(None))))
        .unwrap();
 }
 fn call(client: &mut Client, session: &SessionId) -> PreparedRequest {
    client
        .prepare_call(
            session,
            "/scope/item",
            &reference(),
            "double",
            BTreeMap::from([("n".into(), Value::Integer(3))]),
        )
        .unwrap()
 }
 #[test]
 fn typed_interactions_succeed_with_optional_identity_and_validators_absent() {
    let (mut client, session) = setup();
    ready(&mut client, &session);
    assert!(
        client
            .ensure_observed(&session, "/scope/item", 0)
            .unwrap()
            .is_none()
    );
    assert!(
        client
            .ensure_interface(&session, reference())
            .unwrap()
            .is_none()
    );
    let request = call(&mut client, &session);
    let Request::CallOperation(logical) = request.request else {
        panic!("wrong request")
    };
    assert_eq!(logical.target.path, "/scope/item");
    assert_eq!(logical.target.validator, None);
    assert_eq!(logical.interface.scope_ref, None);
    assert_eq!(logical.interface.validator, None);
    assert_eq!(logical.arguments["n"], Value::Integer(3));
    client.mark_dispatched(request.id).unwrap();
    let result = CallOperationResponse {
        result: Value::Integer(6),
        validator: Some(vec![2]),
    };
    let completion = client
        .complete(request.id, Response::CallOperation(Ok(result.clone())))
        .unwrap();
    assert!(
        matches!(completion, Completion::Call(record) if record.outcome == CallOutcome::Success(result))
    );
    assert_eq!(
        client.object(&session, "/scope/item").unwrap().validator,
        Some(vec![2])
    );
    assert_eq!(client.in_flight_len(), 0);
    assert_eq!(
        client
            .complete(
                request.id,
                Response::CallOperation(Ok(CallOperationResponse {
                    result: Value::Integer(6),
                    validator: None,
                }))
            )
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidRequest
    );
 }
 #[test]
 fn worldspace_and_security_identities_partition_observations_without_urls() {
    let (mut client, session) = setup();
    ready(&mut client, &session);
    let other_world = client
        .open_session("another world", SecurityContext::new("alice"))
        .unwrap();
    let other_security = client
        .open_session("in-process world", SecurityContext::new("bob"))
        .unwrap();
    for other in [&other_world, &other_security] {
        assert!(client.object(other, "/scope/item").is_none());
        assert!(client.interface(other, &reference()).is_none());
    }
    assert_eq!(
        client
            .open_session("in-process world", SecurityContext::new("alice"))
            .unwrap(),
        session
    );
 }
 #[test]
 fn typed_observations_validate_name_depth_duplicate_children_and_interface_scope() {
    let (mut client, session) = setup();
    let mut wrong_scope = object("item", None);
    wrong_scope.object.interfaces[0].scope = "/elsewhere".into();
    let mut unexpected_children = object("item", None);
    unexpected_children.children = Some(vec![]);
    let mut duplicate = object("item", None);
    duplicate.children = Some(vec![object("child", None), object("child", None)]);
    for (depth, response) in [
        (0, object("wrong-name", None)),
        (1, object("item", None)),
        (0, unexpected_children),
        (0, wrong_scope),
        (1, duplicate),
    ] {
        let request = client
            .refresh_observed(&session, "/scope/item", depth)
            .unwrap();
        let error = client
            .complete(request.id, Response::Observe(Ok(response)))
            .unwrap_err();
        assert_eq!(error.kind, ClientErrorKind::InvalidResponse);
        assert!(matches!(
            client.object(&session, "/scope/item").unwrap().state,
            ObservationState::Error(_)
        ));
    }
 }
 #[test]
 fn typed_descriptor_correspondence_structure_and_format_are_checked() {
    let (mut client, session) = setup();
    let mut mismatched = interface(None);
    mismatched.interface.name = "other".into();
    let mut malformed = interface(None);
    malformed
        .descriptor
        .operations
        .push(malformed.descriptor.operations[0].clone());
    let mut unsupported = interface(None);
    unsupported.descriptor.format = "future".into();
    for (value, kind) in [
        (mismatched, ClientErrorKind::InvalidResponse),
        (malformed, ClientErrorKind::InvalidResponse),
        (unsupported, ClientErrorKind::UnsupportedDescriptorFormat),
    ] {
        let request = client.prepare_interface(&session, reference()).unwrap();
        assert_eq!(
            client
                .complete(request.id, Response::FetchInterface(Ok(value)))
                .unwrap_err()
                .kind,
            kind
        );
    }
 }
 #[test]
 fn typed_arguments_and_results_use_the_fixed_descriptor() {
    let (mut client, session) = setup();
    ready(&mut client, &session);
    let invalid = client
        .prepare_call(
            &session,
            "/scope/item",
            &reference(),
            "double",
            BTreeMap::from([("n".into(), Value::String("not integer".into()))]),
        )
        .unwrap_err();
    assert_eq!(invalid.kind, ClientErrorKind::InvalidRequest);
    assert_eq!(client.in_flight_len(), 0);
    let request = call(&mut client, &session);
    client.mark_dispatched(request.id).unwrap();
    let completion = client
        .complete(
            request.id,
            Response::CallOperation(Ok(CallOperationResponse {
                result: Value::String("not integer".into()),
                validator: None,
            })),
        )
        .unwrap();
    assert!(
        matches!(completion, Completion::Call(record) if matches!(record.outcome,
        CallOutcome::Unknown { reason: OutcomeUnknownReason::ResponseDecode, .. }))
    );
    assert_eq!(
        client.object(&session, "/scope/item").unwrap().state,
        ObservationState::Stale
    );
    assert!(
        client
            .ensure_observed(&session, "/scope/item", 0)
            .unwrap()
            .is_none()
    );
    assert_eq!(client.in_flight_len(), 0);
 }
 #[test]
 fn typed_protocol_failures_validate_interaction_and_apply_recovery() {
    let (mut client, session) = setup();
    let request = client.refresh_object(&session, "/scope/item").unwrap();
    assert!(matches!(
        client
            .complete(
                request.id,
                Response::Observe(Err(failure(ProtocolErrorCode::NotFound)))
            )
            .unwrap(),
        Completion::ProtocolFailure(_)
    ));
    let request = client.prepare_interface(&session, reference()).unwrap();
    assert!(matches!(
        client
            .complete(
                request.id,
                Response::FetchInterface(Err(failure(ProtocolErrorCode::InterfaceNotFound)))
            )
            .unwrap(),
        Completion::ProtocolFailure(_)
    ));
    let request = client.refresh_object(&session, "/scope/item").unwrap();
    assert_eq!(
        client
            .complete(
                request.id,
                Response::Observe(Err(failure(ProtocolErrorCode::OperationOutcomeUnknown)))
            )
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidResponse
    );
    let request = client.prepare_interface(&session, reference()).unwrap();
    assert_eq!(
        client
            .complete(
                request.id,
                Response::FetchInterface(Err(failure(ProtocolErrorCode::ValidatorMismatch)))
            )
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidResponse
    );
    ready(&mut client, &session);
    let request = call(&mut client, &session);
    let completion = client
        .complete(
            request.id,
            Response::CallOperation(Err(failure(ProtocolErrorCode::InterfaceMismatch))),
        )
        .unwrap();
    assert!(
        matches!(completion, Completion::Call(record) if matches!(record.outcome, CallOutcome::ProtocolFailure(_)))
    );
    assert_eq!(
        client.object(&session, "/scope/item").unwrap().state,
        ObservationState::Stale
    );
    assert_eq!(
        client.interface(&session, &reference()).unwrap().state,
        ObservationState::Stale
    );
 }
 #[test]
 fn mismatched_interactions_are_not_trusted_and_calls_remain_unknown() {
    let (mut client, session) = setup();
    let request = client.refresh_object(&session, "/scope/item").unwrap();
    assert_eq!(
        client
            .complete(request.id, Response::FetchInterface(Ok(interface(None))))
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidResponse
    );
    let request = client.prepare_interface(&session, reference()).unwrap();
    assert_eq!(
        client
            .complete(request.id, Response::Observe(Ok(object("item", None))))
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidResponse
    );
    ready(&mut client, &session);
    let request = call(&mut client, &session);
    let completion = client
        .complete(
            request.id,
            Response::Observe(Err(failure(ProtocolErrorCode::NotFound))),
        )
        .unwrap();
    assert!(
        matches!(completion, Completion::Call(record) if matches!(record.outcome, CallOutcome::Unknown { .. }))
    );
 }
 #[test]
 fn typed_stale_responses_cannot_replace_new_observations() {
    let (mut client, session) = setup();
    let old = client.refresh_object(&session, "/scope/item").unwrap();
    assert!(
        client
            .ensure_observed(&session, "/scope/item", 0)
            .unwrap()
            .is_none()
    );
    let new = client.refresh_object(&session, "/scope/item").unwrap();
    client
        .complete(new.id, Response::Observe(Ok(object("item", Some("new")))))
        .unwrap();
    assert_eq!(
        client
            .complete(old.id, Response::Observe(Ok(object("item", Some("old")))))
            .unwrap(),
        Completion::StaleResponseRejected(old.id)
    );
    assert_eq!(
        client
            .object(&session, "/scope/item")
            .unwrap()
            .object
            .unwrap()
            .r#ref
            .as_deref(),
        Some("new")
    );
 }
 #[test]
 fn scope_replacement_retires_descriptors_and_pending_fetch_but_not_call_snapshot() {
    let (mut client, session) = setup();
    observe(
        &mut client,
        &session,
        "/scope",
        object("scope", Some("old")),
    );
    ready(&mut client, &session);
    let call = call(&mut client, &session);
    let fetch = client.prepare_interface(&session, reference()).unwrap();
    observe(
        &mut client,
        &session,
        "/scope",
        object("scope", Some("new")),
    );
    assert!(
        client
            .interface(&session, &reference())
            .unwrap()
            .descriptor
            .is_none()
    );
    assert_eq!(
        client
            .complete(
                fetch.id,
                Response::FetchInterface(Ok(interface(Some("old"))))
            )
            .unwrap(),
        Completion::StaleResponseRejected(fetch.id)
    );
    assert_eq!(
        client.pending_call_context(call.id).unwrap().descriptor(),
        &descriptor()
    );
    assert_eq!(
        client
            .pending_call_context(call.id)
            .unwrap()
            .request()
            .interface
            .scope_ref,
        None
    );
    // A newer descriptor has a different return type; the prepared call still uses Integer.
    let fetch = client.prepare_interface(&session, reference()).unwrap();
    let mut next = interface(Some("new"));
    next.descriptor.operations[0].returns.r#type = TypeExpr::String;
    client
        .complete(fetch.id, Response::FetchInterface(Ok(next)))
        .unwrap();
    let completion = client
        .complete(
            call.id,
            Response::CallOperation(Ok(CallOperationResponse {
                result: Value::Integer(6),
                validator: None,
            })),
        )
        .unwrap();
    assert!(
        matches!(completion, Completion::Call(record) if matches!(record.outcome, CallOutcome::Success(_)))
    );
 }
 #[test]
 fn scope_not_found_retires_interfaces_and_late_fetch_cannot_restore_them() {
    let (mut client, session) = setup();
    ready(&mut client, &session);
    let old = client.prepare_interface(&session, reference()).unwrap();
    let missing = client.refresh_object(&session, "/scope").unwrap();
    client
        .complete(
            missing.id,
            Response::Observe(Err(failure(ProtocolErrorCode::NotFound))),
        )
        .unwrap();
    assert!(client.interface(&session, &reference()).is_none());
    assert_eq!(
        client
            .complete(old.id, Response::FetchInterface(Ok(interface(None))))
            .unwrap(),
        Completion::StaleResponseRejected(old.id)
    );
 }
 #[test]
 fn failures_before_and_after_dispatch_never_retry_operations() {
    let (mut client, session) = setup();
    ready(&mut client, &session);
    let before = call(&mut client, &session);
    assert!(
        matches!(client.fail_transport(before.id, "not handed to Host").unwrap(),
        Completion::Call(record) if matches!(record.outcome, CallOutcome::NotDispatched(_)))
    );
    assert_eq!(
        client.object(&session, "/scope/item").unwrap().state,
        ObservationState::Fresh
    );
    let after = call(&mut client, &session);
    client.mark_dispatched(after.id).unwrap();
    assert!(
        matches!(client.fail_dispatched_call(after.id, DispatchedTransportFailure::Timeout, "deadline").unwrap(),
        Completion::Call(record) if matches!(record.outcome, CallOutcome::Unknown { reason: OutcomeUnknownReason::Timeout, .. }))
    );
    assert_eq!(client.in_flight_len(), 0);
    assert!(
        client
            .ensure_observed(&session, "/scope/item", 0)
            .unwrap()
            .is_none()
    );
    ready(&mut client, &session);
    let unknown = call(&mut client, &session);
    assert!(
        matches!(client.complete(unknown.id, Response::CallOperation(Err(failure(ProtocolErrorCode::OperationOutcomeUnknown)))).unwrap(),
        Completion::Call(record) if matches!(record.outcome, CallOutcome::Unknown { reason: OutcomeUnknownReason::Protocol, .. }))
    );
    assert_eq!(client.in_flight_len(), 0);
    assert_eq!(client.call_history(&session).unwrap().len(), 3);
 }
 #[test]
 fn direct_limits_bound_sessions_inflight_cache_and_history() {
    let mut client = Client::new(ClientLimits::new(1, 1, 1, 1, 1).unwrap());
    let session = client
        .open_session("world", SecurityContext::new("alice"))
        .unwrap();
    assert_eq!(
        client
            .open_session("other", SecurityContext::new("alice"))
            .unwrap_err()
            .kind,
        ClientErrorKind::Capacity
    );
    let first = client.refresh_object(&session, "/scope/item").unwrap();
    assert!(
        client
            .ensure_observed(&session, "/scope/other", 0)
            .unwrap()
            .is_none()
    );
    assert_eq!(
        client
            .refresh_object(&session, "/scope/other")
            .unwrap_err()
            .kind,
        ClientErrorKind::Capacity
    );
    client
        .complete(first.id, Response::Observe(Ok(object("item", None))))
        .unwrap();
    observe(&mut client, &session, "/scope/other", object("other", None));
    assert_eq!(client.known_space(&session).unwrap().len(), 1);
    for _ in 0..3 {
        let request = client.refresh_object(&session, "/scope/other").unwrap();
        client
            .complete(request.id, Response::Observe(Ok(object("wrong", None))))
            .unwrap_err();
    }
    assert_eq!(client.diagnostics(&session).unwrap().len(), 1);
 }
 #[test]
 fn invalid_direct_requests_do_not_acquire_pending_state() {
    let (mut client, session) = setup();
    assert_eq!(
        client
            .refresh_object(&session, "not/absolute")
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidRequest
    );
    assert_eq!(
        client
            .prepare_interface(
                &session,
                InterfaceReference {
                    scope: "/".into(),
                    name: "".into()
                }
            )
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidRequest
    );
    assert_eq!(client.in_flight_len(), 0);
    assert!(client.known_space(&session).unwrap().is_empty());
 }
@@ -0,0 +1,289 @@
 #![cfg(feature = "http")]
 //! The same stateful scenario runs through direct DTOs and the HTTP facade.
 use std::collections::BTreeMap;
 use wip_client::direct::{Client as DirectClient, Request, Response};
 use wip_client::{
    CallOutcome, Client, ClientLimits, Completion, InterfaceObservation, ObjectObservation,
    RequestId, SecurityContext, SessionId,
 };
 use wip_http::{
    Limits, decode_call_operation_request, decode_fetch_interface_request, decode_observe_request,
    encode_call_operation_response, encode_fetch_interface_response, encode_observe_response,
    encode_protocol_error_response,
 };
 use wip_protocol::{
    CallOperationResponse, FetchInterfaceResponse, INTERFACE_FORMAT_V1, InterfaceDescriptor,
    InterfaceReference, Object, ObjectObservation as ProtocolObservation, OperationDeclaration,
    ProtocolError, ProtocolErrorCode, ProtocolInteraction, ReturnDeclaration, TypeExpr, Value,
 };
 fn limits() -> Limits {
    Limits::new(64 * 1024, 64 * 1024, 64).unwrap()
 }
 fn reference() -> InterfaceReference {
    InterfaceReference {
        scope: "/scope".into(),
        name: "math".into(),
    }
 }
 fn descriptor() -> InterfaceDescriptor {
    InterfaceDescriptor {
        format: INTERFACE_FORMAT_V1.into(),
        documentation: None,
        types: vec![],
        operations: vec![OperationDeclaration {
            name: "run".into(),
            documentation: None,
            parameters: vec![],
            returns: ReturnDeclaration {
                documentation: None,
                r#type: TypeExpr::Integer,
            },
        }],
    }
 }
 fn observation(name: &str, identity: &str) -> ProtocolObservation {
    ProtocolObservation {
        object: Object {
            name: name.into(),
            description: None,
            interfaces: vec![reference()],
            r#ref: Some(identity.into()),
            validator: None,
        },
        children: None,
    }
 }
 fn interface(identity: &str) -> FetchInterfaceResponse {
    FetchInterfaceResponse {
        interface: reference(),
        scope_ref: Some(identity.into()),
        validator: None,
        descriptor: descriptor(),
    }
 }
 enum Channel {
    Direct(DirectClient),
    Http(Client),
 }
 impl Channel {
    fn core(&self) -> &DirectClient {
        match self {
            Self::Direct(client) => client,
            Self::Http(client) => client,
        }
    }
    fn observe(&mut self, session: &SessionId, path: &str) -> (RequestId, Request) {
        match self {
            Self::Direct(client) => {
                let p = client.refresh_object(session, path).unwrap();
                (p.id, p.request)
            }
            Self::Http(client) => {
                let p = client.refresh_object(session, path).unwrap();
                (
                    p.id,
                    Request::Observe(decode_observe_request(p.request.body(), limits()).unwrap()),
                )
            }
        }
    }
    fn fetch(&mut self, session: &SessionId) -> (RequestId, Request) {
        match self {
            Self::Direct(client) => {
                let p = client.prepare_interface(session, reference()).unwrap();
                (p.id, p.request)
            }
            Self::Http(client) => {
                let p = client.prepare_interface(session, reference()).unwrap();
                (
                    p.id,
                    Request::FetchInterface(
                        decode_fetch_interface_request(p.request.body(), limits()).unwrap(),
                    ),
                )
            }
        }
    }
    fn call(&mut self, session: &SessionId) -> (RequestId, Request) {
        match self {
            Self::Direct(client) => {
                let p = client
                    .prepare_call(session, "/scope/item", &reference(), "run", BTreeMap::new())
                    .unwrap();
                client.mark_dispatched(p.id).unwrap();
                (p.id, p.request)
            }
            Self::Http(client) => {
                let p = client
                    .prepare_call(session, "/scope/item", &reference(), "run", BTreeMap::new())
                    .unwrap();
                client.mark_dispatched(p.id).unwrap();
                (
                    p.id,
                    Request::CallOperation(
                        decode_call_operation_request(p.request.body(), &descriptor(), limits())
                            .unwrap(),
                    ),
                )
            }
        }
    }
    fn complete(&mut self, pending: (RequestId, Request), result: Response) -> Completion {
        let (id, request) = pending;
        match self {
            Self::Direct(client) => client.complete(id, result).unwrap(),
            Self::Http(client) => {
                let wire = match (request, result) {
                    (Request::Observe(request), Response::Observe(Ok(value))) => {
                        encode_observe_response(&request, &value, limits())
                    }
                    (Request::FetchInterface(request), Response::FetchInterface(Ok(value))) => {
                        encode_fetch_interface_response(&request, &value, limits())
                    }
                    (Request::CallOperation(request), Response::CallOperation(Ok(value))) => {
                        encode_call_operation_response(&request, &descriptor(), &value, limits())
                    }
                    (_, Response::Observe(Err(error))) => encode_protocol_error_response(
                        ProtocolInteraction::Observe,
                        &error,
                        limits(),
                    ),
                    (_, Response::FetchInterface(Err(error))) => encode_protocol_error_response(
                        ProtocolInteraction::FetchInterface,
                        &error,
                        limits(),
                    ),
                    (_, Response::CallOperation(Err(error))) => encode_protocol_error_response(
                        ProtocolInteraction::CallOperation,
                        &error,
                        limits(),
                    ),
                    _ => panic!("test interaction mismatch"),
                }
                .unwrap();
                client.complete(id, wire).unwrap()
            }
        }
    }
 }
 #[derive(Debug, PartialEq)]
 struct Snapshot {
    objects: Vec<ObjectObservation>,
    interface: Option<InterfaceObservation>,
    outcomes: Vec<CallOutcome>,
    requests: Vec<Request>,
 }
 fn scenario(http: bool) -> Snapshot {
    let state_limits = ClientLimits::new(4, 16, 8, 8, 8).unwrap();
    let (mut channel, session) = if http {
        let mut client = Client::new(state_limits, limits());
        let session = client
            .open_session("https://example.test/wip", SecurityContext::new("alice"))
            .unwrap();
        (Channel::Http(client), session)
    } else {
        let mut client = DirectClient::new(state_limits);
        let session = client
            .open_session("local world", SecurityContext::new("alice"))
            .unwrap();
        (Channel::Direct(client), session)
    };
    let mut requests = vec![];
    for (path, name, identity) in [
        ("/scope", "scope", "scope-v1"),
        ("/scope/item", "item", "item-v1"),
    ] {
        let p = channel.observe(&session, path);
        requests.push(p.1.clone());
        channel.complete(p, Response::Observe(Ok(observation(name, identity))));
    }
    let p = channel.fetch(&session);
    requests.push(p.1.clone());
    channel.complete(p, Response::FetchInterface(Ok(interface("scope-v1"))));
    let p = channel.call(&session);
    requests.push(p.1.clone());
    channel.complete(
        p,
        Response::CallOperation(Ok(CallOperationResponse {
            result: Value::Integer(42),
            validator: Some(vec![2]),
        })),
    );
    let p = channel.call(&session);
    requests.push(p.1.clone());
    channel.complete(
        p,
        Response::CallOperation(Err(ProtocolError {
            code: ProtocolErrorCode::InterfaceMismatch,
            message: "changed".into(),
        })),
    );
    let p = channel.observe(&session, "/scope/item");
    channel.complete(p, Response::Observe(Ok(observation("item", "item-v1"))));
    let p = channel.fetch(&session);
    channel.complete(p, Response::FetchInterface(Ok(interface("scope-v1"))));
    let old = channel.fetch(&session);
    let p = channel.observe(&session, "/scope");
    channel.complete(p, Response::Observe(Ok(observation("scope", "scope-v2"))));
    let old_id = old.0;
    assert_eq!(
        channel.complete(old, Response::FetchInterface(Ok(interface("scope-v1")))),
        Completion::StaleResponseRejected(old_id)
    );
    let p = channel.fetch(&session);
    channel.complete(p, Response::FetchInterface(Ok(interface("scope-v2"))));
    let p = channel.call(&session);
    requests.push(p.1.clone());
    channel.complete(
        p,
        Response::CallOperation(Err(ProtocolError {
            code: ProtocolErrorCode::OperationOutcomeUnknown,
            message: "unknown".into(),
        })),
    );
    assert_eq!(channel.core().in_flight_len(), 0);
    Snapshot {
        objects: channel.core().known_space(&session).unwrap(),
        interface: channel.core().interface(&session, &reference()).cloned(),
        outcomes: channel
            .core()
            .call_history(&session)
            .unwrap()
            .iter()
            .map(|record| record.outcome.clone())
            .collect(),
        requests,
    }
 }
 #[test]
 fn direct_and_http_agree_on_requests_state_calls_scope_invalidation_and_uncertainty() {
    assert_eq!(scenario(false), scenario(true));
 }
 #[test]
 fn http_endpoint_and_identical_direct_identity_do_not_share_cache() {
    let mut client = Client::new(ClientLimits::new(4, 16, 8, 8, 8).unwrap(), limits());
    let http = client
        .open_session("https://example.test/wip", SecurityContext::new("alice"))
        .unwrap();
    let direct = DirectClient::open_session(
        &mut client,
        "https://example.test/wip/",
        SecurityContext::new("alice"),
    )
    .unwrap();
    assert_ne!(http, direct);
    let request = DirectClient::refresh_object(&mut client, &direct, "/scope").unwrap();
    DirectClient::complete(
        &mut client,
        request.id,
        Response::Observe(Ok(observation("scope", "local"))),
    )
    .unwrap();
    assert!(client.object(&http, "/scope").is_none());
    assert!(client.refresh_object(&direct, "/scope").is_err());
 }
@@ -0,0 +1,128 @@
 #![cfg(feature = "http")]
 //! Wire budgets are adapter-only and failed encoding must not acquire state.
 use std::collections::BTreeMap;
 use wip_client::{Client, ClientErrorKind, ClientLimits, ObservationState, SecurityContext};
 use wip_http::{Limits, encode_fetch_interface_response, encode_observe_response};
 use wip_protocol::{
    FetchInterfaceRequest, FetchInterfaceResponse, INTERFACE_FORMAT_V1, InterfaceDescriptor,
    InterfaceReference, Object, ObjectObservation, ObserveRequest, OperationDeclaration,
    ReturnDeclaration, TypeExpr,
 };
 fn state_limits() -> ClientLimits {
    ClientLimits::new(2, 8, 8, 8, 8).unwrap()
 }
 #[test]
 fn request_encoding_failure_leaves_retrieval_cache_and_inflight_unchanged() {
    let mut client = Client::new(state_limits(), Limits::new(1, 4096, 32).unwrap());
    let session = client
        .open_session("https://example.test/wip", SecurityContext::new("alice"))
        .unwrap();
    assert_eq!(
        client.refresh_object(&session, "/item").unwrap_err().kind,
        ClientErrorKind::InvalidRequest
    );
    let reference = InterfaceReference {
        scope: "/".into(),
        name: "test".into(),
    };
    assert_eq!(
        client
            .prepare_interface(&session, reference.clone())
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidRequest
    );
    assert!(client.object(&session, "/item").is_none());
    assert!(client.interface(&session, &reference).is_none());
    assert_eq!(client.in_flight_len(), 0);
 }
 #[test]
 fn call_encoding_failure_keeps_fresh_observations_and_no_pending_call() {
    let limits = Limits::new(80, 4096, 32).unwrap();
    let mut client = Client::new(state_limits(), limits);
    let session = client
        .open_session("https://example.test/wip", SecurityContext::new("alice"))
        .unwrap();
    let reference = InterfaceReference {
        scope: "/".into(),
        name: "test".into(),
    };
    let observe = client.refresh_object(&session, "/item").unwrap();
    client
        .complete(
            observe.id,
            encode_observe_response(
                &ObserveRequest {
                    path: "/item".into(),
                    depth: 0,
                },
                &ObjectObservation {
                    object: Object {
                        name: "item".into(),
                        description: None,
                        interfaces: vec![reference.clone()],
                        r#ref: None,
                        validator: None,
                    },
                    children: None,
                },
                limits,
            )
            .unwrap(),
        )
        .unwrap();
    let fetch = client
        .prepare_interface(&session, reference.clone())
        .unwrap();
    client
        .complete(
            fetch.id,
            encode_fetch_interface_response(
                &FetchInterfaceRequest {
                    interface: reference.clone(),
                },
                &FetchInterfaceResponse {
                    interface: reference.clone(),
                    scope_ref: None,
                    validator: None,
                    descriptor: InterfaceDescriptor {
                        format: INTERFACE_FORMAT_V1.into(),
                        documentation: None,
                        types: vec![],
                        operations: vec![OperationDeclaration {
                            name: "run".into(),
                            documentation: None,
                            parameters: vec![],
                            returns: ReturnDeclaration {
                                documentation: None,
                                r#type: TypeExpr::Integer,
                            },
                        }],
                    },
                },
                limits,
            )
            .unwrap(),
        )
        .unwrap();
    assert_eq!(
        client
            .prepare_call(&session, "/item", &reference, "run", BTreeMap::new())
            .unwrap_err()
            .kind,
        ClientErrorKind::InvalidRequest
    );
    assert_eq!(
        client.object(&session, "/item").unwrap().state,
        ObservationState::Fresh
    );
    assert_eq!(
        client.interface(&session, &reference).unwrap().state,
        ObservationState::Fresh
    );
    assert!(client.call_history(&session).unwrap().is_empty());
    assert_eq!(client.in_flight_len(), 0);
 }
@@ -1,19 +1,21 @@
 [package]
 name = "wip-fs-server"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
-description = "Request-time filesystem projection server for WIP over HTTPS"
+rust-version.workspace = true
-license = "MIT OR Apache-2.0"
+description = "Extensible request-time filesystem projection library and WIP over HTTP server"
 license.workspace = true
 repository.workspace = true
 readme = "README.md"
 publish = false
 [dependencies]
 http = "1"
 rustix = { version = "1.1", features = ["fs"] }
-wip-host = { path = "../wip-host" }
+wip-host.workspace = true
-wip-https = { path = "../wip-https" }
+wip-http.workspace = true
-wip-interface = { path = "../wip-interface" }
+wip-interface.workspace = true
-wip-protocol = { path = "../wip-protocol" }
+wip-protocol.workspace = true
 [dev-dependencies]
 tempfile = "3"
@@ -3,8 +3,171 @@
 `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,
+operation dispatch and uses the standard `wip-http` routes, JSON codecs,
-envelopes, batching, and HTTP status mapping.
+envelopes, and HTTP status mapping.
 ## Library assembly and migration
 `ServerConfig`, `WipFsServer::new`, `handle_http` and CLI flags retain their
 assembly shape. The scoped Host/Protocol API is a breaking Rust/wire migration:
 Interface references are `{scope, name}` values, registration takes a `Scope`
 and local name, and calls use `interface.reference` plus optional `scope_ref`.
 Fetch returns the same structured reference and current scope Object's optional
 ref. This is the standard WIP wire format, not an FS-specific profile.
 Use `default_projection(root, access, limits)` to obtain the default Linux engine
 without starting a listener. `projection.view(&principal)` is the effective view;
 it owns canonical `observe` and `fetch_interface` and implements the standard
 `wip_host::ObjectProvider` typed `call_operation` API. `DefaultPolicy` has the unit
 principal `()`; default engines also offer unit-principal convenience methods.
 For an external backend/composition:
 1. Implement `BackendEntry` on a local, cloneable, root-confined stable capability.
   Its `WipObject` metadata is public-only; its validator binds identity and the
   protected state. Implement `FilesystemBackend` to resolve one connected
   `ResolvedEntry<Entry>` (root-to-parent ancestry plus pinned target), enumerate
   bounded children, and execute against that already-resolved lineage.
 2. Create `wip_host::Scope::new("/")` for the deployment-pinned root, then
   register generated definitions with `registry.register(&scope, name,
   Definition, validator)`. `DefaultInterfaces::register(&mut registry, &scope)`
   optionally supplies reusable built-in tokens named `file.read`,
   `symlink.inspect`, and `file.write`; tokens do not force publication. For a
   non-root scope, create a handle at its canonical WIP path and implement
   `Composition::scope(path, &entry, context)` to attest that handle only for
   its current Object lifetime. Local names are exact names, not parsed `::`/`#`
   display strings; the same local name can be registered at different scopes.
 3. Implement `Composition<Entry>` on a local type. Its local Object wraps the entry
   and implements both `WipObject` and the chosen generated traits, avoiding orphan
   rules. `PublishedObject::expose` proves each implementation at compile time.
   Publication can add, replace, reorder or omit built-ins based on entry metadata
   and actual backend capabilities, not just entry kind. `LinuxEntry` implements
   bounded `FileRead`, `FileWrite` and `SymlinkInspect` for safe delegation; never
   advertise write in read-only mode or link operations on a non-link capability.
 4. Assemble `Projection::new(backend, registry, composition, policy, limits)`.
   `ProjectionPolicy` supplies an opaque associated `Principal`, hides Objects and
   entire hidden subtrees, selects an ordered subset of implemented interfaces,
   controls descriptor/operation visibility, and permits or denies execution.
 5. An authenticated deployment chooses the principal and `ExecutionContext`. To
   use HTTP, construct `HttpAdapter::new(&view, &endpoint, limits)` and invoke
   `handle_http_with_context`. This uses the standard `wip-http` binding, not a
   filesystem wire profile. Enforce body collection, header, concurrency and
   deadline bounds in the deployment's listener; the adapter owns none of these
   intake resources. The bundled loopback listener remains a thin default user.
 A complete external-style memory backend, local Object with multiple custom
 Operations, typed registration, principal policy and HTTP flow is exercised in
 [`tests/extensions.rs`](tests/extensions.rs). It uses no Linux filesystem for its
 backend. The public library APIs do not require private types, a fork, an HTTP
 listener, a global object registry, or dynamic plugin loading.
 ### Extension security contract
 Backend implementations and Operation authors are trusted code, not sandboxed
 plugins. `FilesystemBackend::resolve` returns `ResolvedEntry::new(ancestors, target)`
 from one connected backend traversal/snapshot, not independent path-prefix
 resolutions. A root target has no ancestors; other targets retain the root first,
 then intermediate parent containers. This is backend-private context, never wire
 metadata. Backend `resolve` and `execute` signatures both carry this type;
 compositions receive exact retained entries, including publication of the root
 scope Object while another target is executing, never independent raw-path
 lookups. Root publication must be deterministic and side-effect-free.
 Every lineage must retain the same deployment-pinned root Object. Replacing that
 Object requires a new projection and fresh `Scope`, not reuse of registrations
 at the same path. The engine constructs `ScopeObservation` from the published
 root Object's metadata using the refreshed retained root capability **inside**
 `FilesystemBackend::execute`, then attaches it with `PublishedObject::bind_scope`.
 It never independently looks up the raw configured root path. Root Objects need
 not expose any interfaces. Calls check both the private lifetime and optional
 `scope_ref`; normal root state updates do not retire the lifetime.
 `Composition::scope` is the trusted non-root lifetime attestation hook. It runs
 only for registered scope paths in the refreshed, principal-visible execution
 lineage, never through independent scope-path resolution. Return `Some(scope)`
 only when the retained entry is still the current Object published at that path;
 use retained backend identity and application publication-lifecycle state under
 the backend boundary, not ref or validator equality. Deletion, replacement or
 movement needs a fresh handle and registration, even if a ref is absent or reused.
 Ordinary state changes retain the handle. A different returned path is an internal
 publication failure; `None` or a fresh unregistered lifetime hides old artifacts.
 The default hook returns `None`, so existing compositions fail closed outside `/`.
 Self-scope needs special care: a backend may allow ordinary execution against an
 unlinked/replaced pinned leaf, but that does not establish that leaf as the current
 scope Object. The hook must attest current membership as well as retained identity
 within the same boundary. The default Linux composition does not attest non-root
 lifetimes or invent inode-based Object refs. External compositions must provide
 that guarantee themselves, including their documented external-writer limits.
 Scope metadata is obtained by publishing that retained entry (reusing the target
 publication for self-scope); scope Objects need not expose interfaces. Optional
 refs are taken from the published Object, not from a raw backend entry. Calls
 without `scope_ref` remain valid when the lifetime is current; supplied stale refs
 reject with `InterfaceMismatch` after Object validator checks.
 `with_object` (including fetch) and individual tree Object publications also
 enter this backend boundary. Generic read callbacks use a `NotStarted` attempt
 as an adapter to the existing execution API; no typed operation runs and no
 commit is implied. Tree observations are bounded traversals, not one global tree
 transaction. Fetch resolves the visible scope Object through the provider and
 returns its ref, Descriptor and Interface validator together; retained registry
 artifacts alone never establish publication.
 `FilesystemBackend::execute` must validate ancestor membership/identity and
 refresh **all** lineage state/validators inside its transaction or lock before
 calling the engine callback, retaining the same target and connected ancestry
 through validation and dispatch. Replaced/detached ancestors must return
 `NotFound` without callback invocation, even when the replacement is visible.
 The engine evaluates Object visibility for every refreshed ancestor and target
 inside that same boundary; a hidden ancestor rejects the entire subtree before
 publication/typed dispatch. Never fix a changed lineage by resolving the raw path
 again and substituting capabilities. Participating policy-relevant backend state
 changes must be serialized by this boundary, not just target-content writes.
 Return the committed post-operation validator. Retained ancestry is subject to
 handle/work ceilings; resource exhaustion is an error, not missing ancestry.
 Confirm rollback only after rollback succeeds. Pre-dispatch failures
 must never commit; failed started operations without a non-commit guarantee remain
 `OperationOutcomeUnknown`. Object implementations must delegate validators to
 that entry and declare requirements per `(InterfaceRef, operation)`, rather than
 classify all operations by a read/write name. Operations use the scoped entry and
 propagated context, not a fresh raw-path resolution; they must check deadlines,
 cancellation and resource budgets throughout backend work and report effects
 truthfully. POSIX symlinks, identity, atomic mutations and locking cannot be assumed
 for other backends.
 The default Linux backend acquires advisory exclusive locks in root-to-parent
 order and then on the lockable target (directory or regular file). It compares
 retained ancestor identity to no-follow descriptor-relative lookup results,
 refreshes lineage snapshots after acquiring the locks, and holds the guards
 through post-dispatch state observation. The configured root remains its pinned
 capability even if its textual path is renamed; replaced intermediate ancestors
 are rejected. Leaf path replacement never redirects execution to a new inode.
 This serializes cooperating library calls; it does **not** promise transactional
 isolation from unrelated processes ignoring `flock`. Linux capabilities only
 expose bounded methods, not raw descriptors or backend paths.
 A policy must be stable/deterministic within one effective Worldspace view.
 Interface/operation visibility is uniform per registered reference within that
 view, so observation, fetch and dispatch use the identical filtered descriptor.
 For entry-specific operation sets, register distinct interface definitions and
 select them by entry. Different principals may have different effective views.
 Changing a policy must establish a new view/reference lifetime (e.g. rebuild the
 registry/engine); do not keep validator-free references while changing their
 meaning. Execution permission may deny a visible Operation without hiding it.
 A published interface is always fetchable by that principal; hidden operations
 are omitted (along with their unreachable named types and interface-wide docs)
 and guessed calls return `OperationNotFound`, whereas visible denied
 operations return `PermissionDenied`. Hidden Objects and descendants return
 `NotFound` and are absent from parent observations. Work spent scanning hidden
 entries still counts against traversal bounds; resource limits are not a
 constant-time/side-channel guarantee.
 Never put absolute paths, hidden metadata, credentials or policy internals in
 public `WipObject` metadata, descriptions, validators or normal logs. Validators
 must be opaque public tokens, not confidential content. Engine/HTTP failures use
 bounded generic diagnostics; arbitrary trusted implementation metadata/logging
 cannot be sanitized automatically. Do not log credentials or sensitive panic
 payloads from extensions.
 ## Security model
@@ -28,9 +191,9 @@ envelopes, batching, and HTTP status mapping.
 - 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
+- The built-in HTTP listener is loopback-only. TLS termination, certificates,
-  must pass `--behind-tls-proxy` and terminate HTTPS at a trusted reverse proxy.
+  authentication, an externally visible URL scheme, and proxy routing are
-  Plain development HTTP requires the explicit `--development-http` flag.
+  deployment concerns rather than separate WIP transport profiles.
 The implementation currently targets Linux because it uses `O_PATH`,
 directory-relative descriptor traversal, and `/proc/self/fd` to reopen the same
@@ -38,59 +201,61 @@ pinned backend object without resolving the untrusted Worldspace path twice.
 ## Run
-Read-only behind a TLS-terminating reverse proxy:
+Run the loopback listener in read-only mode:
 ```console
 cargo run -p wip-fs-server -- \
  --root /srv/public-files \
-  --listen 127.0.0.1:8443 \
+  --listen 127.0.0.1:8080 \
-  --base-path /wip \
+  --base-path /wip
  --behind-tls-proxy
 ```
-Local development with the write capability deliberately enabled:
+Run 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
+The server reports the effective root, `ReadOnly`/`ReadWrite` mode, endpoint,
-mode, endpoint, and actual listen address. It does not enumerate the root.
+and actual listen address. It does not enumerate the root.
 ## Standard interactions
-The following examples use development HTTP for readability. The JSON is the
+The following examples use the built-in HTTP listener. The JSON follows the
-standard `wip-https` profile; validators and operation `Bytes` are base64 body
+standard WIP over HTTP binding; validators and operation `Bytes` are base64 body
 fields, never `ETag` or `If-Match` headers.
-Fetch root:
+Observe only the root Object:
 ```console
-curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch \
+curl -sS -X POST http://127.0.0.1:8080/wip/v1/observe \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
-  --data '{"path":"/"}'
+  --data '{"path":"/","depth":0}'
 ```
-Fetch a bounded tree (the root counts toward `limit`):
+Observe the root and two levels of indexable children:
 ```console
-curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch_tree \
+curl -sS -X POST http://127.0.0.1:8080/wip/v1/observe \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
-  --data '{"path":"/","depth":2,"limit":100}'
+  --data '{"path":"/","depth":2}'
 ```
-A regular-file fetch returns the opaque read interface reference and an object
+A regular-file observation returns a structured read interface reference and an
-validator. Retrieve that descriptor with:
+object validator. Built-ins explicitly use scope `/` and the local names
 `file.read`, `symlink.inspect`, and `file.write`. The Linux root does not issue an
 Object ref, so fetch omits `scope_ref`; its private publication lifetime still
 binds fetch and call to the pinned deployment root. Copy the complete reference
 from the observation to retrieve that descriptor:
 ```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>"}'
+  --data '{"interface":{"scope":"/","name":"file.read"}}'
 ```
 Then call a bounded range read:
@@ -100,7 +265,7 @@ 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>"},
+    "interface":{"reference":{"scope":"/","name":"file.read"}},
    "operation":"read",
    "arguments":{"offset":0,"length":4096}
  }'
@@ -114,31 +279,27 @@ 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>"},
+    "interface":{"reference":{"scope":"/","name":"file.write"}},
    "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,
+nesting, file read/write bytes, tree depth/node count, pinned handles, and active
-and active connections/requests. One absolute request deadline covers header and
+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
+contended lock to stall a worker. Object observation recursively opens only the
-requested entries. Once a limit or depth boundary is reached it reads only far
+requested depth. A successful response is complete through that depth; if the
-enough to
+configured projected-node budget would be exceeded, the interaction fails with
-prove whether an additional visible child exists, so `truncated` is true only
+`ResourceLimitExceeded` instead of returning a partial observation. I/O failure
-when something was actually omitted. I/O failure and cancellation remain errors,
+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
@@ -0,0 +1,155 @@
 //! Reusable default Linux composition; no listener or authentication dependency.
 use crate::engine::{BackendEntry, Composition, DefaultPolicy, EntryKind, Projection};
 use crate::interfaces::{
    FileRead, FileReadDefinition, FileWrite, FileWriteDefinition, SymlinkInspect,
    SymlinkInspectDefinition,
 };
 use crate::projection::{LinuxBackend, LinuxEntry};
 use crate::{AccessMode, ResourceLimits};
 use wip_host::{
    ExecutionContext, HostError, InterfaceRef, InterfaceRegistry, PublishedObject,
    RegisteredInterface, RegistrationError, Scope, Validator, WipObject,
 };
 use wip_interface as wip;
 /// Registered built-in interfaces, usable by external compositions and Objects.
 pub struct DefaultInterfaces {
    /// Bounded regular-file reads.
    pub read: RegisteredInterface<FileReadDefinition>,
    /// No-follow link inspection.
    pub symlink: RegisteredInterface<SymlinkInspectDefinition>,
    /// Validator-protected replacement.
    pub write: RegisteredInterface<FileWriteDefinition>,
 }
 impl DefaultInterfaces {
    /// Register reusable descriptors at an explicit publication scope.
    ///
    /// Built-in local names are `file.read`, `symlink.inspect`, and `file.write`.
    /// The default deployment registers them at `/`; external compositions may
    /// register them at non-root scopes attested by `Composition::scope`.
    pub fn register(
        registry: &mut InterfaceRegistry,
        scope: &Scope,
    ) -> Result<Self, RegistrationError> {
        Ok(Self {
            read: registry.register(scope, "file.read", FileReadDefinition, None)?,
            symlink: registry.register(scope, "symlink.inspect", SymlinkInspectDefinition, None)?,
            write: registry.register(scope, "file.write", FileWriteDefinition, None)?,
        })
    }
 }
 /// Default capability-aware Linux publication, independent of HTTP.
 pub struct DefaultComposition {
    interfaces: DefaultInterfaces,
 }
 impl DefaultComposition {
    /// Use previously registered built-in interface tokens.
    pub fn new(interfaces: DefaultInterfaces) -> Self {
        Self { interfaces }
    }
 }
 /// Request-scoped default Object; external Objects may instead wrap `LinuxEntry`.
 pub struct DefaultObject {
    entry: LinuxEntry,
    write: InterfaceRef,
 }
 impl DefaultObject {
    /// The pinned, bounded capability used by every operation on this Object.
    pub fn entry(&self) -> &LinuxEntry {
        &self.entry
    }
 }
 impl WipObject for DefaultObject {
    fn name(&self) -> &str {
        self.entry.name()
    }
    fn description(&self) -> Option<&str> {
        self.entry.description()
    }
    fn reference(&self) -> Option<&str> {
        self.entry.reference()
    }
    fn validator(&self) -> Option<&Validator> {
        self.entry.validator()
    }
    fn requires_validator(&self, interface: &InterfaceRef, operation: &str) -> bool {
        interface == &self.write && operation == "replace"
    }
 }
 impl FileRead for DefaultObject {
    fn read(&self, offset: Option<u64>, length: Option<u64>) -> wip::OperationResult<wip::Bytes> {
        self.entry.read(offset, length)
    }
 }
 impl SymlinkInspect for DefaultObject {
    fn read_link(&self) -> wip::OperationResult<wip::Bytes> {
        self.entry.read_link()
    }
 }
 impl FileWrite for DefaultObject {
    fn replace(&self, contents: wip::Bytes) -> wip::OperationResult<()> {
        self.entry.replace(contents)
    }
 }
 impl Composition<LinuxEntry> for DefaultComposition {
    type Object = DefaultObject;
    fn publish(
        &self,
        entry: LinuxEntry,
        _: &ExecutionContext,
    ) -> Result<PublishedObject<Self::Object>, HostError> {
        let kind = entry.kind();
        let writable = entry.access_mode() == AccessMode::ReadWrite;
        let mut publication = PublishedObject::new(DefaultObject {
            entry,
            write: self.interfaces.write.reference().clone(),
        });
        match kind {
            EntryKind::Regular => {
                publication = publication
                    .expose(&self.interfaces.read)
                    .map_err(publication_error)?;
                if writable {
                    publication = publication
                        .expose(&self.interfaces.write)
                        .map_err(publication_error)?;
                }
            }
            EntryKind::Symlink => {
                publication = publication
                    .expose(&self.interfaces.symlink)
                    .map_err(publication_error)?;
            }
            EntryKind::Directory | EntryKind::Unsupported => {}
        }
        Ok(publication)
    }
 }
 fn publication_error(_: wip_host::PublicationError) -> HostError {
    HostError::internal(
        "default publication failed",
        wip_host::EffectGuarantee::NotCommitted,
    )
 }
 /// Construct the secure-by-default Linux engine without binding a listener.
 pub fn default_projection(
    root: &std::path::Path,
    access: AccessMode,
    limits: ResourceLimits,
 ) -> Result<Projection<LinuxBackend, DefaultComposition, DefaultPolicy>, std::io::Error> {
    let backend = LinuxBackend::open(root, access, limits)?;
    let mut registry = InterfaceRegistry::new();
    let scope = Scope::new("/").map_err(std::io::Error::other)?;
    let interfaces =
        DefaultInterfaces::register(&mut registry, &scope).map_err(std::io::Error::other)?;
    Ok(Projection::new(
        backend,
        registry,
        DefaultComposition::new(interfaces),
        DefaultPolicy,
        limits,
    ))
 }
@@ -0,0 +1,831 @@
 //! Transport-independent projection, publication, and principal view boundaries.
 use crate::ResourceLimits;
 use wip_host::{
    EffectGuarantee, ExecutionContext, HostError, InterfaceRef, InterfaceRegistry, ObjectProvider,
    OperationAttempt, ProviderResult, PublishedObject, Scope, ScopeObservation, WipObject,
 };
 use wip_protocol::{
    FetchInterfaceRequest, FetchInterfaceResponse, ObjectObservation, ObserveRequest,
    ObserveResponse, ProtocolError, ProtocolErrorCode,
 };
 /// Portable entry classification; capabilities must not be inferred from kind alone.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum EntryKind {
    /// Container whose children can be enumerated.
    Directory,
    /// Regular data entry.
    Regular,
    /// Link itself, never implicitly followed.
    Symlink,
    /// Metadata-only entry unless the composition supplies a capability.
    Unsupported,
 }
 /// A root-confined, request-time capability, not a path to resolve again.
 ///
 /// Metadata must be safe for public exposure. Validators bind both identity and
 /// protected state. Cloning must retain the same target rather than re-resolve it.
 pub trait BackendEntry: WipObject + Clone {
    /// Classification for observation and publication selection.
    fn kind(&self) -> EntryKind;
 }
 /// A single resolved target together with its retained root-to-parent lineage.
 ///
 /// The backend must resolve a connected lineage, never independent raw-path
 /// prefixes. At execution it validates ancestor membership/identity, refreshes
 /// their policy metadata, and pins that snapshot through dispatch. Target
 /// replacement must not redirect the original capability. This value is private
 /// backend context, not protocol metadata.
 #[derive(Clone)]
 pub struct ResolvedEntry<E> {
    ancestors: Vec<E>,
    target: E,
 }
 impl<E> ResolvedEntry<E> {
    /// Create backend resolution context. `/` has no ancestors; a non-root target
    /// has the pinned root first, followed by its intermediate parent containers.
    pub fn new(ancestors: Vec<E>, target: E) -> Self {
        Self { ancestors, target }
    }
    /// Pinned ancestor capabilities, ordered from the root to the direct parent.
    pub fn ancestors(&self) -> &[E] {
        &self.ancestors
    }
    /// The original resolved target capability, never a redirected replacement.
    pub fn target(&self) -> &E {
        &self.target
    }
    /// Consume this snapshot for refresh or request-time publication.
    pub fn into_parts(self) -> (Vec<E>, E) {
        (self.ancestors, self.target)
    }
 }
 /// Trusted backend boundary. Implementations need not use POSIX semantics.
 ///
 /// Resolve and enumerate pinned capabilities within the configured root. Enforce
 /// context cancellation, deadlines and work budgets during backend work. Do not
 /// advertise capabilities the backend cannot guarantee. Errors must not include
 /// backend paths, credentials or hidden metadata.
 ///
 /// The root is a deployment-pinned Object: every resolution/execution lineage
 /// must retain that same root, even if its textual backend path is renamed or
 /// replaced. Replacing the deployment root requires a new projection and Scope
 /// lifetime. The engine binds `/` to this pinned deployment root. Non-root
 /// lifetimes are attested by [`Composition::scope`] from the refreshed lineage.
 ///
 /// `execute` must retain the same target and complete lineage and serialize
 /// ancestor identity/membership checks, policy metadata, validator observation,
 /// publication, validation, typed dispatch and commit/rollback. Changed/detached
 /// ancestors must return `NotFound` before the callback; never substitute a new
 /// ancestor or redirect the target by re-resolving its raw path. Refresh *all*
 /// lineage metadata/validators inside the boundary and retain that snapshot
 /// through dispatch, then return the committed post-operation validator. Never
 /// upgrade an unknown outcome except after confirmed rollback. Locks only protect
 /// actors participating in the protocol; document any external-writer limits.
 pub trait FilesystemBackend {
    /// Stable capability supplied to the composition.
    type Entry: BackendEntry;
    /// Resolve a canonical WIP path and retain its connected ancestry.
    ///
    /// Obtain the target and lineage in one backend traversal/snapshot. Enforce
    /// configured handle/work budgets while retaining ancestors; do not silently
    /// omit ancestry on resource exhaustion.
    fn resolve(
        &self,
        context: &ExecutionContext,
        path: &str,
    ) -> ProviderResult<ResolvedEntry<Self::Entry>>;
    /// Enumerate direct children, at most `maximum`; excess must fail, not truncate.
    fn children(
        &self,
        context: &ExecutionContext,
        entry: &Self::Entry,
        maximum: usize,
    ) -> Result<Vec<Self::Entry>, HostError>;
    /// Execute against this already-resolved target within an atomic boundary.
    fn execute(
        &self,
        context: &ExecutionContext,
        entry: ResolvedEntry<Self::Entry>,
        operation: impl FnOnce(ResolvedEntry<Self::Entry>) -> OperationAttempt,
    ) -> ProviderResult<OperationAttempt>;
 }
 /// Typed publication extension point, implementable on an external crate's type.
 ///
 /// Use `InterfaceRegistry::register` and `PublishedObject::expose` with generated
 /// definitions. An external local Object can wrap the entry and implement any
 /// number of interfaces, avoiding orphan rules. Its `WipObject` implementation
 /// declares validator requirements per qualified operation. Operation failures
 /// declare their own `EffectGuarantee`, not a fixed read/write classification.
 pub trait Composition<E: BackendEntry> {
    /// Local typed operation implementation and safe public metadata.
    type Object: WipObject;
    /// Attest the current non-root scope lifetime of this exact backend entry.
    ///
    /// Called only within `FilesystemBackend::execute`, for refreshed entries in
    /// its connected lineage. Return the same handle used for registration only
    /// while this same Object remains published at `path`. After deletion,
    /// replacement or movement return `None` or a fresh Scope, even without an
    /// Object ref (or when the replacement reuses that ref). Ordinary state
    /// changes retain the handle. In particular a self-scope target must still
    /// be the current member at `path`: a backend's ordinary pinned-leaf guarantee
    /// alone may allow execution after leaf replacement and is not sufficient
    /// evidence for a scope lifetime. Do not re-resolve `path` or infer lifetime from
    /// a validator/ref alone: use the entry's retained backend identity and the
    /// application's publication lifecycle, serialized by the backend boundary.
    ///
    /// The default attests no non-root scopes. The deployment-pinned root is
    /// bound automatically; this hook is not called for `/`. Returning a Scope
    /// for a different path is an internal publication error. A scope Object
    /// need not expose any interfaces and its public ref remains optional.
    fn scope(
        &self,
        _path: &str,
        _entry: &E,
        _context: &ExecutionContext,
    ) -> Result<Option<Scope>, HostError> {
        Ok(None)
    }
    /// Build a request-scoped publication using this exact capability/context.
    ///
    /// Publication and policy hooks must be side-effect-free with respect to the
    /// backend. This hook may also publish retained scope ancestors to observe
    /// their metadata while another target is executing. Scope publication must
    /// be deterministic within the view and use this same retained capability.
    /// A publication failure is a pre-dispatch rejection, never a
    /// started Operation. Delegate metadata/validators to the boundary snapshot.
    fn publish(
        &self,
        entry: E,
        context: &ExecutionContext,
    ) -> Result<PublishedObject<Self::Object>, HostError>;
 }
 /// Principal-specific view policy, independent of authentication transport.
 ///
 /// Keep decisions deterministic and stable within an effective Worldspace view.
 /// A changed policy requires a new view/reference lifetime (or interface
 /// validators). Operation visibility is interface-wide within a view so every
 /// published reference has exactly the descriptor returned by fetch. Entry-
 /// specific differences should select different registered interfaces. Hooks
 /// cannot add implementations, metadata, or raw paths to a publication.
 pub trait ProjectionPolicy<E: BackendEntry, O: WipObject> {
    /// Opaque deployment-established principal/request identity.
    type Principal;
    /// Whether the entry is visible. Invisible ancestors hide their whole subtree.
    fn object_visible(&self, principal: &Self::Principal, entry: &E) -> bool;
    /// Whether an interface descriptor may be fetched in this view.
    fn interface_visible(&self, _principal: &Self::Principal, _interface: &InterfaceRef) -> bool {
        true
    }
    /// Select/order a subset of implemented interfaces; defaults to all.
    fn interfaces(
        &self,
        _principal: &Self::Principal,
        _entry: &E,
        available: &[InterfaceRef],
    ) -> Vec<InterfaceRef> {
        available.to_vec()
    }
    /// Whether an operation is present in this view's descriptor and dispatch.
    fn operation_visible(
        &self,
        _principal: &Self::Principal,
        _interface: &InterfaceRef,
        _operation: &str,
    ) -> bool {
        true
    }
    /// Execution permission for a visible operation, after canonical preconditions.
    fn authorize(
        &self,
        _principal: &Self::Principal,
        _object: &O,
        _interface: &InterfaceRef,
        _operation: &str,
    ) -> bool {
        true
    }
 }
 /// No authentication assumption: all configured objects/operations are visible.
 pub struct DefaultPolicy;
 impl<E: BackendEntry, O: WipObject> ProjectionPolicy<E, O> for DefaultPolicy {
    type Principal = ();
    fn object_visible(&self, _: &(), _: &E) -> bool {
        true
    }
 }
 /// Canonical request-time engine, independent of HTTP and Linux.
 pub struct Projection<B, C, P> {
    backend: B,
    registry: InterfaceRegistry,
    composition: C,
    policy: P,
    limits: ResourceLimits,
 }
 impl<B, C, P> Projection<B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object>,
 {
    /// Assemble trusted components. The registry must contain all exposed tokens.
    pub fn new(
        backend: B,
        registry: InterfaceRegistry,
        composition: C,
        policy: P,
        limits: ResourceLimits,
    ) -> Self {
        Self {
            backend,
            registry,
            composition,
            policy,
            limits,
        }
    }
    /// Backend access for trusted composition/configuration, never serialized.
    pub fn backend(&self) -> &B {
        &self.backend
    }
    /// Borrow one effective principal view for observation, fetch and dispatch.
    pub fn view<'a>(&'a self, principal: &'a P::Principal) -> ProjectionView<'a, B, C, P> {
        ProjectionView {
            projection: self,
            principal,
        }
    }
 }
 /// A coherent principal view implementing canonical typed host dispatch.
 pub struct ProjectionView<'a, B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object>,
 {
    projection: &'a Projection<B, C, P>,
    principal: &'a P::Principal,
 }
 impl<B, C, P> ProjectionView<'_, B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object>,
 {
    fn resolve(
        &self,
        context: &ExecutionContext,
        path: &str,
    ) -> ProviderResult<ResolvedEntry<B::Entry>> {
        if let Err(error) = preflight(context) {
            return ProviderResult::Failure(error);
        }
        if wip_protocol::validate_path(path).is_err() {
            return ProviderResult::NotFound;
        }
        match self.projection.backend.resolve(context, path) {
            ProviderResult::Found(resolved) => {
                if !lineage_matches_path(&resolved, path) {
                    return ProviderResult::Failure(internal());
                }
                if !self.lineage_visible(&resolved) {
                    return ProviderResult::NotFound;
                }
                ProviderResult::Found(resolved)
            }
            ProviderResult::NotFound => ProviderResult::NotFound,
            ProviderResult::Failure(error) => ProviderResult::Failure(error),
        }
    }
    fn lineage_visible(&self, resolved: &ResolvedEntry<B::Entry>) -> bool {
        resolved
            .ancestors()
            .iter()
            .chain(std::iter::once(resolved.target()))
            .all(|entry| self.projection.policy.object_visible(self.principal, entry))
    }
    fn publication(
        &self,
        resolved: &ResolvedEntry<B::Entry>,
        context: &ExecutionContext,
    ) -> Result<PublishedObject<C::Object>, HostError> {
        let entry = resolved.target();
        let publication = self
            .projection
            .composition
            .publish(entry.clone(), context)?;
        let mut current_scopes = Vec::new();
        let mut path = String::from("/");
        // Only this refreshed, visible, connected lineage can attest scopes.
        // Never independently resolve a scope path while a target is executing.
        for (index, scope_entry) in resolved
            .ancestors()
            .iter()
            .chain(std::iter::once(entry))
            .enumerate()
        {
            if index > 0 {
                if path != "/" {
                    path.push('/');
                }
                path.push_str(scope_entry.name());
            }
            if !self
                .projection
                .registry
                .scopes()
                .any(|scope| scope.path() == path)
            {
                continue;
            }
            let scopes = if path == "/" {
                self.projection
                    .registry
                    .scopes()
                    .filter(|scope| scope.path() == "/")
                    .cloned()
                    .collect::<Vec<_>>()
            } else {
                self.projection
                    .composition
                    .scope(&path, scope_entry, context)?
                    .into_iter()
                    .collect::<Vec<_>>()
            };
            if scopes.iter().any(|scope| scope.path() != path) {
                return Err(internal());
            }
            if scopes.is_empty() {
                continue;
            }
            // Refs belong to the Composition's published Object, not necessarily
            // the raw entry. Self-scope reuses exactly the target publication.
            let scope_publication = if index == resolved.ancestors().len() {
                None
            } else {
                Some(
                    self.projection
                        .composition
                        .publish(scope_entry.clone(), context)?,
                )
            };
            let object = scope_publication
                .as_ref()
                .map_or(publication.implementation(), |scope| scope.implementation());
            current_scopes.extend(
                scopes
                    .iter()
                    .map(|scope| ScopeObservation::new(scope, object)),
            );
        }
        let available = publication
            .protocol_object()
            .interfaces
            .iter()
            .map(|reference| {
                self.projection
                    .registry
                    .resolve(reference)
                    .ok_or_else(internal)
            })
            .collect::<Result<Vec<_>, _>>()?;
        let mut selected = self
            .projection
            .policy
            .interfaces(self.principal, entry, &available);
        selected.retain(|reference| {
            let reference_value = reference.protocol_reference();
            current_scopes.iter().any(|current| {
                self.projection
                    .registry
                    .fetch_interface(&reference_value, current)
                    .is_ok()
            }) && self
                .projection
                .policy
                .interface_visible(self.principal, reference)
        });
        let mut publication = publication
            .project(&selected, |reference, operation| {
                self.projection
                    .policy
                    .operation_visible(self.principal, reference, operation)
            })
            .map_err(|_| internal())?;
        for current in current_scopes {
            publication = publication.bind_scope(current);
        }
        Ok(publication)
    }
    // Adapt read-only callbacks to the existing backend execution boundary. The
    // sentinel is NotStarted: no typed operation ran and no commit/rollback may
    // be inferred. The actual callback result never escapes until execute exits.
    fn with_publication<R>(
        &self,
        context: &ExecutionContext,
        path: &str,
        resolved: ResolvedEntry<B::Entry>,
        operation: impl FnOnce(&PublishedObject<C::Object>) -> R,
    ) -> ProviderResult<R> {
        let mut observed = None;
        let boundary = self
            .projection
            .backend
            .execute(context, resolved, |resolved| {
                if !lineage_matches_path(&resolved, path) {
                    observed = Some(ProviderResult::Failure(internal()));
                    return OperationAttempt::reject(wip_host::CallErrorKind::Internal);
                }
                if !self.lineage_visible(&resolved) {
                    observed = Some(ProviderResult::NotFound);
                    return OperationAttempt::reject(wip_host::CallErrorKind::NotFound);
                }
                observed = Some(
                    match preflight(context).and_then(|()| {
                        self.publication(&resolved, context)
                            .map(|publication| operation(&publication))
                    }) {
                        Ok(result) => ProviderResult::Found(result),
                        Err(error) => ProviderResult::Failure(error),
                    },
                );
                OperationAttempt::reject(wip_host::CallErrorKind::Internal)
            });
        match boundary {
            ProviderResult::Found(_) => {
                observed.unwrap_or_else(|| ProviderResult::Failure(internal()))
            }
            ProviderResult::NotFound => ProviderResult::NotFound,
            ProviderResult::Failure(error) => ProviderResult::Failure(error),
        }
    }
    /// Retrieve the descriptor with precisely this principal's visible operations.
    pub fn fetch_interface(
        &self,
        request: &FetchInterfaceRequest,
    ) -> Result<FetchInterfaceResponse, ProtocolError> {
        read_boundary(|| self.fetch_interface_inner(request))
    }
    fn fetch_interface_inner(
        &self,
        request: &FetchInterfaceRequest,
    ) -> Result<FetchInterfaceResponse, ProtocolError> {
        let observation =
            ObjectProvider::fetch_interface(self, &self.projection.registry, &request.interface)?;
        if !self
            .projection
            .policy
            .interface_visible(self.principal, &observation.reference)
        {
            return Err(protocol(
                ProtocolErrorCode::InterfaceNotFound,
                "interface is not published",
            ));
        }
        let reference = observation.reference.clone();
        observation
            .project_operations(|operation| {
                self.projection
                    .policy
                    .operation_visible(self.principal, &reference, operation)
            })
            .protocol_response()
    }
    /// Observe a complete bounded tree, omitting invisible children and subtrees.
    pub fn observe(
        &self,
        context: &ExecutionContext,
        request: &ObserveRequest,
    ) -> Result<ObserveResponse, ProtocolError> {
        read_boundary(|| self.observe_inner(context, request))
    }
    fn observe_inner(
        &self,
        context: &ExecutionContext,
        request: &ObserveRequest,
    ) -> Result<ObserveResponse, ProtocolError> {
        request
            .validate()
            .map_err(|_| protocol(ProtocolErrorCode::InvalidRequest, "invalid observe request"))?;
        if request.depth > self.projection.limits.max_observation_depth {
            return Err(resource_protocol());
        }
        let entry = match self.resolve(context, &request.path) {
            ProviderResult::Found(entry) => entry,
            ProviderResult::NotFound => {
                return Err(protocol(
                    ProtocolErrorCode::NotFound,
                    "target path is not published",
                ));
            }
            ProviderResult::Failure(error) => return Err(read_error(error)),
        };
        let mut remaining = u64::from(self.projection.limits.max_observation_nodes)
            .min(context.resource_budget().unwrap_or(u64::MAX));
        let response =
            self.observe_entry(context, &request.path, entry, request.depth, &mut remaining)?;
        request.validate_response(&response).map_err(|_| {
            protocol(
                ProtocolErrorCode::Internal,
                "invalid projection observation",
            )
        })?;
        Ok(response)
    }
    fn observe_entry(
        &self,
        context: &ExecutionContext,
        path: &str,
        resolved: ResolvedEntry<B::Entry>,
        depth: u32,
        remaining: &mut u64,
    ) -> Result<ObjectObservation, ProtocolError> {
        preflight(context).map_err(read_error)?;
        if *remaining == 0 {
            return Err(resource_protocol());
        }
        *remaining -= 1;
        let object = match self.with_publication(context, path, resolved.clone(), |publication| {
            publication.protocol_object_at(path)
        }) {
            ProviderResult::Found(object) => object.map_err(|error| error.protocol_error())?,
            ProviderResult::NotFound => {
                return Err(protocol(
                    ProtocolErrorCode::NotFound,
                    "target path is not published",
                ));
            }
            ProviderResult::Failure(error) => return Err(read_error(error)),
        };
        let (mut ancestors, entry) = resolved.into_parts();
        if depth == 0 {
            return Ok(ObjectObservation {
                object,
                children: None,
            });
        }
        let mut children = Vec::new();
        if entry.kind() == EntryKind::Directory {
            let entries = self
                .projection
                .backend
                .children(
                    context,
                    &entry,
                    usize::try_from(*remaining).unwrap_or(usize::MAX),
                )
                .map_err(read_error)?;
            if entries.len() as u64 > *remaining {
                return Err(resource_protocol());
            }
            ancestors.push(entry.clone());
            for child in entries {
                if self
                    .projection
                    .policy
                    .object_visible(self.principal, &child)
                {
                    let child_path = if path == "/" {
                        format!("/{}", child.name())
                    } else {
                        format!("{path}/{}", child.name())
                    };
                    children.push(self.observe_entry(
                        context,
                        &child_path,
                        ResolvedEntry::new(ancestors.clone(), child),
                        depth - 1,
                        remaining,
                    )?);
                } else {
                    if *remaining == 0 {
                        return Err(resource_protocol());
                    }
                    *remaining -= 1;
                }
            }
        }
        Ok(ObjectObservation {
            object,
            children: Some(children),
        })
    }
 }
 impl<B, C, P> ObjectProvider for ProjectionView<'_, B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object>,
 {
    type Object = C::Object;
    fn with_object<R>(
        &self,
        context: &ExecutionContext,
        path: &str,
        operation: impl FnOnce(&PublishedObject<Self::Object>) -> R,
    ) -> ProviderResult<R> {
        match self.resolve(context, path) {
            ProviderResult::Found(resolved) => {
                self.with_publication(context, path, resolved, operation)
            }
            ProviderResult::NotFound => ProviderResult::NotFound,
            ProviderResult::Failure(error) => ProviderResult::Failure(error),
        }
    }
    fn execute_operation(
        &self,
        context: &ExecutionContext,
        path: &str,
        operation: impl FnOnce(&PublishedObject<Self::Object>) -> OperationAttempt,
    ) -> ProviderResult<OperationAttempt> {
        let entry = match self.resolve(context, path) {
            ProviderResult::Found(entry) => entry,
            ProviderResult::NotFound => return ProviderResult::NotFound,
            ProviderResult::Failure(error) => return ProviderResult::Failure(error),
        };
        self.projection.backend.execute(context, entry, |resolved| {
            // Backend validates retained lineage membership/identity and refreshes
            // all metadata before this callback under the same boundary as dispatch.
            if !lineage_matches_path(&resolved, path) {
                return OperationAttempt::reject(wip_host::CallErrorKind::Internal);
            }
            if !self.lineage_visible(&resolved) {
                return OperationAttempt::reject(wip_host::CallErrorKind::NotFound);
            }
            if let Err(error) = preflight(context) {
                return OperationAttempt::reject(match error.kind() {
                    wip_host::HostErrorKind::Internal => wip_host::CallErrorKind::Internal,
                    wip_host::HostErrorKind::ResourceLimitExceeded => {
                        wip_host::CallErrorKind::ResourceLimitExceeded
                    }
                });
            }
            match self.publication(&resolved, context) {
                Ok(publication) => operation(&publication),
                Err(error) => OperationAttempt::reject(match error.kind() {
                    wip_host::HostErrorKind::Internal => wip_host::CallErrorKind::Internal,
                    wip_host::HostErrorKind::ResourceLimitExceeded => {
                        wip_host::CallErrorKind::ResourceLimitExceeded
                    }
                }),
            }
        })
    }
    fn authorize(
        &self,
        _: &str,
        object: &Self::Object,
        interface: &InterfaceRef,
        operation: &str,
    ) -> bool {
        self.projection
            .policy
            .authorize(self.principal, object, interface, operation)
    }
 }
 impl<B, C, P> ObjectProvider for Projection<B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object, Principal = ()>,
 {
    type Object = C::Object;
    fn with_object<R>(
        &self,
        context: &ExecutionContext,
        path: &str,
        operation: impl FnOnce(&PublishedObject<Self::Object>) -> R,
    ) -> ProviderResult<R> {
        self.view(&()).with_object(context, path, operation)
    }
    fn execute_operation(
        &self,
        context: &ExecutionContext,
        path: &str,
        operation: impl FnOnce(&PublishedObject<Self::Object>) -> OperationAttempt,
    ) -> ProviderResult<OperationAttempt> {
        self.view(&()).execute_operation(context, path, operation)
    }
    fn authorize(
        &self,
        path: &str,
        object: &Self::Object,
        interface: &InterfaceRef,
        operation: &str,
    ) -> bool {
        self.view(&()).authorize(path, object, interface, operation)
    }
 }
 impl<B, C, P> Projection<B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object, Principal = ()>,
 {
    /// Observe the default unit-principal view.
    pub fn observe(
        &self,
        context: &ExecutionContext,
        request: &ObserveRequest,
    ) -> Result<ObserveResponse, ProtocolError> {
        self.view(&()).observe(context, request)
    }
    /// Fetch in the default unit-principal view.
    pub fn fetch_interface(
        &self,
        request: &FetchInterfaceRequest,
    ) -> Result<FetchInterfaceResponse, ProtocolError> {
        self.view(&()).fetch_interface(request)
    }
 }
 fn lineage_matches_path<E: BackendEntry>(resolved: &ResolvedEntry<E>, path: &str) -> bool {
    let names: Vec<_> = if path == "/" {
        vec![""]
    } else {
        std::iter::once("").chain(path[1..].split('/')).collect()
    };
    if resolved.ancestors().len() + 1 != names.len()
        || resolved.target().name() != names[names.len() - 1]
    {
        return false;
    }
    resolved
        .ancestors()
        .iter()
        .zip(names)
        .all(|(entry, name)| entry.kind() == EntryKind::Directory && entry.name() == name)
 }
 fn read_boundary<T>(
    operation: impl FnOnce() -> Result<T, ProtocolError>,
 ) -> Result<T, ProtocolError> {
    std::panic::catch_unwind(std::panic::AssertUnwindSafe(operation))
        .unwrap_or_else(|_| Err(protocol(ProtocolErrorCode::Internal, "projection failed")))
 }
 fn internal() -> HostError {
    HostError::internal(
        "projection publication failed",
        EffectGuarantee::NotCommitted,
    )
 }
 fn protocol(code: ProtocolErrorCode, message: &str) -> ProtocolError {
    ProtocolError {
        code,
        message: message.into(),
    }
 }
 fn resource_protocol() -> ProtocolError {
    protocol(
        ProtocolErrorCode::ResourceLimitExceeded,
        "projection resource limit exceeded",
    )
 }
 fn read_error(error: HostError) -> ProtocolError {
    match error.kind() {
        wip_host::HostErrorKind::ResourceLimitExceeded => resource_protocol(),
        wip_host::HostErrorKind::Internal => {
            protocol(ProtocolErrorCode::Internal, "projection failed")
        }
    }
 }
 fn preflight(context: &ExecutionContext) -> Result<(), HostError> {
    if context.cancellation().is_cancelled()
        || context
            .deadline()
            .is_some_and(|deadline| std::time::Instant::now() >= deadline)
        || context.resource_budget() == Some(0)
    {
        Err(HostError::resource_limit(
            "projection work limit exceeded",
            EffectGuarantee::NotCommitted,
        ))
    } else {
        Ok(())
    }
 }
@@ -0,0 +1,435 @@
 //! Framework-neutral standard WIP over HTTP mapping for a projection view.
 use std::time::Instant;
 use http::header::ALLOW;
 use http::{Request, Response, StatusCode};
 use wip_host::{ExecutionContext, ObjectProvider};
 use wip_http::{
    CodecError, EncodeHttpError, Endpoint, RequestMetadataError, Route,
    decode_call_operation_metadata, decode_fetch_interface_request, decode_observe_request,
    encode_call_operation_response, encode_fetch_interface_response, encode_observe_response,
    encode_protocol_error_response, validate_http_request,
 };
 use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
 use crate::engine::ProjectionView;
 use crate::{Composition, FilesystemBackend, ProjectionPolicy, ResourceLimits};
 /// Standard HTTP routes and codecs over a caller-scoped projection view.
 ///
 /// The adapter borrows the view and endpoint without owning a listener, selecting
 /// a principal, or imposing a new execution context. Integrations must enforce
 /// the request body limit while collecting bytes, before calling this adapter.
 pub struct HttpAdapter<'a, 'view, B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object>,
 {
    view: &'a ProjectionView<'view, B, C, P>,
    endpoint: &'a Endpoint,
    limits: ResourceLimits,
 }
 impl<'a, 'view, B, C, P> HttpAdapter<'a, 'view, B, C, P>
 where
    B: FilesystemBackend,
    C: Composition<B::Entry>,
    P: ProjectionPolicy<B::Entry, C::Object>,
 {
    /// Creates an adapter for an already-selected principal's projection view.
    #[must_use]
    pub fn new(
        view: &'a ProjectionView<'view, B, C, P>,
        endpoint: &'a Endpoint,
        limits: ResourceLimits,
    ) -> Self {
        Self {
            view,
            endpoint,
            limits,
        }
    }
    /// Handles one buffered request using the supplied execution controls.
    ///
    /// Observation and operation dispatch receive the original context, including
    /// cancellation and resource budget. An elapsed deadline after dispatch keeps
    /// the listener's existing empty HTTP 504 transport-failure behavior.
    #[must_use]
    pub fn handle_http_with_context(
        &self,
        request: Request<Vec<u8>>,
        context: &ExecutionContext,
    ) -> Response<Vec<u8>> {
        let Some(route) = self.route(request.uri()) else {
            return empty_response(StatusCode::NOT_FOUND);
        };
        if let Err(error) = validate_http_request(self.endpoint, route, &request) {
            return self.metadata_error(error);
        }
        let response = match route {
            Route::Observe => self.observe(request.body(), context),
            Route::FetchInterface => self.fetch_interface(request.body()),
            Route::CallOperation => self.call_operation(request.body(), context),
        };
        if context
            .deadline()
            .is_some_and(|deadline| Instant::now() >= deadline)
        {
            empty_response(StatusCode::GATEWAY_TIMEOUT)
        } else {
            response
        }
    }
    fn route(&self, uri: &http::Uri) -> Option<Route> {
        if uri.query().is_some() {
            return None;
        }
        [Route::Observe, Route::FetchInterface, Route::CallOperation]
            .into_iter()
            .find(|route| self.endpoint.route(*route).path() == uri.path())
    }
    fn observe(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
        let request = match decode_observe_request(body, self.limits.wire) {
            Ok(request) => request,
            Err(error) => return self.codec_error(ProtocolInteraction::Observe, error),
        };
        match self.view.observe(context, &request) {
            Ok(tree) => {
                encode_observe_response(&request, &tree, self.limits.wire).unwrap_or_else(|error| {
                    self.read_encode_error(ProtocolInteraction::Observe, error)
                })
            }
            Err(error) => self.protocol_error(ProtocolInteraction::Observe, &error),
        }
    }
    fn fetch_interface(&self, body: &[u8]) -> Response<Vec<u8>> {
        let request = match decode_fetch_interface_request(body, self.limits.wire) {
            Ok(request) => request,
            Err(error) => return self.codec_error(ProtocolInteraction::FetchInterface, error),
        };
        match self.view.fetch_interface(&request) {
            Ok(interface) => {
                encode_fetch_interface_response(&request, &interface, self.limits.wire)
                    .unwrap_or_else(|error| {
                        self.read_encode_error(ProtocolInteraction::FetchInterface, error)
                    })
            }
            Err(error) => self.protocol_error(ProtocolInteraction::FetchInterface, &error),
        }
    }
    fn call_operation(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
        let metadata = match decode_call_operation_metadata(body, self.limits.wire) {
            Ok(metadata) => metadata,
            Err(error) => return self.codec_error(ProtocolInteraction::CallOperation, error),
        };
        let decoded = std::sync::Mutex::new(None);
        let execution = self.view.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.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 {
                    return self.protocol_error(
                        ProtocolInteraction::CallOperation,
                        &operation_outcome_unknown(),
                    );
                };
                encode_call_operation_response(&request, &descriptor, &result, self.limits.wire)
                    .unwrap_or_else(|error| self.operation_encode_error(error))
            }
            Err(error) => self.protocol_error(ProtocolInteraction::CallOperation, &error),
        }
    }
    fn operation_encode_error(&self, error: EncodeHttpError) -> Response<Vec<u8>> {
        if matches!(&error, EncodeHttpError::Codec(codec) if is_transport_limit(codec)) {
            return empty_response(StatusCode::INTERNAL_SERVER_ERROR);
        }
        // Any successfully executed operation may have committed effects. Its
        // name cannot establish a non-commit guarantee after response failure.
        self.protocol_error(
            ProtocolInteraction::CallOperation,
            &operation_outcome_unknown(),
        )
    }
    fn metadata_error(&self, error: RequestMetadataError) -> Response<Vec<u8>> {
        match error {
            RequestMetadataError::NotFound => empty_response(StatusCode::NOT_FOUND),
            error @ RequestMetadataError::MethodNotAllowed => Response::builder()
                .status(error.status())
                .header(
                    ALLOW,
                    error
                        .allow()
                        .expect("method-not-allowed metadata has an Allow value"),
                )
                .body(Vec::new())
                .expect("static method response is valid"),
            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 is_transport_limit(&error) {
            empty_response(StatusCode::PAYLOAD_TOO_LARGE)
        } else {
            self.protocol_error(
                interaction,
                &ProtocolError {
                    code: ProtocolErrorCode::InvalidRequest,
                    message: "malformed WIP request".into(),
                },
            )
        }
    }
    fn read_encode_error(
        &self,
        interaction: ProtocolInteraction,
        error: EncodeHttpError,
    ) -> Response<Vec<u8>> {
        match error {
            EncodeHttpError::Codec(codec) if is_transport_limit(&codec) => {
                empty_response(StatusCode::INTERNAL_SERVER_ERROR)
            }
            _ => self.protocol_error(
                interaction,
                &ProtocolError {
                    code: ProtocolErrorCode::Internal,
                    message: "HTTP adapter failed".into(),
                },
            ),
        }
    }
    fn protocol_error(
        &self,
        interaction: ProtocolInteraction,
        error: &ProtocolError,
    ) -> Response<Vec<u8>> {
        // Engine and policy diagnostics may contain paths, argument values, or
        // backend details. Emit only fixed, bounded diagnostics on the wire.
        let sanitized = ProtocolError {
            code: error.code,
            message: sanitized_message(error.code).into(),
        };
        encode_protocol_error_response(interaction, &sanitized, self.limits.wire)
            .unwrap_or_else(|_| empty_response(StatusCode::INTERNAL_SERVER_ERROR))
    }
 }
 fn operation_outcome_unknown() -> ProtocolError {
    ProtocolError {
        code: ProtocolErrorCode::OperationOutcomeUnknown,
        message: "operation completed but its response could not be encoded".into(),
    }
 }
 fn sanitized_message(code: ProtocolErrorCode) -> &'static str {
    match code {
        ProtocolErrorCode::InvalidRequest => "malformed WIP request",
        ProtocolErrorCode::NotFound => "target path is not published",
        ProtocolErrorCode::InterfaceNotFound => "interface is not published",
        ProtocolErrorCode::InterfaceMismatch => "interface is not published on the target",
        ProtocolErrorCode::OperationNotFound => "operation is not published",
        ProtocolErrorCode::InvalidArguments => "arguments do not match the operation",
        ProtocolErrorCode::ValidatorRequired => "object validator is required",
        ProtocolErrorCode::ValidatorMismatch => "object validator does not match",
        ProtocolErrorCode::InterfaceValidatorRequired => "interface validator is required",
        ProtocolErrorCode::InterfaceValidatorMismatch => "interface validator does not match",
        ProtocolErrorCode::PermissionDenied => "operation is not permitted",
        ProtocolErrorCode::ResourceLimitExceeded => "projection resource limit exceeded",
        ProtocolErrorCode::Internal => "HTTP adapter failed",
        ProtocolErrorCode::OperationOutcomeUnknown => "operation outcome is unknown",
    }
 }
 fn is_transport_limit(error: &CodecError) -> bool {
    matches!(
        error,
        CodecError::BodyTooLarge { .. } | CodecError::NestingTooDeep { .. }
    )
 }
 fn empty_response(status: StatusCode) -> Response<Vec<u8>> {
    Response::builder()
        .status(status)
        .body(Vec::new())
        .expect("static status builds an HTTP response")
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use tempfile::tempdir;
    use wip_http::{
        DecodedResponse, Limits, decode_fetch_interface_response, decode_observe_response,
        encode_fetch_interface_request, encode_observe_request,
    };
    use wip_protocol::{FetchInterfaceRequest, ObserveRequest};
    #[test]
    fn adapter_serves_observation_and_interface_fetch_without_server() {
        let root = tempdir().unwrap();
        std::fs::write(root.path().join("file"), b"contents").unwrap();
        let limits = ResourceLimits::default();
        let projection =
            crate::default_projection(root.path(), crate::AccessMode::ReadOnly, limits).unwrap();
        let view = projection.view(&());
        let endpoint = Endpoint::parse("http://localhost/custom").unwrap();
        let adapter = HttpAdapter::new(&view, &endpoint, limits);
        let context = ExecutionContext::new();
        let request = ObserveRequest {
            path: "/file".into(),
            depth: 0,
        };
        let response = adapter.handle_http_with_context(
            encode_observe_request(&endpoint, &request, limits.wire).unwrap(),
            &context,
        );
        let DecodedResponse::Success(observation) =
            decode_observe_response(&request, &response, limits.wire).unwrap()
        else {
            panic!("expected observation success")
        };
        let request = FetchInterfaceRequest {
            interface: observation.object.interfaces[0].clone(),
        };
        let response = adapter.handle_http_with_context(
            encode_fetch_interface_request(&endpoint, &request, limits.wire).unwrap(),
            &context,
        );
        assert!(matches!(
            decode_fetch_interface_response(&request, &response, limits.wire).unwrap(),
            DecodedResponse::Success(_)
        ));
    }
    #[test]
    fn adapter_preserves_transport_boundaries_and_execution_context() {
        let root = tempdir().unwrap();
        let limits = ResourceLimits::default();
        let projection =
            crate::default_projection(root.path(), crate::AccessMode::ReadOnly, limits).unwrap();
        let view = projection.view(&());
        let endpoint = Endpoint::parse("http://localhost/wip").unwrap();
        let adapter = HttpAdapter::new(&view, &endpoint, limits);
        let context = ExecutionContext::new();
        for uri in [
            "/wip/v1/observe?query=1",
            "/wip/v1/unknown",
            "/wip/v1/observe/extra",
        ] {
            let response = adapter.handle_http_with_context(
                Request::builder().uri(uri).body(Vec::new()).unwrap(),
                &context,
            );
            assert_eq!(response.status(), StatusCode::NOT_FOUND);
            assert!(response.body().is_empty());
        }
        let response = adapter.handle_http_with_context(
            Request::builder()
                .uri("/wip/v1/observe")
                .body(Vec::new())
                .unwrap(),
            &context,
        );
        assert_eq!(response.status(), StatusCode::METHOD_NOT_ALLOWED);
        assert_eq!(response.headers()[ALLOW], "POST");
        assert!(response.body().is_empty());
        let request = ObserveRequest {
            path: "/".into(),
            depth: 0,
        };
        let response = adapter.handle_http_with_context(
            encode_observe_request(&endpoint, &request, limits.wire).unwrap(),
            &ExecutionContext::new().with_resource_budget(0),
        );
        let text = std::str::from_utf8(response.body()).unwrap();
        assert!(text.contains("resource_limit_exceeded"));
        let response = adapter.handle_http_with_context(
            encode_observe_request(&endpoint, &request, limits.wire).unwrap(),
            &ExecutionContext::new().with_deadline(Instant::now()),
        );
        assert_eq!(response.status(), StatusCode::GATEWAY_TIMEOUT);
        assert!(response.body().is_empty());
    }
    #[test]
    fn post_success_encoding_is_unknown_except_empty_transport_limit_failure() {
        let root = tempdir().unwrap();
        let limits = ResourceLimits::default();
        let projection =
            crate::default_projection(root.path(), crate::AccessMode::ReadOnly, limits).unwrap();
        let view = projection.view(&());
        let endpoint = Endpoint::parse("http://localhost/wip").unwrap();
        let adapter = HttpAdapter::new(&view, &endpoint, limits);
        let error = decode_observe_request(b"{", limits.wire).unwrap_err();
        let response = adapter.operation_encode_error(EncodeHttpError::Codec(error));
        assert!(
            std::str::from_utf8(response.body())
                .unwrap()
                .contains("operation_outcome_unknown")
        );
        let tiny_limits = Limits::new(1, 1, 1).unwrap();
        let error = decode_observe_request(b"{}", tiny_limits).unwrap_err();
        assert!(is_transport_limit(&error));
        let response = adapter.operation_encode_error(EncodeHttpError::Codec(error));
        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
        assert!(response.body().is_empty());
        assert!(!response.headers().contains_key(http::header::CONTENT_TYPE));
    }
    #[test]
    fn engine_error_diagnostics_are_sanitized_and_bounded() {
        let root = tempdir().unwrap();
        let limits = ResourceLimits::default();
        let projection =
            crate::default_projection(root.path(), crate::AccessMode::ReadOnly, limits).unwrap();
        let view = projection.view(&());
        let endpoint = Endpoint::parse("http://localhost/wip").unwrap();
        let adapter = HttpAdapter::new(&view, &endpoint, limits);
        let response = adapter.protocol_error(
            ProtocolInteraction::Observe,
            &ProtocolError {
                code: ProtocolErrorCode::Internal,
                message: "/private/backend/secret".repeat(1000),
            },
        );
        assert!(response.body().len() < 512);
        assert!(
            !std::str::from_utf8(response.body())
                .unwrap()
                .contains("secret")
        );
        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
    }
 }
@@ -1,18 +1,65 @@
-//! Request-time filesystem projection served through the standard WIP HTTPS binding.
+//! Request-time filesystem projection served through the standard WIP over HTTP 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;
+//! - [`wip_http`] owns routes, JSON, envelopes, 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
+//! # Extension boundary
-//! listener accepts cleartext only on loopback, either behind that proxy or when
+//!
-//! [`TransportSecurity::DevelopmentHttp`] is deliberately selected.
+//! [`Projection`] composes a [`FilesystemBackend`], typed [`Composition`] and
 //! [`ProjectionPolicy`]. External local Objects can wrap a [`BackendEntry`] and
 //! implement generated interfaces without orphan-rule workarounds. The backend
 //! retains a root-confined target and atomic validator/dispatch boundary; the
 //! engine owns recursive observation and standard host typed validation. No
 //! listener is needed to use [`ProjectionView`]. [`HttpAdapter`] applies the
 //! existing standard HTTP binding to a deployment-established principal view.
 //!
 //! # Scope publication migration
 //!
 //! Registration uses `registry.register(&scope, name, Definition, validator)`.
 //! [`DefaultInterfaces::register`] takes an explicit [`wip_host::Scope`]; built-ins
 //! use root-local names `file.read`, `symlink.inspect` and `file.write`. The engine
 //! binds its deployment-pinned root lifetime automatically inside the backend
 //! execution boundary. External [`Composition::scope`] implementations attest
 //! non-root lifetimes using the refreshed connected lineage in that same boundary.
 //! Without an attestation non-root registrations fail closed. Scope refs come
 //! from the current published scope Object and remain optional.
 //! The Linux root survives textual root renames and does not issue an Object ref;
 //! fetch therefore omits `scope_ref` without weakening the private lifetime check.
 //!
 //! Backends and Operations are trusted code, responsible for truthful effects,
 //! public-only metadata and ongoing execution-context bounds. Policies must be
 //! stable within a view; changing descriptor visibility requires new reference
 //! lifetimes. See the crate README for implementer security and migration details.
 //!
 //! ```no_run
 //! use wip_fs_server::{default_projection, AccessMode, ResourceLimits};
 //! use wip_host::{ExecutionContext, ObjectProvider};
 //! use wip_protocol::ObserveRequest;
 //!
 //! let engine = default_projection(std::path::Path::new("./public"),
 //!     AccessMode::ReadOnly, ResourceLimits::default())?;
 //! let view = engine.view(&());
 //! let context = ExecutionContext::new().with_resource_budget(128);
 //! let tree = view.observe(&context, &ObserveRequest { path: "/".into(), depth: 1 })?;
 //! assert_eq!(tree.object.name, "");
 //! let object = view.observe_object_with_context(&context, "/")?;
 //! assert!(object.interfaces.is_empty());
 //! # Ok::<(), Box<dyn std::error::Error>>(())
 //! ```
 //!
 //! The built-in HTTP listener is intentionally loopback-only. TLS termination,
 //! certificates, authentication, and externally visible schemes are independent
 //! deployment concerns rather than WIP transport profiles.
 #![deny(missing_docs)]
 mod defaults;
 mod engine;
 mod http_adapter;
 mod interfaces;
 mod projection;
 mod server;
@@ -21,7 +68,17 @@ use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 use std::path::PathBuf;
 use std::time::Duration;
-pub use interfaces::{FileRead, FileWrite, SymlinkInspect};
+pub use defaults::{DefaultComposition, DefaultInterfaces, DefaultObject, default_projection};
 pub use engine::{
    BackendEntry, Composition, DefaultPolicy, EntryKind, FilesystemBackend, Projection,
    ProjectionPolicy, ProjectionView, ResolvedEntry,
 };
 pub use http_adapter::HttpAdapter;
 pub use interfaces::{
    FileRead, FileReadDefinition, FileWrite, FileWriteDefinition, SymlinkInspect,
    SymlinkInspectDefinition,
 };
 pub use projection::{LinuxBackend, LinuxEntry};
 pub use server::{BoundServer, ServerBuildError, WipFsServer};
 /// Filesystem capabilities published by regular files.
@@ -33,28 +90,19 @@ pub enum AccessMode {
    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.
+    /// Standard JSON, body-size, and nesting limits.
-    pub wire: wip_https::Limits,
+    pub wire: wip_http::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.
+    /// Maximum accepted `observe` depth.
-    pub max_tree_depth: u32,
+    pub max_observation_depth: u32,
-    /// Maximum accepted `fetch_tree` node count, including its root.
+    /// Maximum accepted `observe` node count, including its root.
-    pub max_tree_nodes: u32,
+    pub max_observation_nodes: u32,
    /// Maximum simultaneously pinned projected filesystem handles.
    pub max_open_handles: usize,
    /// Maximum bytes accepted for one HTTP request head, including its terminator.
@@ -68,12 +116,12 @@ pub struct ResourceLimits {
 impl Default for ResourceLimits {
    fn default() -> Self {
        Self {
-            wire: wip_https::Limits::new(256 * 1024, 2 * 1024 * 1024, 64, 64)
+            wire: wip_http::Limits::new(256 * 1024, 2 * 1024 * 1024, 64)
                .expect("default wire limits are nonzero"),
            max_file_read_bytes: 1024 * 1024,
            max_file_write_bytes: 1024 * 1024,
-            max_tree_depth: 32,
+            max_observation_depth: 32,
-            max_tree_nodes: 1024,
+            max_observation_nodes: 1024,
            max_open_handles: 2048,
            max_http_header_bytes: 16 * 1024,
            max_concurrent_requests: 32,
@@ -93,8 +141,6 @@ pub struct ServerConfig {
    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,
 }
@@ -102,8 +148,7 @@ pub struct ServerConfig {
 impl ServerConfig {
    /// Builds a secure-by-default configuration for `root`.
    ///
-    /// The listener defaults to an ephemeral loopback port, read-only access,
+    /// The listener defaults to an ephemeral loopback port and read-only access.
    /// and TLS termination delegated to a reverse proxy.
    #[must_use]
    pub fn for_root(root: impl Into<PathBuf>) -> Self {
        Self {
@@ -111,7 +156,6 @@ impl ServerConfig {
            listen: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0),
            endpoint_base_path: "/wip".into(),
            access: AccessMode::ReadOnly,
            transport_security: TransportSecurity::ReverseProxyTls,
            limits: ResourceLimits::default(),
        }
    }
@@ -125,7 +169,7 @@ impl ServerConfig {
        }
        if self.limits.max_file_read_bytes == 0
            || self.limits.max_file_write_bytes == 0
-            || self.limits.max_tree_nodes == 0
+            || self.limits.max_observation_nodes == 0
            || self.limits.max_open_handles == 0
            || self.limits.max_http_header_bytes == 0
            || self.limits.max_concurrent_requests == 0
@@ -133,7 +177,7 @@ impl ServerConfig {
        {
            return Err(ConfigError::ZeroLimit);
        }
-        if self.limits.max_open_handles < self.limits.max_tree_nodes as usize {
+        if self.limits.max_open_handles < self.limits.max_observation_nodes as usize {
            return Err(ConfigError::InsufficientHandles);
        }
        if self.limits.wire.max_response_bytes() < 512 {
@@ -142,9 +186,9 @@ impl ServerConfig {
        Ok(())
    }
-    pub(crate) fn endpoint(&self) -> Result<wip_https::Endpoint, ConfigError> {
+    pub(crate) fn endpoint(&self) -> Result<wip_http::Endpoint, ConfigError> {
-        let endpoint = format!("https://localhost{}", self.endpoint_base_path);
+        let endpoint = format!("http://localhost{}", self.endpoint_base_path);
-        wip_https::Endpoint::parse(&endpoint).map_err(|_| ConfigError::InvalidBasePath)
+        wip_http::Endpoint::parse(&endpoint).map_err(|_| ConfigError::InvalidBasePath)
    }
 }
@@ -171,7 +215,7 @@ impl std::fmt::Display for ConfigError {
                "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::InsufficientHandles => "max_open_handles must cover max_observation_nodes",
            Self::ResponseLimitTooSmall => "max_response_bytes must be at least 512",
        })
    }
@@ -2,14 +2,13 @@ use std::error::Error;
 use std::net::SocketAddr;
 use std::path::PathBuf;
-use wip_fs_server::{AccessMode, ServerConfig, TransportSecurity, WipFsServer};
+use wip_fs_server::{AccessMode, ServerConfig, 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 listen: SocketAddr = "127.0.0.1:8080".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() {
@@ -17,12 +16,6 @@ fn main() -> Result<(), Box<dyn Error>> {
            "--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(());
@@ -32,20 +25,17 @@ fn main() -> Result<(), Box<dyn Error>> {
    }
    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={}",
+        "wip-fs-server root={} access={access:?} endpoint={} listen={}",
        effective_root.display(),
        endpoint,
        bound.local_addr()
@@ -63,21 +53,10 @@ fn required_value(
        .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\
+        "Usage: wip-fs-server --root PATH [--listen 127.0.0.1:8080] \\\n         [--base-path /wip] [--read-write]\n\n\
-         The built-in listener is cleartext and loopback-only. In production, \
+         The built-in HTTP listener is loopback-only. TLS termination, authentication, \
-         select --behind-tls-proxy and terminate HTTPS at a trusted reverse proxy."
+         and external routing are deployment concerns."
    );
 }
@@ -6,28 +6,19 @@ use std::thread;
 use std::time::{Duration, Instant};
 use http::{Request, Response, StatusCode};
-use wip_host::{ExecutionContext, ObjectProvider};
+use wip_host::ExecutionContext;
-use wip_https::{
+use wip_http::Endpoint;
    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::engine::Projection;
-use crate::{ConfigError, ServerConfig};
+use crate::http_adapter::HttpAdapter;
 use crate::{ConfigError, DefaultComposition, DefaultPolicy, LinuxBackend, ServerConfig};
-/// Filesystem projection and framework-neutral standard WIP request adapter.
+/// Default Linux filesystem projection and bounded loopback HTTP listener.
 pub struct WipFsServer {
    config: ServerConfig,
    endpoint: Endpoint,
    effective_root: std::path::PathBuf,
-    projection: Arc<Projection>,
+    projection: Arc<Projection<LinuxBackend, DefaultComposition, DefaultPolicy>>,
 }
 impl WipFsServer {
@@ -35,8 +26,8 @@ impl WipFsServer {
    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 projection = crate::default_projection(&config.root, config.access, config.limits)?;
-        let effective_root = projection.effective_root()?;
+        let effective_root = projection.backend().effective_root()?;
        Ok(Self {
            config,
            endpoint,
@@ -57,7 +48,7 @@ impl WipFsServer {
        &self.endpoint
    }
-    /// Handles one already-buffered HTTP request with the standard `wip-https` codecs.
+    /// Handles one already-buffered HTTP request with the standard `wip-http` codecs.
    ///
    /// Listener integrations must enforce the same body limit while collecting bytes.
    #[must_use]
@@ -70,28 +61,19 @@ impl WipFsServer {
        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));
+            .with_resource_budget(u64::from(self.config.limits.max_observation_nodes));
-        match route {
+        let view = self.projection.view(&());
-            Route::Fetch => self.fetch(request.body(), &context),
+        HttpAdapter::new(&view, &self.endpoint, self.config.limits)
-            Route::FetchTree => self.fetch_tree(request.body(), &context),
+            .handle_http_with_context(request, &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
+    /// The built-in listener is cleartext and loopback-only. Externally visible
-    /// whether TLS is terminated by a reverse proxy or development HTTP is in use.
+    /// schemes, TLS termination, authentication, and proxy routing are deployment
    /// concerns rather than WIP transport profiles.
    pub fn bind(self) -> Result<BoundServer, ServerBuildError> {
        let listener = TcpListener::bind(self.config.listen)
            .map_err(|error| ServerBuildError::Listener(error.to_string()))?;
@@ -107,259 +89,6 @@ impl WipFsServer {
            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`].
@@ -428,7 +157,7 @@ struct ParsedRequestHead {
 enum IntakeError {
    Timeout,
    HeaderTooLarge,
-    PayloadTooLarge { target: String },
+    PayloadTooLarge,
    BadRequest,
    Socket,
 }
@@ -449,9 +178,7 @@ fn serve_connection(service: &WipFsServer, mut stream: TcpStream) {
        Err(IntakeError::HeaderTooLarge) => {
            Some(empty_response(StatusCode::REQUEST_HEADER_FIELDS_TOO_LARGE))
        }
-        Err(IntakeError::PayloadTooLarge { target }) => {
+        Err(IntakeError::PayloadTooLarge) => Some(empty_response(StatusCode::PAYLOAD_TOO_LARGE)),
            Some(payload_too_large_response(service, &target))
        }
        Err(IntakeError::BadRequest) => Some(empty_response(StatusCode::BAD_REQUEST)),
        Err(IntakeError::Timeout | IntakeError::Socket) => None,
    };
@@ -490,9 +217,7 @@ fn read_http_request(
    let parsed = parse_request_head(&received[..header_end])?;
    if parsed.content_length > maximum_body {
-        return Err(IntakeError::PayloadTooLarge {
+        return Err(IntakeError::PayloadTooLarge);
            target: parsed.target,
        });
    }
    let mut body = Vec::with_capacity(parsed.content_length);
    let buffered = &received[header_end..];
@@ -591,27 +316,6 @@ fn read_with_deadline(
    })
 }
 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>>,
@@ -672,30 +376,6 @@ fn write_all_with_deadline(
    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)
@@ -7,28 +7,26 @@ use std::thread;
 use std::time::{Duration, Instant};
 use tempfile::tempdir;
-use wip_fs_server::{AccessMode, ServerConfig, TransportSecurity, WipFsServer};
+use wip_fs_server::{AccessMode, ServerConfig, WipFsServer};
-use wip_https::{
+use wip_http::{
-    BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse, BatchSuccess, DecodedResponse,
+    ClientResponseError, DecodedResponse, Endpoint, JSON_CONTENT_TYPE, Limits, Route,
-    Endpoint, JSON_CONTENT_TYPE, Limits, Route, decode_batch_request, decode_batch_response,
+    TransportFailureKind, decode_call_operation_response, decode_fetch_interface_response,
-    decode_call_operation_response, decode_fetch_interface_response, decode_fetch_response,
+    decode_observe_response, encode_call_operation_request, encode_fetch_interface_request,
-    decode_fetch_tree_response, encode_batch_request, encode_call_operation_request,
+    encode_observe_request,
    encode_fetch_interface_request, encode_fetch_request, encode_fetch_tree_request,
 };
 use wip_protocol::{
-    CallOperationRequest, FetchInterfaceRequest, FetchRequest, FetchTreeRequest, InterfaceTarget,
+    CallOperationRequest, FetchInterfaceRequest, InterfaceTarget, ObserveRequest,
    ProtocolErrorCode, Target, Value,
 };
 #[test]
-fn real_listener_serves_four_core_interactions_batch_and_write() {
+fn real_listener_serves_three_core_interactions_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)
@@ -43,35 +41,42 @@ fn real_listener_serves_four_core_interactions_batch_and_write() {
        let shutdown = Arc::clone(&shutdown);
        thread::spawn(move || bound.serve_until(shutdown))
    };
-    let endpoint = Endpoint::parse(&format!("https://localhost:{}/wip", address.port()))
+    let endpoint = Endpoint::parse(&format!("http://localhost:{}/wip", address.port()))
        .expect("client endpoint");
-    let file_request = FetchRequest {
+    let file_request = ObserveRequest {
        path: "/hello.txt".into(),
        depth: 0,
    };
    let response = exchange(
        address,
-        encode_fetch_request(&endpoint, &file_request, limits).expect("encode fetch"),
+        encode_observe_request(&endpoint, &file_request, limits).expect("encode observation"),
    );
-    let file =
+    let file = success(
-        success(decode_fetch_response(&file_request, &response, limits).expect("decode fetch"));
+        decode_observe_response(&file_request, &response, limits).expect("decode observation"),
    )
    .object;
    assert_eq!(file.name, "hello.txt");
    assert_eq!(file.interfaces.len(), 2);
    assert!(file.validator.is_some());
-    let tree_request = FetchTreeRequest {
+    let tree_request = ObserveRequest {
        path: "/".into(),
        depth: 1,
        limit: 10,
    };
    let response = exchange(
        address,
-        encode_fetch_tree_request(&endpoint, &tree_request, limits).expect("encode tree"),
+        encode_observe_request(&endpoint, &tree_request, limits).expect("encode tree"),
    );
    let tree =
-        success(decode_fetch_tree_response(&tree_request, &response, limits).expect("decode tree"));
+        success(decode_observe_response(&tree_request, &response, limits).expect("decode tree"));
-    assert!(!tree.truncated);
+    assert_eq!(
-    assert_eq!(tree.root.children.len(), 2);
+        tree.children
            .as_ref()
            .expect("root children observed")
            .len(),
        2
    );
    let read_interface_request = FetchInterfaceRequest {
        interface: file.interfaces[0].clone(),
@@ -93,6 +98,7 @@ fn real_listener_serves_four_core_interactions_batch_and_write() {
            validator: file.validator.clone(),
        },
        interface: InterfaceTarget {
            scope_ref: None,
            reference: file.interfaces[0].clone(),
            validator: None,
        },
@@ -118,34 +124,6 @@ fn real_listener_serves_four_core_interactions_batch_and_write() {
    );
    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(),
    };
@@ -164,6 +142,7 @@ fn real_listener_serves_four_core_interactions_batch_and_write() {
            validator: file.validator,
        },
        interface: InterfaceTarget {
            scope_ref: None,
            reference: file.interfaces[1].clone(),
            validator: None,
        },
@@ -202,11 +181,166 @@ fn real_listener_serves_four_core_interactions_batch_and_write() {
        .expect("listener exits cleanly");
 }
 #[test]
 fn real_listener_keeps_route_method_and_malformed_body_boundaries_distinct() {
    let temporary = tempdir().expect("temporary root");
    let mut config = ServerConfig::for_root(temporary.path());
    config.limits.wire = Limits::new(64, 4_096, 64).expect("wire limits");
    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))
    };
    for uri in [
        "/wip/v1/unknown",
        "/wip/v1/batch",
        "/wip/v1/observe?unexpected=true",
        "/wip/v1/observe/extra",
    ] {
        let response = exchange(address, json_request(http::Method::POST, uri, b"{}"));
        assert_eq!(response.status(), http::StatusCode::NOT_FOUND);
        assert!(response.body().is_empty());
        assert!(!response.headers().contains_key(http::header::CONTENT_TYPE));
        assert!(!response.headers().contains_key(http::header::ALLOW));
    }
    let wrong_method = exchange(
        address,
        json_request(http::Method::GET, "/wip/v1/observe", b""),
    );
    assert_eq!(wrong_method.status(), http::StatusCode::METHOD_NOT_ALLOWED);
    assert_eq!(wrong_method.headers()[http::header::ALLOW], "POST");
    assert!(wrong_method.body().is_empty());
    assert!(
        !wrong_method
            .headers()
            .contains_key(http::header::CONTENT_TYPE)
    );
    let mut unsupported_coding = json_request(
        http::Method::POST,
        "/wip/v1/observe",
        br#"{"path":"/","depth":0}"#,
    );
    unsupported_coding
        .headers_mut()
        .insert(http::header::CONTENT_ENCODING, "gzip".parse().unwrap());
    let unsupported_coding = exchange(address, unsupported_coding);
    assert_eq!(
        unsupported_coding.status(),
        http::StatusCode::UNSUPPORTED_MEDIA_TYPE
    );
    assert!(unsupported_coding.body().is_empty());
    assert!(
        !unsupported_coding
            .headers()
            .contains_key(http::header::CONTENT_TYPE)
    );
    let malformed = exchange(
        address,
        json_request(http::Method::POST, "/wip/v1/observe", b"{"),
    );
    assert_eq!(malformed.status(), http::StatusCode::BAD_REQUEST);
    assert_eq!(
        malformed.headers()[http::header::CONTENT_TYPE],
        JSON_CONTENT_TYPE
    );
    assert!(
        std::str::from_utf8(malformed.body())
            .expect("UTF-8 error envelope")
            .contains("\"invalid_request\"")
    );
    let oversized = exchange(
        address,
        json_request(http::Method::POST, "/wip/v1/observe", &[b'x'; 65]),
    );
    assert_eq!(oversized.status(), http::StatusCode::PAYLOAD_TOO_LARGE);
    assert!(oversized.body().is_empty());
    assert!(!oversized.headers().contains_key(http::header::CONTENT_TYPE));
    let mut header_only = TcpStream::connect(address).expect("connect header-only client");
    header_only
        .set_read_timeout(Some(Duration::from_secs(1)))
        .expect("set header-only timeout");
    write!(
        header_only,
        "POST /wip/v1/observe HTTP/1.1\r\nHost: localhost\r\nContent-Type: application/json\r\nContent-Length: 65\r\n\r\n"
    )
    .expect("write oversized request head");
    header_only.flush().expect("flush oversized request head");
    let mut raw = Vec::new();
    header_only
        .read_to_end(&mut raw)
        .expect("read immediate limit response");
    assert!(raw.starts_with(b"HTTP/1.1 413 "));
    assert!(raw.ends_with(b"\r\n\r\n"));
    assert!(
        !raw.windows(b"resource_limit_exceeded".len())
            .any(|window| { window == b"resource_limit_exceeded" })
    );
    shutdown.store(true, Ordering::Release);
    worker
        .join()
        .expect("join listener")
        .expect("listener exits cleanly");
 }
 #[test]
 fn raw_decoder_limits_are_transport_failures() {
    let temporary = tempdir().expect("temporary root");
    let mut config = ServerConfig::for_root(temporary.path());
    config.limits.wire = Limits::new(4_096, 4_096, 8).expect("wire limits");
    let server = WipFsServer::new(config).expect("build server");
    let nested = br#"{"path":[[[[[[[[["/"]]]]]]]]],"depth":0}"#;
    let response = server.handle_http(json_request(http::Method::POST, "/wip/v1/observe", nested));
    assert_eq!(response.status(), http::StatusCode::PAYLOAD_TOO_LARGE);
    assert!(response.body().is_empty());
    assert!(!response.headers().contains_key(http::header::CONTENT_TYPE));
 }
 #[test]
 fn logical_observation_limit_remains_protocol_resource_failure() {
    let temporary = tempdir().expect("temporary root");
    let mut config = ServerConfig::for_root(temporary.path());
    config.limits.max_observation_depth = 0;
    let limits = config.limits.wire;
    let server = WipFsServer::new(config).expect("build server");
    let endpoint = Endpoint::parse("http://localhost/wip").expect("endpoint");
    let request = ObserveRequest {
        path: "/".into(),
        depth: 1,
    };
    let response = server.handle_http(
        encode_observe_request(&endpoint, &request, limits).expect("encode observation"),
    );
    assert_eq!(response.status(), http::StatusCode::UNPROCESSABLE_ENTITY);
    assert!(matches!(
        decode_observe_response(&request, &response, limits).expect("decode logical limit"),
        DecodedResponse::ProtocolFailure {
            error,
            status_mismatch: None,
        } if error.code == ProtocolErrorCode::ResourceLimitExceeded
    ));
 }
 #[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;
@@ -230,21 +364,25 @@ fn stalled_request_body_times_out_and_releases_the_only_worker() {
        .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{{"
+        "POST /wip/v1/observe 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()))
+    let endpoint = Endpoint::parse(&format!("http://localhost:{}/wip", address.port()))
        .expect("client endpoint");
-    let fetch = FetchRequest { path: "/".into() };
+    let observe = ObserveRequest {
        path: "/".into(),
        depth: 0,
    };
    let started = Instant::now();
    let response = exchange(
        address,
-        encode_fetch_request(&endpoint, &fetch, limits).expect("encode fetch"),
+        encode_observe_request(&endpoint, &observe, limits).expect("encode observation"),
    );
-    let _root = success(decode_fetch_response(&fetch, &response, limits).expect("decode fetch"));
+    let _root =
        success(decode_observe_response(&observe, &response, limits).expect("decode observation"));
    assert!(
        started.elapsed() < Duration::from_secs(1),
        "the valid request remained starved after the intake deadline"
@@ -270,44 +408,13 @@ fn stalled_request_body_times_out_and_releases_the_only_worker() {
        .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 endpoint = Endpoint::parse("http://localhost/wip").expect("endpoint");
-    let body = br#"{"target":{"path":"/missing"},"interface":{"reference":"unknown"},"operation":"missing","arguments":{"bytes":"not-base64"}}"#;
+    let body = br#"{"target":{"path":"/missing"},"interface":{"reference":{"scope":"/","name":"unknown"}},"operation":"missing","arguments":{"bytes":"not-base64"}}"#;
    let request = http::Request::builder()
        .method(http::Method::POST)
        .uri(endpoint.route(Route::CallOperation).as_str())
@@ -330,14 +437,16 @@ fn backend_invalid_unicode_path_is_not_found_not_internal() {
    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 endpoint = Endpoint::parse("http://localhost/wip").expect("endpoint");
-    let request = FetchRequest {
+    let request = ObserveRequest {
        path: "/bad\0name".into(),
        depth: 0,
    };
-    let response = server
+    let response = server.handle_http(
-        .handle_http(encode_fetch_request(&endpoint, &request, limits).expect("encode fetch"));
+        encode_observe_request(&endpoint, &request, limits).expect("encode observation"),
    );
    assert_eq!(response.status(), http::StatusCode::NOT_FOUND);
-    match decode_fetch_response(&request, &response, limits).expect("decode missing response") {
+    match decode_observe_response(&request, &response, limits).expect("decode missing response") {
        DecodedResponse::ProtocolFailure { error, .. } => {
            assert_eq!(error.code, ProtocolErrorCode::NotFound);
        }
@@ -346,23 +455,26 @@ fn backend_invalid_unicode_path_is_not_found_not_internal() {
 }
 #[test]
-fn read_response_size_failure_preserves_non_commit_guarantee() {
+fn read_response_size_failure_is_transport_local() {
    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");
+    config.limits.wire = Limits::new(4_096, 1_024, 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 endpoint = Endpoint::parse("http://localhost/wip").expect("endpoint");
-    let fetch_request = FetchRequest {
+    let observe_request = ObserveRequest {
        path: "/large".into(),
        depth: 0,
    };
    let response = server.handle_http(
-        encode_fetch_request(&endpoint, &fetch_request, limits).expect("encode fetch"),
+        encode_observe_request(&endpoint, &observe_request, limits).expect("encode observation"),
    );
-    let file =
+    let file = success(
-        success(decode_fetch_response(&fetch_request, &response, limits).expect("decode fetch"));
+        decode_observe_response(&observe_request, &response, limits).expect("decode observation"),
    )
    .object;
    let interface_request = FetchInterfaceRequest {
        interface: file.interfaces[0].clone(),
    };
@@ -380,6 +492,7 @@ fn read_response_size_failure_preserves_non_commit_guarantee() {
            validator: file.validator,
        },
        interface: InterfaceTarget {
            scope_ref: None,
            reference: file.interfaces[0].clone(),
            validator: None,
        },
@@ -390,30 +503,15 @@ fn read_response_size_failure_preserves_non_commit_guarantee() {
        encode_call_operation_request(&endpoint, &call, &interface.descriptor, limits)
            .expect("encode read call"),
    );
-    assert_eq!(response.status(), http::StatusCode::PAYLOAD_TOO_LARGE);
+    assert_eq!(response.status(), http::StatusCode::INTERNAL_SERVER_ERROR);
-    match decode_call_operation_response(&call, &interface.descriptor, &response, limits)
+    assert!(response.body().is_empty());
-        .expect("decode resource failure")
+    assert!(!response.headers().contains_key(http::header::CONTENT_TYPE));
    {
        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,
+        decode_call_operation_response(&call, &interface.descriptor, &response, limits)
-        Ok(BatchSuccess::Fetch(_))
+            .expect_err("oversized representation is not a protocol failure"),
-    ));
+        ClientResponseError::TransportBinding(failure)
-    assert!(matches!(
+            if failure.status == http::StatusCode::INTERNAL_SERVER_ERROR
-        batch.responses[1].outcome,
+                && failure.kind == TransportFailureKind::HttpStatus
        Ok(BatchSuccess::FetchTree(_))
    ));
    assert!(matches!(
        batch.responses[2].outcome,
        Ok(BatchSuccess::FetchInterface(_))
    ));
 }
@@ -424,6 +522,16 @@ fn success<T>(response: DecodedResponse<T>) -> T {
    }
 }
 fn json_request(method: http::Method, uri: &str, body: &[u8]) -> http::Request<Vec<u8>> {
    http::Request::builder()
        .method(method)
        .uri(uri)
        .header(http::header::CONTENT_TYPE, JSON_CONTENT_TYPE)
        .header(http::header::ACCEPT, "application/json")
        .body(body.to_vec())
        .expect("build JSON request")
 }
 fn exchange(address: SocketAddr, request: http::Request<Vec<u8>>) -> http::Response<Vec<u8>> {
    let mut stream = TcpStream::connect(address).expect("connect listener");
    stream
@@ -0,0 +1,456 @@
 //! External non-root scope regression coverage, sharing the memory backend.
 use super::*;
 struct ScopedObject {
    inner: Object,
    reference: Option<String>,
 }
 impl WipObject for ScopedObject {
    fn name(&self) -> &str {
        self.inner.name()
    }
    fn reference(&self) -> Option<&str> {
        self.reference.as_deref()
    }
    fn validator(&self) -> Option<&Validator> {
        self.inner.validator()
    }
    fn requires_validator(&self, _: &InterfaceRef, operation: &str) -> bool {
        operation == "read"
    }
 }
 impl FileRead for ScopedObject {
    fn read(&self, offset: Option<u64>, length: Option<u64>) -> wip::OperationResult<wip::Bytes> {
        FileRead::read(&self.inner, offset, length)
    }
 }
 struct ScopedComposition {
    shared: Arc<Shared>,
    associations: BTreeMap<String, (Arc<Node>, Scope)>,
    interfaces: Vec<RegisteredInterface<wip_fs_server::FileReadDefinition>>,
    with_refs: bool,
 }
 impl Composition<Entry> for ScopedComposition {
    type Object = ScopedObject;
    fn scope(
        &self,
        path: &str,
        entry: &Entry,
        context: &ExecutionContext,
    ) -> Result<Option<Scope>, HostError> {
        assert!(matches!(
            self.shared.transaction.try_lock(),
            Err(TryLockError::WouldBlock)
        ));
        assert_eq!(path, entry.path);
        self.shared.record("scope", path, context);
        assert_eq!(
            entry.validator,
            Entry::snapshot(entry.path.clone(), entry.node.clone()).validator
        );
        let nodes = self.shared.nodes.lock().unwrap();
        // Self-scope also requires current membership; ordinary pinned-leaf
        // execution intentionally need not check its path mapping.
        Ok(self.associations.get(path).and_then(|(identity, scope)| {
            (Arc::ptr_eq(identity, &entry.node)
                && nodes
                    .get(path)
                    .is_some_and(|node| Arc::ptr_eq(node, identity)))
            .then(|| scope.clone())
        }))
    }
    fn publish(
        &self,
        entry: Entry,
        context: &ExecutionContext,
    ) -> Result<PublishedObject<ScopedObject>, HostError> {
        assert!(matches!(
            self.shared.transaction.try_lock(),
            Err(TryLockError::WouldBlock)
        ));
        self.shared.record("scoped_publish", &entry.path, context);
        let path = entry.path.clone();
        let regular = entry.kind() == EntryKind::Regular;
        let reference = self
            .with_refs
            .then(|| format!("published-object-{}", entry.node.id));
        let mut publication = PublishedObject::new(ScopedObject {
            inner: Object {
                entry,
                custom: self.interfaces[0].reference().clone(),
                shared: self.shared.clone(),
                context: context.clone(),
            },
            reference,
        });
        // Containers expose no interfaces but remain valid fetch subjects.
        if regular {
            for interface in &self.interfaces {
                if interface
                    .reference()
                    .protocol_reference()
                    .validate_for_path(&path)
                    .is_ok()
                {
                    publication = publication.expose(interface).unwrap();
                }
            }
        }
        Ok(publication)
    }
 }
 struct ScopedPolicy;
 impl ProjectionPolicy<Entry, ScopedObject> for ScopedPolicy {
    type Principal = Principal;
    fn object_visible(&self, principal: &Principal, entry: &Entry) -> bool {
        !entry.hidden && (!matches!(principal, Principal::Limited) || entry.path != "/secret")
    }
    fn interface_visible(&self, principal: &Principal, interface: &InterfaceRef) -> bool {
        !(matches!(principal, Principal::Limited)
            && interface.protocol_reference().scope == "/added")
    }
 }
 type ScopedEngine = Projection<MemoryBackend, ScopedComposition, ScopedPolicy>;
 fn scoped_engine(shared: Arc<Shared>, with_refs: bool) -> ScopedEngine {
    configured_engine(shared, with_refs, None)
 }
 fn configured_engine(
    shared: Arc<Shared>,
    with_refs: bool,
    interface_validator: Option<Validator>,
 ) -> ScopedEngine {
    let mut registry = InterfaceRegistry::new();
    let mut associations = BTreeMap::new();
    let mut interfaces = Vec::new();
    for path in ["/", "/secret", "/secret/nested", "/added"] {
        let scope = Scope::new(path).unwrap();
        let validator = if path == "/secret" {
            interface_validator.clone()
        } else {
            None
        };
        interfaces.push(
            registry
                .register(
                    &scope,
                    "file.read",
                    wip_fs_server::FileReadDefinition,
                    validator,
                )
                .unwrap(),
        );
        associations.insert(path.into(), (shared.node(path), scope));
    }
    Projection::new(
        MemoryBackend::new(shared.clone()),
        registry,
        ScopedComposition {
            shared,
            associations,
            interfaces,
            with_refs,
        },
        ScopedPolicy,
        ResourceLimits::default(),
    )
 }
 fn reference(scope: &str) -> wip_protocol::InterfaceReference {
    wip_protocol::InterfaceReference {
        scope: scope.into(),
        name: "file.read".into(),
    }
 }
 fn request(path: &str, scope: &str, scope_ref: Option<String>) -> CallOperationRequest {
    CallOperationRequest {
        target: Target {
            path: path.into(),
            validator: None,
        },
        interface: InterfaceTarget {
            reference: reference(scope),
            scope_ref,
            validator: None,
        },
        operation: "read".into(),
        arguments: BTreeMap::new(),
    }
 }
 #[test]
 fn nonroot_observe_fetch_call_with_optional_refs_over_http() {
    for with_refs in [false, true] {
        let fixture = Fixture::new();
        let engine = scoped_engine(fixture.shared.clone(), with_refs);
        let view = engine.view(&Principal::Admin);
        let limits = ResourceLimits::default();
        let endpoint = Endpoint::parse("https://example.test/scopes").unwrap();
        let adapter = HttpAdapter::new(&view, &endpoint, limits);
        for (path, scope) in [("/secret/nested/data", "/secret"), ("/added", "/added")] {
            let observe = observe_request(path, 0);
            let response = adapter.handle_http_with_context(
                encode_observe_request(&endpoint, &observe, limits.wire).unwrap(),
                &ExecutionContext::new(),
            );
            let DecodedResponse::Success(observed) =
                decode_observe_response(&observe, &response, limits.wire).unwrap()
            else {
                panic!("observation must succeed");
            };
            assert!(observed.object.interfaces.contains(&reference(scope)));
            let fetch = fetch_request(&reference(scope));
            let response = adapter.handle_http_with_context(
                encode_fetch_interface_request(&endpoint, &fetch, limits.wire).unwrap(),
                &ExecutionContext::new(),
            );
            let DecodedResponse::Success(fetched) =
                decode_fetch_interface_response(&fetch, &response, limits.wire).unwrap()
            else {
                panic!("fetch must succeed");
            };
            assert_eq!(
                fetched.scope_ref,
                with_refs.then(|| format!("published-object-{}", fixture.shared.node(scope).id))
            );
            let mut call = request(path, scope, fetched.scope_ref);
            call.target.validator = observed.object.validator;
            let response = adapter.handle_http_with_context(
                encode_call_operation_request(&endpoint, &call, &fetched.descriptor, limits.wire)
                    .unwrap(),
                &ExecutionContext::new(),
            );
            let DecodedResponse::Success(result) =
                decode_call_operation_response(&call, &fetched.descriptor, &response, limits.wire)
                    .unwrap()
            else {
                panic!("call must succeed");
            };
            assert_eq!(result.result, Value::Bytes(b"hello memory".to_vec()));
            if !with_refs {
                call.interface.scope_ref = Some("ref-not-provided-by-publication".into());
                assert_eq!(
                    view.call_operation(call).unwrap_err().kind(),
                    wip_host::CallErrorKind::InterfaceMismatch
                );
            }
        }
        assert!(
            view.observe_object("/secret")
                .unwrap()
                .interfaces
                .is_empty()
        );
        assert_eq!(
            view.observe_object("/secret/nested/data")
                .unwrap()
                .interfaces,
            [
                reference("/"),
                reference("/secret"),
                reference("/secret/nested")
            ]
        );
        let limited = engine.view(&Principal::Limited);
        for scope in ["/secret", "/secret/nested", "/added"] {
            assert_eq!(
                limited
                    .fetch_interface(&fetch_request(&reference(scope)))
                    .unwrap_err()
                    .code,
                ProtocolErrorCode::InterfaceNotFound
            );
        }
        assert_eq!(
            limited
                .observe_object("/secret/nested/data")
                .unwrap_err()
                .kind(),
            wip_host::CallErrorKind::NotFound
        );
        assert!(
            !limited
                .observe_object("/added")
                .unwrap()
                .interfaces
                .contains(&reference("/added"))
        );
    }
 }
 #[test]
 fn scope_refs_and_object_validator_precedence_use_current_atomic_lineage() {
    let fixture = Fixture::new();
    let engine = scoped_engine(fixture.shared.clone(), true);
    let view = engine.view(&Principal::Admin);
    let mut call = request("/secret/nested/data", "/secret", Some("stale".into()));
    call.target.validator = Some(vec![0]);
    assert_eq!(
        view.call_operation(call.clone()).unwrap_err().kind(),
        wip_host::CallErrorKind::ValidatorMismatch
    );
    call.target.validator = view.observe_object(&call.target.path).unwrap().validator;
    assert_eq!(
        view.call_operation(call.clone()).unwrap_err().kind(),
        wip_host::CallErrorKind::InterfaceMismatch
    );
    call.interface.scope_ref = view
        .fetch_interface(&fetch_request(&call.interface.reference))
        .unwrap()
        .scope_ref;
    // Scope state changes do not retire its lifetime; the published ref is not
    // its validator, and the hook runs on refreshed metadata under the lock.
    fixture.shared.controls.lock().unwrap().bump_ancestor = Some("/secret".into());
    fixture.shared.seen.lock().unwrap().clear();
    view.call_operation(call).unwrap();
    let seen = fixture.shared.seen.lock().unwrap();
    let resolves: Vec<_> = seen
        .iter()
        .filter(|event| event.stage == "resolve")
        .map(|event| event.path.as_str())
        .collect();
    assert_eq!(resolves, ["/secret/nested/data"]);
    assert!(
        seen.iter()
            .any(|event| event.stage == "scope" && event.path == "/secret")
    );
 }
 #[test]
 fn nonroot_interface_validator_checks_follow_scope_ref_checks() {
    let fixture = Fixture::new();
    let engine = configured_engine(fixture.shared.clone(), true, Some(Validator::new(vec![7])));
    let view = engine.view(&Principal::Admin);
    let fetched = view
        .fetch_interface(&fetch_request(&reference("/secret")))
        .unwrap();
    assert_eq!(fetched.validator, Some(vec![7]));
    let mut call = request("/secret/nested/data", "/secret", Some("stale".into()));
    call.target.validator = view.observe_object(&call.target.path).unwrap().validator;
    assert_eq!(
        view.call_operation(call.clone()).unwrap_err().kind(),
        wip_host::CallErrorKind::InterfaceMismatch
    );
    call.interface.scope_ref = fetched.scope_ref;
    assert_eq!(
        view.call_operation(call.clone()).unwrap_err().kind(),
        wip_host::CallErrorKind::InterfaceValidatorRequired
    );
    call.interface.validator = Some(vec![8]);
    assert_eq!(
        view.call_operation(call.clone()).unwrap_err().kind(),
        wip_host::CallErrorKind::InterfaceValidatorMismatch
    );
    assert!(
        fixture
            .shared
            .node(&call.target.path)
            .calls
            .lock()
            .unwrap()
            .is_empty()
    );
    call.interface.validator = fetched.validator;
    view.call_operation(call).unwrap();
 }
 #[test]
 fn visibility_and_replacement_races_reject_before_dispatch() {
    for replace in [false, true] {
        let fixture = Fixture::new();
        let engine = scoped_engine(fixture.shared.clone(), false);
        let view = engine.view(&Principal::Admin);
        let mut call = request("/secret/nested/data", "/secret", None);
        call.target.validator = view.observe_object(&call.target.path).unwrap().validator;
        let leaf = fixture.shared.node(&call.target.path);
        if replace {
            fixture.shared.controls.lock().unwrap().replace_ancestor = Some("/secret".into());
        } else {
            fixture.shared.controls.lock().unwrap().hide_ancestor = Some("/secret".into());
        }
        assert_eq!(
            view.call_operation(call).unwrap_err().kind(),
            wip_host::CallErrorKind::NotFound
        );
        assert!(leaf.calls.lock().unwrap().is_empty());
        assert_eq!(
            view.fetch_interface(&fetch_request(&reference("/secret")))
                .unwrap_err()
                .code,
            ProtocolErrorCode::InterfaceNotFound
        );
    }
 }
 #[test]
 fn deletion_replacement_and_self_scope_do_not_reuse_registry_lifetimes() {
    for with_refs in [false, true] {
        let fixture = Fixture::new();
        let engine = scoped_engine(fixture.shared.clone(), with_refs);
        let view = engine.view(&Principal::Admin);
        let old_scope = fixture.shared.node("/secret");
        let old_ref = view
            .fetch_interface(&fetch_request(&reference("/secret")))
            .unwrap()
            .scope_ref;
        fixture.shared.nodes.lock().unwrap().remove("/secret");
        assert_eq!(
            view.fetch_interface(&fetch_request(&reference("/secret")))
                .unwrap_err()
                .code,
            ProtocolErrorCode::InterfaceNotFound
        );
        // Reuse even the same id/public ref: refs cannot attest a lifetime.
        fixture.shared.nodes.lock().unwrap().insert(
            "/secret".into(),
            Arc::new(Node {
                id: old_scope.id,
                kind: EntryKind::Directory,
                data: Mutex::new(old_scope.data.lock().unwrap().clone()),
                calls: Mutex::new(Vec::new()),
            }),
        );
        assert_eq!(
            view.fetch_interface(&fetch_request(&reference("/secret")))
                .unwrap_err()
                .code,
            ProtocolErrorCode::InterfaceNotFound
        );
        let mut call = request("/secret/nested/data", "/secret", old_ref);
        call.target.validator = view.observe_object(&call.target.path).unwrap().validator;
        assert_eq!(
            view.call_operation(call).unwrap_err().kind(),
            wip_host::CallErrorKind::InterfaceMismatch
        );
        assert!(
            fixture
                .shared
                .node("/secret/nested/data")
                .calls
                .lock()
                .unwrap()
                .is_empty()
        );
        // Fresh registration/engine attests the new publication.
        let republished = scoped_engine(fixture.shared.clone(), with_refs);
        republished
            .view(&Principal::Admin)
            .fetch_interface(&fetch_request(&reference("/secret")))
            .unwrap();
        // Scope == target: ordinary execution pins the old leaf, but cannot
        // attest it as the current scope after its mapping is replaced.
        let leaf = fixture.shared.node("/added");
        let mut call = request("/added", "/added", None);
        call.target.validator = view.observe_object("/added").unwrap().validator;
        fixture.shared.controls.lock().unwrap().replace_mapping = true;
        assert_eq!(
            view.call_operation(call).unwrap_err().kind(),
            wip_host::CallErrorKind::InterfaceMismatch
        );
        assert!(leaf.calls.lock().unwrap().is_empty());
        assert_eq!(
            view.fetch_interface(&fetch_request(&reference("/added")))
                .unwrap_err()
                .code,
            ProtocolErrorCode::InterfaceNotFound
        );
    }
 }
@@ -1,13 +1,17 @@
 [package]
 name = "wip-host"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
 rust-version.workspace = true
 description = "Host-side object publication and operation dispatch for WIP"
-license = "MIT OR Apache-2.0"
+license.workspace = true
 repository.workspace = true
 readme = "README.md"
 documentation = "https://docs.rs/wip-host"
 [dependencies]
-wip-interface = { path = "../wip-interface" }
+wip-interface.workspace = true
-wip-protocol = { path = "../wip-protocol" }
+wip-protocol.workspace = true
 [dev-dependencies]
 trybuild = "1"
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Hare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,19 @@
 # wip-host
 Framework-independent Host publication and operation dispatch for the Worldspace Interface Protocol (WIP).
 `wip-host` registers generated interfaces, explicitly publishes them on request-scoped objects, validates object and interface preconditions, and performs interface-qualified operation dispatch against one host-owned instance. Backend transactions, persistence, and network serving remain application responsibilities.
 ```toml
 [dependencies]
 wip-host = "0.2.0"
 wip-interface = "0.2.0"
 ```
 Protocol publication and dispatch use `wip_protocol::InterfaceReference { scope, name }` and compare both fields exactly. Registration takes an explicit `Scope` and local name; `InterfaceRef::protocol_reference()` preserves those coordinates without parsing display text. Providers attach a current `ScopeObservation` inside the coherent backend boundary, and fetch returns its optional Object ref as `scope_ref`. Calls check a supplied `scope_ref` against that current binding; omission adds no identity precondition. Retire a Scope on Object deletion, replacement or movement; retained registry artifacts alone do not establish publication.
 Malformed interface-reference shapes fail calls as `InvalidRequest` before object resolution. A well-shaped reference outside the target path's ancestor-or-self scope fails at the membership check as `InterfaceMismatch`.
 See the [API documentation](https://docs.rs/wip-host) for publication, provider, execution-context, and effect-guarantee boundaries.
 Licensed under either of Apache-2.0 or MIT at your option.
@@ -1,9 +1,9 @@
-//! Host-side publication and operation dispatch for Web Interface Protocol objects.
+//! Host-side publication and operation dispatch for Worldspace Interface Protocol objects.
 //!
 //! # Responsibility boundaries
 //!
 //! [`InterfaceRegistry::register`] validates and freezes a generated interface
-//! descriptor, assigns an opaque [`InterfaceRef`], and leaves that reference
+//! descriptor at an explicit scope and local name, and leaves that reference
 //! outside the descriptor. [`PublishedObject::expose`] explicitly combines a
 //! request-scoped Rust object with a registered interface; its
 //! [`InterfaceImplementation`] bound proves at compile time that the object
@@ -11,7 +11,8 @@
 //! and a publication with no interfaces is valid.
 //!
 //! [`ObjectProvider::call_operation`] resolves `target.path` exactly once and
-//! keeps the resulting object, interface membership, descriptor, implementation,
+//! keeps the resulting object, current scope Object association/ref, interface
 //! membership, descriptor, implementation,
 //! and backend target fixed within the provider's [`ObjectProvider::with_object`]
 //! callback. Dispatch is qualified by `(interface reference, operation name)`.
 //! The same frozen operation declaration validates both arguments and results.
@@ -29,14 +30,13 @@
 #![deny(missing_docs)]
 use std::any::TypeId;
 use std::collections::{BTreeMap, HashMap, HashSet};
 use std::error::Error;
 use std::fmt::{self, Display, Formatter};
 use std::marker::PhantomData;
 use std::panic::{AssertUnwindSafe, catch_unwind};
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Instant;
 use wip_interface::DispatchError;
@@ -49,8 +49,8 @@ pub use wip_protocol::{
    Target,
 };
 use wip_protocol::{
-    FetchInterfaceRequest, FetchInterfaceResponse, InterfaceDescriptor, Object, ProtocolError,
+    FetchInterfaceRequest, FetchInterfaceResponse, InterfaceDescriptor, InterfaceReference, Object,
-    ProtocolErrorCode, ValidationError, Value,
+    ProtocolError, ProtocolErrorCode, ValidationError, Value,
 };
 /// Opaque bytes used as a conditional execution precondition.
@@ -187,30 +187,120 @@ impl ExecutionContext {
    }
 }
-/// Opaque host-assigned reference to one registered interface artifact.
+/// One publication lifetime of the Object at a canonical scope path.
 ///
 /// Clone while the same Object remains published, including state updates. Create
 /// a new handle after deletion, replacement or movement, even with the same ref.
 /// This private lifetime is not a Protocol identity component or generated ref.
 #[derive(Debug, Clone)]
 pub struct Scope {
    path: String,
    lifetime: Arc<AtomicBool>,
 }
 impl Scope {
    /// Creates a fresh lifetime without implicitly publishing an Object.
    pub fn new(path: impl Into<String>) -> Result<Self, ValidationError> {
        let path = path.into();
        wip_protocol::validate_path(&path)?;
        Ok(Self {
            path,
            lifetime: Arc::new(AtomicBool::new(true)),
        })
    }
    /// Returns the client-facing canonical scope path.
    #[must_use]
    pub fn path(&self) -> &str {
        &self.path
    }
    fn same_lifetime(&self, other: &Self) -> bool {
        self.path == other.path && Arc::ptr_eq(&self.lifetime, &other.lifetime)
    }
    fn active(&self) -> bool {
        self.lifetime.load(Ordering::Acquire)
    }
 }
 /// Provider-attested current scope Object association.
 ///
 /// Construct only inside a coherent boundary that proves this lifetime belongs
 /// to the Object at `scope.path()`. A prelookup or matching ref alone is not proof.
 /// The Object need not expose interfaces. Its validator is not scope identity.
 #[derive(Debug, Clone)]
 pub struct ScopeObservation {
    scope: Scope,
    reference: Option<String>,
 }
 impl ScopeObservation {
    /// Attests the association and captures the current Object's optional ref.
    #[must_use]
    pub fn new(scope: &Scope, object: &impl WipObject) -> Self {
        Self {
            scope: scope.clone(),
            reference: object.reference().map(str::to_owned),
        }
    }
    /// Returns the observed optional ref.
    #[must_use]
    pub fn reference(&self) -> Option<&str> {
        self.reference.as_deref()
    }
    /// Returns the associated scope publication lifetime.
    #[must_use]
    pub fn scope(&self) -> &Scope {
        &self.scope
    }
 }
 /// Structured client-facing reference to a scoped Interface publication.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct InterfaceRef(String);
+pub struct InterfaceRef(InterfaceReference);
 impl InterfaceRef {
-    /// Returns the opaque reference for a protocol transport.
+    /// Returns the local name without parsing or adding display delimiters.
    #[must_use]
    pub fn as_str(&self) -> &str {
-        &self.0
+        &self.0.name
    }
    /// Returns the structured Protocol reference.
    #[must_use]
    pub fn protocol_reference(&self) -> InterfaceReference {
        self.0.clone()
    }
 }
 /// One atomic observation of an interface reference, descriptor, and validator.
 #[derive(Debug, Clone, PartialEq)]
 pub struct InterfaceObservation {
-    /// Opaque reference selected by published objects and operation calls.
+    /// Structured reference selected by published objects and operation calls.
    pub reference: InterfaceRef,
    /// Canonical descriptor frozen when the interface was registered.
    pub descriptor: InterfaceDescriptor,
    /// Optional ref of the scope Object from this same observation.
    pub scope_ref: Option<String>,
    /// Optional validator. Its presence makes it a required call precondition.
    pub validator: Option<Validator>,
 }
 impl InterfaceObservation {
    /// Restricts this effective view to visible operations and reachable types.
    ///
    /// Registry artifacts are unchanged. When operations are removed, interface-
    /// wide documentation is omitted because it may describe hidden operations.
    /// Providers must use the same predicate for publication and fetch.
    #[must_use]
    pub fn project_operations(mut self, visible: impl Fn(&str) -> bool) -> Self {
        restrict_descriptor(&mut self.descriptor, visible);
        self
    }
    /// Converts this host observation to a validated canonical protocol response.
    ///
    /// A Host-side response construction failure is returned as `Internal`; it is
@@ -218,13 +308,14 @@ impl InterfaceObservation {
    /// local validation error.
    pub fn protocol_response(&self) -> Result<FetchInterfaceResponse, ProtocolError> {
        let response = FetchInterfaceResponse {
-            interface: self.reference.0.clone(),
+            interface: self.reference.protocol_reference(),
            descriptor: self.descriptor.clone(),
            scope_ref: self.scope_ref.clone(),
            validator: self.validator.as_ref().map(|validator| validator.0.clone()),
        };
        response
            .validate_for(&FetchInterfaceRequest {
-                interface: self.reference.0.clone(),
+                interface: self.reference.protocol_reference(),
            })
            .map_err(|_| ProtocolError {
                code: ProtocolErrorCode::Internal,
@@ -236,6 +327,7 @@ impl InterfaceObservation {
 #[derive(Debug)]
 struct InterfaceArtifact {
    scope: Scope,
    reference: InterfaceRef,
    descriptor: InterfaceDescriptor,
    validator: Option<Validator>,
@@ -244,7 +336,7 @@ struct InterfaceArtifact {
 /// A typed registration token for a generated interface definition.
 ///
 /// Tokens can be reused by any number of request-scoped objects. They expose an
-/// opaque reference, not the Rust type name or an address.
+/// scoped reference and a private publication lifetime, not a Rust address.
 pub struct RegisteredInterface<D> {
    artifact: Arc<InterfaceArtifact>,
    definition: PhantomData<fn() -> D>,
@@ -260,158 +352,161 @@ impl<D> Clone for RegisteredInterface<D> {
 }
 impl<D> RegisteredInterface<D> {
-    /// Returns the opaque protocol reference assigned by the registry.
+    /// Returns the explicit scope/name reference.
    #[must_use]
    pub fn reference(&self) -> &InterfaceRef {
        &self.artifact.reference
    }
 }
-/// Registry of validated, immutable interface artifacts.
+/// Registry of frozen definition artifacts and explicitly scoped registrations.
 ///
-/// Generated descriptors are never rewritten to contain their assigned
+/// Artifact retention is not proof of current publication. Fetch requires a live
-/// references. A validator-free artifact is immutable for the lifetime of its
+/// provider-attested ScopeObservation; execution requires the same lifetime in
-/// reference. A validator-bearing artifact requires that exact validator on a
+/// the target's atomic boundary. Collision keys are exact (scope, name) pairs,
-/// call. Re-registering a definition is rejected rather than silently changing
+/// not Rust TypeId: the same Definition can be registered at multiple coordinates.
-/// the observation associated with an existing reference.
+#[derive(Debug, Default)]
 #[derive(Debug)]
 pub struct InterfaceRegistry {
    namespace: u64,
    next_reference: u64,
    definitions: HashSet<TypeId>,
    artifacts: HashMap<InterfaceRef, Arc<InterfaceArtifact>>,
 }
 static NEXT_REGISTRY_NAMESPACE: AtomicU64 = AtomicU64::new(1);
 impl Default for InterfaceRegistry {
    fn default() -> Self {
        Self {
            namespace: NEXT_REGISTRY_NAMESPACE.fetch_add(1, Ordering::Relaxed),
            next_reference: 0,
            definitions: HashSet::new(),
            artifacts: HashMap::new(),
        }
    }
 }
 impl InterfaceRegistry {
-    /// Creates an empty interface registry.
+    /// Creates an empty artifact registry without publishing any Object.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
-    /// Registers and freezes one generated interface definition.
+    /// Freezes a Definition at an explicit scope and local name.
    pub fn register<D>(
        &mut self,
        scope: &Scope,
        name: impl Into<String>,
        _definition: D,
        validator: Option<Validator>,
    ) -> Result<RegisteredInterface<D>, RegistrationError>
    where
        D: InterfaceDefinition + 'static,
    {
-        let definition = TypeId::of::<D>();
+        let reference = InterfaceRef(InterfaceReference {
-        if self.definitions.contains(&definition) {
+            scope: scope.path.clone(),
            name: name.into(),
        });
        reference
            .0
            .validate()
            .map_err(RegistrationError::InvalidReference)?;
        if !scope.active() {
            return Err(RegistrationError::RetiredScope);
        }
        if self.artifacts.contains_key(&reference) {
            return Err(RegistrationError::AlreadyRegistered);
        }
        let descriptor = D::descriptor();
        descriptor
            .validate()
            .map_err(RegistrationError::InvalidDescriptor)?;
        let reference = InterfaceRef(format!(
            "wip-interface:{}:{}",
            self.namespace, self.next_reference
        ));
        self.next_reference = self
            .next_reference
            .checked_add(1)
            .ok_or(RegistrationError::ReferenceSpaceExhausted)?;
        let artifact = Arc::new(InterfaceArtifact {
            scope: scope.clone(),
            reference: reference.clone(),
            descriptor,
            validator,
        });
        self.definitions.insert(definition);
        self.artifacts.insert(reference, Arc::clone(&artifact));
        Ok(RegisteredInterface {
            artifact,
            definition: PhantomData,
        })
    }
-    /// Resolves a transport-provided opaque reference string in this registry.
+    /// Ends a scope lifetime and releases its registry entries.
    ///
    /// Retained tokens cannot start new calls/fetches. Started calls retain their
    /// frozen Descriptor. Re-publication requires a fresh Scope.
    pub fn remove_scope(&mut self, scope: &Scope) {
        scope.lifetime.store(false, Ordering::Release);
        self.artifacts
            .retain(|_, artifact| !artifact.scope.same_lifetime(scope));
    }
    /// Resolves a stored artifact, not evidence of current publication.
    #[must_use]
-    pub fn resolve(&self, reference: &str) -> Option<InterfaceRef> {
+    pub fn resolve(&self, reference: &InterfaceReference) -> Option<InterfaceRef> {
-        let reference = InterfaceRef(reference.to_owned());
+        let reference = InterfaceRef(reference.clone());
        self.artifacts.contains_key(&reference).then_some(reference)
    }
-    /// Observes a registered interface by its host-side reference.
+    /// Iterates registered scope handles, possibly repeated for multiple names.
-    #[must_use]
+    pub fn scopes(&self) -> impl Iterator<Item = &Scope> {
-    pub fn observe(&self, reference: &InterfaceRef) -> Option<InterfaceObservation> {
+        self.artifacts.values().map(|artifact| &artifact.scope)
        self.artifacts.get(reference).map(Self::observation)
    }
-    /// Implements canonical `fetch_interface` semantics for an opaque reference.
+    /// Fetches only with a coherent current scope Object attestation.
-    ///
+    pub fn fetch_interface(
-    /// Unknown and currently unpublished references map to `InterfaceNotFound`,
+        &self,
-    /// not object membership errors or authorization failures.
+        reference: &InterfaceReference,
-    pub fn fetch_interface(&self, reference: &str) -> Result<InterfaceObservation, ProtocolError> {
+        current: &ScopeObservation,
-        let reference = InterfaceRef(reference.to_owned());
+    ) -> Result<InterfaceObservation, ProtocolError> {
        reference.validate().map_err(|error| ProtocolError {
            code: ProtocolErrorCode::InvalidRequest,
            message: error.to_string(),
        })?;
        self.artifacts
-            .get(&reference)
+            .get(&InterfaceRef(reference.clone()))
-            .map(Self::observation)
+            .filter(|artifact| {
-            .ok_or_else(|| ProtocolError {
+                artifact.scope.active() && artifact.scope.same_lifetime(&current.scope)
                code: ProtocolErrorCode::InterfaceNotFound,
                message: "interface reference is not currently published".into(),
            })
-    }
+            .map(|artifact| InterfaceObservation {
-
+                reference: artifact.reference.clone(),
-    fn observation(artifact: &Arc<InterfaceArtifact>) -> InterfaceObservation {
+                descriptor: artifact.descriptor.clone(),
-        InterfaceObservation {
+                scope_ref: current.reference.clone(),
-            reference: artifact.reference.clone(),
+                validator: artifact.validator.clone(),
-            descriptor: artifact.descriptor.clone(),
+            })
-            validator: artifact.validator.clone(),
+            .ok_or_else(interface_not_found)
        }
    }
 }
-/// Failure while registering a generated interface definition.
+fn interface_not_found() -> ProtocolError {
    ProtocolError {
        code: ProtocolErrorCode::InterfaceNotFound,
        message: "interface is not currently published".into(),
    }
 }
 /// Failure while registering a generated interface Definition.
 #[derive(Debug)]
 pub enum RegistrationError {
-    /// The same generated definition was already assigned a reference.
+    /// The exact scope/name coordinate is already occupied.
    AlreadyRegistered,
-    /// The generated descriptor is structurally invalid.
+    /// The generated Descriptor is invalid.
    InvalidDescriptor(ValidationError),
-    /// The registry cannot assign another opaque reference.
+    /// The scope or local name is invalid.
-    ReferenceSpaceExhausted,
+    InvalidReference(ValidationError),
    /// The lifetime ended; re-publication needs a fresh Scope.
    RetiredScope,
 }
 impl Display for RegistrationError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        match self {
            Self::AlreadyRegistered => {
-                formatter.write_str("interface definition already registered")
+                formatter.write_str("interface scope/name already registered")
            }
            Self::InvalidDescriptor(error) => {
                write!(formatter, "invalid interface descriptor: {error}")
            }
-            Self::ReferenceSpaceExhausted => {
+            Self::InvalidReference(error) => {
-                formatter.write_str("interface reference space exhausted")
+                write!(formatter, "invalid interface reference: {error}")
            }
            Self::RetiredScope => formatter.write_str("scope publication lifetime has ended"),
        }
    }
 }
 impl Error for RegistrationError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
-            Self::InvalidDescriptor(error) => Some(error),
+            Self::InvalidDescriptor(error) | Self::InvalidReference(error) => Some(error),
-            Self::AlreadyRegistered | Self::ReferenceSpaceExhausted => None,
+            Self::AlreadyRegistered | Self::RetiredScope => None,
        }
    }
 }
@@ -449,6 +544,60 @@ pub trait WipObject {
    }
 }
 fn restrict_descriptor(descriptor: &mut InterfaceDescriptor, visible: impl Fn(&str) -> bool) {
    let count = descriptor.operations.len();
    descriptor
        .operations
        .retain(|operation| visible(&operation.name));
    if descriptor.operations.len() == count {
        return;
    }
    descriptor.documentation = None;
    let mut used = HashSet::new();
    fn references(expression: &wip_protocol::TypeExpr, used: &mut HashSet<String>) {
        use wip_protocol::TypeExpr;
        match expression {
            TypeExpr::Named { name } => {
                used.insert(name.clone());
            }
            TypeExpr::Record { fields } => {
                for field in fields {
                    references(&field.r#type, used);
                }
            }
            TypeExpr::List { items } => references(items, used),
            TypeExpr::Union { cases } => {
                for case in cases {
                    if let Some(payload) = &case.payload {
                        references(payload, used);
                    }
                }
            }
            _ => {}
        }
    }
    for operation in &descriptor.operations {
        for parameter in &operation.parameters {
            references(&parameter.r#type, &mut used);
        }
        references(&operation.returns.r#type, &mut used);
    }
    loop {
        let before = used.len();
        for declaration in &descriptor.types {
            if used.contains(&declaration.name) {
                references(&declaration.definition, &mut used);
            }
        }
        if before == used.len() {
            break;
        }
    }
    descriptor
        .types
        .retain(|declaration| used.contains(&declaration.name));
 }
 type DispatchFn<T> = fn(&T, &str, BTreeMap<String, Value>) -> Result<Value, DispatchError>;
 struct BoundInterface<T> {
@@ -464,6 +613,7 @@ struct BoundInterface<T> {
 pub struct PublishedObject<T: WipObject> {
    implementation: T,
    interfaces: Vec<BoundInterface<T>>,
    scopes: Vec<ScopeObservation>,
 }
 impl<T: WipObject> PublishedObject<T> {
@@ -473,13 +623,45 @@ impl<T: WipObject> PublishedObject<T> {
        Self {
            implementation,
            interfaces: Vec::new(),
            scopes: Vec::new(),
        }
    }
    /// Attaches a current scope snapshot inside the provider's atomic boundary.
    ///
    /// Never populate this from a stale prelookup. Target, scope association,
    /// Descriptor and backend handles must remain coherent through dispatch and
    /// commit. A later same-path binding replaces the earlier snapshot.
    #[must_use]
    pub fn bind_scope(mut self, current: ScopeObservation) -> Self {
        self.scopes
            .retain(|old| old.scope.path != current.scope.path);
        self.scopes.push(current);
        self
    }
    fn current_scope(&self, scope: &Scope) -> Option<&ScopeObservation> {
        self.scopes
            .iter()
            .find(|current| scope.active() && scope.same_lifetime(&current.scope))
    }
    fn scopes_valid_at(&self, path: &str) -> bool {
        self.interfaces.iter().all(|bound| {
            bound.artifact.reference.0.validate_for_path(path).is_ok()
                && self
                    .current_scope(&bound.artifact.scope)
                    .is_some_and(|current| {
                        current.scope.path != path
                            || current.reference() == self.implementation.reference()
                    })
        })
    }
    /// Explicitly exposes a registered generated interface in insertion order.
    ///
    /// The `InterfaceImplementation<T>` bound is generated only when `T`
-    /// implements the corresponding Rust interface trait. Duplicate opaque
+    /// implements the corresponding Rust interface trait. Duplicate scoped
    /// references are rejected.
    pub fn expose<D>(mut self, interface: &RegisteredInterface<D>) -> Result<Self, PublicationError>
    where
@@ -502,15 +684,60 @@ impl<T: WipObject> PublishedObject<T> {
        Ok(self)
    }
    /// Restricts a publication to an ordered interface/operation view.
    ///
    /// This never adds implementations or changes codecs. The provider must use
    /// the identical operation predicate for `fetch_interface`, and keep the
    /// effective view stable for the lifetime of its references. Filtered
    /// descriptors are scoped to that view, not mutations of registry artifacts.
    pub fn project(
        mut self,
        interfaces: &[InterfaceRef],
        visible: impl Fn(&InterfaceRef, &str) -> bool,
    ) -> Result<Self, PublicationError> {
        let mut projected = Vec::with_capacity(interfaces.len());
        for reference in interfaces {
            if projected
                .iter()
                .any(|bound: &BoundInterface<T>| &bound.artifact.reference == reference)
            {
                return Err(PublicationError::DuplicateInterface(reference.clone()));
            }
            let Some(index) = self
                .interfaces
                .iter()
                .position(|bound| &bound.artifact.reference == reference)
            else {
                return Err(PublicationError::UnexposedInterface(reference.clone()));
            };
            let mut bound = self.interfaces.remove(index);
            let mut descriptor = bound.artifact.descriptor.clone();
            restrict_descriptor(&mut descriptor, |operation| visible(reference, operation));
            bound.artifact = Arc::new(InterfaceArtifact {
                scope: bound.artifact.scope.clone(),
                reference: reference.clone(),
                descriptor,
                validator: bound.artifact.validator.clone(),
            });
            projected.push(bound);
        }
        self.interfaces = projected;
        Ok(self)
    }
    /// Returns the host-private implementation without projecting its fields.
    #[must_use]
    pub fn implementation(&self) -> &T {
        &self.implementation
    }
-    /// Builds canonical protocol object metadata in interface insertion order.
+    /// Builds metadata from the explicit exposure set in insertion order.
    ///
-    /// The observation contains no path, children, descriptor, backend handle,
+    /// This path-free projection is useful while composing a publication, but is
    /// not proof that its scopes are currently published. Use
    /// [`ObjectProvider::observe_object`] for a validated current observation, or
    /// [`Self::protocol_object_at`] inside a provider's coherent boundary.
    /// The metadata contains no path, children, descriptor, backend handle,
    /// credential, or provider resolution state.
    #[must_use]
    pub fn protocol_object(&self) -> Object {
@@ -520,7 +747,7 @@ impl<T: WipObject> PublishedObject<T> {
            interfaces: self
                .interfaces
                .iter()
-                .map(|bound| bound.artifact.reference.0.clone())
+                .map(|bound| bound.artifact.reference.protocol_reference())
                .collect(),
            r#ref: self.implementation.reference().map(str::to_owned),
            validator: self
@@ -530,6 +757,30 @@ impl<T: WipObject> PublishedObject<T> {
        }
    }
    /// Validates a current Object observation inside the provider's boundary.
    ///
    /// All exposed interfaces must have compatible, live scope associations. The
    /// provider must still establish those associations atomically; this method
    /// cannot verify backend lifetime assertions or lock external writers.
    pub fn protocol_object_at(&self, path: &str) -> Result<Object, CallError> {
        wip_protocol::validate_path(path)
            .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
        if !self.scopes_valid_at(path) {
            return Err(CallError::new(
                CallErrorKind::Internal,
                "Host published interfaces without current compatible scope Objects",
            ));
        }
        let object = self.protocol_object();
        object.validate_at_path(path).map_err(|_| {
            CallError::new(
                CallErrorKind::Internal,
                "Host produced an invalid object response",
            )
        })?;
        Ok(object)
    }
    fn dispatch_resolved(
        &self,
        context: &ExecutionContext,
@@ -573,10 +824,17 @@ impl<T: WipObject> PublishedObject<T> {
            );
        }
        if interface.reference.validate_for_path(&target.path).is_err() {
            return pre_dispatch_failure(
                CallErrorKind::InterfaceMismatch,
                "interface scope is not an ancestor of the target path",
            );
        }
        let Some(bound) = self
            .interfaces
            .iter()
-            .find(|bound| bound.artifact.reference.as_str() == interface.reference.as_str())
+            .find(|bound| bound.artifact.reference.protocol_reference() == interface.reference)
        else {
            return pre_dispatch_failure(
                CallErrorKind::InterfaceMismatch,
@@ -584,6 +842,31 @@ impl<T: WipObject> PublishedObject<T> {
            );
        };
        let Some(current_scope) = self.current_scope(&bound.artifact.scope) else {
            return pre_dispatch_failure(
                CallErrorKind::InterfaceMismatch,
                "interface scope Object is not currently associated with this publication",
            );
        };
        if current_scope.scope.path == target.path
            && current_scope.reference() != self.implementation.reference()
        {
            return pre_dispatch_failure(
                CallErrorKind::Internal,
                "provider produced inconsistent self-scope metadata",
            );
        }
        if interface
            .scope_ref
            .as_deref()
            .is_some_and(|supplied| current_scope.reference() != Some(supplied))
        {
            return pre_dispatch_failure(
                CallErrorKind::InterfaceMismatch,
                "scope Object ref does not match the current association",
            );
        }
        match (
            bound.artifact.validator.as_ref(),
            interface.validator.as_deref(),
@@ -782,6 +1065,15 @@ pub enum OperationAttempt {
 }
 impl OperationAttempt {
    /// Rejects a provider precondition before typed implementation invocation.
    ///
    /// Only use this before dispatch starts; post-invocation failures require
    /// an explicit effect disposition. The diagnostic is intentionally generic.
    #[must_use]
    pub fn reject(kind: CallErrorKind) -> Self {
        Self::NotStarted(CallError::new(kind, "provider precondition failed"))
    }
    /// Marks a post-invocation failure as fully rolled back.
    ///
    /// Successful attempts and pre-dispatch failures are returned unchanged.
@@ -813,7 +1105,12 @@ pub enum ProviderResult<T> {
 ///
 /// `with_object` must resolve the current object at `path` exactly once and pass
 /// a publication that pins its current interface set, implementations, and
-/// backend target for the duration of `operation`. The execution context is the
+/// backend target and all current scope Object associations for the duration of
 /// `operation`. Attach them with PublishedObject::bind_scope inside this same
 /// boundary, never via an independent scope prelookup. A new Object at the same
 /// path needs a fresh Scope; ordinary state changes retain the handle. Providers
 /// own lifetime/atomicity enforcement, including external writers and backend
 /// commit/rollback. The execution context is the
 /// runtime-neutral carrier for cancellation, deadline, and resource controls.
 /// The borrowed publication cannot escape the callback.
 ///
@@ -863,13 +1160,13 @@ pub trait ObjectProvider {
        true
    }
-    /// Fetches the canonical object projection currently published at `path`.
+    /// Observes the canonical object projection currently published at `path`.
-    fn fetch(&self, path: &str) -> Result<Object, CallError> {
+    fn observe_object(&self, path: &str) -> Result<Object, CallError> {
-        self.fetch_with_context(&ExecutionContext::default(), path)
+        self.observe_object_with_context(&ExecutionContext::default(), path)
    }
-    /// Fetches an object while propagating runtime execution controls.
+    /// Observes an object while propagating runtime execution controls.
-    fn fetch_with_context(
+    fn observe_object_with_context(
        &self,
        context: &ExecutionContext,
        path: &str,
@@ -877,16 +1174,18 @@ pub trait ObjectProvider {
        wip_protocol::validate_path(path)
            .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
        let resolved = catch_unwind(AssertUnwindSafe(|| {
-            self.with_object(context, path, PublishedObject::protocol_object)
+            self.with_object(context, path, |publication| {
                publication.protocol_object_at(path)
            })
        }))
        .map_err(|_| {
            CallError::new(
                CallErrorKind::Internal,
-                "provider panicked while fetching an object",
+                "provider panicked while observing an object",
            )
        })?;
        let object = match resolved {
-            ProviderResult::Found(object) => object,
+            ProviderResult::Found(object) => object?,
            ProviderResult::NotFound => {
                return Err(CallError::new(
                    CallErrorKind::NotFound,
@@ -895,15 +1194,58 @@ pub trait ObjectProvider {
            }
            ProviderResult::Failure(error) => return Err(CallError::from_read_failure(error)),
        };
        object.validate_at_path(path).map_err(|_| {
            CallError::new(
                CallErrorKind::Internal,
                "Host produced an invalid object response",
            )
        })?;
        Ok(object)
    }
    /// Fetches Descriptor, scope Object ref and Interface validator atomically.
    ///
    /// The scope Object may expose no interfaces. Its publication must still
    /// bind the live ScopeObservation. Registry retention is not publication.
    fn fetch_interface(
        &self,
        registry: &InterfaceRegistry,
        reference: &InterfaceReference,
    ) -> Result<InterfaceObservation, ProtocolError> {
        reference.validate().map_err(|error| ProtocolError {
            code: ProtocolErrorCode::InvalidRequest,
            message: error.to_string(),
        })?;
        let observed = catch_unwind(AssertUnwindSafe(|| {
            self.with_object(
                &ExecutionContext::default(),
                &reference.scope,
                |publication| {
                    publication
                        .scopes
                        .iter()
                        .find(|current| current.scope.path == reference.scope)
                        .ok_or_else(interface_not_found)
                        .and_then(|current| {
                            if current.reference() != publication.implementation.reference() {
                                return Err(ProtocolError {
                                    code: ProtocolErrorCode::Internal,
                                    message: "provider produced inconsistent scope Object metadata"
                                        .into(),
                                });
                            }
                            registry.fetch_interface(reference, current)
                        })
                },
            )
        }))
        .map_err(|_| ProtocolError {
            code: ProtocolErrorCode::Internal,
            message: "provider panicked while observing an interface".into(),
        })?;
        match observed {
            ProviderResult::Found(observation) => observation,
            ProviderResult::NotFound => Err(interface_not_found()),
            ProviderResult::Failure(error) => {
                Err(CallError::from_read_failure(error).protocol_error())
            }
        }
    }
    /// Resolves and executes a canonical path-targeted operation request.
    ///
    /// Structural path validation precedes provider resolution. For a valid
@@ -925,6 +1267,11 @@ pub trait ObjectProvider {
    ) -> Result<CallResult, CallError> {
        wip_protocol::validate_path(&request.target.path)
            .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
        request
            .interface
            .reference
            .validate()
            .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
        let path = request.target.path.clone();
        let execution = catch_unwind(AssertUnwindSafe(|| {
            self.execute_operation(context, &path, |publication| {
@@ -974,6 +1321,10 @@ pub trait ObjectProvider {
    ) -> Result<CallResult, CallError> {
        wip_protocol::validate_path(&target.path)
            .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
        interface
            .reference
            .validate()
            .map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
        let path = target.path.clone();
        let execution = catch_unwind(AssertUnwindSafe(|| {
            self.execute_operation(context, &path, |publication| {
@@ -1014,13 +1365,20 @@ pub trait ObjectProvider {
 /// Failure to construct an explicit object publication.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum PublicationError {
-    /// The same opaque interface reference was exposed more than once.
+    /// The same scope/name Interface reference was exposed more than once.
    DuplicateInterface(InterfaceRef),
    /// Projection attempted to add an interface without an implementation.
    UnexposedInterface(InterfaceRef),
 }
 impl Display for PublicationError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnexposedInterface(reference) => write!(
                formatter,
                "interface `{}` has no implementation",
                reference.as_str()
            ),
            Self::DuplicateInterface(reference) => write!(
                formatter,
                "interface `{}` is already exposed by this object",
@@ -1032,6 +1390,70 @@ impl Display for PublicationError {
 impl Error for PublicationError {}
 #[cfg(test)]
 mod projection_tests {
    use super::*;
    use wip_protocol::{
        Documentation, OperationDeclaration, ReturnDeclaration, TypeDeclaration, TypeExpr,
    };
    #[test]
    fn operation_views_prune_hidden_types_and_documentation_without_mutating_registry() {
        let named = |name: &str| TypeExpr::Named { name: name.into() };
        let operation = |name: &str, returns| OperationDeclaration {
            name: name.into(),
            documentation: None,
            parameters: Vec::new(),
            returns: ReturnDeclaration {
                documentation: None,
                r#type: returns,
            },
        };
        let declaration = |name: &str, definition| TypeDeclaration {
            name: name.into(),
            documentation: None,
            definition,
        };
        let descriptor = InterfaceDescriptor {
            format: "wip/1".into(),
            documentation: Some(Documentation {
                summary: "contains hidden operation details".into(),
                details: None,
            }),
            operations: vec![
                operation("visible", named("Public")),
                operation("secret", named("Secret")),
            ],
            types: vec![
                declaration(
                    "Public",
                    TypeExpr::List {
                        items: Box::new(named("Shared")),
                    },
                ),
                declaration("Shared", TypeExpr::String),
                declaration("Secret", TypeExpr::Bytes),
            ],
        };
        let mut projected = descriptor.clone();
        restrict_descriptor(&mut projected, |operation| operation == "visible");
        assert_eq!(projected.operations.len(), 1);
        assert!(projected.documentation.is_none());
        assert_eq!(
            projected
                .types
                .iter()
                .map(|declaration| declaration.name.as_str())
                .collect::<Vec<_>>(),
            vec!["Public", "Shared"]
        );
        assert_eq!(descriptor.types.len(), 3);
        restrict_descriptor(&mut projected, |_| false);
        assert!(projected.types.is_empty());
        assert!(projected.operations.is_empty());
    }
 }
 /// Stable Host dispatch failure kind.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum CallErrorKind {
@@ -6,7 +6,7 @@ use std::time::{Duration, Instant};
 use wip_host::{
    CallError, CallErrorKind, CallRequest, CancellationToken, ExecutionContext, InterfaceRef,
    InterfaceRegistry, InterfaceTarget, ObjectProvider, OperationAttempt, ProviderResult,
-    PublishedObject, RegisteredInterface, Target, Validator, WipObject,
+    PublishedObject, RegisteredInterface, Scope, ScopeObservation, Target, Validator, WipObject,
 };
 use wip_interface::{
    CodecError, EffectGuarantee, HostError, OperationResult, TypeDeclaration, TypeExpr, Value,
@@ -14,6 +14,77 @@ use wip_interface::{
 };
 use wip_protocol::ProtocolErrorCode;
 #[test]
 fn principal_projection_orders_subsets_and_rejects_unimplemented_or_duplicate_tokens() {
    let mut registry = InterfaceRegistry::new();
    let root = Scope::new("/").unwrap();
    let read = registry
        .register(&root, "reader", ReaderDefinition, None)
        .unwrap();
    let write = registry
        .register(&root, "writer::#日本語", WriterDefinition, None)
        .unwrap();
    let hidden = registry
        .register(&root, "hidden", HiddenDefinition, None)
        .unwrap();
    let publication = || {
        PublishedObject::new(Document::open("document", None, Rc::new(Cell::new(0))))
            .expose(&read)
            .unwrap()
            .expose(&write)
            .unwrap()
    };
    let projected = publication()
        .project(
            &[write.reference().clone(), read.reference().clone()],
            |_, operation| operation == "label",
        )
        .unwrap();
    assert_eq!(
        projected.protocol_object().interfaces,
        vec![
            write.reference().protocol_reference(),
            read.reference().protocol_reference()
        ]
    );
    assert!(
        publication()
            .project(&[hidden.reference().clone()], |_, _| true)
            .is_err()
    );
    assert!(
        publication()
            .project(
                &[read.reference().clone(), read.reference().clone()],
                |_, _| true
            )
            .is_err()
    );
    assert!(
        publication()
            .project(&[], |_, _| true)
            .unwrap()
            .protocol_object()
            .interfaces
            .is_empty()
    );
    let current = ScopeObservation::new(&root, &Document::open("", None, Rc::new(Cell::new(0))));
    let full = registry
        .fetch_interface(&read.reference().protocol_reference(), &current)
        .unwrap();
    let filtered = full
        .clone()
        .project_operations(|operation| operation == "label");
    assert_eq!(filtered.descriptor.operations.len(), 1);
    assert_eq!(full.descriptor.operations.len(), 3);
    assert_eq!(
        registry
            .fetch_interface(&read.reference().protocol_reference(), &current)
            .unwrap(),
        full
    );
 }
 #[interface]
 pub trait Reader {
    /// Returns the reader-qualified label.
@@ -246,6 +317,7 @@ impl Broken for Document {
 }
 struct TestProvider {
    root: Scope,
    reader: RegisteredInterface<ReaderDefinition>,
    writer: RegisteredInterface<WriterDefinition>,
    broken: RegisteredInterface<BrokenDefinition>,
@@ -263,11 +335,13 @@ struct TestProvider {
 impl TestProvider {
    fn new(
        root: Scope,
        reader: RegisteredInterface<ReaderDefinition>,
        writer: RegisteredInterface<WriterDefinition>,
        broken: RegisteredInterface<BrokenDefinition>,
    ) -> Self {
        Self {
            root,
            reader,
            writer,
            broken,
@@ -299,7 +373,10 @@ impl ObjectProvider for TestProvider {
        self.observed_cancelled
            .set(context.cancellation().is_cancelled());
        self.resolutions.set(self.resolutions.get() + 1);
        let scope_object = Document::open("", None, Rc::clone(&self.calls));
        let current_scope = ScopeObservation::new(&self.root, &scope_object);
        let (document, interfaces) = match path {
            "/" => (scope_object, 0),
            "/document" => (
                Document::strict(
                    "document",
@@ -357,6 +434,7 @@ impl ObjectProvider for TestProvider {
            3 => publication.expose(&self.broken).unwrap(),
            _ => unreachable!(),
        };
        let publication = publication.bind_scope(current_scope);
        ProviderResult::Found(operation(&publication))
    }
@@ -398,13 +476,25 @@ fn registry_and_provider() -> (
    RegisteredInterface<HiddenDefinition>,
 ) {
    let mut registry = InterfaceRegistry::new();
    let root = Scope::new("/").unwrap();
    let reader = registry
-        .register(ReaderDefinition, Some(Validator::new(b"schema-v1")))
+        .register(
            &root,
            "reader",
            ReaderDefinition,
            Some(Validator::new(b"schema-v1")),
        )
        .unwrap();
-    let writer = registry.register(WriterDefinition, None).unwrap();
+    let writer = registry
-    let hidden = registry.register(HiddenDefinition, None).unwrap();
+        .register(&root, "writer::#日本語", WriterDefinition, None)
-    let broken = registry.register(BrokenDefinition, None).unwrap();
+        .unwrap();
-    let provider = TestProvider::new(reader, writer, broken);
+    let hidden = registry
        .register(&root, "hidden", HiddenDefinition, None)
        .unwrap();
    let broken = registry
        .register(&root, "broken", BrokenDefinition, None)
        .unwrap();
    let provider = TestProvider::new(root, reader, writer, broken);
    (registry, provider, hidden)
 }
@@ -422,7 +512,8 @@ fn request(
            validator: object_validator.map(<[u8]>::to_vec),
        },
        interface: InterfaceTarget {
-            reference: reference.as_str().to_owned(),
+            reference: reference.protocol_reference(),
            scope_ref: None,
            validator: interface_validator.map(<[u8]>::to_vec),
        },
        operation: operation.into(),
@@ -441,17 +532,22 @@ fn registry_returns_atomic_canonical_observation_without_rewriting_descriptor()
    let reference = provider.reader.reference();
    assert_ne!(reference.as_str(), "Reader");
-    let observation = registry.fetch_interface(reference.as_str()).unwrap();
+    let observation = provider
        .fetch_interface(&registry, &reference.protocol_reference())
        .unwrap();
    assert_eq!(observation.reference, *reference);
    assert_eq!(observation.descriptor, ReaderDefinition::descriptor());
    assert_eq!(observation.validator, Some(Validator::new(b"schema-v1")));
    let response = observation.protocol_response().unwrap();
-    assert_eq!(response.interface, reference.as_str());
+    assert_eq!(response.interface, reference.protocol_reference());
    assert_eq!(response.scope_ref, None);
    assert_eq!(response.descriptor, ReaderDefinition::descriptor());
    assert_eq!(response.validator.as_deref(), Some(b"schema-v1".as_slice()));
    response.descriptor.validate().unwrap();
-    let mut invalid_observation = registry.fetch_interface(reference.as_str()).unwrap();
+    let mut invalid_observation = provider
        .fetch_interface(&registry, &reference.protocol_reference())
        .unwrap();
    let duplicate_operation = invalid_observation.descriptor.operations[0].clone();
    invalid_observation
        .descriptor
@@ -460,14 +556,22 @@ fn registry_returns_atomic_canonical_observation_without_rewriting_descriptor()
    let invalid_response = invalid_observation.protocol_response().unwrap_err();
    assert_eq!(invalid_response.code, ProtocolErrorCode::Internal);
-    let error = registry.fetch_interface("unknown").unwrap_err();
+    let error = provider
        .fetch_interface(
            &registry,
            &wip_protocol::InterfaceReference {
                scope: "/".into(),
                name: "unknown".into(),
            },
        )
        .unwrap_err();
    assert_eq!(error.code, ProtocolErrorCode::InterfaceNotFound);
 }
 #[test]
 fn canonical_object_projection_supports_optional_metadata_and_ordered_sets() {
    let (_, provider, _) = registry_and_provider();
-    let object = provider.fetch("/document").unwrap();
+    let object = provider.observe_object("/document").unwrap();
    assert_eq!(object.name, "document");
    assert_eq!(object.description.as_deref(), Some("public document"));
@@ -476,14 +580,14 @@ fn canonical_object_projection_supports_optional_metadata_and_ordered_sets() {
    assert_eq!(
        object.interfaces,
        vec![
-            provider.writer.reference().as_str().to_owned(),
+            provider.writer.reference().protocol_reference(),
-            provider.reader.reference().as_str().to_owned(),
+            provider.reader.reference().protocol_reference(),
        ]
    );
    assert!(!format!("{object:?}").contains("secret-handle"));
    assert!(!format!("{object:?}").contains("/document"));
-    let empty = provider.fetch("/empty").unwrap();
+    let empty = provider.observe_object("/empty").unwrap();
    assert!(empty.interfaces.is_empty());
    assert_eq!(empty.r#ref, None);
    assert_eq!(empty.validator, None);
@@ -518,13 +622,13 @@ fn duplicate_exposure_is_rejected_and_private_state_is_not_projected() {
 fn paths_are_resolution_context_not_object_identity() {
    let (_, provider, _) = registry_and_provider();
-    let left = provider.fetch("/left/document").unwrap();
+    let left = provider.observe_object("/left/document").unwrap();
-    let right = provider.fetch("/right/document").unwrap();
+    let right = provider.observe_object("/right/document").unwrap();
    assert_eq!(left, right);
    assert_eq!(left.r#ref.as_deref(), Some("shared-ref"));
-    let first = provider.fetch("/switch").unwrap();
+    let first = provider.observe_object("/switch").unwrap();
-    let second = provider.fetch("/switch").unwrap();
+    let second = provider.observe_object("/switch").unwrap();
    assert_ne!(first.r#ref, second.r#ref);
    assert_ne!(first.validator, second.validator);
 }
@@ -603,7 +707,7 @@ fn call_failures_follow_canonical_precedence_without_execution() {
    }
    assert_eq!(provider.resolutions.get(), resolutions);
    assert_failure(
-        provider.fetch("/invalid/").unwrap_err(),
+        provider.observe_object("/invalid/").unwrap_err(),
        CallErrorKind::InvalidRequest,
        ProtocolErrorCode::InvalidRequest,
    );
@@ -758,7 +862,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
                validator: Some(b"stale".to_vec()),
            },
            InterfaceTarget {
-                reference: hidden.reference().as_str().into(),
+                reference: hidden.reference().protocol_reference(),
                scope_ref: None,
                validator: None,
            },
            "missing".into(),
@@ -776,7 +881,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
                validator: Some(b"stale".to_vec()),
            },
            InterfaceTarget {
-                reference: hidden.reference().as_str().into(),
+                reference: hidden.reference().protocol_reference(),
                scope_ref: None,
                validator: None,
            },
            "hidden".into(),
@@ -794,7 +900,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
                validator: Some(b"object-v1".to_vec()),
            },
            InterfaceTarget {
-                reference: hidden.reference().as_str().into(),
+                reference: hidden.reference().protocol_reference(),
                scope_ref: None,
                validator: None,
            },
            "hidden".into(),
@@ -812,7 +919,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
                validator: Some(b"object-v1".to_vec()),
            },
            InterfaceTarget {
-                reference: provider.reader.reference().as_str().into(),
+                reference: provider.reader.reference().protocol_reference(),
                scope_ref: None,
                validator: Some(b"schema-v1".to_vec()),
            },
            "add".into(),
@@ -849,7 +957,7 @@ fn invalid_host_responses_and_uncertain_operation_failures_use_canonical_codes()
    let (_, provider, _) = registry_and_provider();
    assert_failure(
-        provider.fetch("/invalid-object").unwrap_err(),
+        provider.observe_object("/invalid-object").unwrap_err(),
        CallErrorKind::Internal,
        ProtocolErrorCode::Internal,
    );
@@ -1066,3 +1174,105 @@ fn execution_context_is_propagated_and_preflight_prevents_invocation() {
    );
    assert_eq!(provider.calls.get(), calls);
 }
 #[test]
 fn registry_boundaries_preserve_names_verbatim_and_match_exact_scope() {
    let (registry, provider, _) = registry_and_provider();
    let legacy = provider.writer.reference();
    let reference = legacy.protocol_reference();
    assert_eq!(reference.scope, "/");
    assert_eq!(reference.name, legacy.as_str());
    assert_eq!(reference.name, "writer::#日本語");
    assert_eq!(registry.resolve(&reference).as_ref(), Some(legacy));
    let nested = wip_protocol::InterfaceReference {
        scope: "/open".into(),
        name: reference.name.clone(),
    };
    assert!(registry.resolve(&nested).is_none());
    assert_eq!(
        provider
            .fetch_interface(&registry, &nested)
            .unwrap_err()
            .code,
        ProtocolErrorCode::InterfaceNotFound
    );
    let malformed = wip_protocol::InterfaceReference {
        scope: "relative".into(),
        name: reference.name,
    };
    assert_eq!(
        provider
            .fetch_interface(&registry, &malformed)
            .unwrap_err()
            .code,
        ProtocolErrorCode::InvalidRequest
    );
 }
 #[test]
 fn call_reference_shape_precedes_resolution_and_scope_membership_is_exact() {
    let (_, provider, _) = registry_and_provider();
    for (scope, name) in [("relative", "valid"), ("/", ""), ("/bad/", "valid")] {
        let mut call = request(
            "/open",
            None,
            provider.writer.reference(),
            None,
            "label",
            BTreeMap::new(),
        );
        call.interface.reference = wip_protocol::InterfaceReference {
            scope: scope.into(),
            name: name.into(),
        };
        assert_eq!(
            provider.call_operation(call.clone()).unwrap_err().kind(),
            CallErrorKind::InvalidRequest
        );
        assert_eq!(
            provider
                .call_operation_with_context_and_decoder(
                    &ExecutionContext::new(),
                    call.target,
                    call.interface,
                    call.operation,
                    |_| Ok::<_, ()>(BTreeMap::new()),
                )
                .unwrap_err()
                .kind(),
            CallErrorKind::InvalidRequest
        );
    }
    assert_eq!(provider.resolutions.get(), 0);
    // /other is outside the target scope; /open is self but has no legacy artifact.
    for scope in ["/other", "/open"] {
        let mut call = request(
            "/open",
            None,
            provider.writer.reference(),
            None,
            "label",
            BTreeMap::new(),
        );
        call.interface.reference.scope = scope.into();
        assert_eq!(
            provider.call_operation(call.clone()).unwrap_err().kind(),
            CallErrorKind::InterfaceMismatch
        );
        assert_eq!(
            provider
                .call_operation_with_context_and_decoder(
                    &ExecutionContext::new(),
                    call.target,
                    call.interface,
                    call.operation,
                    |_| -> Result<BTreeMap<String, Value>, ()> { panic!("must not decode") },
                )
                .unwrap_err()
                .kind(),
            CallErrorKind::InterfaceMismatch
        );
    }
    assert_eq!(provider.calls.get(), 0);
    assert_eq!(provider.authorization_checks.get(), 0);
 }
@@ -0,0 +1,560 @@
 use std::cell::{Cell, RefCell};
 use std::collections::BTreeMap;
 use std::rc::Rc;
 use wip_host::{
    CallErrorKind, CallRequest, ExecutionContext, InterfaceRegistry, InterfaceTarget,
    ObjectProvider, ProviderResult, PublishedObject, RegisteredInterface, RegistrationError, Scope,
    ScopeObservation, Target, Validator, WipObject,
 };
 use wip_interface::{OperationResult, interface};
 use wip_protocol::{InterfaceReference, ProtocolErrorCode, Value};
 #[interface]
 pub trait Read {
    fn read(&self, value: String) -> OperationResult<String>;
 }
 #[interface]
 pub trait Count {
    fn read(&self, value: i64) -> OperationResult<i64>;
 }
 #[derive(Clone)]
 struct Metadata {
    name: String,
    reference: Option<String>,
    validator: Option<Validator>,
 }
 impl WipObject for Metadata {
    fn name(&self) -> &str {
        &self.name
    }
    fn reference(&self) -> Option<&str> {
        self.reference.as_deref()
    }
    fn validator(&self) -> Option<&Validator> {
        self.validator.as_ref()
    }
 }
 type OnStart = Rc<RefCell<Option<Box<dyn Fn()>>>>;
 struct Implementation {
    metadata: Metadata,
    calls: Rc<Cell<usize>>,
    on_start: OnStart,
 }
 impl WipObject for Implementation {
    fn name(&self) -> &str {
        self.metadata.name()
    }
    fn reference(&self) -> Option<&str> {
        self.metadata.reference()
    }
    fn validator(&self) -> Option<&Validator> {
        self.metadata.validator()
    }
 }
 impl Read for Implementation {
    fn read(&self, value: String) -> OperationResult<String> {
        self.calls.set(self.calls.get() + 1);
        if let Some(action) = self.on_start.borrow_mut().take() {
            action();
        }
        Ok(value)
    }
 }
 struct Provider {
    interface: RegisteredInterface<ReadDefinition>,
    current: Rc<RefCell<Option<(Scope, Metadata)>>>,
    target_path: String,
    target_exists: Cell<bool>,
    member: Cell<bool>,
    calls: Rc<Cell<usize>>,
    resolutions: Cell<usize>,
    on_start: OnStart,
 }
 impl Provider {
    fn new(
        scope: &Scope,
        interface: RegisteredInterface<ReadDefinition>,
        target: &str,
        reference: Option<&str>,
    ) -> Self {
        Self {
            interface,
            current: Rc::new(RefCell::new(Some((
                scope.clone(),
                Metadata {
                    name: scope.path().rsplit('/').next().unwrap().into(),
                    reference: reference.map(str::to_owned),
                    validator: Some(Validator::new(b"scope-state-v1")),
                },
            )))),
            target_path: target.into(),
            target_exists: Cell::new(true),
            member: Cell::new(true),
            calls: Rc::new(Cell::new(0)),
            resolutions: Cell::new(0),
            on_start: Rc::new(RefCell::new(None)),
        }
    }
    fn request(&self, scope_ref: Option<&str>) -> CallRequest {
        CallRequest {
            target: Target {
                path: self.target_path.clone(),
                validator: None,
            },
            interface: InterfaceTarget {
                reference: self.interface.reference().protocol_reference(),
                scope_ref: scope_ref.map(str::to_owned),
                validator: Some(b"descriptor-v1".to_vec()),
            },
            operation: "read".into(),
            arguments: BTreeMap::from([("value".into(), Value::String("original backend".into()))]),
        }
    }
 }
 impl ObjectProvider for Provider {
    type Object = Implementation;
    fn with_object<R>(
        &self,
        _: &ExecutionContext,
        path: &str,
        callback: impl FnOnce(&PublishedObject<Self::Object>) -> R,
    ) -> ProviderResult<R> {
        self.resolutions.set(self.resolutions.get() + 1);
        // A single boundary captures both the target and the live scope association.
        let current = self.current.borrow().clone();
        let target = path == self.target_path;
        let metadata = if target {
            if !self.target_exists.get() {
                return ProviderResult::NotFound;
            }
            if let Some((scope, object)) = &current
                && scope.path() == path
            {
                object.clone()
            } else {
                Metadata {
                    name: path.rsplit('/').next().unwrap().into(),
                    reference: None,
                    validator: Some(Validator::new(b"target-v1")),
                }
            }
        } else if let Some((scope, object)) = &current {
            if path != scope.path() {
                return ProviderResult::NotFound;
            }
            object.clone()
        } else {
            return ProviderResult::NotFound;
        };
        let mut publication = PublishedObject::new(Implementation {
            metadata,
            calls: self.calls.clone(),
            on_start: self.on_start.clone(),
        });
        if target && self.member.get() {
            publication = publication.expose(&self.interface).unwrap();
        }
        if let Some((scope, object)) = current {
            publication = publication.bind_scope(ScopeObservation::new(&scope, &object));
        }
        ProviderResult::Found(callback(&publication))
    }
 }
 fn setup(
    scope: &str,
    target: &str,
    reference: Option<&str>,
 ) -> (InterfaceRegistry, Scope, Provider) {
    let scope = Scope::new(scope).unwrap();
    let mut registry = InterfaceRegistry::new();
    let interface = registry
        .register(
            &scope,
            "read::#日本語",
            ReadDefinition,
            Some(Validator::new(b"descriptor-v1")),
        )
        .unwrap();
    let provider = Provider::new(&scope, interface, target, reference);
    (registry, scope, provider)
 }
 #[test]
 fn registrations_use_scope_name_not_definition_type_or_delimiters() {
    let mut registry = InterfaceRegistry::new();
    let left = Scope::new("/left").unwrap();
    let right = Scope::new("/right").unwrap();
    let a = registry
        .register(&left, "read::#日本語", ReadDefinition, None)
        .unwrap();
    let b = registry
        .register(&right, "read::#日本語", ReadDefinition, None)
        .unwrap();
    assert_ne!(a.reference(), b.reference());
    assert_eq!(
        a.reference().protocol_reference(),
        InterfaceReference {
            scope: "/left".into(),
            name: "read::#日本語".into(),
        }
    );
    assert!(matches!(
        registry.register(&left, "read::#日本語", CountDefinition, None),
        Err(RegistrationError::AlreadyRegistered)
    ));
    assert!(matches!(
        registry.register(&left, "", ReadDefinition, None),
        Err(RegistrationError::InvalidReference(_))
    ));
    assert!(Scope::new("/invalid/").is_err());
    registry
        .register(&left, "another", ReadDefinition, None)
        .unwrap();
 }
 #[test]
 fn self_root_ancestor_and_membership_are_independent() {
    for (scope, target) in [
        ("/", "/"),
        ("/", "/target"),
        ("/scope", "/scope"),
        ("/scope", "/scope/target"),
    ] {
        let (registry, _, provider) = setup(scope, target, Some("scope-id"));
        assert_eq!(
            provider
                .call_operation(provider.request(Some("scope-id")))
                .unwrap()
                .result,
            Value::String("original backend".into())
        );
        assert_eq!(
            provider
                .fetch_interface(&registry, &provider.request(None).interface.reference)
                .unwrap()
                .scope_ref
                .as_deref(),
            Some("scope-id")
        );
        provider.member.set(false);
        assert_eq!(
            provider
                .call_operation(provider.request(None))
                .unwrap_err()
                .kind(),
            CallErrorKind::InterfaceMismatch
        );
    }
    // Non-self scope Objects need not implement or expose any Interface.
    let (registry, _, provider) = setup("/scope", "/scope/target", None);
    assert!(
        provider
            .observe_object("/scope")
            .unwrap()
            .interfaces
            .is_empty()
    );
    provider
        .fetch_interface(&registry, &provider.request(None).interface.reference)
        .unwrap();
    for target in ["/sibling/target", "/scopelong", "/"] {
        let (_, _, provider) = setup("/scope", target, None);
        assert_eq!(
            provider
                .call_operation(provider.request(None))
                .unwrap_err()
                .kind(),
            CallErrorKind::InterfaceMismatch
        );
        assert_eq!(provider.calls.get(), 0);
        assert_eq!(
            provider.observe_object(target).unwrap_err().kind(),
            CallErrorKind::Internal
        );
    }
 }
 #[test]
 fn optional_scope_ref_and_state_validator_have_distinct_responsibilities() {
    for current in [Some("scope-id"), None, Some("")] {
        let (registry, _, provider) = setup("/scope", "/scope/target", current);
        let observation = provider
            .fetch_interface(&registry, &provider.request(None).interface.reference)
            .unwrap();
        assert_eq!(
            observation
                .protocol_response()
                .unwrap()
                .scope_ref
                .as_deref(),
            current
        );
        assert_eq!(
            observation.validator,
            Some(Validator::new(b"descriptor-v1"))
        );
        provider.call_operation(provider.request(None)).unwrap();
        if let Some(reference) = current {
            provider
                .call_operation(provider.request(Some(reference)))
                .unwrap();
        }
        let before = provider.calls.get();
        for supplied in ["other", "missing"] {
            let mut call = provider.request(Some(supplied));
            call.interface.validator = None;
            call.operation = "missing".into();
            assert_eq!(
                provider.call_operation(call).unwrap_err().kind(),
                CallErrorKind::InterfaceMismatch
            );
        }
        assert_eq!(provider.calls.get(), before);
        provider.current.borrow_mut().as_mut().unwrap().1.validator =
            Some(Validator::new(b"scope-state-v2"));
        provider.call_operation(provider.request(current)).unwrap();
        assert_eq!(
            provider
                .fetch_interface(&registry, &provider.request(None).interface.reference)
                .unwrap(),
            observation
        );
    }
 }
 #[test]
 fn scope_precondition_is_membership_stage_in_both_dispatch_paths() {
    let (_, _, provider) = setup("/scope", "/scope/target", Some("current"));
    let mut call = provider.request(Some("stale"));
    call.target.validator = Some(b"wrong".to_vec());
    assert_eq!(
        provider.call_operation(call.clone()).unwrap_err().kind(),
        CallErrorKind::ValidatorMismatch
    );
    provider.target_exists.set(false);
    assert_eq!(
        provider.call_operation(call).unwrap_err().kind(),
        CallErrorKind::NotFound
    );
    provider.target_exists.set(true);
    let call = provider.request(Some("stale"));
    assert_eq!(
        provider
            .call_operation_with_context_and_decoder(
                &ExecutionContext::new(),
                call.target,
                call.interface,
                call.operation,
                |_| -> Result<BTreeMap<String, Value>, ()> { panic!("decoder must not run") }
            )
            .unwrap_err()
            .kind(),
        CallErrorKind::InterfaceMismatch
    );
    assert_eq!(provider.calls.get(), 0);
 }
 #[test]
 fn deletion_republication_and_movement_never_inherit_retained_artifacts() {
    let (mut registry, scope, provider) = setup("/scope", "/scope/target", Some("old"));
    let reference = provider.request(None).interface.reference;
    provider.fetch_interface(&registry, &reference).unwrap();
    *provider.current.borrow_mut() = None;
    provider.target_exists.set(false);
    assert_eq!(
        provider
            .fetch_interface(&registry, &reference)
            .unwrap_err()
            .code,
        ProtocolErrorCode::InterfaceNotFound
    );
    assert_eq!(
        provider
            .call_operation(provider.request(None))
            .unwrap_err()
            .kind(),
        CallErrorKind::NotFound
    );
    provider.target_exists.set(true);
    // Even the same ref is not proof that a replacement inherits registration.
    let replacement = Scope::new("/scope").unwrap();
    *provider.current.borrow_mut() = Some((
        replacement.clone(),
        Metadata {
            name: "scope".into(),
            reference: Some("old".into()),
            validator: None,
        },
    ));
    assert_eq!(
        provider
            .fetch_interface(&registry, &reference)
            .unwrap_err()
            .code,
        ProtocolErrorCode::InterfaceNotFound
    );
    assert_eq!(
        provider
            .call_operation(provider.request(Some("old")))
            .unwrap_err()
            .kind(),
        CallErrorKind::InterfaceMismatch
    );
    registry.remove_scope(&scope);
    assert!(matches!(
        registry.register(&scope, "new", ReadDefinition, None),
        Err(RegistrationError::RetiredScope)
    ));
    let fresh = registry
        .register(&replacement, reference.name.clone(), ReadDefinition, None)
        .unwrap();
    provider.fetch_interface(&registry, &reference).unwrap();
    // Old target membership still binds the old lifetime, even after new publication.
    assert_eq!(
        provider
            .call_operation(provider.request(None))
            .unwrap_err()
            .kind(),
        CallErrorKind::InterfaceMismatch
    );
    let new_provider = Provider::new(&replacement, fresh, "/scope/target", Some("new"));
    let mut new_call = new_provider.request(Some("new"));
    new_call.interface.validator = None;
    new_provider.call_operation(new_call).unwrap();
    let moved = Scope::new("/moved").unwrap();
    new_provider.target_exists.set(false);
    *new_provider.current.borrow_mut() = Some((
        moved.clone(),
        Metadata {
            name: "moved".into(),
            reference: Some("new".into()),
            validator: None,
        },
    ));
    assert_eq!(
        new_provider
            .fetch_interface(&registry, &reference)
            .unwrap_err()
            .code,
        ProtocolErrorCode::InterfaceNotFound
    );
    assert_eq!(
        new_provider
            .call_operation(new_provider.request(None))
            .unwrap_err()
            .kind(),
        CallErrorKind::NotFound
    );
    let moved_interface = registry
        .register(&moved, reference.name, ReadDefinition, None)
        .unwrap();
    assert_eq!(
        moved_interface.reference().protocol_reference().scope,
        "/moved"
    );
    assert_eq!(provider.calls.get(), 0);
 }
 #[test]
 fn replacement_after_fetch_rejects_old_ref_but_omission_and_refless_are_allowed() {
    for previous_ref in [Some("old"), None] {
        let (mut registry, old_scope, old_provider) =
            setup("/scope", "/scope/target", previous_ref);
        let observed = old_provider
            .fetch_interface(&registry, &old_provider.request(None).interface.reference)
            .unwrap();
        registry.remove_scope(&old_scope);
        let new_scope = Scope::new("/scope").unwrap();
        let token = registry
            .register(
                &new_scope,
                "read::#日本語",
                ReadDefinition,
                Some(Validator::new(b"descriptor-v1")),
            )
            .unwrap();
        let new_provider = Provider::new(&new_scope, token, "/scope/target", None);
        if let Some(reference) = observed.scope_ref {
            assert_eq!(
                new_provider
                    .call_operation(new_provider.request(Some(&reference)))
                    .unwrap_err()
                    .kind(),
                CallErrorKind::InterfaceMismatch
            );
            assert_eq!(new_provider.calls.get(), 0);
        }
        new_provider
            .call_operation(new_provider.request(None))
            .unwrap();
    }
 }
 #[test]
 fn started_execution_retains_target_and_same_descriptor_through_replacement() {
    let (registry, old_scope, provider) = setup("/scope", "/scope/target", Some("old"));
    let registry = Rc::new(RefCell::new(registry));
    let current = provider.current.clone();
    let replacement = Scope::new("/scope").unwrap();
    let registry_for_action = registry.clone();
    let replacement_for_action = replacement.clone();
    *provider.on_start.borrow_mut() = Some(Box::new(move || {
        let mut registry = registry_for_action.borrow_mut();
        registry.remove_scope(&old_scope);
        registry
            .register(
                &replacement_for_action,
                "read::#日本語",
                CountDefinition,
                Some(Validator::new(b"descriptor-v2")),
            )
            .unwrap();
        *current.borrow_mut() = Some((
            replacement_for_action.clone(),
            Metadata {
                name: "scope".into(),
                reference: Some("new".into()),
                validator: None,
            },
        ));
    }));
    let call = provider.request(Some("old"));
    let result = provider
        .call_operation_with_context_and_decoder(
            &ExecutionContext::new(),
            call.target,
            call.interface,
            call.operation,
            |descriptor| {
                assert_eq!(descriptor, &ReadDefinition::descriptor());
                Ok::<_, ()>(call.arguments)
            },
        )
        .unwrap();
    assert_eq!(result.result, Value::String("original backend".into()));
    assert_eq!(provider.calls.get(), 1);
    assert_eq!(provider.resolutions.get(), 1);
    let new = provider
        .fetch_interface(
            &registry.borrow(),
            &provider.request(None).interface.reference,
        )
        .unwrap();
    assert_eq!(new.descriptor, CountDefinition::descriptor());
    assert_eq!(new.scope_ref.as_deref(), Some("new"));
    // The old bound target can no longer start a call against the new descriptor.
    assert_eq!(
        provider
            .call_operation(provider.request(None))
            .unwrap_err()
            .kind(),
        CallErrorKind::InterfaceMismatch
    );
    assert_eq!(provider.calls.get(), 1);
 }
@@ -16,6 +16,6 @@ impl WipObject for Object {
 fn main() {
    let mut registry = InterfaceRegistry::new();
-    let search = registry.register(SearchDefinition, None).unwrap();
+    let search = registry.register(&wip_host::Scope::new("/").unwrap(), "search", SearchDefinition, None).unwrap();
    let _published = PublishedObject::new(Object).expose(&search).unwrap();
 }
@@ -0,0 +1,18 @@
 [package]
 name = "wip-http"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 description = "Framework-independent standard WIP over HTTP v1 binding"
 license.workspace = true
 repository.workspace = true
 readme = "README.md"
 documentation = "https://docs.rs/wip-http"
 [dependencies]
 base64 = "0.22"
 http = "1"
 serde = "1"
 serde_json = "1"
 url = "2"
 wip-protocol.workspace = true
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Hare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,52 @@
 # wip-http
 Framework-independent WIP over HTTP v1 endpoint, route, JSON codec, and response-classification support.
 The crate maps the three WIP Core interactions to fixed HTTP routes and strict UTF-8 JSON representations. It constructs and validates `http` request and response values but deliberately performs no network I/O and does not define TLS, authentication, proxy, or connection policy.
 ```toml
 [dependencies]
 wip-http = "0.2.0"
 ```
 ```rust
 use wip_http::wip_protocol::ObserveRequest;
 use wip_http::{Endpoint, Limits, encode_observe_request};
 fn main() -> Result<(), Box<dyn std::error::Error>> {
    let endpoint = Endpoint::parse("https://example.test/wip")?;
    let limits = Limits::new(64 * 1024, 1024 * 1024, 64)?;
    let request = encode_observe_request(
        &endpoint,
        &ObserveRequest { path: "/".into(), depth: 0 },
        limits,
    )?;
    assert_eq!(request.uri(), "https://example.test/wip/v1/observe");
    Ok(())
 }
 ```
 ## Interface references and scope identity
 Every interface reference is encoded as an exact JSON object with required
 `scope` and `name` strings, for example `{"scope":"/github","name":"issue.read"}`.
 This applies to `Object.interfaces` elements, fetch request/response `interface`,
 and call `interface.reference`. Scope must be a canonical absolute Worldspace
 path and name must be nonempty. Legacy opaque strings, short-form strings,
 relative scopes, missing fields, and extra members are rejected. Unicode, `::`,
 and `#` in names remain literal data; comparison uses decoded field values,
 independent of JSON member order and escapes. HTTP endpoint prefixes do not
 change Worldspace scope.
 Fetch responses and call interface targets additionally carry optional
 `scope_ref`, an opaque string copied from the scope Object's `ref` observation.
 It is not base64 and is not part of interface identity. Absent values are omitted;
 null and nonstring values are rejected. Descriptor-independent call metadata
 validates reference shape, but leaves scope ancestry and identity preconditions
 to the Host's `InterfaceMismatch` check, preserving protocol error precedence.
 Invalid success responses remain client-local `InvalidResponse` errors; protocol
 error envelopes and transport failures retain their existing classification.
 See the [API documentation](https://docs.rs/wip-http) for codec and failure-boundary details.
 Licensed under either of Apache-2.0 or MIT at your option.
@@ -1,18 +1,18 @@
 use std::error::Error;
 use std::fmt::{self, Display, Formatter};
-use http::header::{ACCEPT, CONTENT_TYPE};
+use http::header::{ACCEPT, CONTENT_ENCODING, CONTENT_TYPE};
 use http::{HeaderMap, Method, Request, Response, StatusCode};
 use wip_protocol::{
    CallOperationRequest, CallOperationResponse, FetchInterfaceRequest, FetchInterfaceResponse,
-    FetchRequest, FetchResponse, FetchTreeRequest, FetchTreeResponse, INTERFACE_FORMAT_V1,
+    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, ObserveRequest, ObserveResponse,
-    InterfaceDescriptor, InterfaceTarget, ProtocolError, ProtocolInteraction, Target,
+    ProtocolError, ProtocolInteraction, Target,
 };
 use crate::response::{self, DecodedResponse};
 use crate::{
    BodyKind, ClientResponseError, CodecError, Endpoint, InvalidResponseKind, JSON_CONTENT_TYPE,
-    Limits, ResourceLimitKind, Route, json,
+    Limits, Route, json,
 };
 fn request(
@@ -36,6 +36,9 @@ fn response(status: StatusCode, body: Vec<u8>) -> Result<Response<Vec<u8>>, http
 }
 fn require_response_content_type<B>(response: &Response<B>) -> Result<(), ClientResponseError> {
    if !has_supported_content_coding(response.headers()) {
        return Err(response::unsupported_content_coding(response.status()));
    }
    let valid = response
        .headers()
        .get(CONTENT_TYPE)
@@ -181,9 +184,11 @@ fn accepts_json(headers: &HeaderMap) -> bool {
 /// A failure while validating inbound HTTP request metadata.
 #[derive(Debug)]
 pub enum RequestMetadataError {
-    /// The method or route does not match the selected WIP interaction.
+    /// The request URI does not exactly identify the selected standard route.
-    InvalidRequest(CodecError),
+    NotFound,
-    /// The request body does not use UTF-8 `application/json`.
+    /// A known standard route was requested with a method other than `POST`.
    MethodNotAllowed,
    /// The request body does not use UTF-8 `application/json` or identity coding.
    UnsupportedMediaType,
    /// The request's `Accept` metadata excludes `application/json`.
    NotAcceptable,
@@ -194,32 +199,47 @@ impl RequestMetadataError {
    #[must_use]
    pub const fn status(&self) -> StatusCode {
        match self {
-            Self::InvalidRequest(_) => StatusCode::BAD_REQUEST,
+            Self::NotFound => StatusCode::NOT_FOUND,
            Self::MethodNotAllowed => StatusCode::METHOD_NOT_ALLOWED,
            Self::UnsupportedMediaType => StatusCode::UNSUPPORTED_MEDIA_TYPE,
            Self::NotAcceptable => StatusCode::NOT_ACCEPTABLE,
        }
    }
    /// Returns the value for an `Allow` response header, when required.
    #[must_use]
    pub const fn allow(&self) -> Option<&'static str> {
        match self {
            Self::MethodNotAllowed => Some("POST"),
            Self::NotFound | Self::UnsupportedMediaType | Self::NotAcceptable => None,
        }
    }
 }
 impl Display for RequestMetadataError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        match self {
-            Self::InvalidRequest(error) => error.fmt(formatter),
+            Self::NotFound => formatter.write_str("request URI is not a standard WIP route"),
            Self::MethodNotAllowed => formatter.write_str("standard WIP routes require POST"),
            Self::UnsupportedMediaType => {
-                formatter.write_str("expected UTF-8 application/json Content-Type")
+                formatter.write_str("expected identity-coded UTF-8 application/json Content-Type")
            }
            Self::NotAcceptable => formatter.write_str("request does not accept application/json"),
        }
    }
 }
-impl Error for RequestMetadataError {
+impl Error for RequestMetadataError {}
-    fn source(&self) -> Option<&(dyn Error + 'static)> {
+
-        match self {
+pub(crate) fn has_supported_content_coding(headers: &HeaderMap) -> bool {
-            Self::InvalidRequest(error) => Some(error),
+    headers.get_all(CONTENT_ENCODING).iter().all(|value| {
-            Self::UnsupportedMediaType | Self::NotAcceptable => None,
+        value.to_str().is_ok_and(|value| {
-        }
+            let mut codings = value.split(',').map(str::trim);
-    }
+            let first = codings.next();
            first.is_some_and(|coding| coding.eq_ignore_ascii_case("identity"))
                && codings.all(|coding| coding.eq_ignore_ascii_case("identity"))
        })
    })
 }
 /// Validates mandatory HTTP metadata for an inbound WIP request.
@@ -233,29 +253,19 @@ pub fn validate_http_request<B>(
    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(
+        return Err(RequestMetadataError::NotFound);
-            CodecError::InvalidField {
+    }
-                field: "route".into(),
+    if value.method() != Method::POST {
-                reason: "request URI does not match the selected standard route".into(),
+        return Err(RequestMetadataError::MethodNotAllowed);
            },
        ));
    }
    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 !valid_content_type || !has_supported_content_coding(value.headers()) {
        return Err(RequestMetadataError::UnsupportedMediaType);
    }
    if !accepts_json(value.headers()) {
@@ -264,57 +274,36 @@ pub fn validate_http_request<B>(
    Ok(())
 }
-/// Encodes a `fetch` HTTP request.
+/// Encodes an `observe` HTTP request.
-pub fn encode_fetch_request(
+pub fn encode_observe_request(
    endpoint: &Endpoint,
-    value: &FetchRequest,
+    value: &ObserveRequest,
    limits: Limits,
 ) -> Result<Request<Vec<u8>>, EncodeHttpError> {
    value.validate().map_err(CodecError::from)?;
    let body = json::serialize(
-        &json::fetch_request_to_json(value),
+        &json::observe_request_to_json(value),
        BodyKind::Request,
        limits,
    )?;
-    Ok(request(endpoint, Route::Fetch, body)?)
+    Ok(request(endpoint, Route::Observe, body)?)
 }
-/// Decodes a `fetch` request body.
+/// Decodes an `observe` request body.
-pub fn decode_fetch_request(body: &[u8], limits: Limits) -> Result<FetchRequest, CodecError> {
+pub fn decode_observe_request(body: &[u8], limits: Limits) -> Result<ObserveRequest, CodecError> {
    let value = json::parse(body, BodyKind::Request, limits)?;
-    json::fetch_request_from_json(&value)
+    json::observe_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.
 ///
 /// Validates reference shape without requiring a target Object path.
 pub fn encode_fetch_interface_request(
    endpoint: &Endpoint,
    value: &FetchInterfaceRequest,
    limits: Limits,
 ) -> Result<Request<Vec<u8>>, EncodeHttpError> {
    value.interface.validate().map_err(CodecError::from)?;
    let body = json::serialize(
        &json::fetch_interface_request_to_json(value),
        BodyKind::Request,
@@ -372,6 +361,10 @@ impl CallOperationMetadata {
 }
 /// Decodes descriptor-independent `call_operation` routing metadata.
 ///
 /// Reference shape is validated, but scope ancestry and `scope_ref` identity
 /// are left to Host resolution so `NotFound`, validator failures, and
 /// `InterfaceMismatch` retain their protocol precedence.
 pub fn decode_call_operation_metadata(
    body: &[u8],
    limits: Limits,
@@ -407,72 +400,39 @@ pub fn decode_call_operation_request(
    json::call_request_from_json(&value, descriptor)
 }
-/// Encodes a successful `fetch` response as a direct body with HTTP 200.
+/// Encodes a successful `observe` response as a direct body with HTTP 200.
-pub fn encode_fetch_response(
+pub fn encode_observe_response(
-    request_value: &FetchRequest,
+    request_value: &ObserveRequest,
-    value: &FetchResponse,
+    value: &ObserveResponse,
    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),
+        &json::observe_response_to_json(value),
        BodyKind::Response,
        limits,
    )?;
    Ok(response(StatusCode::OK, body)?)
 }
-/// Decodes and classifies a `fetch_tree` client response.
+/// Decodes and classifies an `observe` client response.
-pub fn decode_fetch_tree_response<B: AsRef<[u8]>>(
+pub fn decode_observe_response<B: AsRef<[u8]>>(
-    request_value: &FetchTreeRequest,
+    request_value: &ObserveRequest,
    value: &Response<B>,
    limits: Limits,
-) -> Result<DecodedResponse<FetchTreeResponse>, ClientResponseError> {
+) -> Result<DecodedResponse<ObserveResponse>, ClientResponseError> {
    require_response_content_type(value)?;
    response::decode(
        value.status(),
        value.body().as_ref(),
-        ProtocolInteraction::FetchTree,
+        ProtocolInteraction::Observe,
        limits,
        |json| {
-            let tree = json::fetch_tree_response_from_json(json)?;
+            let observation = json::observe_response_from_json(json)?;
-            tree.validate_for(request_value)?;
+            request_value.validate_response(&observation)?;
-            Ok(tree)
+            Ok(observation)
        },
    )
 }
@@ -583,9 +543,8 @@ fn encode_protocol_error_with_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
+/// error envelopes. Logical `resource_limit_exceeded` failures use HTTP 422;
-/// that know the concrete limit class should use
+/// representation and deployment limits are not protocol errors.
 /// [`encode_resource_limit_error_response`].
 pub fn encode_protocol_error_response(
    interaction: ProtocolInteraction,
    error: &ProtocolError,
@@ -599,28 +558,6 @@ pub fn encode_protocol_error_response(
    )
 }
 /// 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 {
@@ -6,19 +6,15 @@ 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.
+/// A fixed standard WIP over HTTP v1 route.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Route {
-    /// Fetch one object.
+    /// Observe one object and its indexable descendants.
-    Fetch,
+    Observe,
    /// Fetch a bounded object tree.
    FetchTree,
    /// Fetch an interface descriptor.
    FetchInterface,
    /// Call one operation.
    CallOperation,
    /// Package independent retrieval interactions.
    Batch,
 }
 impl Route {
@@ -26,31 +22,27 @@ impl Route {
    #[must_use]
    pub const fn relative_reference(self) -> &'static str {
        match self {
-            Self::Fetch => "v1/fetch",
+            Self::Observe => "v1/observe",
            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 `/`.
+/// A canonical absolute hierarchical 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
+    /// The input must be an absolute hierarchical URL with a host and without a
-    /// path is an endpoint prefix, not a Worldspace path. A trailing slash is
+    /// query or fragment. Its path is an endpoint prefix, not a Worldspace path.
-    /// appended when absent so RFC 3986 relative-reference resolution preserves
+    /// A trailing slash is appended when absent so RFC 3986 relative-reference
-    /// the final prefix segment.
+    /// resolution preserves the final prefix segment. The supplied scheme is
    /// preserved; scheme and transport security are deployment concerns.
    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);
        }
@@ -87,13 +79,7 @@ impl Endpoint {
    /// are not route components and therefore never match.
    #[must_use]
    pub fn recognize(&self, candidate: &Url) -> Option<Route> {
-        const ROUTES: [Route; 5] = [
+        const ROUTES: [Route; 3] = [Route::Observe, Route::FetchInterface, Route::CallOperation];
            Route::Fetch,
            Route::FetchTree,
            Route::FetchInterface,
            Route::CallOperation,
            Route::Batch,
        ];
        if candidate.query().is_some() || candidate.fragment().is_some() {
            return None;
        }
@@ -117,13 +103,11 @@ impl TryFrom<&str> for Endpoint {
    }
 }
-/// Why an endpoint is not a valid standard WIP HTTPS base.
+/// Why an endpoint is not a valid standard WIP over HTTP 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.
@@ -136,7 +120,6 @@ 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")
            }
@@ -10,8 +10,6 @@ pub struct Limits {
    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 {
@@ -20,7 +18,6 @@ impl Limits {
        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);
@@ -31,14 +28,10 @@ impl Limits {
        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,
        })
    }
@@ -59,12 +52,6 @@ impl Limits {
    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.
@@ -76,8 +63,6 @@ pub enum LimitConfigurationError {
    ZeroResponseBytes,
    /// Nesting limit was zero.
    ZeroNesting,
    /// Batch-item limit was zero.
    ZeroBatchItems,
 }
 impl Display for LimitConfigurationError {
@@ -86,7 +71,6 @@ impl Display for LimitConfigurationError {
            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",
        })
    }
 }
@@ -102,15 +86,6 @@ pub enum BodyKind {
    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 {
@@ -157,47 +132,6 @@ pub enum CodecError {
    },
    /// 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 {
@@ -225,15 +159,6 @@ impl Display for CodecError {
                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}`")
            }
        }
    }
 }
@@ -7,10 +7,10 @@ use serde::de::{self, Deserialize, Deserializer, MapAccess, SeqAccess, Visitor};
 use serde_json::{Map, Number, Value as Json};
 use wip_protocol::{
    CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
-    FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
+    FetchInterfaceResponse, FieldDeclaration, INTERFACE_FORMAT_V1, InterfaceDescriptor,
-    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER,
+    InterfaceReference, InterfaceTarget, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, Object,
-    Object, ObjectTreeNode, OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target,
+    ObjectObservation, ObserveRequest, ObserveResponse, OperationDeclaration, ParameterDeclaration,
-    TypeDeclaration, TypeExpr, UnionCase, Value,
+    ReturnDeclaration, Target, TypeDeclaration, TypeExpr, UnionCase, Value,
 };
 use crate::{BodyKind, CodecError, Limits};
@@ -271,36 +271,39 @@ fn insert_optional_bytes(map: &mut Map<String, Json>, name: &str, value: &Option
    }
 }
-pub(crate) fn fetch_request_to_json(request: &FetchRequest) -> Json {
+pub(crate) fn observe_request_to_json(request: &ObserveRequest) -> Json {
-    serde_json::json!({"path": request.path})
+    serde_json::json!({"path": request.path, "depth": request.depth})
 }
-pub(crate) fn fetch_request_from_json(value: &Json) -> Result<FetchRequest, CodecError> {
+pub(crate) fn observe_request_from_json(value: &Json) -> Result<ObserveRequest, CodecError> {
-    let fields = exact_object(value, "request", &["path"])?;
+    let fields = exact_object(value, "request", &["path", "depth"])?;
-    let request = FetchRequest {
+    let request = ObserveRequest {
        path: string(required(fields, "path")?, "path")?,
    };
    request.validate()?;
    Ok(request)
 }
 pub(crate) fn fetch_tree_request_to_json(request: &FetchTreeRequest) -> Json {
    serde_json::json!({"path": request.path, "depth": request.depth, "limit": request.limit})
 }
 pub(crate) fn fetch_tree_request_from_json(value: &Json) -> Result<FetchTreeRequest, CodecError> {
    let fields = exact_object(value, "request", &["path", "depth", "limit"])?;
    let request = FetchTreeRequest {
        path: string(required(fields, "path")?, "path")?,
        depth: u32_number(required(fields, "depth")?, "depth")?,
        limit: u32_number(required(fields, "limit")?, "limit")?,
    };
    request.validate()?;
    Ok(request)
 }
 fn interface_reference_to_json(reference: &InterfaceReference) -> Json {
    serde_json::json!({"scope": reference.scope, "name": reference.name})
 }
 fn interface_reference_from_json(
    value: &Json,
    field: &str,
 ) -> Result<InterfaceReference, CodecError> {
    let fields = exact_object(value, field, &["scope", "name"])?;
    let reference = InterfaceReference {
        scope: string(required(fields, "scope")?, &qualified(field, "scope"))?,
        name: string(required(fields, "name")?, &qualified(field, "name"))?,
    };
    reference.validate()?;
    Ok(reference)
 }
 pub(crate) fn fetch_interface_request_to_json(request: &FetchInterfaceRequest) -> Json {
-    serde_json::json!({"interface": request.interface})
+    serde_json::json!({"interface": interface_reference_to_json(&request.interface)})
 }
 pub(crate) fn fetch_interface_request_from_json(
@@ -308,7 +311,7 @@ pub(crate) fn fetch_interface_request_from_json(
 ) -> Result<FetchInterfaceRequest, CodecError> {
    let fields = exact_object(value, "request", &["interface"])?;
    Ok(FetchInterfaceRequest {
-        interface: string(required(fields, "interface")?, "interface")?,
+        interface: interface_reference_from_json(required(fields, "interface")?, "interface")?,
    })
 }
@@ -322,8 +325,7 @@ pub(crate) fn object_to_json(object: &Object) -> Json {
            object
                .interfaces
                .iter()
-                .cloned()
+                .map(interface_reference_to_json)
                .map(Json::String)
                .collect(),
        ),
    );
@@ -341,7 +343,7 @@ pub(crate) fn object_from_json(value: &Json, field: &str) -> Result<Object, Code
    let interfaces = array(required(fields, "interfaces")?, "interfaces")?
        .iter()
        .enumerate()
-        .map(|(index, value)| string(value, &format!("interfaces[{index}]")))
+        .map(|(index, value)| interface_reference_from_json(value, &format!("interfaces[{index}]")))
        .collect::<Result<Vec<_>, _>>()?;
    let object = Object {
        name: string(required(fields, "name")?, "name")?,
@@ -360,35 +362,43 @@ pub(crate) fn object_from_json(value: &Json, field: &str) -> Result<Object, Code
    Ok(object)
 }
-fn tree_node_to_json(node: &ObjectTreeNode) -> Json {
+fn observation_to_json(node: &ObjectObservation) -> Json {
-    serde_json::json!({
+    let mut fields = Map::new();
-        "object": object_to_json(&node.object),
+    fields.insert("object".into(), object_to_json(&node.object));
-        "children": node.children.iter().map(tree_node_to_json).collect::<Vec<_>>()
+    if let Some(children) = &node.children {
-    })
+        fields.insert(
            "children".into(),
            Json::Array(children.iter().map(observation_to_json).collect()),
        );
    }
    Json::Object(fields)
 }
-fn tree_node_from_json(value: &Json, field: &str) -> Result<ObjectTreeNode, CodecError> {
+fn observation_from_json(value: &Json, field: &str) -> Result<ObjectObservation, CodecError> {
    let fields = exact_object(value, field, &["object", "children"])?;
-    Ok(ObjectTreeNode {
+    let children = optional(fields, "children")?
        .map(|value| {
            array(value, &qualified(field, "children"))?
                .iter()
                .enumerate()
                .map(|(index, child)| {
                    observation_from_json(child, &format!("{field}.children[{index}]"))
                })
                .collect::<Result<Vec<_>, _>>()
        })
        .transpose()?;
    Ok(ObjectObservation {
        object: object_from_json(required(fields, "object")?, &qualified(field, "object"))?,
-        children: array(required(fields, "children")?, &qualified(field, "children"))?
+        children,
            .iter()
            .enumerate()
            .map(|(index, child)| tree_node_from_json(child, &format!("{field}.children[{index}]")))
            .collect::<Result<Vec<_>, _>>()?,
    })
 }
-pub(crate) fn fetch_tree_response_to_json(response: &FetchTreeResponse) -> Json {
+pub(crate) fn observe_response_to_json(response: &ObserveResponse) -> Json {
-    serde_json::json!({"root": tree_node_to_json(&response.root), "truncated": response.truncated})
+    observation_to_json(response)
 }
-pub(crate) fn fetch_tree_response_from_json(value: &Json) -> Result<FetchTreeResponse, CodecError> {
+pub(crate) fn observe_response_from_json(value: &Json) -> Result<ObserveResponse, CodecError> {
-    let fields = exact_object(value, "response", &["root", "truncated"])?;
+    observation_from_json(value, "response")
    Ok(FetchTreeResponse {
        root: tree_node_from_json(required(fields, "root")?, "root")?,
        truncated: boolean(required(fields, "truncated")?, "truncated")?,
    })
 }
 fn documentation_to_json(documentation: &Documentation) -> Json {
@@ -751,7 +761,11 @@ pub(crate) fn descriptor_from_json(
 pub(crate) fn fetch_interface_response_to_json(response: &FetchInterfaceResponse) -> Json {
    let mut fields = Map::new();
-    fields.insert("interface".into(), Json::String(response.interface.clone()));
+    fields.insert(
        "interface".into(),
        interface_reference_to_json(&response.interface),
    );
    insert_optional_string(&mut fields, "scope_ref", &response.scope_ref);
    fields.insert(
        "descriptor".into(),
        descriptor_to_json(&response.descriptor),
@@ -763,8 +777,15 @@ pub(crate) fn fetch_interface_response_to_json(response: &FetchInterfaceResponse
 pub(crate) fn fetch_interface_response_from_json(
    value: &Json,
 ) -> Result<FetchInterfaceResponse, CodecError> {
-    let fields = exact_object(value, "response", &["interface", "descriptor", "validator"])?;
+    let fields = exact_object(
-    let interface = string(required(fields, "interface")?, "interface")?;
+        value,
        "response",
        &["interface", "scope_ref", "descriptor", "validator"],
    )?;
    let interface = interface_reference_from_json(required(fields, "interface")?, "interface")?;
    let scope_ref = optional(fields, "scope_ref")?
        .map(|value| string(value, "scope_ref"))
        .transpose()?;
    let validator = optional(fields, "validator")?
        .map(|value| base64_decode(value, "validator"))
        .transpose()?;
@@ -786,6 +807,7 @@ pub(crate) fn fetch_interface_response_from_json(
    };
    Ok(FetchInterfaceResponse {
        interface,
        scope_ref,
        descriptor,
        validator,
    })
@@ -1127,18 +1149,25 @@ fn target_from_json(value: &Json, field: &str) -> Result<Target, CodecError> {
 fn interface_target_to_json(target: &InterfaceTarget) -> Json {
    let mut fields = Map::new();
-    fields.insert("reference".into(), Json::String(target.reference.clone()));
+    fields.insert(
        "reference".into(),
        interface_reference_to_json(&target.reference),
    );
    insert_optional_string(&mut fields, "scope_ref", &target.scope_ref);
    insert_optional_bytes(&mut fields, "validator", &target.validator);
    Json::Object(fields)
 }
 fn interface_target_from_json(value: &Json, field: &str) -> Result<InterfaceTarget, CodecError> {
-    let fields = exact_object(value, field, &["reference", "validator"])?;
+    let fields = exact_object(value, field, &["reference", "scope_ref", "validator"])?;
    Ok(InterfaceTarget {
-        reference: string(
+        reference: interface_reference_from_json(
            required(fields, "reference")?,
            &qualified(field, "reference"),
        )?,
        scope_ref: optional(fields, "scope_ref")?
            .map(|value| string(value, &qualified(field, "scope_ref")))
            .transpose()?,
        validator: optional(fields, "validator")?
            .map(|value| base64_decode(value, &qualified(field, "validator")))
            .transpose()?,
@@ -0,0 +1,67 @@
 //! Framework-independent standard WIP over HTTP 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. It deliberately performs no I/O and depends on no
 //! server framework, TLS implementation, filesystem projection, client cache, or
 //! presentation layer. URL schemes, TLS, certificates, authentication mechanisms,
 //! proxies, and caches are selected by the HTTP implementation and deployment
 //! rather than by WIP conformance.
 //!
 //! 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`.
 //!
 //! Interface references use exact JSON objects with required `scope` and `name`
 //! strings in every position. Legacy strings and display shorthand are rejected.
 //! Scope is a canonical absolute Worldspace path, not an HTTP endpoint prefix.
 //! Optional `scope_ref` metadata on fetch responses and call interface targets is
 //! an opaque string, never base64; absent fields are omitted and null is rejected.
 //! Call metadata validates reference shape without resolving scope ancestry or
 //! identity, which remain Host checks with `InterfaceMismatch` precedence.
 //!
 //! ```
 //! use wip_http::{Endpoint, Limits, encode_observe_request};
 //! use wip_protocol::ObserveRequest;
 //!
 //! let endpoint = Endpoint::parse("http://example.test/api/wip")?;
 //! let limits = Limits::new(64 * 1024, 1024 * 1024, 64)?;
 //! let request = encode_observe_request(
 //!     &endpoint,
 //!     &ObserveRequest { path: "/items/123".into(), depth: 0 },
 //!     limits,
 //! )?;
 //! assert_eq!(request.uri(), "http://example.test/api/wip/v1/observe");
 //! assert_eq!(request.method(), http::Method::POST);
 //! # Ok::<(), Box<dyn std::error::Error>>(())
 //! ```
 #![deny(missing_docs)]
 mod codec;
 mod endpoint;
 mod error;
 mod json;
 mod 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_observe_request, decode_observe_response,
    encode_call_operation_request, encode_call_operation_response, encode_fetch_interface_request,
    encode_fetch_interface_response, encode_observe_request, encode_observe_response,
    encode_protocol_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};
 pub use response::{
    ClientResponseError, DecodedResponse, InvalidResponseKind, StatusMismatch,
    TransportBindingFailure, TransportFailureKind, error_code_name, status_for_error,
 };
 /// 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;
@@ -5,7 +5,7 @@ use http::StatusCode;
 use serde_json::{Map, Value as Json};
 use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
-use crate::{BodyKind, CodecError, Limits, ResourceLimitKind, json};
+use crate::{BodyKind, CodecError, Limits, json};
 /// A successfully classified client response.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -37,6 +37,8 @@ pub enum TransportFailureKind {
    AuthenticationRequired,
    /// HTTP 403, commonly emitted by endpoint policy or infrastructure.
    EndpointForbidden,
    /// The response uses a content coding the client does not support.
    UnsupportedContentCoding,
    /// Another non-success HTTP response without a WIP error envelope.
    HttpStatus,
 }
@@ -63,8 +65,6 @@ pub enum InvalidResponseKind {
    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.
@@ -119,10 +119,6 @@ impl Display for ClientResponseError {
 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 {
@@ -145,22 +141,8 @@ pub const fn status_for_error(code: ProtocolErrorCode) -> StatusCode {
    }
 }
 /// 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 {
+    status == status_for_error(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.
@@ -213,14 +195,7 @@ pub(crate) fn error_to_json(error: &ProtocolError) -> Json {
    })
 }
-pub(crate) fn item_error_to_json(error: &ProtocolError) -> Json {
+fn protocol_error_from_json(value: &Json) -> Result<ProtocolError, CodecError> {
    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"))?;
@@ -239,7 +214,7 @@ fn envelope_error_from_json(value: &Json) -> Result<Option<ProtocolError>, Codec
    if fields.len() != 1 || !fields.contains_key("error") {
        return Ok(None);
    }
-    item_error_from_json(&fields["error"]).map(Some)
+    protocol_error_from_json(&fields["error"]).map(Some)
 }
 fn exact(fields: &Map<String, Json>, allowed: &[&str], parent: &str) -> Result<(), CodecError> {
@@ -355,6 +330,13 @@ pub(crate) fn decode<T>(
    }
 }
 pub(crate) fn unsupported_content_coding(status: StatusCode) -> ClientResponseError {
    ClientResponseError::TransportBinding(TransportBindingFailure {
        status,
        kind: TransportFailureKind::UnsupportedContentCoding,
    })
 }
 pub(crate) fn transport_failure(status: StatusCode) -> ClientResponseError {
    let kind = match status {
        StatusCode::UNAUTHORIZED => TransportFailureKind::AuthenticationRequired,
@@ -1,37 +1,42 @@
 use std::collections::BTreeMap;
-use wip_https::http::StatusCode;
+use wip_http::http::StatusCode;
-use wip_https::wip_protocol::{
+use wip_http::wip_protocol::{
    CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
-    FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
+    FetchInterfaceResponse, FieldDeclaration, INTERFACE_FORMAT_V1, InterfaceDescriptor,
-    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, Object,
+    InterfaceReference, InterfaceTarget, MAX_SAFE_INTEGER, Object, ObjectObservation,
-    ObjectTreeNode, OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target,
+    ObserveRequest, OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target,
    TypeDeclaration, TypeExpr, UnionCase, Value,
 };
-use wip_https::{
+use wip_http::{
    ClientResponseError, CodecError, DecodedResponse, Endpoint, InvalidResponseKind, Limits,
-    ResourceLimitKind, decode_call_operation_metadata, decode_call_operation_request,
+    decode_call_operation_metadata, decode_call_operation_request, decode_call_operation_response,
-    decode_call_operation_response, decode_fetch_interface_request,
+    decode_fetch_interface_request, decode_fetch_interface_response, decode_observe_request,
-    decode_fetch_interface_response, decode_fetch_request, decode_fetch_response,
+    decode_observe_response, encode_call_operation_request, encode_call_operation_response,
-    decode_fetch_tree_request, decode_fetch_tree_response, encode_call_operation_request,
+    encode_fetch_interface_request, encode_fetch_interface_response, encode_observe_request,
-    encode_call_operation_response, encode_fetch_interface_request,
+    encode_observe_response,
    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()
+    Limits::new(1_000_000, 1_000_000, 100).unwrap()
 }
 fn endpoint() -> Endpoint {
    Endpoint::parse("https://example.test/wip").unwrap()
 }
 fn reference(scope: &str, name: &str) -> InterfaceReference {
    InterfaceReference {
        scope: scope.into(),
        name: name.into(),
    }
 }
 fn object(name: &str, validator: &[u8]) -> Object {
    Object {
        name: name.into(),
        description: Some("description".into()),
-        interfaces: vec!["interface-v1".into()],
+        interfaces: vec![reference("/", "interface-v1")],
        r#ref: Some(format!("object:{name}")),
        validator: Some(validator.to_vec()),
    }
@@ -154,7 +159,8 @@ fn call_request() -> CallOperationRequest {
            validator: Some(vec![0, 1, 2, 255]),
        },
        interface: InterfaceTarget {
-            reference: "interface-v1".into(),
+            reference: reference("/", "interface-v1"),
            scope_ref: None,
            validator: Some(vec![9, 8, 7]),
        },
        operation: "everything".into(),
@@ -196,14 +202,11 @@ fn call_request() -> CallOperationRequest {
 #[test]
 fn every_single_interaction_request_accepts_json() {
-    let fetch =
+    let observe = encode_observe_request(
        encode_fetch_request(&endpoint(), &FetchRequest { path: "/".into() }, limits()).unwrap();
    let fetch_tree = encode_fetch_tree_request(
        &endpoint(),
-        &FetchTreeRequest {
+        &ObserveRequest {
            path: "/".into(),
-            depth: 1,
+            depth: 0,
            limit: 1,
        },
        limits(),
    )
@@ -211,7 +214,7 @@ fn every_single_interaction_request_accepts_json() {
    let fetch_interface = encode_fetch_interface_request(
        &endpoint(),
        &FetchInterfaceRequest {
-            interface: "interface-v1".into(),
+            interface: reference("/", "interface-v1"),
        },
        limits(),
    )
@@ -219,63 +222,79 @@ fn every_single_interaction_request_accepts_json() {
    let call = encode_call_operation_request(&endpoint(), &call_request(), &descriptor(), limits())
        .unwrap();
-    for request in [fetch, fetch_tree, fetch_interface, call] {
+    for request in [observe, fetch_interface, call] {
        assert_eq!(request.headers()["accept"], "application/json");
    }
 }
 #[test]
-fn fetch_round_trips_direct_body_and_body_validator() {
+fn depth_zero_observe_round_trips_direct_body_and_validator() {
-    let request = FetchRequest {
+    let request = ObserveRequest {
        path: "/items/123".into(),
        depth: 0,
    };
-    let encoded_request = encode_fetch_request(&endpoint(), &request, limits()).unwrap();
+    let encoded_request = encode_observe_request(&endpoint(), &request, limits()).unwrap();
-    assert_eq!(encoded_request.uri().path(), "/wip/v1/fetch");
+    assert_eq!(encoded_request.uri().path(), "/wip/v1/observe");
    assert_eq!(
-        decode_fetch_request(encoded_request.body(), limits()).unwrap(),
+        decode_observe_request(encoded_request.body(), limits()).unwrap(),
        request
    );
-    let expected = object("123", &[0, 1, 2, 255]);
+    let expected = ObjectObservation {
-    let encoded = encode_fetch_response(&request, &expected, limits()).unwrap();
+        object: object("123", &[0, 1, 2, 255]),
        children: None,
    };
    let encoded = encode_observe_response(&request, &expected, limits()).unwrap();
    assert_eq!(encoded.status(), StatusCode::OK);
    assert!(
        !std::str::from_utf8(encoded.body())
            .unwrap()
            .contains("children")
    );
    assert_eq!(
-        decode_fetch_response(&request, &encoded, limits()).unwrap(),
+        decode_observe_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() {
+fn observe_and_interface_round_trip_nested_logical_models() {
-    let tree_request = FetchTreeRequest {
+    let observe_request = ObserveRequest {
        path: "/items".into(),
        depth: 1,
        limit: 2,
    };
-    let encoded_request = encode_fetch_tree_request(&endpoint(), &tree_request, limits()).unwrap();
+    let encoded_request = encode_observe_request(&endpoint(), &observe_request, limits()).unwrap();
    assert_eq!(
-        decode_fetch_tree_request(encoded_request.body(), limits()).unwrap(),
+        decode_observe_request(encoded_request.body(), limits()).unwrap(),
-        tree_request
+        observe_request
    );
-    let tree = FetchTreeResponse {
+    let observation = ObjectObservation {
-        root: ObjectTreeNode {
+        object: object("items", b"root-validator"),
-            object: object("items", b"root-validator"),
+        children: Some(vec![ObjectObservation {
-            children: vec![ObjectTreeNode {
+            object: object("123", b"child-validator"),
-                object: object("123", b"child-validator"),
+            children: None,
-                children: vec![],
+        }]),
            }],
        },
        truncated: false,
    };
-    let encoded = encode_fetch_tree_response(&tree_request, &tree, limits()).unwrap();
+    let encoded = encode_observe_response(&observe_request, &observation, limits()).unwrap();
    assert_eq!(
-        decode_fetch_tree_response(&tree_request, &encoded, limits()).unwrap(),
+        decode_observe_response(&observe_request, &encoded, limits()).unwrap(),
-        DecodedResponse::Success(tree)
+        DecodedResponse::Success(observation)
    );
    let empty = ObjectObservation {
        object: object("items", b"root-validator"),
        children: Some(vec![]),
    };
    let encoded_empty = encode_observe_response(&observe_request, &empty, limits()).unwrap();
    assert!(
        std::str::from_utf8(encoded_empty.body())
            .unwrap()
            .contains("\"children\":[]")
    );
    let interface_request = FetchInterfaceRequest {
-        interface: "interface-v1".into(),
+        interface: reference("/", "interface-v1"),
    };
    let encoded_request =
        encode_fetch_interface_request(&endpoint(), &interface_request, limits()).unwrap();
@@ -285,6 +304,7 @@ fn tree_and_interface_round_trip_nested_logical_models() {
    );
    let interface = FetchInterfaceResponse {
        interface: interface_request.interface.clone(),
        scope_ref: None,
        descriptor: descriptor(),
        validator: Some(vec![4, 5, 6, 255]),
    };
@@ -363,14 +383,16 @@ fn descriptor_guided_values_and_validators_round_trip_both_directions() {
 #[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_observe_request(br#"{"path":"/","depth":0,"extra":true}"#, limits).is_err());
-    assert!(decode_fetch_request(br#"{"path":"relative","path":"/"}"#, limits).is_err());
+    assert!(
        decode_observe_request(br#"{"path":"relative","path":"/","depth":0}"#, 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"},
+        "interface": {"reference": {"scope": "/", "name": "interface-v1"}},
        "operation": "everything",
        "arguments": {}
    }))
@@ -391,25 +413,17 @@ fn malformed_unknown_null_and_noncanonical_base64_are_rejected() {
 }
 #[test]
-fn caller_limits_bound_bytes_and_nesting() {
+fn caller_limits_remain_local_codec_failures() {
-    let tiny = Limits::new(8, 8, 2, 1).unwrap();
+    let tiny = Limits::new(8, 8, 2).unwrap();
-    let too_large = decode_fetch_request(br#"{"path":"/long"}"#, tiny).unwrap_err();
+    let too_large = decode_observe_request(br#"{"path":"/long","depth":0}"#, tiny).unwrap_err();
    assert!(matches!(&too_large, CodecError::BodyTooLarge { .. }));
    assert_eq!(
        too_large.resource_limit_kind(),
        Some(ResourceLimitKind::RepresentationBytes)
    );
-    let nested = br#"{"path":[[["/"]]]}"#;
+    let nested = br#"{"path":[[["/"]]],"depth":0}"#;
-    let nesting_limited = Limits::new(1024, 1024, 2, 1).unwrap();
+    let nesting_limited = Limits::new(1024, 1024, 2).unwrap();
-    let too_deep = decode_fetch_request(nested, nesting_limited).unwrap_err();
+    let too_deep = decode_observe_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();
+    let outbound_limited = Limits::new(1_000_000, 1_000_000, 1).unwrap();
    assert!(
        encode_call_operation_request(
            &endpoint(),
@@ -420,11 +434,15 @@ fn caller_limits_bound_bytes_and_nesting() {
        .is_err()
    );
    assert!(
-        encode_fetch_response(
+        encode_observe_response(
-            &FetchRequest {
+            &ObserveRequest {
                path: "/item".into(),
                depth: 0,
            },
            &ObjectObservation {
                object: object("item", b"validator"),
                children: None,
            },
            &object("item", b"validator"),
            outbound_limited,
        )
        .is_err()
@@ -434,10 +452,11 @@ fn caller_limits_bound_bytes_and_nesting() {
 #[test]
 fn unsupported_descriptor_format_is_client_local() {
    let request = FetchInterfaceRequest {
-        interface: "interface-v1".into(),
+        interface: reference("/", "interface-v1"),
    };
    let mut interface = FetchInterfaceResponse {
        interface: request.interface.clone(),
        scope_ref: None,
        descriptor: descriptor(),
        validator: None,
    };
@@ -449,11 +468,11 @@ fn unsupported_descriptor_format_is_client_local() {
        ClientResponseError::UnsupportedDescriptorFormat { .. }
    ));
-    let future_shape = wip_https::http::Response::builder()
+    let future_shape = wip_http::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}}"#
+            br#"{"interface":{"scope":"/","name":"interface-v1"},"descriptor":{"format":"wip-interface/2","future_shape":true}}"#
                .to_vec(),
        )
        .unwrap();
@@ -464,11 +483,11 @@ fn unsupported_descriptor_format_is_client_local() {
    ));
    for malformed in [
-        br#"{"interface":"wrong","descriptor":{"format":"wip-interface/2"}}"#.as_slice(),
+        br#"{"interface":{"scope":"/","name":"wrong"},"descriptor":{"format":"wip-interface/2"}}"#.as_slice(),
-        br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"},"validator":null}"#
+        br#"{"interface":{"scope":"/","name":"interface-v1"},"descriptor":{"format":"wip-interface/2"},"validator":null}"#
            .as_slice(),
    ] {
-        let response = wip_https::http::Response::builder()
+        let response = wip_http::http::Response::builder()
            .status(StatusCode::OK)
            .header("content-type", "application/json; charset=utf-8")
            .body(malformed.to_vec())
@@ -485,14 +504,15 @@ fn unsupported_descriptor_format_is_client_local() {
 #[test]
 fn invalid_success_is_classified_as_invalid_response() {
-    let response = wip_https::http::Response::builder()
+    let response = wip_http::http::Response::builder()
        .status(StatusCode::OK)
        .header("content-type", "application/json; charset=utf-8")
-        .body(br#"{"name":"wrong","interfaces":[]}"#.to_vec())
+        .body(br#"{"object":{"name":"wrong","interfaces":[]}}"#.to_vec())
        .unwrap();
-    let error = decode_fetch_response(
+    let error = decode_observe_response(
-        &FetchRequest {
+        &ObserveRequest {
            path: "/expected".into(),
            depth: 0,
        },
        &response,
        limits(),
@@ -0,0 +1,740 @@
 use std::collections::BTreeMap;
 use serde_json::{Value as Json, json};
 use wip_http::http::{Response, StatusCode};
 use wip_http::wip_protocol::{
    CallOperationRequest, FetchInterfaceRequest, FetchInterfaceResponse, INTERFACE_FORMAT_V1,
    InterfaceDescriptor, InterfaceReference, InterfaceTarget, Object, ObjectObservation,
    ObserveRequest, OperationDeclaration, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
    ReturnDeclaration, Target, TypeExpr,
 };
 use wip_http::{
    ClientResponseError, CodecError, DecodedResponse, Endpoint, InvalidResponseKind, Limits,
    TransportFailureKind, decode_call_operation_metadata, decode_call_operation_request,
    decode_call_operation_response, decode_fetch_interface_request,
    decode_fetch_interface_response, decode_observe_response, encode_call_operation_request,
    encode_fetch_interface_request, encode_fetch_interface_response, encode_observe_response,
    encode_protocol_error_response,
 };
 fn limits() -> Limits {
    Limits::new(64 * 1024, 64 * 1024, 64).unwrap()
 }
 fn endpoint() -> Endpoint {
    Endpoint::parse("https://example.test/deployment/prefix").unwrap()
 }
 fn reference(scope: &str, name: &str) -> InterfaceReference {
    InterfaceReference {
        scope: scope.into(),
        name: name.into(),
    }
 }
 fn descriptor() -> InterfaceDescriptor {
    InterfaceDescriptor {
        format: INTERFACE_FORMAT_V1.into(),
        documentation: None,
        types: vec![],
        operations: vec![OperationDeclaration {
            name: "run#::操作".into(),
            documentation: None,
            parameters: vec![],
            returns: ReturnDeclaration {
                documentation: None,
                r#type: TypeExpr::Unit,
            },
        }],
    }
 }
 fn call(reference: InterfaceReference, scope_ref: Option<String>) -> CallOperationRequest {
    CallOperationRequest {
        target: Target {
            path: "/世界::#/item".into(),
            validator: Some(vec![0, 255]),
        },
        interface: InterfaceTarget {
            reference,
            scope_ref,
            validator: Some(vec![1, 255]),
        },
        operation: "run#::操作".into(),
        arguments: BTreeMap::new(),
    }
 }
 fn observation(references: Vec<InterfaceReference>) -> ObjectObservation {
    ObjectObservation {
        object: Object {
            name: "item".into(),
            description: None,
            interfaces: references,
            r#ref: None,
            validator: None,
        },
        children: None,
    }
 }
 fn observe_request() -> ObserveRequest {
    ObserveRequest {
        path: "/世界::#/item".into(),
        depth: 0,
    }
 }
 fn response(status: StatusCode, value: Json) -> Response<Vec<u8>> {
    raw_response(status, &serde_json::to_vec(&value).unwrap())
 }
 fn raw_response(status: StatusCode, body: &[u8]) -> Response<Vec<u8>> {
    Response::builder()
        .status(status)
        .header("content-type", "application/json")
        .body(body.to_vec())
        .unwrap()
 }
 fn fetch_json(interface: Json) -> Json {
    json!({
        "interface": interface,
        "descriptor": {"format": INTERFACE_FORMAT_V1, "types": [], "operations": []}
    })
 }
 fn call_json(reference: Json) -> Json {
    json!({
        "target": {"path": "/世界::#/item"},
        "interface": {"reference": reference},
        "operation": "run#::操作",
        "arguments": {}
    })
 }
 fn invalid_success<T: std::fmt::Debug>(result: Result<T, ClientResponseError>) {
    assert!(matches!(
        result.unwrap_err(),
        ClientResponseError::InvalidResponse {
            kind: InvalidResponseKind::InvalidSuccessBody,
            ..
        }
    ));
 }
 #[test]
 fn exact_structured_reference_is_encoded_and_round_tripped_in_every_position() {
    let interface_ref = reference("/世界::#", "é::接口#read/with\"quote\\slash");
    let expected = json!({"scope": interface_ref.scope, "name": interface_ref.name});
    let fetch_request = FetchInterfaceRequest {
        interface: interface_ref.clone(),
    };
    let encoded = encode_fetch_interface_request(&endpoint(), &fetch_request, limits()).unwrap();
    assert_eq!(
        encoded.uri().path(),
        "/deployment/prefix/v1/fetch_interface"
    );
    assert_eq!(
        serde_json::from_slice::<Json>(encoded.body()).unwrap(),
        json!({"interface": expected})
    );
    assert_eq!(
        decode_fetch_interface_request(encoded.body(), limits()).unwrap(),
        fetch_request
    );
    let fetch_response = FetchInterfaceResponse {
        interface: interface_ref.clone(),
        scope_ref: Some("opaque:世界::# not base64!".into()),
        descriptor: descriptor(),
        validator: Some(vec![1, 255]),
    };
    let encoded =
        encode_fetch_interface_response(&fetch_request, &fetch_response, limits()).unwrap();
    let body: Json = serde_json::from_slice(encoded.body()).unwrap();
    assert_eq!(body["interface"], expected);
    assert_eq!(body["scope_ref"], "opaque:世界::# not base64!");
    assert_eq!(body["validator"], "Af8=");
    assert_eq!(
        decode_fetch_interface_response(&fetch_request, &encoded, limits()).unwrap(),
        DecodedResponse::Success(fetch_response)
    );
    let observation = observation(vec![interface_ref.clone(), reference("/", "root")]);
    let encoded = encode_observe_response(&observe_request(), &observation, limits()).unwrap();
    let body: Json = serde_json::from_slice(encoded.body()).unwrap();
    assert_eq!(
        body["object"]["interfaces"],
        json!([expected, {"scope": "/", "name": "root"}])
    );
    assert_eq!(
        decode_observe_response(&observe_request(), &encoded, limits()).unwrap(),
        DecodedResponse::Success(observation)
    );
    let request = call(interface_ref, Some("opaque:世界::# not base64!".into()));
    let encoded =
        encode_call_operation_request(&endpoint(), &request, &descriptor(), limits()).unwrap();
    let body: Json = serde_json::from_slice(encoded.body()).unwrap();
    assert_eq!(body["interface"]["reference"], expected);
    assert_eq!(body["interface"]["scope_ref"], "opaque:世界::# not base64!");
    assert_eq!(body["interface"]["validator"], "Af8=");
    assert_eq!(body["target"]["validator"], "AP8=");
    assert_eq!(body["operation"], "run#::操作");
    assert_eq!(
        decode_call_operation_request(encoded.body(), &descriptor(), limits()).unwrap(),
        request
    );
    assert_eq!(
        decode_call_operation_metadata(encoded.body(), limits())
            .unwrap()
            .interface,
        request.interface
    );
 }
 #[test]
 fn malformed_reference_corpus_is_rejected_in_all_positions() {
    let request = FetchInterfaceRequest {
        interface: reference("/", "interface-v1"),
    };
    for bad in [
        json!("interface-v1"),
        json!("/::interface-v1"),
        json!("interface-v1#run"),
        Json::Null,
        json!(false),
        json!(1),
        json!([]),
        json!({}),
        json!({"name": "interface-v1"}),
        json!({"scope": "/"}),
        json!({"scope": null, "name": "interface-v1"}),
        json!({"scope": 1, "name": "interface-v1"}),
        json!({"scope": "/", "name": null}),
        json!({"scope": "/", "name": []}),
        json!({"scope": "/", "name": ""}),
        json!({"scope": "/", "name": "interface-v1", "extra": true}),
        json!({"scope": "/", "name": "interface-v1", "scope_ref": "identity"}),
        json!({"Scope": "/", "name": "interface-v1"}),
        json!({"scope": "", "name": "interface-v1"}),
        json!({"scope": "relative", "name": "interface-v1"}),
        json!({"scope": ".", "name": "interface-v1"}),
        json!({"scope": "..", "name": "interface-v1"}),
        json!({"scope": "/a/", "name": "interface-v1"}),
        json!({"scope": "//a", "name": "interface-v1"}),
        json!({"scope": "/a//b", "name": "interface-v1"}),
        json!({"scope": "/a/./b", "name": "interface-v1"}),
        json!({"scope": "/a/../b", "name": "interface-v1"}),
    ] {
        let body = serde_json::to_vec(&json!({"interface": bad})).unwrap();
        assert!(
            decode_fetch_interface_request(&body, limits()).is_err(),
            "{bad}"
        );
        let body = serde_json::to_vec(&call_json(bad.clone())).unwrap();
        assert!(
            decode_call_operation_metadata(&body, limits()).is_err(),
            "{bad}"
        );
        assert!(
            decode_call_operation_request(&body, &descriptor(), limits()).is_err(),
            "{bad}"
        );
        invalid_success(decode_fetch_interface_response(
            &request,
            &response(StatusCode::OK, fetch_json(bad.clone())),
            limits(),
        ));
        let mut future = fetch_json(bad.clone());
        future["descriptor"] = json!({"format": "future-format", "future": true});
        invalid_success(decode_fetch_interface_response(
            &request,
            &response(StatusCode::OK, future),
            limits(),
        ));
        invalid_success(decode_observe_response(
            &observe_request(),
            &response(
                StatusCode::OK,
                json!({"object": {"name": "item", "interfaces": [bad]}}),
            ),
            limits(),
        ));
    }
 }
 #[test]
 fn duplicate_reference_members_are_rejected_even_when_escaped_or_equal() {
    let request = FetchInterfaceRequest {
        interface: reference("/", "x"),
    };
    for bad in [
        r#"{"scope":"/","scope":"/","name":"x"}"#,
        r#"{"scope":"/","name":"x","name":"x"}"#,
        r#"{"scope":"/","name":"x","na\u006de":"x"}"#,
    ] {
        let fetch = format!(r#"{{"interface":{bad}}}"#);
        assert!(matches!(
            decode_fetch_interface_request(fetch.as_bytes(), limits()).unwrap_err(),
            CodecError::InvalidJson(_)
        ));
        let call = format!(
            r#"{{"target":{{"path":"/"}},"interface":{{"reference":{bad}}},"operation":"run","arguments":{{}}}}"#
        );
        assert!(matches!(
            decode_call_operation_metadata(call.as_bytes(), limits()).unwrap_err(),
            CodecError::InvalidJson(_)
        ));
        assert!(matches!(
            decode_call_operation_request(call.as_bytes(), &descriptor(), limits()).unwrap_err(),
            CodecError::InvalidJson(_)
        ));
        let fetch_response = format!(
            r#"{{"interface":{bad},"descriptor":{{"format":"wip-interface/1","types":[],"operations":[]}}}}"#
        );
        invalid_success(decode_fetch_interface_response(
            &request,
            &raw_response(StatusCode::OK, fetch_response.as_bytes()),
            limits(),
        ));
        let observe = format!(r#"{{"object":{{"name":"item","interfaces":[{bad}]}}}}"#);
        invalid_success(decode_observe_response(
            &observe_request(),
            &raw_response(StatusCode::OK, observe.as_bytes()),
            limits(),
        ));
    }
 }
 #[test]
 fn member_order_and_json_escapes_do_not_change_reference_identity() {
    let expected = reference("/世界::#", "é::接口#");
    let raw_reference = r#"{"name":"\u00e9::\u63a5\u53e3#","scope":"\/\u4e16\u754c::#"}"#;
    let fetch = format!(r#"{{"interface":{raw_reference}}}"#);
    let request = decode_fetch_interface_request(fetch.as_bytes(), limits()).unwrap();
    assert_eq!(request.interface, expected);
    let fetch_response = format!(
        r#"{{"descriptor":{{"operations":[],"types":[],"format":"wip-interface/1"}},"interface":{raw_reference}}}"#
    );
    assert!(
        matches!(decode_fetch_interface_response(&request, &raw_response(StatusCode::OK, fetch_response.as_bytes()), limits()).unwrap(), DecodedResponse::Success(value) if value.interface == expected)
    );
    let call = format!(
        r#"{{"arguments":{{}},"operation":"run#::操作","interface":{{"reference":{raw_reference}}},"target":{{"path":"/世界::#/item"}}}}"#
    );
    assert_eq!(
        decode_call_operation_metadata(call.as_bytes(), limits())
            .unwrap()
            .interface
            .reference,
        expected
    );
    assert_eq!(
        decode_call_operation_request(call.as_bytes(), &descriptor(), limits())
            .unwrap()
            .interface
            .reference,
        expected
    );
    let observe = format!(r#"{{"object":{{"interfaces":[{raw_reference}],"name":"item"}}}}"#);
    assert!(
        matches!(decode_observe_response(&observe_request(), &raw_response(StatusCode::OK, observe.as_bytes()), limits()).unwrap(), DecodedResponse::Success(value) if value.object.interfaces == vec![expected])
    );
 }
 #[test]
 fn reference_comparison_is_exact_without_normalization_case_or_url_decoding() {
    for different in [
        reference("/", "e\u{301}"),
        reference("/", "É"),
        reference("/", "%C3%A9"),
        reference("/other", "é"),
    ] {
        let request = FetchInterfaceRequest {
            interface: reference("/", "é"),
        };
        invalid_success(decode_fetch_interface_response(
            &request,
            &response(
                StatusCode::OK,
                fetch_json(json!({"scope": different.scope, "name": different.name})),
            ),
            limits(),
        ));
    }
    let request = FetchInterfaceRequest {
        interface: reference("/%2E", "é"),
    };
    let encoded = encode_fetch_interface_request(&endpoint(), &request, limits()).unwrap();
    assert_eq!(
        decode_fetch_interface_request(encoded.body(), limits()).unwrap(),
        request
    );
    let request = FetchInterfaceRequest {
        interface: reference("/", "."),
    };
    assert!(encode_fetch_interface_request(&endpoint(), &request, limits()).is_ok());
 }
 #[test]
 fn request_encoding_rejects_invalid_reference_shape_without_needing_a_fetch_target() {
    for bad in [
        reference("relative", "x"),
        reference("", "x"),
        reference("/a/../b", "x"),
        reference("/", ""),
    ] {
        assert!(
            encode_fetch_interface_request(
                &endpoint(),
                &FetchInterfaceRequest {
                    interface: bad.clone()
                },
                limits()
            )
            .is_err()
        );
        assert!(
            encode_call_operation_request(&endpoint(), &call(bad, None), &descriptor(), limits())
                .is_err()
        );
    }
    let request = FetchInterfaceRequest {
        interface: reference("/unrelated/scope", "x"),
    };
    let encoded = encode_fetch_interface_request(&endpoint(), &request, limits()).unwrap();
    assert_eq!(
        decode_fetch_interface_request(encoded.body(), limits()).unwrap(),
        request
    );
 }
 #[test]
 fn call_metadata_leaves_valid_out_of_scope_references_and_identity_to_host_resolution() {
    let request = call(
        reference("/elsewhere", "x"),
        Some("not-current-identity".into()),
    );
    let encoded =
        encode_call_operation_request(&endpoint(), &request, &descriptor(), limits()).unwrap();
    let metadata = decode_call_operation_metadata(encoded.body(), limits()).unwrap();
    assert_eq!(metadata.interface, request.interface);
    assert_eq!(
        metadata
            .decode_request(encoded.body(), &descriptor(), limits())
            .unwrap(),
        request
    );
    // Neither an unknown operation nor descriptor-bound argument values are
    // resolved by the metadata boundary before Host precondition checks.
    let mut body: Json = serde_json::from_slice(encoded.body()).unwrap();
    body["operation"] = json!("missing");
    body["arguments"] = json!({"not_declared": [null, {"anything": true}]});
    let metadata =
        decode_call_operation_metadata(&serde_json::to_vec(&body).unwrap(), limits()).unwrap();
    assert_eq!(metadata.operation, "missing");
    assert_eq!(metadata.interface, request.interface);
 }
 #[test]
 fn observation_scope_validation_uses_each_nodes_path_and_structural_duplicates() {
    let request = ObserveRequest {
        path: "/a".into(),
        depth: 1,
    };
    let valid = json!({
        "object": {"name": "a", "interfaces": [{"scope": "/", "name": "x"}, {"scope": "/a", "name": "x"}]},
        "children": [{"object": {"name": "b", "interfaces": [{"scope": "/a/b", "name": "x"}]}}]
    });
    assert!(
        decode_observe_response(&request, &response(StatusCode::OK, valid.clone()), limits())
            .is_ok()
    );
    for scope in ["/ab", "/elsewhere", "/a/b/c"] {
        let mut bad = valid.clone();
        bad["children"][0]["object"]["interfaces"][0]["scope"] = json!(scope);
        invalid_success(decode_observe_response(
            &request,
            &response(StatusCode::OK, bad),
            limits(),
        ));
    }
    let mut duplicate = valid;
    duplicate["object"]["interfaces"] =
        json!([{"scope": "/a", "name": "x"}, {"name": "x", "scope": "/a"}]);
    invalid_success(decode_observe_response(
        &request,
        &response(StatusCode::OK, duplicate),
        limits(),
    ));
    let root_request = ObserveRequest {
        path: "/".into(),
        depth: 0,
    };
    for (scope, valid) in [("/", true), ("/a", false)] {
        let result = decode_observe_response(
            &root_request,
            &response(
                StatusCode::OK,
                json!({"object": {"name": "", "interfaces": [{"scope": scope, "name": "x"}]}}),
            ),
            limits(),
        );
        if valid {
            assert!(result.is_ok());
        } else {
            invalid_success(result);
        }
    }
 }
 #[test]
 fn scope_ref_omission_and_opaque_strings_round_trip_in_both_positions() {
    for scope_ref in [
        None,
        Some(String::new()),
        Some("opaque::# 世界 ! not base64 /+=".into()),
        Some("\"\\\n\u{0}".into()),
    ] {
        let request = FetchInterfaceRequest {
            interface: reference("/", "x"),
        };
        let expected = FetchInterfaceResponse {
            interface: request.interface.clone(),
            scope_ref: scope_ref.clone(),
            descriptor: descriptor(),
            validator: None,
        };
        let encoded = encode_fetch_interface_response(&request, &expected, limits()).unwrap();
        let body: Json = serde_json::from_slice(encoded.body()).unwrap();
        assert_eq!(
            body.get("scope_ref"),
            scope_ref
                .as_ref()
                .map(|value| Json::String(value.clone()))
                .as_ref()
        );
        assert!(body.get("validator").is_none());
        assert_eq!(
            decode_fetch_interface_response(&request, &encoded, limits()).unwrap(),
            DecodedResponse::Success(expected)
        );
        let call = call(request.interface, scope_ref);
        let encoded =
            encode_call_operation_request(&endpoint(), &call, &descriptor(), limits()).unwrap();
        let body: Json = serde_json::from_slice(encoded.body()).unwrap();
        assert_eq!(
            body["interface"].get("scope_ref"),
            call.interface
                .scope_ref
                .as_ref()
                .map(|value| Json::String(value.clone()))
                .as_ref()
        );
        assert_eq!(
            decode_call_operation_metadata(encoded.body(), limits())
                .unwrap()
                .interface,
            call.interface
        );
        assert_eq!(
            decode_call_operation_request(encoded.body(), &descriptor(), limits()).unwrap(),
            call
        );
    }
 }
 #[test]
 fn scope_ref_null_and_every_nonstring_type_are_rejected_before_descriptor_resolution() {
    let request = FetchInterfaceRequest {
        interface: reference("/", "x"),
    };
    for bad in [Json::Null, json!(true), json!(0), json!([]), json!({})] {
        let mut fetch = fetch_json(json!({"scope": "/", "name": "x"}));
        fetch["scope_ref"] = bad.clone();
        invalid_success(decode_fetch_interface_response(
            &request,
            &response(StatusCode::OK, fetch.clone()),
            limits(),
        ));
        // Unknown format does not mask malformed common response fields.
        fetch["descriptor"] = json!({"format": "future-format", "future": true});
        invalid_success(decode_fetch_interface_response(
            &request,
            &response(StatusCode::OK, fetch),
            limits(),
        ));
        let mut call = call_json(json!({"scope": "/", "name": "x"}));
        call["interface"]["scope_ref"] = bad.clone();
        let body = serde_json::to_vec(&call).unwrap();
        let error = decode_call_operation_metadata(&body, limits()).unwrap_err();
        if bad.is_null() {
            assert!(matches!(error, CodecError::NullOptionalField { .. }));
        } else {
            assert!(matches!(error, CodecError::InvalidField { .. }));
        }
        assert!(decode_call_operation_request(&body, &descriptor(), limits()).is_err());
    }
 }
 #[test]
 fn scope_ref_is_only_allowed_on_fetch_responses_and_call_interface_targets() {
    let request = FetchInterfaceRequest {
        interface: reference("/", "x"),
    };
    let reference = json!({"scope": "/", "name": "x"});
    let fetch_request = json!({"interface": reference, "scope_ref": "identity"});
    assert!(
        decode_fetch_interface_request(&serde_json::to_vec(&fetch_request).unwrap(), limits())
            .is_err()
    );
    let mut call = call_json(reference.clone());
    call["scope_ref"] = json!("identity");
    assert!(decode_call_operation_metadata(&serde_json::to_vec(&call).unwrap(), limits()).is_err());
    let mut call = call_json(reference);
    call["target"]["scope_ref"] = json!("identity");
    assert!(decode_call_operation_metadata(&serde_json::to_vec(&call).unwrap(), limits()).is_err());
    let duplicate = br#"{"interface":{"scope":"/","name":"x"},"scope_ref":"identity","scope_ref":"identity","descriptor":{"format":"wip-interface/1","types":[],"operations":[]}}"#;
    invalid_success(decode_fetch_interface_response(
        &request,
        &raw_response(StatusCode::OK, duplicate),
        limits(),
    ));
    let duplicate = br#"{"target":{"path":"/"},"interface":{"reference":{"scope":"/","name":"x"},"scope_ref":"identity","scope_ref":"identity"},"operation":"run#::\u64cd\u4f5c","arguments":{}}"#;
    assert!(matches!(
        decode_call_operation_metadata(duplicate, limits()).unwrap_err(),
        CodecError::InvalidJson(_)
    ));
    assert!(matches!(
        decode_call_operation_request(duplicate, &descriptor(), limits()).unwrap_err(),
        CodecError::InvalidJson(_)
    ));
 }
 #[test]
 fn metadata_correspondence_includes_reference_and_scope_ref_but_not_wire_order() {
    let request = call(reference("/", "x"), Some("identity".into()));
    let encoded =
        encode_call_operation_request(&endpoint(), &request, &descriptor(), limits()).unwrap();
    let metadata = decode_call_operation_metadata(encoded.body(), limits()).unwrap();
    for (field, changed) in [
        ("scope_ref", json!("other")),
        ("reference", json!({"scope": "/", "name": "other"})),
    ] {
        let mut body: Json = serde_json::from_slice(encoded.body()).unwrap();
        body["interface"][field] = changed;
        assert!(
            matches!(metadata.decode_request(&serde_json::to_vec(&body).unwrap(), &descriptor(), limits()).unwrap_err(), CodecError::InvalidField { field, .. } if field == "request")
        );
    }
    let mut body: Json = serde_json::from_slice(encoded.body()).unwrap();
    body["interface"]
        .as_object_mut()
        .unwrap()
        .remove("scope_ref");
    assert!(
        metadata
            .decode_request(&serde_json::to_vec(&body).unwrap(), &descriptor(), limits())
            .is_err()
    );
 }
 #[test]
 fn fetch_classification_preserves_transport_status_and_error_envelope_semantics() {
    let request = FetchInterfaceRequest {
        interface: reference("/", "x"),
    };
    let valid = fetch_json(json!({"scope": "/", "name": "x"}));
    for (status, kind) in [
        (
            StatusCode::CREATED,
            InvalidResponseKind::NonCanonicalSuccessStatus,
        ),
        (
            StatusCode::BAD_GATEWAY,
            InvalidResponseKind::SuccessBodyOnErrorStatus,
        ),
    ] {
        assert!(
            matches!(decode_fetch_interface_response(&request, &response(status, valid.clone()), limits()).unwrap_err(), ClientResponseError::InvalidResponse { kind: actual, .. } if actual == kind)
        );
    }
    for status in [
        StatusCode::UNAUTHORIZED,
        StatusCode::FORBIDDEN,
        StatusCode::BAD_GATEWAY,
    ] {
        let malformed = response(status, fetch_json(json!("legacy")));
        assert!(
            matches!(decode_fetch_interface_response(&request, &malformed, limits()).unwrap_err(), ClientResponseError::TransportBinding(failure) if failure.status == status)
        );
    }
    let error = ProtocolError {
        code: ProtocolErrorCode::InterfaceNotFound,
        message: "unpublished".into(),
    };
    let mut encoded =
        encode_protocol_error_response(ProtocolInteraction::FetchInterface, &error, limits())
            .unwrap();
    assert_eq!(
        decode_fetch_interface_response(&request, &encoded, limits()).unwrap(),
        DecodedResponse::ProtocolFailure {
            error: error.clone(),
            status_mismatch: None
        }
    );
    *encoded.status_mut() = StatusCode::BAD_GATEWAY;
    assert!(
        matches!(decode_fetch_interface_response(&request, &encoded, limits()).unwrap(), DecodedResponse::ProtocolFailure { error: actual, status_mismatch: Some(_) } if actual == error)
    );
    *encoded.status_mut() = StatusCode::OK;
    assert!(matches!(
        decode_fetch_interface_response(&request, &encoded, limits()).unwrap_err(),
        ClientResponseError::InvalidResponse {
            kind: InvalidResponseKind::ErrorEnvelopeOnSuccessStatus,
            ..
        }
    ));
    let disallowed = response(
        StatusCode::CONFLICT,
        json!({"error": {"code": "interface_mismatch", "message": "wrong interaction"}}),
    );
    assert!(matches!(
        decode_fetch_interface_response(&request, &disallowed, limits()).unwrap_err(),
        ClientResponseError::InvalidResponse {
            kind: InvalidResponseKind::DisallowedProtocolCode,
            ..
        }
    ));
    let mut coded = response(StatusCode::OK, valid);
    coded
        .headers_mut()
        .insert("content-encoding", "gzip".parse().unwrap());
    assert!(
        matches!(decode_fetch_interface_response(&request, &coded, limits()).unwrap_err(), ClientResponseError::TransportBinding(failure) if failure.kind == TransportFailureKind::UnsupportedContentCoding)
    );
 }
 #[test]
 fn call_interface_mismatch_envelope_remains_protocol_failure_with_structured_metadata() {
    let request = call(reference("/unrelated", "x"), Some("stale identity".into()));
    let error = ProtocolError {
        code: ProtocolErrorCode::InterfaceMismatch,
        message: "interface precondition".into(),
    };
    let encoded =
        encode_protocol_error_response(ProtocolInteraction::CallOperation, &error, limits())
            .unwrap();
    assert_eq!(
        decode_call_operation_response(&request, &descriptor(), &encoded, limits()).unwrap(),
        DecodedResponse::ProtocolFailure {
            error,
            status_mismatch: None
        }
    );
 }
@@ -1,20 +1,22 @@
-use wip_https::http::{Response, StatusCode};
+use wip_http::http::{Response, StatusCode};
-use wip_https::wip_protocol::{
+use wip_http::wip_protocol::{
-    FetchRequest, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
+    ObserveRequest, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
 };
-use wip_https::{
+use wip_http::{
-    ClientResponseError, DecodedResponse, InvalidResponseKind, Limits, ResourceLimitKind,
+    ClientResponseError, DecodedResponse, InvalidResponseKind, Limits, TransportFailureKind,
-    TransportFailureKind, decode_fetch_response, encode_protocol_error_response,
+    decode_observe_response, encode_protocol_error_response, error_code_name, is_json_content_type,
-    encode_resource_limit_error_response, error_code_name, is_json_content_type, status_for_error,
+    status_for_error,
    status_for_resource_limit,
 };
 fn limits() -> Limits {
-    Limits::new(64 * 1024, 64 * 1024, 32, 16).unwrap()
+    Limits::new(64 * 1024, 64 * 1024, 32).unwrap()
 }
-fn request() -> FetchRequest {
+fn request() -> ObserveRequest {
-    FetchRequest { path: "/".into() }
+    ObserveRequest {
        path: "/".into(),
        depth: 0,
    }
 }
 fn response(status: StatusCode, body: impl Into<Vec<u8>>) -> Response<Vec<u8>> {
@@ -117,41 +119,45 @@ fn every_protocol_code_has_stable_name_and_status() {
 }
 #[test]
-fn resource_limit_statuses_encode_and_decode_by_concrete_limit_class() {
+fn logical_resource_limit_uses_only_422_and_bare_413_is_transport_failure() {
    let error = ProtocolError {
        code: ProtocolErrorCode::ResourceLimitExceeded,
-        message: "bounded".into(),
+        message: "logical observation limit exceeded".into(),
    };
-    let cases = [
+    let encoded =
-        (
+        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).unwrap();
-            ResourceLimitKind::RepresentationBytes,
+    assert_eq!(encoded.status(), StatusCode::UNPROCESSABLE_ENTITY);
-            StatusCode::PAYLOAD_TOO_LARGE,
+    assert_eq!(
-        ),
+        decode_observe_response(&request(), &encoded, limits()).unwrap(),
-        (ResourceLimitKind::Logical, StatusCode::UNPROCESSABLE_ENTITY),
+        DecodedResponse::ProtocolFailure {
-    ];
+            error: error.clone(),
-    for (kind, status) in cases {
+            status_mismatch: None,
-        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 =
+    let mut noncanonical = encoded;
-        encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
+    *noncanonical.status_mut() = StatusCode::PAYLOAD_TOO_LARGE;
-    assert_eq!(default.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    assert_eq!(
-    assert_ne!(default.status(), StatusCode::TOO_MANY_REQUESTS);
+        decode_observe_response(&request(), &noncanonical, limits()).unwrap(),
        DecodedResponse::ProtocolFailure {
            error,
            status_mismatch: Some(wip_http::StatusMismatch {
                actual: StatusCode::PAYLOAD_TOO_LARGE,
                expected: StatusCode::UNPROCESSABLE_ENTITY,
            }),
        }
    );
    let bare_413 = Response::builder()
        .status(StatusCode::PAYLOAD_TOO_LARGE)
        .body(Vec::<u8>::new())
        .unwrap();
    assert!(matches!(
        decode_observe_response(&request(), &bare_413, limits()).unwrap_err(),
        ClientResponseError::TransportBinding(failure)
            if failure.status == StatusCode::PAYLOAD_TOO_LARGE
                && failure.kind == TransportFailureKind::HttpStatus
    ));
 }
 #[test]
@@ -161,19 +167,62 @@ fn rate_limit_status_without_protocol_envelope_stays_transport_failure() {
        .body(b"rate limited".to_vec())
        .unwrap();
    assert!(matches!(
-        decode_fetch_response(&request(), &response, limits()).unwrap_err(),
+        decode_observe_response(&request(), &response, limits()).unwrap_err(),
        ClientResponseError::TransportBinding(failure)
            if failure.status == StatusCode::TOO_MANY_REQUESTS
                && failure.kind == TransportFailureKind::HttpStatus
    ));
 }
 #[test]
 fn unsupported_response_content_coding_is_transport_failure() {
    let mut encoded = encode_protocol_error_response(
        ProtocolInteraction::Observe,
        &ProtocolError {
            code: ProtocolErrorCode::NotFound,
            message: "missing".into(),
        },
        limits(),
    )
    .unwrap();
    encoded
        .headers_mut()
        .insert("content-encoding", "gzip".parse().unwrap());
    assert!(matches!(
        decode_observe_response(&request(), &encoded, limits()).unwrap_err(),
        ClientResponseError::TransportBinding(failure)
            if failure.status == StatusCode::NOT_FOUND
                && failure.kind == TransportFailureKind::UnsupportedContentCoding
    ));
    let success = response(StatusCode::OK, br#"{"object":{"name":"","interfaces":[]}}"#);
    let mut identity = success.clone();
    identity
        .headers_mut()
        .insert("content-encoding", "identity".parse().unwrap());
    assert!(matches!(
        decode_observe_response(&request(), &identity, limits()).unwrap(),
        DecodedResponse::Success(_)
    ));
    let mut unsupported = success;
    unsupported
        .headers_mut()
        .insert("content-encoding", "br".parse().unwrap());
    assert!(matches!(
        decode_observe_response(&request(), &unsupported, limits()).unwrap_err(),
        ClientResponseError::TransportBinding(failure)
            if failure.status == StatusCode::OK
                && failure.kind == TransportFailureKind::UnsupportedContentCoding
    ));
 }
 #[test]
 fn valid_success_body_requires_exactly_http_200() {
-    let success_body = br#"{"name":"","interfaces":[]}"#;
+    let success_body = br#"{"object":{"name":"","interfaces":[]}}"#;
    for status in [StatusCode::CREATED, StatusCode::ACCEPTED] {
        assert!(matches!(
-            decode_fetch_response(&request(), &response(status, success_body), limits())
+            decode_observe_response(&request(), &response(status, success_body), limits())
                .unwrap_err(),
            ClientResponseError::InvalidResponse {
                kind: InvalidResponseKind::NonCanonicalSuccessStatus,
@@ -187,9 +236,11 @@ fn valid_success_body_requires_exactly_http_200() {
 fn server_encoder_rejects_codes_disallowed_for_the_interaction() {
    let error = ProtocolError {
        code: ProtocolErrorCode::InterfaceNotFound,
-        message: "not valid for fetch".into(),
+        message: "not valid for observe".into(),
    };
-    assert!(encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).is_err());
+    assert!(
        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).is_err()
    );
 }
 #[test]
@@ -199,14 +250,14 @@ fn valid_envelope_code_is_authoritative_when_status_mismatches() {
        message: "missing".into(),
    };
    let mut encoded =
-        encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
+        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).unwrap();
    *encoded.status_mut() = StatusCode::IM_A_TEAPOT;
    assert_eq!(
-        decode_fetch_response(&request(), &encoded, limits()).unwrap(),
+        decode_observe_response(&request(), &encoded, limits()).unwrap(),
        DecodedResponse::ProtocolFailure {
            error,
-            status_mismatch: Some(wip_https::StatusMismatch {
+            status_mismatch: Some(wip_http::StatusMismatch {
                actual: StatusCode::IM_A_TEAPOT,
                expected: StatusCode::NOT_FOUND,
            }),
@@ -218,7 +269,7 @@ fn valid_envelope_code_is_authoritative_when_status_mismatches() {
 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())
+        decode_observe_response(&request(), &response(StatusCode::OK, error_body), limits())
            .unwrap_err();
    assert!(matches!(
        on_success,
@@ -228,8 +279,8 @@ fn envelope_and_status_contradictions_are_invalid_responses() {
        }
    ));
-    let success_body = br#"{"name":"","interfaces":[]}"#;
+    let success_body = br#"{"object":{"name":"","interfaces":[]}}"#;
-    let on_error = decode_fetch_response(
+    let on_error = decode_observe_response(
        &request(),
        &response(StatusCode::BAD_GATEWAY, success_body),
        limits(),
@@ -247,8 +298,9 @@ fn envelope_and_status_contradictions_are_invalid_responses() {
 #[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())
+    let error =
-        .unwrap_err();
+        decode_observe_response(&request(), &response(StatusCode::NOT_FOUND, body), limits())
            .unwrap_err();
    assert!(matches!(
        error,
        ClientResponseError::InvalidResponse {
@@ -282,7 +334,7 @@ fn proxy_authentication_and_endpoint_failures_stay_transport_failures() {
            .status(status)
            .body(body.to_vec())
            .unwrap();
-        let error = decode_fetch_response(&request(), &response, limits()).unwrap_err();
+        let error = decode_observe_response(&request(), &response, limits()).unwrap_err();
        assert!(matches!(
            error,
            ClientResponseError::TransportBinding(failure)
@@ -298,7 +350,7 @@ fn malformed_non_success_envelope_is_transport_binding_failure() {
        br#"{"error":{"code":"not_found","message":null}}"#,
    );
    assert!(matches!(
-        decode_fetch_response(&request(), &malformed, limits()).unwrap_err(),
+        decode_observe_response(&request(), &malformed, limits()).unwrap_err(),
        ClientResponseError::TransportBinding(_)
    ));
 }
@@ -0,0 +1,182 @@
 use wip_http::http::{Method, Request, StatusCode};
 use wip_http::{Endpoint, RequestMetadataError, Route, validate_http_request};
 #[test]
 fn endpoint_preserves_http_and_https_when_resolving_canonical_routes() {
    for scheme in ["http", "https"] {
        let endpoint = Endpoint::parse(&format!("{scheme}://example.test/root/prefix")).unwrap();
        assert_eq!(
            endpoint.to_string(),
            format!("{scheme}://example.test/root/prefix/")
        );
        let expected = [
            (Route::Observe, "v1/observe"),
            (Route::FetchInterface, "v1/fetch_interface"),
            (Route::CallOperation, "v1/call_operation"),
        ];
        for (route, suffix) in expected {
            let url = format!("{scheme}://example.test/root/prefix/{suffix}");
            assert_eq!(endpoint.route(route).as_str(), url);
            assert_eq!(
                endpoint.recognize(&wip_http::url::Url::parse(&url).unwrap()),
                Some(route)
            );
        }
        assert_eq!(
            endpoint.recognize(
                &wip_http::url::Url::parse(&format!(
                    "{scheme}://example.test/root/prefix/v1/observe?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::Observe);
    assert_eq!(route.path(), "/wip/%E4%B8%96%E7%95%8C/v1/observe");
    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/observe")
        .header("content-type", "application/json; charset=utf-8")
        .body(Vec::<u8>::new())
        .unwrap();
    assert!(validate_http_request(&endpoint, Route::Observe, &valid).is_ok());
    let wrong_method = Request::builder()
        .method(Method::GET)
        .uri("/wip/v1/observe")
        .header("content-type", "application/json")
        .body(Vec::<u8>::new())
        .unwrap();
    let error = validate_http_request(&endpoint, Route::Observe, &wrong_method).unwrap_err();
    assert!(matches!(&error, RequestMetadataError::MethodNotAllowed));
    assert_eq!(error.status(), StatusCode::METHOD_NOT_ALLOWED);
    assert_eq!(error.allow(), Some("POST"));
    let wrong_route = Request::builder()
        .method(Method::POST)
        .uri("/wip/v1/fetch_interface")
        .header("content-type", "application/json")
        .body(Vec::<u8>::new())
        .unwrap();
    let error = validate_http_request(&endpoint, Route::Observe, &wrong_route).unwrap_err();
    assert!(matches!(&error, RequestMetadataError::NotFound));
    assert_eq!(error.status(), StatusCode::NOT_FOUND);
    assert_eq!(error.allow(), None);
    let query_and_wrong_method = Request::builder()
        .method(Method::GET)
        .uri("/wip/v1/observe?unexpected=true")
        .header("content-type", "application/json")
        .body(Vec::<u8>::new())
        .unwrap();
    assert!(matches!(
        validate_http_request(&endpoint, Route::Observe, &query_and_wrong_method).unwrap_err(),
        RequestMetadataError::NotFound
    ));
    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/observe")
            .header("content-type", "application/json")
            .header("accept", accept)
            .body(Vec::<u8>::new())
            .unwrap();
        let error =
            validate_http_request(&endpoint, Route::Observe, &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/observe")
            .header("content-type", "application/json")
            .header("accept", accept)
            .body(Vec::<u8>::new())
            .unwrap();
        assert!(validate_http_request(&endpoint, Route::Observe, &compatible_accept).is_ok());
    }
    let unsupported_media_type = Request::builder()
        .method(Method::POST)
        .uri("/wip/v1/observe")
        .header("content-type", "text/plain")
        .header("accept", "application/json")
        .body(Vec::<u8>::new())
        .unwrap();
    let error =
        validate_http_request(&endpoint, Route::Observe, &unsupported_media_type).unwrap_err();
    assert!(matches!(&error, RequestMetadataError::UnsupportedMediaType));
    assert_eq!(error.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
    for coding in ["gzip", "identity, gzip"] {
        let unsupported_coding = Request::builder()
            .method(Method::POST)
            .uri("/wip/v1/observe")
            .header("content-type", "application/json")
            .header("content-encoding", coding)
            .body(Vec::<u8>::new())
            .unwrap();
        let error =
            validate_http_request(&endpoint, Route::Observe, &unsupported_coding).unwrap_err();
        assert!(matches!(&error, RequestMetadataError::UnsupportedMediaType));
        assert_eq!(error.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
    }
    let identity_coding = Request::builder()
        .method(Method::POST)
        .uri("/wip/v1/observe")
        .header("content-type", "application/json")
        .header("content-encoding", "identity")
        .body(Vec::<u8>::new())
        .unwrap();
    assert!(validate_http_request(&endpoint, Route::Observe, &identity_coding).is_ok());
 }
 #[test]
 fn invalid_endpoint_components_and_non_routes_are_rejected() {
    assert!(Endpoint::parse("/relative").is_err());
    assert!(Endpoint::parse("file:///wip").is_err());
    assert!(Endpoint::parse("https://example.test/wip?q=1").is_err());
    assert!(Endpoint::parse("https://example.test/wip#fragment").is_err());
    let deployment_endpoint = Endpoint::parse("http://user:secret@example.test/wip").unwrap();
    assert_eq!(deployment_endpoint.as_url().scheme(), "http");
    assert_eq!(deployment_endpoint.as_url().username(), "user");
    let endpoint = Endpoint::parse("http://example.test/wip").unwrap();
    for outside in [
        "http://example.test/wip/v1/unknown",
        "http://example.test/wip/v1/batch",
        "http://example.test/wip/v1/observe/extra",
        "https://example.test/wip/v1/observe",
        "http://other.test/wip/v1/observe",
    ] {
        assert_eq!(
            endpoint.recognize(&wip_http::url::Url::parse(outside).unwrap()),
            None
        );
    }
 }
@@ -1,14 +0,0 @@
 [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" }
@@ -1,596 +0,0 @@
 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(),
        })
 }
@@ -1,67 +0,0 @@
 //! 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;
@@ -1,353 +0,0 @@
 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());
 }
@@ -1,127 +0,0 @@
 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,9 +1,13 @@
 [package]
 name = "wip-interface-macros"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
 rust-version.workspace = true
 description = "Procedural macros for WIP interface declarations and DTO codecs"
-license = "MIT OR Apache-2.0"
+license.workspace = true
 repository.workspace = true
 readme = "README.md"
 documentation = "https://docs.rs/wip-interface-macros"
 [lib]
 proc-macro = true
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Hare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,9 @@
 # wip-interface-macros
 Procedural-macro implementation used by [`wip-interface`](https://crates.io/crates/wip-interface).
 Applications should depend on `wip-interface`, which re-exports `#[interface]` and `#[derive(WipType)]` together with the traits and types required by generated code. Direct use of this implementation crate is not a supported application API.
 See the [API documentation](https://docs.rs/wip-interface-macros) for the exported macro entry points.
 Licensed under either of Apache-2.0 or MIT at your option.
@@ -1,13 +1,17 @@
 [package]
 name = "wip-interface"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
 rust-version.workspace = true
 description = "Public Rust authoring API for WIP interfaces and operation value codecs"
-license = "MIT OR Apache-2.0"
+license.workspace = true
 repository.workspace = true
 readme = "README.md"
 documentation = "https://docs.rs/wip-interface"
 [dependencies]
-wip-interface-macros = { path = "../wip-interface-macros" }
+wip-interface-macros.workspace = true
-wip-protocol = { path = "../wip-protocol" }
+wip-protocol.workspace = true
 [dev-dependencies]
 trybuild = "1"
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Hare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,32 @@
 # wip-interface
 Public Rust authoring API for Worldspace Interface Protocol (WIP) interfaces and application DTO codecs.
 The crate re-exports `#[interface]` and `#[derive(WipType)]`, generates Interface Descriptors and typed dispatch companions, and converts application-owned Rust values to and from the transport-independent value model.
 ```toml
 [dependencies]
 wip-interface = "0.2.0"
 ```
 ```rust
 use wip_interface as wip;
 #[derive(wip::WipType)]
 struct Greeting {
    message: String,
 }
 #[wip::interface]
 pub trait Greeter {
    /// Builds a greeting.
    ///
    /// # Returns
    /// The generated greeting.
    fn greet(&self, name: String) -> wip::OperationResult<Greeting>;
 }
 ```
 See the [API documentation](https://docs.rs/wip-interface) for supported interface syntax, DTO shapes, and failure semantics.
 Licensed under either of Apache-2.0 or MIT at your option.
@@ -1,4 +1,4 @@
-//! Public authoring API for Web Interface Protocol (WIP) interfaces.
+//! Public authoring API for Worldspace Interface Protocol (WIP) interfaces.
 //!
 //! Add `wip-interface` to an application and import it under the short name
 //! used by the attribute examples:
@@ -1,8 +1,12 @@
 [package]
 name = "wip-protocol"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
 rust-version.workspace = true
 description = "Transport-independent logical model and validation for WIP"
-license = "MIT OR Apache-2.0"
+license.workspace = true
 repository.workspace = true
 readme = "README.md"
 documentation = "https://docs.rs/wip-protocol"
 [dependencies]
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Hare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,23 @@
 # wip-protocol
 Transport-independent logical types and validation for the Worldspace Interface Protocol (WIP).
 This crate defines the canonical Object and Interface Descriptor models, the three Core interaction request and response types, schema-neutral operation `Value`s, validators, protocol errors, and structural validation. It does not define an HTTP mapping, application DTOs, persistence, or network I/O.
 ```toml
 [dependencies]
 wip-protocol = "0.2.0"
 ```
 Interface identity is an exact `InterfaceReference { scope, name }` pair.
 `scope` is a canonical absolute Worldspace path and `name` is nonempty Unicode.
 Use `validate()` for shape, `validate_for_path()` for ancestor-or-self placement,
 and Object/interaction validation at response boundaries. Fetching needs no
 target Object path. Fetch responses and interface call targets carry optional
 opaque string `scope_ref` metadata, not a third identity field. Descriptors do
 not embed identity. See the repository's [migration guide](../../MIGRATION.md)
 for the breaking Rust and HTTP wire changes and consumer migration guidance.
 See the [API documentation](https://docs.rs/wip-protocol) for the complete model and validation rules.
 Licensed under either of Apache-2.0 or MIT at your option.
@@ -62,7 +62,7 @@ pub enum PathSegment {
    Return,
    /// Object at a Worldspace path.
    Object(String),
-    /// Child object in a tree response.
+    /// Child object in an observation response.
    Child(String),
 }
@@ -143,8 +143,17 @@ pub enum ValidationErrorKind {
    },
    /// An object's ordered interface set contains a duplicate.
    DuplicateInterface {
-        /// Duplicate opaque interface reference.
+        /// Duplicate structured interface reference.
-        reference: String,
+        reference: crate::InterfaceReference,
    },
    /// The local interface name is empty.
    EmptyInterfaceName,
    /// A valid scope is not an ancestor-or-self of the target path.
    InterfaceScopeMismatch {
        /// Selected scope path.
        scope: String,
        /// Target Object path.
        path: String,
    },
    /// A string is not a canonical absolute Worldspace path.
    InvalidPath {
@@ -163,24 +172,22 @@ pub enum ValidationErrorKind {
        /// Shared opaque object reference.
        reference: String,
    },
-    /// A `fetch_tree` request used a zero limit.
+    /// An observation omitted children before reaching the requested depth.
-    ZeroTreeLimit,
+    ChildrenMissingBeforeDepth {
-    /// A tree response exceeds the requested maximum depth.
+        /// Node depth where children were required.
-    TreeDepthExceeded {
+        depth: u32,
        /// Requested maximum depth.
        maximum: u32,
    },
-    /// A tree response exceeds the requested maximum node count.
+    /// An observation included children at the requested depth boundary.
-    TreeLimitExceeded {
+    ChildrenAtDepthBoundary {
-        /// Requested maximum node count.
+        /// Boundary depth where children must be unobserved.
-        limit: u32,
+        depth: u32,
    },
    /// A response refers to a different interface than its request.
    InterfaceResponseMismatch {
-        /// Requested opaque reference.
+        /// Requested structured reference (boxed to keep validation errors small).
-        expected: String,
+        expected: Box<crate::InterfaceReference>,
-        /// Returned opaque reference.
+        /// Returned structured reference (boxed to keep validation errors small).
-        actual: String,
+        actual: Box<crate::InterfaceReference>,
    },
 }
@@ -226,11 +233,9 @@ impl Error for ValidationError {}
 /// 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.
+    /// Observe one object and its indexable descendants to a requested depth.
-    Fetch,
+    Observe,
-    /// Fetch a bounded tree of objects.
+    /// Fetch one interface descriptor by its structured reference.
    FetchTree,
    /// Fetch one interface descriptor by its opaque reference.
    FetchInterface,
    /// Invoke one operation on a path-targeted object.
    CallOperation,
@@ -315,11 +320,11 @@ impl ProtocolErrorCode {
            OperationNotFound, OperationOutcomeUnknown, PermissionDenied, ResourceLimitExceeded,
            ValidatorMismatch, ValidatorRequired,
        };
-        use ProtocolInteraction::{CallOperation, Fetch, FetchInterface, FetchTree};
+        use ProtocolInteraction::{CallOperation, FetchInterface, Observe};
        match (interaction, self) {
            (_, InvalidRequest | ResourceLimitExceeded | Internal) => true,
-            (Fetch | FetchTree, NotFound) => true,
+            (Observe, NotFound) => true,
            (FetchInterface, InterfaceNotFound) => true,
            (
                CallOperation,
@@ -1,4 +1,4 @@
-//! Canonical transport-independent logical types for the Web Interface Protocol.
+//! Canonical transport-independent logical types for the Worldspace Interface Protocol.
 //!
 //! This crate follows the Core Model and `3-protocol.md` without assigning HTTP
 //! routes, methods, headers, URL encodings, or JSON envelopes. The correspondence
@@ -11,8 +11,7 @@
 //! | Interface Descriptor | [`InterfaceDescriptor`] |
 //! | Named declaration and all schema expressions | [`TypeDeclaration`] / [`TypeExpr`] |
 //! | Schema-neutral primitive/composite value | [`Value`] |
-//! | `fetch` | [`FetchRequest`] / [`FetchResponse`] |
+//! | `observe` | [`ObserveRequest`] / [`ObserveResponse`] |
 //! | `fetch_tree` | [`FetchTreeRequest`] / [`FetchTreeResponse`] |
 //! | `fetch_interface` | [`FetchInterfaceRequest`] / [`FetchInterfaceResponse`] |
 //! | Object and interface call preconditions | [`Target`] / [`InterfaceTarget`] |
 //! | `call_operation` | [`CallOperationRequest`] / [`CallOperationResponse`] |
@@ -32,7 +31,7 @@
 //! 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
+//! Interface refs use [`InterfaceReference`]; other metadata use strings/bytes in their
 //! fields. In particular, object refs are optional, operation targeting uses a
 //! path, and this crate defines no interaction that fetches an object by ref.
 //!
@@ -53,8 +52,8 @@ pub use error::{
 };
 pub use model::{
    CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
-    FetchInterfaceResponse, FetchRequest, FetchResponse, FetchTreeRequest, FetchTreeResponse,
+    FetchInterfaceResponse, FieldDeclaration, InterfaceDescriptor, InterfaceReference,
-    FieldDeclaration, InterfaceDescriptor, InterfaceTarget, Object, ObjectTreeNode,
+    InterfaceTarget, Object, ObjectObservation, ObserveRequest, ObserveResponse,
    OperationDeclaration, ParameterDeclaration, ProtocolResult, ReturnDeclaration, Target,
    TypeDeclaration, TypeExpr, UnionCase, Value,
 };
@@ -11,9 +11,49 @@ pub struct Documentation {
    pub details: Option<String>,
 }
 /// An interface identified by an exact `(scope, name)` pair in one Worldspace.
 ///
 /// Neither field is normalized, case-folded, URL-decoded, or split on display
 /// delimiters. Descriptor identity is external to the descriptor itself.
 ///
 /// ```
 /// use wip_protocol::{FetchInterfaceRequest, InterfaceReference};
 /// let reference = InterfaceReference {
 ///     scope: "/世::界/#".into(),
 ///     name: "read::書く#λ".into(),
 /// };
 /// reference.validate_for_path("/世::界/#/item")?;
 /// // Fetching is independent of an Object target path.
 /// FetchInterfaceRequest { interface: reference }.validate()?;
 /// # Ok::<(), wip_protocol::ValidationError>(())
 /// ```
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct InterfaceReference {
    /// Canonical absolute Worldspace path of the interface's scope Object.
    pub scope: String,
    /// Nonempty Unicode local name, with no delimiter restrictions.
    pub name: String,
 }
 impl InterfaceReference {
    /// Validates reference shape without requiring a target Object path.
    pub fn validate(&self) -> Result<(), ValidationError> {
        crate::validation::validate_interface_reference(self)
    }
    /// Validates shape and that scope is an ancestor-or-self of `path`.
    ///
    /// This is independent of indexability. A Host maps a valid reference's
    /// scope mismatch to `InterfaceMismatch` at the interface-selection stage,
    /// not to the earlier shape-validation `InvalidRequest` stage.
    pub fn validate_for_path(&self, path: &str) -> Result<(), ValidationError> {
        crate::validation::validate_interface_scope(self, path)
    }
 }
 /// The protocol projection currently published at one Worldspace path.
 ///
-/// `name` is a path segment, `interfaces` is an ordered set of opaque interface
+/// `name` is a path segment, `interfaces` is an ordered set of structured interface
 /// references, `r#ref` is optional object identity, and `validator` is an
 /// independent optional observation precondition. In particular, neither the
 /// path nor `r#ref` is a mandatory object identifier.
@@ -23,8 +63,8 @@ pub struct Object {
    pub name: String,
    /// Short public description of the object.
    pub description: Option<String>,
-    /// Opaque interface references in host publication order.
+    /// Structured interface references in host publication order.
-    pub interfaces: Vec<String>,
+    pub interfaces: Vec<InterfaceReference>,
    /// Optional opaque identity within one client-facing Worldspace.
    pub r#ref: Option<String>,
    /// Optional opaque validator for the object's observed state.
@@ -218,57 +258,41 @@ impl Value {
    }
 }
-/// Request for the object currently published at one path.
+/// Request for the object currently published at one path and its indexable descendants.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct FetchRequest {
+pub struct ObserveRequest {
-    /// Canonical absolute Worldspace path.
+    /// Canonical absolute path of the observation root.
    pub path: String,
-}
+    /// Maximum observed depth, where the requested object has depth zero.
 /// Successful `fetch` response.
 pub type FetchResponse = Object;
 /// Request for a bounded breadth-first object-tree observation.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct FetchTreeRequest {
    /// Canonical absolute path of the tree root.
    pub path: String,
    /// Maximum depth, where the requested object has depth zero.
    pub depth: u32,
    /// Maximum total node count, including the root. Must be nonzero.
    pub limit: u32,
 }
-/// One node in a tree observation.
+/// One node in an object observation.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ObjectTreeNode {
+pub struct ObjectObservation {
-    /// Object observed at this tree position.
+    /// Object observed at this Worldspace position.
    pub object: Object,
-    /// Direct children in host-defined traversal order.
+    /// Complete direct children when observed, or `None` at the requested depth boundary.
-    pub children: Vec<ObjectTreeNode>,
+    pub children: Option<Vec<ObjectObservation>>,
 }
-/// Successful `fetch_tree` response.
+/// Successful `observe` response.
-#[derive(Debug, Clone, PartialEq, Eq)]
+pub type ObserveResponse = ObjectObservation;
 pub struct FetchTreeResponse {
    /// Observed tree rooted at the requested path.
    pub root: ObjectTreeNode,
    /// Whether public indexable children were omitted by depth or limit.
    pub truncated: bool,
 }
-/// Request for the current descriptor of one opaque interface reference.
+/// Request for the current descriptor of one structured interface reference.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct FetchInterfaceRequest {
-    /// Opaque interface reference obtained from an object.
+    /// Structured interface reference obtained from an object.
-    pub interface: String,
+    pub interface: InterfaceReference,
 }
 /// Successful `fetch_interface` response.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct FetchInterfaceResponse {
-    /// Opaque interface reference corresponding to the request.
+    /// Structured interface reference corresponding to the request.
-    pub interface: String,
+    pub interface: InterfaceReference,
    /// Optional opaque ref of the scope Object, not part of interface identity.
    pub scope_ref: Option<String>,
    /// Current validated descriptor.
    pub descriptor: InterfaceDescriptor,
    /// Optional opaque validator for this descriptor observation.
@@ -287,8 +311,10 @@ pub struct Target {
 /// Interface portion of an operation target.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InterfaceTarget {
-    /// Opaque interface reference selected from the object's interface set.
+    /// Structured reference selected from the object's interface set.
-    pub reference: String,
+    pub reference: InterfaceReference,
    /// Optional scope Object ref copied from the same interface observation.
    pub scope_ref: Option<String>,
    /// Optional validator copied from the interface observation.
    pub validator: Option<Vec<u8>>,
 }
@@ -372,35 +398,25 @@ impl InterfaceDescriptor {
    }
 }
-impl FetchRequest {
+impl ObserveRequest {
    /// Validates the request path.
    pub fn validate(&self) -> Result<(), ValidationError> {
        crate::validation::validate_path(&self.path)
    }
-    /// Validates an object returned for this request.
+    /// Validates observation shape, names, and requested depth.
    ///
    /// 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> {
+    pub fn validate_response(&self, response: &ObserveResponse) -> Result<(), ValidationError> {
-        response.validate_at_path(&self.path)
+        crate::validation::validate_observe_response(response, self)
    }
 }
-impl FetchTreeRequest {
+impl FetchInterfaceRequest {
-    /// Validates the request path and nonzero node limit.
+    /// Validates reference shape; fetching an interface needs no target path.
    pub fn validate(&self) -> Result<(), ValidationError> {
-        crate::validation::validate_fetch_tree_request(self)
+        self.interface.validate()
    }
 }
 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)
    }
 }
@@ -417,7 +433,16 @@ impl FetchInterfaceResponse {
 }
 impl CallOperationRequest {
-    /// Validates this call against the descriptor selected by `interface`.
+    /// Validates descriptor-independent request shape only.
    ///
    /// Scope compatibility is deliberately deferred to interface selection so
    /// that `NotFound` precedes `InterfaceMismatch` at the Host boundary.
    pub fn validate(&self) -> Result<(), ValidationError> {
        crate::validation::validate_call_shape(self)
    }
    /// Validates this call's shape and descriptor-bound operation/arguments.
    /// Scope compatibility and membership require Host publication context.
    pub fn validate_with(&self, descriptor: &InterfaceDescriptor) -> Result<(), ValidationError> {
        descriptor.validate_call(self)
    }
@@ -1,9 +1,9 @@
 use std::collections::{BTreeMap, HashMap, HashSet};
 use crate::{
-    CallOperationRequest, FetchInterfaceRequest, FetchInterfaceResponse, FetchTreeRequest,
+    CallOperationRequest, FetchInterfaceRequest, FetchInterfaceResponse, InterfaceDescriptor,
-    FetchTreeResponse, InterfaceDescriptor, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, NameNamespace,
+    InterfaceReference, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, NameNamespace, Object,
-    Object, ObjectTreeNode, PathSegment, TypeDeclaration, TypeExpr, UNION_CASE_FIELD,
+    ObjectObservation, ObserveRequest, PathSegment, TypeDeclaration, TypeExpr, UNION_CASE_FIELD,
    UNION_VALUE_FIELD, ValidationError, ValidationErrorKind, Value, ValueKind,
 };
@@ -11,8 +11,13 @@ pub(crate) fn validate_object(object: &Object) -> Result<(), ValidationError> {
    validate_object_name(&object.name, true)?;
    let mut seen = HashSet::new();
-    for interface in &object.interfaces {
+    for (index, interface) in object.interfaces.iter().enumerate() {
-        if !seen.insert(interface.as_str()) {
+        interface.validate().map_err(|error| {
            error
                .prepend(PathSegment::Index(index))
                .prepend(PathSegment::Field("interfaces".into()))
        })?;
        if !seen.insert(interface) {
            return Err(
                ValidationError::new(ValidationErrorKind::DuplicateInterface {
                    reference: interface.clone(),
@@ -51,6 +56,14 @@ pub(crate) fn validate_object_at_path(object: &Object, path: &str) -> Result<(),
            .next()
            .expect("non-root path has a segment")
    };
    for (index, interface) in object.interfaces.iter().enumerate() {
        interface.validate_for_path(path).map_err(|error| {
            error
                .prepend(PathSegment::Index(index))
                .prepend(PathSegment::Field("interfaces".into()))
                .prepend(PathSegment::Object(path.to_owned()))
        })?;
    }
    if object.name == expected {
        Ok(())
    } else {
@@ -106,6 +119,54 @@ pub(crate) fn validate_path(path: &str) -> Result<(), ValidationError> {
    }
 }
 pub(crate) fn validate_interface_reference(
    reference: &InterfaceReference,
 ) -> Result<(), ValidationError> {
    validate_path(&reference.scope)
        .map_err(|error| error.prepend(PathSegment::Field("scope".into())))?;
    if reference.name.is_empty() {
        return Err(
            ValidationError::new(ValidationErrorKind::EmptyInterfaceName)
                .prepend(PathSegment::Field("name".into())),
        );
    }
    Ok(())
 }
 pub(crate) fn validate_interface_scope(
    reference: &InterfaceReference,
    path: &str,
 ) -> Result<(), ValidationError> {
    reference.validate()?;
    validate_path(path)?;
    let scope = reference.scope.as_str();
    if scope == "/"
        || path == scope
        || path
            .strip_prefix(scope)
            .is_some_and(|rest| rest.starts_with('/'))
    {
        Ok(())
    } else {
        Err(ValidationError::new(
            ValidationErrorKind::InterfaceScopeMismatch {
                scope: reference.scope.clone(),
                path: path.to_owned(),
            },
        ))
    }
 }
 pub(crate) fn validate_call_shape(request: &CallOperationRequest) -> Result<(), ValidationError> {
    validate_path(&request.target.path)
        .map_err(|error| error.prepend(PathSegment::Field("target".into())))?;
    request.interface.reference.validate().map_err(|error| {
        error
            .prepend(PathSegment::Field("reference".into()))
            .prepend(PathSegment::Field("interface".into()))
    })
 }
 pub(crate) fn validate_descriptor(descriptor: &InterfaceDescriptor) -> Result<(), ValidationError> {
    let declarations = declaration_map(descriptor)?;
@@ -582,8 +643,7 @@ pub(crate) fn validate_call(
    descriptor: &InterfaceDescriptor,
    request: &CallOperationRequest,
 ) -> Result<(), ValidationError> {
-    validate_path(&request.target.path)
+    request.validate()?;
        .map_err(|error| error.prepend(PathSegment::Field("target".into())))?;
    validate_arguments(descriptor, &request.operation, &request.arguments)
 }
@@ -604,60 +664,38 @@ fn find_operation<'a>(
        })
 }
-pub(crate) fn validate_fetch_tree_request(
+pub(crate) fn validate_observe_response(
-    request: &FetchTreeRequest,
+    response: &ObjectObservation,
-) -> Result<(), ValidationError> {
+    request: &ObserveRequest,
    validate_path(&request.path)?;
    if request.limit == 0 {
        Err(ValidationError::new(ValidationErrorKind::ZeroTreeLimit))
    } else {
        Ok(())
    }
 }
 pub(crate) fn validate_fetch_tree_response(
    response: &FetchTreeResponse,
    request: &FetchTreeRequest,
 ) -> Result<(), ValidationError> {
    request.validate()?;
-    let mut node_count = 0_u32;
+    validate_observation_node(response, &request.path, 0, request.depth)
    validate_tree_node(
        &response.root,
        &request.path,
        0,
        request.depth,
        request.limit,
        &mut node_count,
    )
 }
-fn validate_tree_node(
+fn validate_observation_node(
-    node: &ObjectTreeNode,
+    node: &ObjectObservation,
    path: &str,
    depth: u32,
    maximum_depth: u32,
    limit: u32,
    node_count: &mut u32,
 ) -> Result<(), ValidationError> {
-    if depth > maximum_depth {
+    node.object.validate_at_path(path)?;
-        return Err(
+
-            ValidationError::new(ValidationErrorKind::TreeDepthExceeded {
+    if depth == maximum_depth {
-                maximum: maximum_depth,
+        if node.children.is_some() {
-            })
+            return Err(
-            .prepend(PathSegment::Object(path.to_owned())),
+                ValidationError::new(ValidationErrorKind::ChildrenAtDepthBoundary { depth })
-        );
+                    .prepend(PathSegment::Object(path.to_owned())),
-    }
+            );
-    *node_count = node_count.saturating_add(1);
+        }
-    if *node_count > limit {
+        return Ok(());
        return Err(
            ValidationError::new(ValidationErrorKind::TreeLimitExceeded { limit })
                .prepend(PathSegment::Object(path.to_owned())),
        );
    }
-    node.object.validate_at_path(path)?;
+    let children = node.children.as_ref().ok_or_else(|| {
        ValidationError::new(ValidationErrorKind::ChildrenMissingBeforeDepth { depth })
            .prepend(PathSegment::Object(path.to_owned()))
    })?;
    let mut names = HashSet::new();
-    for child in &node.children {
+    for child in children {
        validate_object_name(&child.object.name, false)
            .map_err(|error| error.prepend(PathSegment::Child(child.object.name.clone())))?;
        if !names.insert(child.object.name.as_str()) {
@@ -673,14 +711,7 @@ fn validate_tree_node(
        } else {
            format!("{path}/{}", child.object.name)
        };
-        validate_tree_node(
+        validate_observation_node(child, &child_path, depth + 1, maximum_depth)?;
            child,
            &child_path,
            depth.saturating_add(1),
            maximum_depth,
            limit,
            node_count,
        )?;
    }
    Ok(())
 }
@@ -689,11 +720,13 @@ pub(crate) fn validate_fetch_interface_response(
    response: &FetchInterfaceResponse,
    request: &FetchInterfaceRequest,
 ) -> Result<(), ValidationError> {
    request.validate()?;
    response.interface.validate()?;
    if response.interface != request.interface {
        return Err(
            ValidationError::new(ValidationErrorKind::InterfaceResponseMismatch {
-                expected: request.interface.clone(),
+                expected: Box::new(request.interface.clone()),
-                actual: response.interface.clone(),
+                actual: Box::new(response.interface.clone()),
            })
            .prepend(PathSegment::Field("interface".into())),
        );
@@ -0,0 +1,219 @@
 use std::collections::BTreeMap;
 use wip_protocol::{
    CallOperationRequest, FetchInterfaceRequest, FetchInterfaceResponse, InterfaceDescriptor,
    InterfaceReference, InterfaceTarget, Object, ObjectObservation, ObserveRequest,
    OperationDeclaration, ReturnDeclaration, Target, TypeExpr, ValidationErrorKind,
 };
 fn reference(scope: &str, name: &str) -> InterfaceReference {
    InterfaceReference {
        scope: scope.into(),
        name: name.into(),
    }
 }
 fn object(path: &str, interfaces: Vec<InterfaceReference>) -> Object {
    Object {
        name: path.rsplit('/').next().unwrap().into(),
        description: None,
        interfaces,
        r#ref: None,
        validator: None,
    }
 }
 fn descriptor() -> InterfaceDescriptor {
    InterfaceDescriptor {
        format: wip_protocol::INTERFACE_FORMAT_V1.into(),
        documentation: None,
        types: vec![],
        operations: vec![OperationDeclaration {
            name: "run".into(),
            documentation: None,
            parameters: vec![],
            returns: ReturnDeclaration {
                documentation: None,
                r#type: TypeExpr::Unit,
            },
        }],
    }
 }
 #[test]
 fn scope_is_segment_based_ancestor_or_self_not_indexability() {
    for (scope, path) in [
        ("/", "/"),
        ("/", "/a/b"),
        ("/a", "/a"),
        ("/a", "/a/b"),
        ("/a/b", "/a/b/c"),
    ] {
        reference(scope, "read").validate_for_path(path).unwrap();
        object(path, vec![reference(scope, "read")])
            .validate_at_path(path)
            .unwrap();
    }
    for (scope, path) in [
        ("/a", "/ab"),
        ("/a", "/ab/c"),
        ("/a/b", "/a/c"),
        ("/a/b", "/a"),
        ("/a", "/"),
    ] {
        assert!(matches!(
            reference(scope, "read")
                .validate_for_path(path)
                .unwrap_err()
                .kind,
            ValidationErrorKind::InterfaceScopeMismatch { .. }
        ));
        // Without the placement context, the Object/reference shape is valid.
        let object = object(path, vec![reference(scope, "read")]);
        object.validate().unwrap();
        assert!(matches!(
            object.validate_at_path(path).unwrap_err().kind,
            ValidationErrorKind::InterfaceScopeMismatch { .. }
        ));
    }
 }
 #[test]
 fn shape_validation_does_not_normalize_or_parse_fields() {
    for scope in ["", "relative", "//a", "/a/", "/a//b", "/a/./b", "/a/../b"] {
        let reference = reference(scope, "read");
        assert!(matches!(
            reference.validate().unwrap_err().kind,
            ValidationErrorKind::InvalidPath { .. }
        ));
        assert!(
            FetchInterfaceRequest {
                interface: reference.clone()
            }
            .validate()
            .is_err()
        );
        assert!(object("/a", vec![reference]).validate().is_err());
    }
    assert_eq!(
        reference("/", "").validate().unwrap_err().kind,
        ValidationErrorKind::EmptyInterfaceName
    );
    for name in [".", "..", "a/b", "::", "#", "読み::書き#λ", "e\u{301}"] {
        let reference = reference("/世::界/#/%2F", name);
        reference.validate().unwrap();
        assert_eq!(reference.name, name);
        assert_eq!(reference.scope, "/世::界/#/%2F");
    }
    assert_ne!(reference("/", "é"), reference("/", "e\u{301}"));
    assert_ne!(reference("/A", "read"), reference("/a", "read"));
    assert_ne!(reference("/%61", "read"), reference("/a", "read"));
 }
 #[test]
 fn duplicate_membership_and_correlation_use_complete_pair() {
    let root = reference("/", "read");
    let scoped = reference("/a", "read");
    let mut object = object("/a", vec![root.clone(), scoped.clone()]);
    object.validate_at_path("/a").unwrap();
    assert!(object.interfaces.contains(&scoped));
    assert!(!object.interfaces.contains(&reference("/b", "read")));
    object.interfaces.push(root.clone());
    assert_eq!(
        object.validate().unwrap_err().kind,
        ValidationErrorKind::DuplicateInterface {
            reference: root.clone()
        }
    );
    let request = FetchInterfaceRequest { interface: root };
    let mut response = FetchInterfaceResponse {
        interface: scoped,
        scope_ref: None,
        descriptor: descriptor(),
        validator: None,
    };
    assert!(matches!(
        response.validate_for(&request).unwrap_err().kind,
        ValidationErrorKind::InterfaceResponseMismatch { .. }
    ));
    response.interface = request.interface.clone();
    for scope_ref in [None, Some(String::new()), Some("opaque::世界#/%".into())] {
        response.scope_ref = scope_ref;
        response.validate_for(&request).unwrap();
    }
    response.interface.name.clear();
    assert_eq!(
        response.validate_for(&request).unwrap_err().kind,
        ValidationErrorKind::EmptyInterfaceName
    );
 }
 #[test]
 fn observe_checks_scope_at_every_node_including_depth_boundary() {
    let request = ObserveRequest {
        path: "/a".into(),
        depth: 1,
    };
    let mut response = ObjectObservation {
        object: object("/a", vec![reference("/a", "read")]),
        children: Some(vec![ObjectObservation {
            object: object("/a/b", vec![reference("/a/b", "read")]),
            children: None,
        }]),
    };
    request.validate_response(&response).unwrap();
    response.children.as_mut().unwrap()[0].object.interfaces[0].scope = "/a/c".into();
    assert!(matches!(
        request.validate_response(&response).unwrap_err().kind,
        ValidationErrorKind::InterfaceScopeMismatch { .. }
    ));
 }
 #[test]
 fn fetch_needs_no_target_path_and_call_separates_shape_from_scope_selection() {
    let reference = reference("/some/unrelated/scope", "read");
    let fetch = FetchInterfaceRequest {
        interface: reference.clone(),
    };
    fetch.validate().unwrap();
    FetchInterfaceResponse {
        interface: reference.clone(),
        scope_ref: None,
        descriptor: descriptor(),
        validator: None,
    }
    .validate_for(&fetch)
    .unwrap();
    let mut call = CallOperationRequest {
        target: Target {
            path: "/a".into(),
            validator: None,
        },
        interface: InterfaceTarget {
            reference,
            scope_ref: Some("opaque".into()),
            validator: None,
        },
        operation: "run".into(),
        arguments: BTreeMap::new(),
    };
    call.validate().unwrap();
    call.validate_with(&descriptor()).unwrap();
    // This stage is Host InterfaceMismatch, after NotFound, not shape InvalidRequest.
    assert!(matches!(
        call.interface
            .reference
            .validate_for_path(&call.target.path)
            .unwrap_err()
            .kind,
        ValidationErrorKind::InterfaceScopeMismatch { .. }
    ));
    call.interface.reference.name.clear();
    assert_eq!(
        call.validate().unwrap_err().kind,
        ValidationErrorKind::EmptyInterfaceName
    );
    assert_eq!(
        call.validate_with(&descriptor()).unwrap_err().kind,
        ValidationErrorKind::EmptyInterfaceName
    );
 }
@@ -2,13 +2,20 @@ use std::collections::BTreeMap;
 use wip_protocol::{
    CallOperationRequest, CallOperationResponse, EnumCase, FetchInterfaceRequest,
-    FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
+    FetchInterfaceResponse, FieldDeclaration, INTERFACE_FORMAT_V1, InterfaceDescriptor,
-    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, NameNamespace,
+    InterfaceReference, InterfaceTarget, MAX_SAFE_INTEGER, NameNamespace, Object,
-    Object, ObjectTreeNode, OperationDeclaration, ParameterDeclaration, PathSegment, ProtocolError,
+    ObjectObservation, ObserveRequest, OperationDeclaration, ParameterDeclaration, PathSegment,
-    ProtocolErrorCode, ProtocolInteraction, ProtocolResult, ReturnDeclaration, Target,
+    ProtocolError, ProtocolErrorCode, ProtocolInteraction, ProtocolResult, ReturnDeclaration,
-    TypeDeclaration, TypeExpr, UnionCase, ValidationErrorKind, Value, ValueKind,
+    Target, TypeDeclaration, TypeExpr, UnionCase, ValidationErrorKind, Value, ValueKind,
 };
 fn reference(scope: &str, name: &str) -> InterfaceReference {
    InterfaceReference {
        scope: scope.into(),
        name: name.into(),
    }
 }
 fn record(entries: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
    Value::Record(
        entries
@@ -135,7 +142,7 @@ fn object(name: &str) -> Object {
    Object {
        name: name.into(),
        description: Some(format!("Object {name}")),
-        interfaces: vec!["catalog-v1".into(), "search-v2".into()],
+        interfaces: vec![reference("/", "catalog-v1"), reference("/", "search-v2")],
        r#ref: Some("opaque-object-ref".into()),
        validator: Some(vec![1, 2, 3]),
    }
@@ -146,16 +153,19 @@ fn object_fields_have_canonical_identity_and_ordered_set_semantics() {
    let object = object("article");
    object.validate().unwrap();
    object.validate_at_path("/articles/article").unwrap();
-    assert_eq!(object.interfaces, ["catalog-v1", "search-v2"]);
+    assert_eq!(
        object.interfaces,
        [reference("/", "catalog-v1"), reference("/", "search-v2")]
    );
    let duplicate = Object {
-        interfaces: vec!["catalog-v1".into(), "catalog-v1".into()],
+        interfaces: vec![reference("/", "catalog-v1"), reference("/", "catalog-v1")],
        ..object.clone()
    };
    assert_eq!(
        duplicate.validate().unwrap_err().kind,
        ValidationErrorKind::DuplicateInterface {
-            reference: "catalog-v1".into()
+            reference: reference("/", "catalog-v1")
        }
    );
@@ -574,7 +584,8 @@ fn calls_validate_canonical_paths_named_arguments_and_unit_results() {
            validator: Some(vec![1]),
        },
        interface: InterfaceTarget {
-            reference: "catalog-v1".into(),
+            scope_ref: None,
            reference: reference("/", "catalog-v1"),
            validator: Some(vec![2]),
        },
        operation: "publish".into(),
@@ -617,13 +628,26 @@ fn calls_validate_canonical_paths_named_arguments_and_unit_results() {
 }
 #[test]
-fn fetch_and_fetch_interface_dtos_validate_request_response_correspondence() {
+fn observe_and_fetch_interface_dtos_validate_request_response_correspondence() {
-    let fetch = FetchRequest {
+    let observe = ObserveRequest {
        path: "/articles/one".into(),
        depth: 0,
    };
-    fetch.validate().unwrap();
+    observe.validate().unwrap();
-    fetch.validate_response(&object("one")).unwrap();
+    observe
-    assert!(fetch.validate_response(&object("two")).is_err());
+        .validate_response(&ObjectObservation {
            object: object("one"),
            children: None,
        })
        .unwrap();
    assert!(
        observe
            .validate_response(&ObjectObservation {
                object: object("two"),
                children: None,
            })
            .is_err()
    );
    for invalid in [
        "",
@@ -634,8 +658,9 @@ fn fetch_and_fetch_interface_dtos_validate_request_response_correspondence() {
        "/a/../b",
    ] {
        assert!(matches!(
-            FetchRequest {
+            ObserveRequest {
-                path: invalid.into()
+                path: invalid.into(),
                depth: 0,
            }
            .validate()
            .unwrap_err()
@@ -645,17 +670,18 @@ fn fetch_and_fetch_interface_dtos_validate_request_response_correspondence() {
    }
    let request = FetchInterfaceRequest {
-        interface: "catalog-v1".into(),
+        interface: reference("/", "catalog-v1"),
    };
    let response = FetchInterfaceResponse {
-        interface: "catalog-v1".into(),
+        scope_ref: None,
        interface: reference("/", "catalog-v1"),
        descriptor: descriptor(),
        validator: Some(vec![9]),
    };
    response.validate_for(&request).unwrap();
    assert!(matches!(
        FetchInterfaceResponse {
-            interface: "other".into(),
+            interface: reference("/", "other"),
            ..response
        }
        .validate_for(&request)
@@ -666,61 +692,51 @@ fn fetch_and_fetch_interface_dtos_validate_request_response_correspondence() {
 }
 #[test]
-fn fetch_tree_dtos_validate_names_depth_limit_and_siblings() {
+fn observe_response_validates_complete_children_and_depth_boundary() {
-    let request = FetchTreeRequest {
+    let request = ObserveRequest {
        path: "/articles".into(),
        depth: 1,
        limit: 3,
    };
-    let leaf = |name: &str| ObjectTreeNode {
+    let leaf = |name: &str| ObjectObservation {
        object: object(name),
-        children: vec![],
+        children: None,
    };
-    let response = FetchTreeResponse {
+    let response = ObjectObservation {
-        root: ObjectTreeNode {
+        object: object("articles"),
-            object: object("articles"),
+        children: Some(vec![leaf("one"), leaf("two")]),
            children: vec![leaf("one"), leaf("two")],
        },
        truncated: false,
    };
-    response.validate_for(&request).unwrap();
+    request.validate_response(&response).unwrap();
-    let zero = FetchTreeRequest {
+    let empty = ObjectObservation {
-        limit: 0,
+        object: object("articles"),
-        ..request.clone()
+        children: Some(vec![]),
    };
-    assert_eq!(
+    request.validate_response(&empty).unwrap();
        zero.validate().unwrap_err().kind,
        ValidationErrorKind::ZeroTreeLimit
    );
-    let shallow = FetchTreeRequest {
+    let missing = ObjectObservation {
        object: object("articles"),
        children: None,
    };
    assert!(matches!(
        request.validate_response(&missing).unwrap_err().kind,
        ValidationErrorKind::ChildrenMissingBeforeDepth { depth: 0 }
    ));
    let boundary = ObserveRequest {
        depth: 0,
        ..request.clone()
    };
    assert!(matches!(
-        response.validate_for(&shallow).unwrap_err().kind,
+        boundary.validate_response(&response).unwrap_err().kind,
-        ValidationErrorKind::TreeDepthExceeded { .. }
+        ValidationErrorKind::ChildrenAtDepthBoundary { depth: 0 }
    ));
-    let small = FetchTreeRequest {
+    let duplicate = ObjectObservation {
-        limit: 2,
+        object: object("articles"),
-        ..request.clone()
+        children: Some(vec![leaf("one"), leaf("one")]),
    };
    assert!(matches!(
-        response.validate_for(&small).unwrap_err().kind,
+        request.validate_response(&duplicate).unwrap_err().kind,
        ValidationErrorKind::TreeLimitExceeded { .. }
    ));
    let duplicate = FetchTreeResponse {
        root: ObjectTreeNode {
            object: object("articles"),
            children: vec![leaf("one"), leaf("one")],
        },
        truncated: false,
    };
    assert!(matches!(
        duplicate.validate_for(&request).unwrap_err().kind,
        ValidationErrorKind::DuplicateName {
            namespace: NameNamespace::ChildObject,
            ..
@@ -778,22 +794,9 @@ fn assert_allowed_codes(interaction: ProtocolInteraction, expected: &[ProtocolEr
 }
 #[test]
-fn fetch_error_codes_are_exhaustive() {
+fn observe_error_codes_are_exhaustive() {
    assert_allowed_codes(
-        ProtocolInteraction::Fetch,
+        ProtocolInteraction::Observe,
        &[
            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,
@@ -840,16 +843,23 @@ fn call_operation_error_codes_are_exhaustive() {
 #[test]
 fn invalid_success_payloads_remain_client_local_validation_failures() {
-    let fetch = FetchRequest {
+    let observe = ObserveRequest {
        path: "/articles/one".into(),
        depth: 0,
    };
    assert!(matches!(
-        fetch.validate_response(&object("other")).unwrap_err().kind,
+        observe
            .validate_response(&ObjectObservation {
                object: object("other"),
                children: None,
            })
            .unwrap_err()
            .kind,
        ValidationErrorKind::ObjectNameMismatch { .. }
    ));
    let interface_request = FetchInterfaceRequest {
-        interface: "catalog-v1".into(),
+        interface: reference("/", "catalog-v1"),
    };
    let mut invalid_descriptor = descriptor();
    invalid_descriptor
@@ -858,6 +868,7 @@ fn invalid_success_payloads_remain_client_local_validation_failures() {
    assert!(matches!(
        FetchInterfaceResponse {
            interface: interface_request.interface.clone(),
            scope_ref: None,
            descriptor: invalid_descriptor,
            validator: None,
        }
@@ -1,12 +1,18 @@
 [package]
 name = "wip-public-api-example"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
 rust-version.workspace = true
 description = "Public-only end-to-end conformance consumer for the WIP Rust APIs"
-license = "MIT OR Apache-2.0"
+license.workspace = true
 repository.workspace = true
 publish = false
 [dependencies]
-wip-host = { path = "../wip-host" }
+wip-host.workspace = true
-wip-interface = { path = "../wip-interface" }
+wip-interface.workspace = true
-wip-protocol = { path = "../wip-protocol" }
+wip-protocol.workspace = true
 [dev-dependencies]
 wip-client.workspace = true
 wip-http.workspace = true
@@ -10,13 +10,20 @@
 //! 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.
+//! part of an application trait or interface descriptor. Its dev-only conformance
 //! suite also uses the public Client and HTTP crates over real TCP HTTP to test
 //! scope replacement/deletion, optional refs, principal visibility and precondition
 //! precedence. Those dependencies are not required by the example executable.
 //!
 //! # 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
+//! optional observation fields. This demo registers explicit `catalog`, `audit`
 //! and `diagnostics` names at the service Object self-scope. A private [`Scope`]
 //! lifetime and coherent [`ScopeObservation`] bind fetch and call to that Object;
 //! successful calls carry its optional `scope_ref` identity precondition.
 //! Interface references are structured scope/name 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`]
@@ -41,12 +48,12 @@ use std::io;
 use wip_host::{
    CallErrorKind, CallRequest, ExecutionContext, InterfaceRef, InterfaceRegistry, InterfaceTarget,
-    ObjectProvider, ProviderResult, PublishedObject, RegisteredInterface, Target, Validator,
+    ObjectProvider, ProviderResult, PublishedObject, RegisteredInterface, Scope, ScopeObservation,
-    WipObject,
+    Target, Validator, WipObject,
 };
 use wip_interface as wip;
 use wip_interface::WipType;
-use wip_protocol::{ProtocolError, ProtocolErrorCode, Value};
+use wip_protocol::{InterfaceReference, ProtocolError, ProtocolErrorCode, Value};
 const OBJECT_PATH: &str = "/article-service";
 const OBJECT_VALIDATOR: &[u8] = b"object-v1";
@@ -134,16 +141,22 @@ pub struct DemoReport {
    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.
+    /// Structured interface references published by the object, in exposure order.
-    pub published_interfaces: Vec<String>,
+    pub published_interfaces: Vec<InterfaceReference>,
-    /// Opaque reference assigned to the catalog descriptor.
+    /// Self-scoped reference assigned to the catalog descriptor.
-    pub catalog_interface_reference: String,
+    pub catalog_interface_reference: InterfaceReference,
-    /// Opaque reference assigned to the audit descriptor.
+    /// Self-scoped reference assigned to the audit descriptor.
-    pub audit_interface_reference: String,
+    pub audit_interface_reference: InterfaceReference,
    /// 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,
    /// Scope Object ref observed together with the catalog Descriptor.
    pub catalog_scope_ref: Option<String>,
    /// Scope Object ref observed together with the audit Descriptor.
    pub audit_scope_ref: Option<String>,
    /// Membership rejection when the supplied scope Object ref is stale.
    pub scope_mismatch: ProtocolErrorCode,
    /// Typed successful application result decoded from a validated [`Value`].
    pub published: PublishOutcome,
    /// Typed application-domain rejection decoded from a validated [`Value`].
@@ -182,25 +195,34 @@ pub struct DemoReport {
 /// 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 scope = Scope::new(OBJECT_PATH)?;
-    let audit = registry.register(AuditDefinition, None)?;
+    let catalog = registry.register(
-    let diagnostics = registry.register(DiagnosticsDefinition, None)?;
+        &scope,
        "catalog",
        CatalogDefinition,
        Some(Validator::new(CATALOG_VALIDATOR)),
    )?;
    let audit = registry.register(&scope, "audit", AuditDefinition, None)?;
    let diagnostics = registry.register(&scope, "diagnostics", DiagnosticsDefinition, None)?;
    let provider = ApplicationProvider {
        scope,
        catalog: catalog.clone(),
        audit: audit.clone(),
    };
-    let object = provider.fetch(OBJECT_PATH)?;
+    let object = provider.observe_object(OBJECT_PATH)?;
-    let catalog_response = registry
+    let catalog_response = provider
        .fetch_interface(
            &registry,
            object
                .interfaces
                .first()
                .ok_or_else(|| io::Error::other("catalog interface was not published"))?,
        )?
        .protocol_response()?;
-    let audit_response = registry
+    let audit_response = provider
        .fetch_interface(
            &registry,
            object
                .interfaces
                .get(1)
@@ -210,7 +232,7 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
    let published = dispatch_publish(
        &provider,
-        catalog.reference(),
+        &catalog_response,
        PublishRequest {
            title: "Public APIs".into(),
            body: Some("protocol values in, validated values out".into()),
@@ -224,7 +246,7 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
    )?;
    let rejected = dispatch_publish(
        &provider,
-        catalog.reference(),
+        &catalog_response,
        PublishRequest {
            title: String::new(),
            body: None,
@@ -237,7 +259,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
        &provider,
        request(
            OBJECT_PATH,
-            catalog.reference(),
+            &catalog_response.interface,
            catalog_response.scope_ref.as_deref(),
            Some(CATALOG_VALIDATOR),
            "status",
            BTreeMap::new(),
@@ -247,7 +270,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
        &provider,
        request(
            OBJECT_PATH,
-            audit.reference(),
+            &audit_response.interface,
            audit_response.scope_ref.as_deref(),
            None,
            "status",
            BTreeMap::new(),
@@ -257,7 +281,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
    let host_error = provider
        .call_operation(request(
            OBJECT_PATH,
-            catalog.reference(),
+            &catalog_response.interface,
            catalog_response.scope_ref.as_deref(),
            Some(CATALOG_VALIDATOR),
            "backend_status",
            BTreeMap::new(),
@@ -269,7 +294,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
    let unknown_protocol_failure = provider
        .call_operation(request(
            OBJECT_PATH,
-            catalog.reference(),
+            &catalog_response.interface,
            catalog_response.scope_ref.as_deref(),
            Some(CATALOG_VALIDATOR),
            "uncertain_backend_status",
            BTreeMap::new(),
@@ -280,7 +306,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
    let permission_failure = provider
        .call_operation(request(
            OBJECT_PATH,
-            catalog.reference(),
+            &catalog_response.interface,
            catalog_response.scope_ref.as_deref(),
            Some(CATALOG_VALIDATOR),
            "restricted_status",
            BTreeMap::new(),
@@ -296,7 +323,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
                validator: Some(b"stale-object".to_vec()),
            },
            interface: InterfaceTarget {
-                reference: diagnostics.reference().as_str().to_owned(),
+                scope_ref: None,
                reference: diagnostics.reference().protocol_reference(),
                validator: Some(b"stale-interface".to_vec()),
            },
            operation: "missing".into(),
@@ -309,7 +337,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
    let interface_mismatch = provider
        .call_operation(request(
            OBJECT_PATH,
-            diagnostics.reference(),
+            &diagnostics.reference().protocol_reference(),
            catalog_response.scope_ref.as_deref(),
            None,
            "diagnostics",
            BTreeMap::new(),
@@ -318,11 +347,32 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
        .protocol_error()
        .code;
-    let interface_not_found = registry
+    let interface_not_found = provider
-        .fetch_interface("missing-interface")
+        .fetch_interface(
            &registry,
            &InterfaceReference {
                scope: OBJECT_PATH.into(),
                name: "missing-interface".into(),
            },
        )
        .expect_err("unknown interface references must not resolve")
        .code;
    let mut stale_scope = request(
        OBJECT_PATH,
        &catalog_response.interface,
        catalog_response.scope_ref.as_deref(),
        Some(CATALOG_VALIDATOR),
        "status",
        BTreeMap::new(),
    );
    stale_scope.interface.scope_ref = Some("replaced-service-instance".into());
    let scope_mismatch = provider
        .call_operation(stale_scope)
        .expect_err("stale scope identity must reject before operation dispatch")
        .protocol_error()
        .code;
    let precedence_failure = provider
        .call_operation(CallRequest {
            target: Target {
@@ -330,7 +380,8 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
                validator: Some(b"stale-object".to_vec()),
            },
            interface: InterfaceTarget {
-                reference: diagnostics.reference().as_str().to_owned(),
+                scope_ref: None,
                reference: diagnostics.reference().protocol_reference(),
                validator: Some(b"stale-interface".to_vec()),
            },
            operation: "missing".into(),
@@ -345,10 +396,13 @@ pub fn run() -> Result<DemoReport, Box<dyn Error>> {
        object_reference: object.r#ref,
        object_validator: object.validator,
        published_interfaces: object.interfaces,
-        catalog_interface_reference: catalog.reference().as_str().to_owned(),
+        catalog_interface_reference: catalog.reference().protocol_reference(),
-        audit_interface_reference: audit.reference().as_str().to_owned(),
+        audit_interface_reference: audit.reference().protocol_reference(),
        catalog_descriptor_format: catalog_response.descriptor.format,
        audit_descriptor_format: audit_response.descriptor.format,
        catalog_scope_ref: catalog_response.scope_ref,
        audit_scope_ref: audit_response.scope_ref,
        scope_mismatch,
        published,
        rejected,
        catalog_status,
@@ -377,13 +431,14 @@ fn ensure_kind(error: &wip_host::CallError, expected: CallErrorKind) -> Result<(
 fn dispatch_publish(
    provider: &ApplicationProvider,
-    catalog: &InterfaceRef,
+    catalog: &wip_protocol::FetchInterfaceResponse,
    request_value: PublishRequest,
 ) -> Result<PublishOutcome, Box<dyn Error>> {
    let encoded_request = request_value.encode()?;
    let result = provider.call_operation(request(
        OBJECT_PATH,
-        catalog,
+        &catalog.interface,
        catalog.scope_ref.as_deref(),
        Some(CATALOG_VALIDATOR),
        "publish",
        BTreeMap::from([("request".into(), encoded_request)]),
@@ -401,7 +456,8 @@ fn dispatch_string(
 fn request(
    path: &str,
-    interface: &InterfaceRef,
+    interface: &InterfaceReference,
    scope_ref: Option<&str>,
    interface_validator: Option<&[u8]>,
    operation: &str,
    arguments: BTreeMap<String, Value>,
@@ -412,7 +468,8 @@ fn request(
            validator: Some(OBJECT_VALIDATOR.to_vec()),
        },
        interface: InterfaceTarget {
-            reference: interface.as_str().to_owned(),
+            scope_ref: scope_ref.map(str::to_owned),
            reference: interface.clone(),
            validator: interface_validator.map(<[u8]>::to_vec),
        },
        operation: operation.into(),
@@ -421,6 +478,7 @@ fn request(
 }
 struct ApplicationProvider {
    scope: Scope,
    catalog: RegisteredInterface<CatalogDefinition>,
    audit: RegisteredInterface<AuditDefinition>,
 }
@@ -437,7 +495,12 @@ impl ObjectProvider for ApplicationProvider {
        if path != OBJECT_PATH {
            return ProviderResult::NotFound;
        }
-        let publication = PublishedObject::new(ApplicationService::new())
+        // The immutable demo has no mutable backend actors. A real backend
        // must retain its transaction/lock across association and operation.
        let service = ApplicationService::new();
        let current = ScopeObservation::new(&self.scope, &service);
        let publication = PublishedObject::new(service)
            .bind_scope(current)
            .expose(&self.catalog)
            .expect("ApplicationService implements Catalog")
            .expose(&self.audit)
@@ -28,10 +28,20 @@ fn public_crates_support_the_complete_qualified_end_to_end_scenario() {
    );
    assert_ne!(
        report.catalog_interface_reference, report.audit_interface_reference,
-        "interfaces form an ordered set of distinct opaque references"
+        "interfaces form an ordered set of distinct scope/name references"
    );
    assert_eq!(report.catalog_interface_reference.scope, "/article-service");
    assert_eq!(report.catalog_interface_reference.name, "catalog");
    assert_eq!(report.audit_interface_reference.scope, "/article-service");
    assert_eq!(report.audit_interface_reference.name, "audit");
    assert_eq!(report.catalog_descriptor_format, INTERFACE_FORMAT_V1);
    assert_eq!(report.audit_descriptor_format, INTERFACE_FORMAT_V1);
    assert_eq!(
        report.catalog_scope_ref.as_deref(),
        Some("article-service-instance")
    );
    assert_eq!(report.audit_scope_ref, report.catalog_scope_ref);
    assert_eq!(report.scope_mismatch, ProtocolErrorCode::InterfaceMismatch);
    assert_eq!(
        report.published,
        PublishOutcome::Published("article-1".into())
@@ -97,7 +107,7 @@ fn object_fields_keep_path_context_and_optional_ref_separate() {
    let object = Object {
        name: "article".into(),
        description: None,
-        interfaces: vec!["catalog-ref".into(), "audit-ref".into()],
+        interfaces: vec![root_reference("catalog-ref"), root_reference("audit-ref")],
        r#ref: None,
        validator: None,
    };
@@ -105,7 +115,10 @@ fn object_fields_keep_path_context_and_optional_ref_separate() {
    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"]);
+    assert_eq!(
        object.interfaces,
        [root_reference("catalog-ref"), root_reference("audit-ref")]
    );
 }
 #[test]
@@ -244,3 +257,44 @@ fn assert_schema_neutral(value: &Value) {
        }
    }
 }
 #[test]
 fn scoped_dtos_keep_identity_binding_and_validators_separate() {
    // Exact literals/destructuring guard the public Rust contract, including
    // omission of refs rather than requiring a fabricated identity.
    let reference = wip_protocol::InterfaceReference {
        scope: "/article-service".into(),
        name: "catalog::read#raw".into(),
    };
    let request = wip_protocol::FetchInterfaceRequest {
        interface: reference.clone(),
    };
    request.validate().unwrap();
    let wip_protocol::FetchInterfaceResponse {
        interface,
        scope_ref,
        descriptor,
        validator,
    } = wip_protocol::FetchInterfaceResponse {
        interface: reference.clone(),
        scope_ref: None,
        descriptor: CatalogDefinition::descriptor(),
        validator: None,
    };
    let target = wip_protocol::InterfaceTarget {
        reference: interface,
        scope_ref,
        validator,
    };
    assert_eq!(target.reference, reference);
    assert!(target.scope_ref.is_none());
    assert!(target.validator.is_none());
    assert_eq!(descriptor.format, INTERFACE_FORMAT_V1);
 }
 fn root_reference(name: &str) -> wip_protocol::InterfaceReference {
    wip_protocol::InterfaceReference {
        scope: "/".into(),
        name: name.into(),
    }
 }
@@ -0,0 +1,559 @@
 //! External-style consumer: a transactional provider, real TCP HTTP, and Client.
 use std::collections::BTreeMap;
 use std::io::{Read, Write};
 use std::net::{TcpListener, TcpStream};
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::Duration;
 use wip_client::{
    CallOutcome, Client, ClientLimits, Completion, ObservationState, SecurityContext,
 };
 use wip_host::{
    ExecutionContext, InterfaceRegistry, ObjectProvider, ProviderResult, PublishedObject,
    RegisteredInterface, Scope, ScopeObservation, Validator, WipObject,
 };
 use wip_http::{http, *};
 use wip_interface as wip;
 use wip_protocol::{InterfaceReference, ObjectObservation, ProtocolErrorCode, ProtocolInteraction};
 #[wip::interface]
 pub trait Status {
    fn status(&self) -> wip::OperationResult<String>;
    fn uncertain(&self) -> wip::OperationResult<String>;
 }
 struct Service {
    name: String,
    reference: Option<String>,
    validator: Validator,
    calls: Arc<AtomicUsize>,
 }
 impl WipObject for Service {
    fn name(&self) -> &str {
        &self.name
    }
    fn reference(&self) -> Option<&str> {
        self.reference.as_deref()
    }
    fn validator(&self) -> Option<&Validator> {
        Some(&self.validator)
    }
 }
 impl Status for Service {
    fn status(&self) -> wip::OperationResult<String> {
        self.calls.fetch_add(1, Ordering::SeqCst);
        Ok(self.name.clone())
    }
    fn uncertain(&self) -> wip::OperationResult<String> {
        self.calls.fetch_add(1, Ordering::SeqCst);
        Err(wip::HostError::internal(
            "commit acknowledgement lost",
            wip::EffectGuarantee::Unknown,
        ))
    }
 }
 struct Publication {
    scope: Scope,
    api: RegisteredInterface<StatusDefinition>,
    reference: Option<String>,
 }
 struct State {
    registry: InterfaceRegistry,
    root: Publication,
    service: Option<Publication>,
    calls: Arc<AtomicUsize>,
 }
 impl State {
    fn new(reference: Option<&str>) -> Self {
        let mut registry = InterfaceRegistry::new();
        let scope = Scope::new("/").unwrap();
        let root = Publication {
            api: registry
                .register(&scope, "status", StatusDefinition, None)
                .unwrap(),
            scope,
            reference: None,
        };
        let mut state = Self {
            registry,
            root,
            service: None,
            calls: Arc::default(),
        };
        state.republish(reference);
        state
    }
    fn remove(&mut self) {
        if let Some(old) = self.service.take() {
            self.registry.remove_scope(&old.scope);
        }
    }
    fn republish(&mut self, reference: Option<&str>) {
        self.remove();
        let scope = Scope::new("/service").unwrap();
        self.service = Some(Publication {
            api: self
                .registry
                .register(
                    &scope,
                    "status",
                    StatusDefinition,
                    Some(Validator::new(b"api-v1")),
                )
                .unwrap(),
            scope,
            reference: reference.map(str::to_owned),
        });
    }
 }
 // The HTTP adapter holds the State lock across all provider lookups, preconditions
 // and dispatch. No separate scope prelookup can race a replacement.
 struct Provider<'a> {
    state: &'a State,
    visible: bool,
 }
 impl ObjectProvider for Provider<'_> {
    type Object = Service;
    fn with_object<R>(
        &self,
        _: &ExecutionContext,
        path: &str,
        operation: impl FnOnce(&PublishedObject<Service>) -> R,
    ) -> ProviderResult<R> {
        let publication = match path {
            "/" => &self.state.root,
            "/service" if self.visible => match &self.state.service {
                Some(value) => value,
                None => return ProviderResult::NotFound,
            },
            _ => return ProviderResult::NotFound,
        };
        let object = Service {
            name: if path == "/" { "" } else { "service" }.into(),
            reference: publication.reference.clone(),
            validator: Validator::new(b"object-v1"),
            calls: self.state.calls.clone(),
        };
        let current = ScopeObservation::new(&publication.scope, &object);
        let mut object = PublishedObject::new(object)
            .bind_scope(current)
            .expose(&publication.api)
            .unwrap();
        if path == "/service" {
            let root_object = Service {
                name: "".into(),
                reference: None,
                validator: Validator::new(b"object-v1"),
                calls: self.state.calls.clone(),
            };
            object = object
                .bind_scope(ScopeObservation::new(&self.state.root.scope, &root_object))
                .expose(&self.state.root.api)
                .unwrap();
        }
        ProviderResult::Found(operation(&object))
    }
 }
 fn limits() -> Limits {
    Limits::new(65536, 65536, 64).unwrap()
 }
 fn reference(scope: &str) -> InterfaceReference {
    InterfaceReference {
        scope: scope.into(),
        name: "status".into(),
    }
 }
 fn handle(state: &State, path: &str, body: &[u8], visible: bool) -> http::Response<Vec<u8>> {
    let provider = Provider { state, visible };
    match path {
        "/wip/v1/observe" => {
            let request = decode_observe_request(body, limits()).unwrap();
            match provider.observe_object(&request.path) {
                Ok(object) => encode_observe_response(
                    &request,
                    &ObjectObservation {
                        object,
                        children: None,
                    },
                    limits(),
                )
                .unwrap(),
                Err(error) => encode_protocol_error_response(
                    ProtocolInteraction::Observe,
                    &error.protocol_error(),
                    limits(),
                )
                .unwrap(),
            }
        }
        "/wip/v1/fetch_interface" => {
            let request = decode_fetch_interface_request(body, limits()).unwrap();
            match provider.fetch_interface(&state.registry, &request.interface) {
                Ok(observation) => encode_fetch_interface_response(
                    &request,
                    &observation.protocol_response().unwrap(),
                    limits(),
                )
                .unwrap(),
                Err(error) => encode_protocol_error_response(
                    ProtocolInteraction::FetchInterface,
                    &error,
                    limits(),
                )
                .unwrap(),
            }
        }
        "/wip/v1/call_operation" => {
            let metadata = decode_call_operation_metadata(body, limits()).unwrap();
            let decoded = Mutex::new(None);
            let result = provider.call_operation_with_context_and_decoder(
                &ExecutionContext::default(),
                metadata.target.clone(),
                metadata.interface.clone(),
                metadata.operation.clone(),
                |descriptor| {
                    let request = metadata.decode_request(body, descriptor, limits())?;
                    let arguments = request.arguments.clone();
                    *decoded.lock().unwrap() = Some((request, descriptor.clone()));
                    Ok::<_, CodecError>(arguments)
                },
            );
            match result {
                Ok(result) => {
                    let (request, descriptor) = decoded.into_inner().unwrap().unwrap();
                    encode_call_operation_response(&request, &descriptor, &result, limits())
                        .unwrap()
                }
                Err(error) => encode_protocol_error_response(
                    ProtocolInteraction::CallOperation,
                    &error.protocol_error(),
                    limits(),
                )
                .unwrap(),
            }
        }
        _ => panic!("unexpected route {path}"),
    }
 }
 // Small bounded test-only HTTP/1.1 listener. Production serving is deliberately
 // not an example dependency; both directions still cross an actual TCP socket.
 fn exchange(
    state: &Arc<Mutex<State>>,
    request: http::Request<Vec<u8>>,
    visible: bool,
 ) -> http::Response<Vec<u8>> {
    let listener = TcpListener::bind("127.0.0.1:0").unwrap();
    let address = listener.local_addr().unwrap();
    let state = state.clone();
    let server = thread::spawn(move || {
        let (mut stream, _) = listener.accept().unwrap();
        stream
            .set_read_timeout(Some(Duration::from_secs(5)))
            .unwrap();
        let mut raw = Vec::new();
        let (split, length) = loop {
            let mut chunk = [0; 1024];
            let count = stream.read(&mut chunk).unwrap();
            assert!(count > 0);
            raw.extend_from_slice(&chunk[..count]);
            assert!(raw.len() <= 70000);
            if let Some(split) = raw.windows(4).position(|part| part == b"\r\n\r\n") {
                let head = std::str::from_utf8(&raw[..split]).unwrap();
                let length = head
                    .lines()
                    .find_map(|line| line.strip_prefix("Content-Length: "))
                    .unwrap()
                    .parse::<usize>()
                    .unwrap();
                if raw.len() >= split + 4 + length {
                    break (split, length);
                }
            }
        };
        let path = std::str::from_utf8(&raw[..split])
            .unwrap()
            .lines()
            .next()
            .unwrap()
            .split_whitespace()
            .nth(1)
            .unwrap();
        let response = handle(
            &state.lock().unwrap(),
            path,
            &raw[split + 4..split + 4 + length],
            visible,
        );
        write!(stream, "HTTP/1.1 {} OK\r\nConnection: close\r\nContent-Length: {}\r\nContent-Type: application/json\r\n\r\n", response.status().as_u16(), response.body().len()).unwrap();
        stream.write_all(response.body()).unwrap();
    });
    let mut stream = TcpStream::connect(address).unwrap();
    stream
        .set_read_timeout(Some(Duration::from_secs(5)))
        .unwrap();
    write!(stream, "POST {} HTTP/1.1\r\nHost: localhost\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n", request.uri().path(), request.body().len()).unwrap();
    stream.write_all(request.body()).unwrap();
    let mut raw = Vec::new();
    stream.read_to_end(&mut raw).unwrap();
    server.join().unwrap();
    let split = raw.windows(4).position(|part| part == b"\r\n\r\n").unwrap();
    let status = std::str::from_utf8(&raw[..split])
        .unwrap()
        .split_whitespace()
        .nth(1)
        .unwrap()
        .parse::<u16>()
        .unwrap();
    http::Response::builder()
        .status(status)
        .header("content-type", "application/json")
        .body(raw[split + 4..].to_vec())
        .unwrap()
 }
 fn setup() -> (Client, wip_client::SessionId) {
    let mut client = Client::new(ClientLimits::new(1, 16, 16, 16, 16).unwrap(), limits());
    let session = client
        .open_session("http://localhost/wip", SecurityContext::new("alice"))
        .unwrap();
    (client, session)
 }
 fn observe(
    client: &mut Client,
    session: &wip_client::SessionId,
    state: &Arc<Mutex<State>>,
    path: &str,
 ) {
    let request = client.refresh_object(session, path).unwrap();
    let response = exchange(state, request.request, true);
    client.complete(request.id, response).unwrap();
 }
 fn fetch(
    client: &mut Client,
    session: &wip_client::SessionId,
    state: &Arc<Mutex<State>>,
    reference: &InterfaceReference,
 ) {
    let request = client
        .prepare_interface(session, reference.clone())
        .unwrap();
    let body = std::str::from_utf8(request.request.body()).unwrap();
    assert!(body.contains("\"scope\""));
    assert!(body.contains("\"name\""));
    let response = exchange(state, request.request, true);
    assert!(matches!(
        client.complete(request.id, response).unwrap(),
        Completion::Interface(_)
    ));
 }
 #[test]
 fn real_http_root_self_same_name_and_optional_scope_refs() {
    for scope_ref in [Some("instance-a"), None] {
        let state = Arc::new(Mutex::new(State::new(scope_ref)));
        let (mut client, session) = setup();
        observe(&mut client, &session, &state, "/");
        let root = client.object(&session, "/").unwrap();
        assert_eq!(root.object.unwrap().name, "");
        observe(&mut client, &session, &state, "/service");
        for scope in ["/", "/service"] {
            let selected = reference(scope);
            fetch(&mut client, &session, &state, &selected);
            let observation = client.interface(&session, &selected).unwrap().clone();
            assert_eq!(
                observation.scope_ref.as_deref(),
                if scope == "/" { None } else { scope_ref }
            );
            let request = client
                .prepare_call(&session, "/service", &selected, "status", BTreeMap::new())
                .unwrap();
            let logical = decode_call_operation_request(
                request.request.body(),
                observation.descriptor.as_ref().unwrap(),
                limits(),
            )
            .unwrap();
            assert_eq!(logical.interface.reference, selected);
            assert_eq!(logical.interface.scope_ref, observation.scope_ref);
            let response = exchange(&state, request.request, true);
            assert!(matches!(
                client.complete(request.id, response).unwrap(),
                Completion::Call(record) if matches!(record.outcome, CallOutcome::Success(_))
            ));
        }
        assert_eq!(state.lock().unwrap().calls.load(Ordering::SeqCst), 2);
    }
 }
 #[test]
 fn stale_scope_republication_and_ref_less_replacement_require_explicit_calls() {
    let selected = reference("/service");
    let state = Arc::new(Mutex::new(State::new(Some("instance-a"))));
    let (mut client, session) = setup();
    observe(&mut client, &session, &state, "/service");
    fetch(&mut client, &session, &state, &selected);
    let request = client
        .prepare_call(&session, "/service", &selected, "status", BTreeMap::new())
        .unwrap();
    state.lock().unwrap().republish(Some("instance-b"));
    let response = exchange(&state, request.request, true);
    assert_eq!(response.status(), http::StatusCode::CONFLICT);
    assert!(matches!(client.complete(request.id, response).unwrap(),
        Completion::Call(record) if matches!(record.outcome,
            CallOutcome::ProtocolFailure(ref error) if error.code == ProtocolErrorCode::InterfaceMismatch)));
    assert_eq!(state.lock().unwrap().calls.load(Ordering::SeqCst), 0);
    assert_ne!(
        client.interface(&session, &selected).unwrap().state,
        ObservationState::Fresh
    );
    assert!(
        client
            .prepare_call(&session, "/service", &selected, "status", BTreeMap::new())
            .is_err()
    );
    observe(&mut client, &session, &state, "/service");
    fetch(&mut client, &session, &state, &selected);
    assert_eq!(
        client
            .interface(&session, &selected)
            .unwrap()
            .scope_ref
            .as_deref(),
        Some("instance-b")
    );
    assert_eq!(
        state.lock().unwrap().calls.load(Ordering::SeqCst),
        0,
        "re-observation is not execution"
    );
    state.lock().unwrap().remove();
    observe(&mut client, &session, &state, "/service");
    assert!(client.interface(&session, &selected).is_none());
    state.lock().unwrap().republish(None);
    observe(&mut client, &session, &state, "/service");
    fetch(&mut client, &session, &state, &selected);
    let request = client
        .prepare_call(&session, "/service", &selected, "status", BTreeMap::new())
        .unwrap();
    // Ref-less replacement is intentionally not identity-trackable. Current
    // membership, live publication and both validators still apply at dispatch.
    state.lock().unwrap().republish(None);
    let response = exchange(&state, request.request, true);
    client.complete(request.id, response).unwrap();
    assert_eq!(state.lock().unwrap().calls.load(Ordering::SeqCst), 1);
 }
 #[test]
 fn real_http_unknown_outcome_is_never_automatically_retried() {
    let state = Arc::new(Mutex::new(State::new(Some("instance-a"))));
    let (mut client, session) = setup();
    observe(&mut client, &session, &state, "/service");
    let selected = reference("/service");
    fetch(&mut client, &session, &state, &selected);
    let request = client
        .prepare_call(
            &session,
            "/service",
            &selected,
            "uncertain",
            BTreeMap::new(),
        )
        .unwrap();
    let response = exchange(&state, request.request, true);
    let completion = client.complete(request.id, response).unwrap();
    assert!(
        matches!(completion, Completion::Call(record) if matches!(record.outcome, CallOutcome::Unknown { .. }))
    );
    assert_eq!(client.in_flight_len(), 0);
    assert_eq!(state.lock().unwrap().calls.load(Ordering::SeqCst), 1);
    observe(&mut client, &session, &state, "/service");
    assert_eq!(state.lock().unwrap().calls.load(Ordering::SeqCst), 1);
 }
 #[test]
 fn principal_visibility_and_validator_precedence_cross_real_http() {
    let state = Arc::new(Mutex::new(State::new(Some("instance-a"))));
    let endpoint = Endpoint::parse("http://localhost/wip").unwrap();
    let selected = reference("/service");
    let fetch = wip_protocol::FetchInterfaceRequest {
        interface: selected.clone(),
    };
    let response = exchange(
        &state,
        encode_fetch_interface_request(&endpoint, &fetch, limits()).unwrap(),
        false,
    );
    assert!(
        matches!(decode_fetch_interface_response(&fetch, &response, limits()).unwrap(), DecodedResponse::ProtocolFailure { error, .. } if error.code == ProtocolErrorCode::InterfaceNotFound)
    );
    let descriptor = StatusDefinition::descriptor();
    let mut call = wip_protocol::CallOperationRequest {
        target: wip_protocol::Target {
            path: "/service".into(),
            validator: Some(b"stale-object".to_vec()),
        },
        interface: wip_protocol::InterfaceTarget {
            reference: selected,
            scope_ref: Some("stale-scope".into()),
            validator: Some(b"stale-api".to_vec()),
        },
        operation: "status".into(),
        arguments: BTreeMap::new(),
    };
    for (visible, object_validator, scope_ref, interface_validator, expected) in [
        (
            false,
            b"stale-object".as_slice(),
            Some("stale-scope"),
            Some(b"stale-api".as_slice()),
            ProtocolErrorCode::NotFound,
        ),
        (
            true,
            b"stale-object".as_slice(),
            Some("stale-scope"),
            Some(b"stale-api".as_slice()),
            ProtocolErrorCode::ValidatorMismatch,
        ),
        (
            true,
            b"object-v1".as_slice(),
            Some("stale-scope"),
            Some(b"stale-api".as_slice()),
            ProtocolErrorCode::InterfaceMismatch,
        ),
        (
            true,
            b"object-v1".as_slice(),
            Some("instance-a"),
            None,
            ProtocolErrorCode::InterfaceValidatorRequired,
        ),
        (
            true,
            b"object-v1".as_slice(),
            None,
            Some(b"stale-api".as_slice()),
            ProtocolErrorCode::InterfaceValidatorMismatch,
        ),
    ] {
        call.target.validator = Some(object_validator.to_vec());
        call.interface.scope_ref = scope_ref.map(str::to_owned);
        call.interface.validator = interface_validator.map(<[u8]>::to_vec);
        let response = exchange(
            &state,
            encode_call_operation_request(&endpoint, &call, &descriptor, limits()).unwrap(),
            visible,
        );
        assert!(
            matches!(decode_call_operation_response(&call, &descriptor, &response, limits()).unwrap(), DecodedResponse::ProtocolFailure { error, .. } if error.code == expected)
        );
    }
    assert_eq!(state.lock().unwrap().calls.load(Ordering::SeqCst), 0);
 }
@@ -0,0 +1,13 @@
 [package]
 name = "wip-text-view"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 description = "Standalone Object and Interface Text View signatures for WIP"
 license.workspace = true
 repository.workspace = true
 readme = "README.md"
 documentation = "https://docs.rs/wip-text-view"
 [dependencies]
 wip-protocol.workspace = true
@@ -0,0 +1,193 @@
 # wip-text-view
 Standalone Object and Interface signature rendering for WIP Text View, following
 `4.2-text-view.md` at reference revision `6086f3c` and the Protocol semantics in
 `3-protocol.md`. Only `wip-protocol` and the Rust standard library are dependencies.
 No Client, Host, HTTP I/O, cache, UI framework or retrieval service is required.
 ```toml
 [dependencies]
 wip-text-view = "0.2.0"
 wip-protocol = "0.2.0"
 ```
 ## Single-entity API
 ```rust
 use wip_protocol::{Object, InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
 use wip_text_view::{Interface, render_object, render_interface};
 let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
 let object = Object {
    name: "item".into(), description: None, interfaces: vec![reference.clone()],
    r#ref: None, validator: None,
 };
 let object_signature = render_object(&object)?;
 assert_eq!(object_signature,
    "object {\n  name: \"item\";\n  interfaces: [\"/::example\"];\n}\n");
 let descriptor = InterfaceDescriptor {
    format: INTERFACE_FORMAT_V1.into(), documentation: None,
    types: vec![], operations: vec![],
 };
 let interface = Interface { reference: &reference, descriptor: &descriptor };
 let interface_signature = render_interface(&interface)?;
 assert_eq!(interface_signature, "interface \"/::example\" {\n}\n");
 # Ok::<(), wip_text_view::RenderError>(())
 ```
 `Interface<'a>` is one borrowed SDK input entity containing a complete structured
 reference and its corresponding descriptor, not a wire schema extension. The
 caller pairs them from a coherent observation or publication. The descriptor has
 no identity, so a renderer cannot prove the pairing's provenance or freshness.
 For example, a caller with a validated `FetchInterfaceResponse` can borrow its
 `interface` and `descriptor`; it does not pass `scope_ref` or validators.
 An Object has no placement path. This API always emits `object { ... }`, never
 requests a path and never infers one from name or ref. It requires no descriptor.
 An Interface needs no Object, separate name/scope/context arguments or lookup.
 There is no document aggregator, configuration or details selector.
 ## Typed display tokens
 ```rust
 use wip_protocol::{Object, InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
 use wip_text_view::{
    Interface, TokenKind, tokenize_object, tokenize_interface, to_plain_text,
    render_object, render_interface,
 };
 let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
 let object = Object {
    name: "item".into(), description: None, interfaces: vec![reference.clone()],
    r#ref: None, validator: None,
 };
 let object_tokens = tokenize_object(&object)?;
 assert_eq!(object_tokens[0].kind(), TokenKind::Keyword);
 assert_eq!(object_tokens[0].text(), "object");
 assert_eq!(to_plain_text(&object_tokens), render_object(&object)?);
 let descriptor = InterfaceDescriptor {
    format: INTERFACE_FORMAT_V1.into(), documentation: None,
    types: vec![], operations: vec![],
 };
 let input = Interface { reference: &reference, descriptor: &descriptor };
 let tokens = tokenize_interface(&input)?;
 for token in &tokens {
    // Custom renderers can select presentation by role without reparsing text.
    if token.kind() == TokenKind::Reference {
        assert_eq!(token.text(), "\"/::example\"");
    }
 }
 let joined: String = tokens.iter().map(|token| token.text()).collect();
 assert_eq!(to_plain_text(&tokens), joined);
 assert_eq!(to_plain_text(&tokens), render_interface(&input)?);
 # Ok::<(), wip_text_view::RenderError>(())
 ```
 `tokenize_object` / `tokenize_interface` return `Result<Vec<Token>, RenderError>`.
 They generate **directly from the input structure**, not by lexing a completed
 Text View string. Each token owns its text (and can outlive the input) and exposes
 `kind()` / `text()`. Existing render APIs use the same token generation followed
 by `to_plain_text(&[Token])`; there is no second grammar/escape/layout engine.
 ### Kind and splitting contract
 | Kind | One token contains |
 | --- | --- |
 | `Keyword` | One grammar keyword, Object property label, or primitive type keyword |
 | `TypeName` | One type declaration name or Named type reference |
 | `OperationName` | One Operation declaration name |
 | `ParameterName` / `FieldName` | One parameter / record field name |
 | `CaseName` | One enum or union case name |
 | `String` | One complete quoted Object name or description |
 | `Reference` | One complete quoted absolute Interface reference, with both quoting layers |
 | `Documentation` | Entire `/// "summary"` content, including marker and internal space, excluding indentation/LF |
 | `Symbol` | One punctuation mark, except the indivisible two-character `->` arrow |
 | `Whitespace` | One inter-token ASCII space |
 | `Newline` | One LF, including the final LF |
 | `Indentation` | All leading spaces of a non-root line, two spaces per depth level |
 Quoted identifiers retain their semantic role even when named like keywords.
 Quotes, backticks and all WIP escapes are part of the data token, never separate
 symbols. Host spaces inside quoted data remain in that token. Adjacent symbols
 are separate; no empty tokens or zero-depth indentation tokens are emitted.
 `TokenKind` is non-exhaustive so consumers should handle future roles with a
 fallback. The API does not distinguish type declaration names from Named uses,
 or enum cases from union cases; both share the documented role.
 All layout is included. Concatenate token text **without separators**, not with
 `join(" ")`. `to_plain_text` is only that concatenation: no interpretation,
 validation, quoting, escaping or layout completion. An empty slice yields `""`;
 a filtered/reordered slice is allowed but need not be a complete signature.
 Token text is escaped for **WIP Text View**, not for HTML or other destinations.
 Custom renderers must escape for their destination and treat Host text as data,
 not markup or instructions. This crate supplies no HTML, ANSI, color or theme
 renderer/adapter and no external text lexer/parser or AST.
 ## Output and validation
 - UTF-8 plain text with LF, two-space indentation and a final LF, without ANSI,
  Markdown fences, syntax highlighting or provider envelopes. Nonempty composites
  and parameter lists use multiple lines; layout is deterministic here, but not a
  byte-canonical protocol format.
 - All Object references remain in Host order. All types, then all operations,
  fields, parameters and cases remain in declaration order, without elision.
 - Missing vs empty description/documentation, optional vs unit, no payload vs
  unit payload, and empty record/enum/union/declaration sets remain distinct.
 - Full absolute references use component quoting **and** outer JSON-string quoting.
  Identifiers use keywords/backtick rules. All Host strings use standard JSON
  escapes plus DEL/C1, Unicode line/paragraph separator and bidi-control escapes.
  No normalization, case conversion, URL encoding or input mutation occurs.
 - Documentation summaries are displayed in their prescribed positions, including
  return documentation between `)` and `->`. Details are not displayed. Host text
  is data, not renderer instructions or markup; quoting alone is not a prompt
  injection defense. AI adapters must preserve the trust boundary.
 - Object ref/validator, children, domain data and Interface scope_ref/validator
  are not signature content. No annotations are inferred from operation names.
 The render functions return `Result<String, RenderError>`; token generation
 returns `Result<Vec<Token>, RenderError>`. Neither returns partial signatures. Resource checks happen first, followed by existing Protocol validators:
 Object shape and reference uniqueness, or Interface reference shape plus descriptor
 structure, duplicate names, unknown Named references and cycles. Descriptor format
 is checked after semantics: valid but unsupported formats return
 `UnsupportedDescriptorFormat`, distinct from `InvalidDescriptor`. Supported format
 is exactly `wip-interface/1`. Other validation errors preserve the Protocol's typed
 `ValidationError` (also exposed as the error source).
 Bounded input limits are **1 MiB** of total string/opaque byte data, **16,384**
 declarations/fields/parameters/cases/type expressions/references, **256** named type
 declarations, and **64** TypeExpr nesting levels. Details and Object runtime
 metadata count toward input bytes even though they are not rendered. A limit
 returns `RenderError::ResourceLimit`, never truncates or supplies `...`. Counts
 bound allocation and recursive validation before those validators run; these are
 library safety limits, not Protocol restrictions.
 Without path/context, this library cannot attest Object scope ancestry, placement,
 observation consistency, identity, membership, authorization or currentness.
 Callers validate those at their observation boundary. Callers also own retrieval,
 resolution, cache, selection, multiple-signature arrangement and AI/UI adaptation.
 Text is display-only, not serialization, a digest, identity/cache key or call
 target. No parser or round-trip API is supplied.
 ## Validation
 `tests/signatures.rs` is an external consumer of the public APIs. Goldens cover
 the spec's Object, issue.read, CloseResult, search/return documentation and
 identifier examples (with permitted multiline layout), plus nested documentation.
 The suite checks all TypeExpr variants/positions, ordering and empty distinctions,
 keyword and Unicode names, both reference quoting layers, all required control
 escapes, input immutability, metadata exclusion and typed rejection cases. Every
 existing case compares the render result (including exact errors) with token
 text concatenation and `to_plain_text`. Additional tests assert complete Object
 token splitting, all semantic roles, keyword collisions, atomic escaped data,
 all documentation positions, layout tokens and ownership beyond input lifetime.
 Input budgets bound token counts per node, indentation depth and escape expansion;
 token generation checks them before any rendering/validation traversal.
 ```console
 cargo test -p wip-text-view
 cargo clippy -p wip-text-view --all-targets -- -D warnings
 RUSTDOCFLAGS='-D warnings' cargo doc -p wip-text-view --no-deps
 ```
@@ -0,0 +1,221 @@
 //! Standalone, single-entity WIP Text View signatures.
 //!
 //! [`render_object`] accepts just an [`Object`], and [`render_interface`] accepts
 //! just an [`Interface`] (a reference paired with its corresponding descriptor).
 //! No Client, Host, HTTP, UI, retrieval, cache, path or display context is needed.
 //! The caller supplies a coherent observation; descriptor identity cannot be
 //! inferred from descriptor contents. No protocol wire fields are added.
 //!
 //! Output follows WIP `4.2-text-view.md` (reference revision `6086f3c`): UTF-8
 //! plain text, LF, two-space indentation, all declarations in original order,
 //! and documentation summaries only. There is no truncation or details setting.
 //! Object paths are neither requested nor guessed: output uses `object { ... }`.
 //! Runtime metadata is never rendered. Host documentation is untrusted data,
 //! not markup or instructions; quoting does not by itself prevent prompt injection.
 //!
 //! Each call checks resource limits, then Protocol shape/semantic validation.
 //! Interface rendering additionally requires [`wip_protocol::INTERFACE_FORMAT_V1`].
 //! Limits reject the entire input, never produce partial text: at most 1 MiB of
 //! input string/byte data, 16,384 declarations/fields/cases/type expressions or
 //! references, 256 named type declarations (bounding validator graph recursion),
 //! and 64 nested TypeExpr levels. These are implementation limits, not new
 //! Protocol semantics. An Object without placement context can only be checked
 //! for name/reference shape and duplicate references; the caller must validate
 //! scope ancestry and observation consistency at its observation boundary.
 //!
 //! Signatures are display-only: no parser, round-trip, identity comparison,
 //! cache key or call-target reconstruction is provided. The caller owns fetching,
 //! freshness, authorization, selection and arrangement of multiple signatures.
 //!
 //! ```
 //! use wip_protocol::{Object, InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
 //! use wip_text_view::{Interface, render_object, render_interface};
 //! let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
 //! let object = Object {
 //!     name: "item".into(), description: None, interfaces: vec![reference.clone()],
 //!     r#ref: Some("not a path".into()), validator: Some(vec![1]),
 //! };
 //! assert_eq!(render_object(&object)?,
 //!     "object {\n  name: \"item\";\n  interfaces: [\"/::example\"];\n}\n");
 //! let descriptor = InterfaceDescriptor {
 //!     format: INTERFACE_FORMAT_V1.into(), documentation: None,
 //!     types: vec![], operations: vec![],
 //! };
 //! let interface = Interface { reference: &reference, descriptor: &descriptor };
 //! assert_eq!(render_interface(&interface)?, "interface \"/::example\" {\n}\n");
 //! # Ok::<(), wip_text_view::RenderError>(())
 //! ```
 //!
 //! # Typed display tokens
 //!
 //! [`tokenize_object`] and [`tokenize_interface`] traverse the input structure
 //! directly and return owned [`Token`] sequences, including all layout. Existing
 //! render APIs use this same generation path followed by [`to_plain_text`]. The
 //! input limits above also bound token allocation: tokens per node, indentation
 //! depth and escape expansion are bounded; no partial signature is returned.
 //! Token text is WIP-escaped, **not HTML-escaped** or escaped for other destinations.
 //! See [`Token`] for the semantic splitting contract; no renderer/theme is supplied.
 //!
 //! ```
 //! use wip_protocol::{InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
 //! use wip_text_view::{Interface, TokenKind, tokenize_interface, to_plain_text, render_interface};
 //! let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
 //! let descriptor = InterfaceDescriptor {
 //!     format: INTERFACE_FORMAT_V1.into(), documentation: None,
 //!     types: vec![], operations: vec![],
 //! };
 //! let input = Interface { reference: &reference, descriptor: &descriptor };
 //! let tokens = tokenize_interface(&input)?;
 //! assert_eq!(tokens[0].kind(), TokenKind::Keyword);
 //! assert_eq!(tokens[0].text(), "interface");
 //! let concatenated: String = tokens.iter().map(|token| token.text()).collect();
 //! assert_eq!(to_plain_text(&tokens), concatenated);
 //! assert_eq!(to_plain_text(&tokens), render_interface(&input)?);
 //! # Ok::<(), wip_text_view::RenderError>(())
 //! ```
 #![deny(missing_docs)]
 mod limits;
 mod render;
 mod token;
 pub use token::{Token, TokenKind, to_plain_text};
 use std::{error::Error, fmt};
 use wip_protocol::{
    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceReference, Object, ValidationError,
 };
 /// One Interface input entity, borrowing its identity and corresponding data.
 ///
 /// The caller pairs values from the same observation/publication. The descriptor
 /// itself has no identity, so rendering cannot verify provenance or freshness.
 /// This is an SDK display input, not a replacement wire schema or a document.
 #[derive(Debug, Clone, Copy)]
 pub struct Interface<'a> {
    /// Complete, absolute, Client-facing Interface reference.
    pub reference: &'a InterfaceReference,
    /// Descriptor corresponding to `reference`.
    pub descriptor: &'a InterfaceDescriptor,
 }
 /// Failure to render a complete, validated signature. No partial text is returned.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum RenderError {
    /// Object-independent Protocol validation failed.
    InvalidObject(ValidationError),
    /// The Interface's structured reference is malformed.
    InvalidReference(ValidationError),
    /// Descriptor structure or semantics failed Protocol validation.
    InvalidDescriptor(ValidationError),
    /// A semantically valid descriptor uses a format this renderer cannot interpret.
    UnsupportedDescriptorFormat {
        /// Exact unsupported format identifier.
        format: String,
    },
    /// Input exceeds an implementation safety limit, without truncation.
    ResourceLimit {
        /// Limit that was exceeded.
        limit: ResourceLimit,
    },
 }
 /// Bounded input dimensions checked before recursive Protocol validation.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ResourceLimit {
    /// Total input string and opaque byte length exceeds 1 MiB.
    InputBytes,
    /// Total declarations, fields, parameters, cases, expressions or references exceeds 16,384.
    Nodes,
    /// More than 256 named type declarations.
    TypeDeclarations,
    /// More than 64 nested TypeExpr levels (outer expression is level one).
    TypeDepth,
 }
 impl fmt::Display for RenderError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::InvalidObject(e) => write!(f, "invalid Object: {e}"),
            Self::InvalidReference(e) => write!(f, "invalid Interface reference: {e}"),
            Self::InvalidDescriptor(e) => write!(f, "invalid Interface descriptor: {e}"),
            Self::UnsupportedDescriptorFormat { format } => {
                write!(f, "unsupported descriptor format: {format:?}")
            }
            Self::ResourceLimit { limit } => write!(f, "Text View input exceeds {limit:?} limit"),
        }
    }
 }
 impl Error for RenderError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            Self::InvalidObject(e) | Self::InvalidReference(e) | Self::InvalidDescriptor(e) => {
                Some(e)
            }
            _ => None,
        }
    }
 }
 /// Renders one complete Object signature, with no placement path or inferred data.
 ///
 /// Validates shape and ordered-set uniqueness, but cannot validate ancestry or
 /// root/non-root placement without context. Missing and empty descriptions remain
 /// distinct; ref and validator bytes are ignored for display. Input is unmodified.
 /// See [crate documentation](crate) for limits and caller responsibilities.
 pub fn render_object(object: &Object) -> Result<String, RenderError> {
    tokenize_object(object).map(|tokens| to_plain_text(&tokens))
 }
 /// Generates the complete owned display token sequence for one Object signature.
 ///
 /// Uses the same validation, limits, metadata exclusion and caller responsibilities
 /// as [`render_object`]. No partial sequence is returned on error. Input is not
 /// modified. See [`Token`] and [`TokenKind`] for semantic roles and splitting.
 pub fn tokenize_object(object: &Object) -> Result<Vec<Token>, RenderError> {
    limits::object(object)?;
    object.validate().map_err(RenderError::InvalidObject)?;
    Ok(render::object(object))
 }
 /// Renders one complete Interface signature from one paired input entity.
 ///
 /// Validates reference shape and all descriptor declarations/named references,
 /// including cycles, before checking format support. No lookup or Object is
 /// needed. All types precede all operations, with original member order; only
 /// documentation summaries are shown, without interpreting Host text.
 /// Input is unmodified. See [crate documentation](crate) for safety limits.
 pub fn render_interface(interface: &Interface<'_>) -> Result<String, RenderError> {
    tokenize_interface(interface).map(|tokens| to_plain_text(&tokens))
 }
 /// Generates the complete owned display token sequence for one Interface signature.
 ///
 /// Uses the same validation, limits, format support and summary-only documentation
 /// as [`render_interface`]. No partial sequence is returned on error. Input is not
 /// modified. See [`Token`] and [`TokenKind`] for semantic roles and splitting.
 /// This traverses structured declarations directly, not a rendered-text lexer.
 pub fn tokenize_interface(interface: &Interface<'_>) -> Result<Vec<Token>, RenderError> {
    limits::interface(interface)?;
    interface
        .reference
        .validate()
        .map_err(RenderError::InvalidReference)?;
    interface
        .descriptor
        .validate()
        .map_err(RenderError::InvalidDescriptor)?;
    if interface.descriptor.format != INTERFACE_FORMAT_V1 {
        return Err(RenderError::UnsupportedDescriptorFormat {
            format: interface.descriptor.format.clone(),
        });
    }
    Ok(render::interface(interface))
 }
 // Keep both README examples executable as external-consumer doctests.
 #[cfg(doctest)]
 #[doc = include_str!("../README.md")]
 mod readme {}
@@ -0,0 +1,125 @@
 use wip_protocol::{Documentation, InterfaceReference, Object, TypeExpr};
 use crate::{Interface, RenderError, ResourceLimit};
 #[derive(Default)]
 struct Budget {
    bytes: usize,
    nodes: usize,
 }
 fn check(value: usize, max: usize, limit: ResourceLimit) -> Result<(), RenderError> {
    if value > max {
        Err(RenderError::ResourceLimit { limit })
    } else {
        Ok(())
    }
 }
 impl Budget {
    fn bytes(&mut self, len: usize) -> Result<(), RenderError> {
        self.bytes = self.bytes.saturating_add(len);
        check(self.bytes, 1024 * 1024, ResourceLimit::InputBytes)
    }
    fn nodes(&mut self, len: usize) -> Result<(), RenderError> {
        self.nodes = self.nodes.saturating_add(len);
        check(self.nodes, 16_384, ResourceLimit::Nodes)
    }
    fn reference(&mut self, reference: &InterfaceReference) -> Result<(), RenderError> {
        self.nodes(1)?;
        self.bytes(reference.scope.len())?;
        self.bytes(reference.name.len())
    }
    fn doc(&mut self, doc: &Option<Documentation>) -> Result<(), RenderError> {
        if let Some(doc) = doc {
            self.bytes(doc.summary.len())?;
            self.bytes(doc.details.as_ref().map_or(0, String::len))?;
        }
        Ok(())
    }
    fn declaration(&mut self, name: &str, doc: &Option<Documentation>) -> Result<(), RenderError> {
        self.nodes(1)?;
        self.bytes(name.len())?;
        self.doc(doc)
    }
    fn expr(&mut self, expr: &TypeExpr, depth: usize) -> Result<(), RenderError> {
        check(depth, 64, ResourceLimit::TypeDepth)?;
        self.nodes(1)?;
        match expr {
            TypeExpr::Named { name } => self.bytes(name.len())?,
            TypeExpr::List { items } => self.expr(items, depth + 1)?,
            TypeExpr::Record { fields } => {
                self.nodes(fields.len())?;
                for field in fields {
                    self.bytes(field.name.len())?;
                    self.doc(&field.documentation)?;
                    self.expr(&field.r#type, depth + 1)?;
                }
            }
            TypeExpr::Enum { cases } => {
                self.nodes(cases.len())?;
                for case in cases {
                    self.bytes(case.name.len())?;
                    self.doc(&case.documentation)?;
                }
            }
            TypeExpr::Union { cases } => {
                self.nodes(cases.len())?;
                for case in cases {
                    self.bytes(case.name.len())?;
                    self.doc(&case.documentation)?;
                    if let Some(payload) = &case.payload {
                        self.expr(payload, depth + 1)?;
                    }
                }
            }
            _ => {}
        }
        Ok(())
    }
 }
 pub(crate) fn object(object: &Object) -> Result<(), RenderError> {
    let mut budget = Budget::default();
    budget.bytes(object.name.len())?;
    budget.bytes(object.description.as_ref().map_or(0, String::len))?;
    budget.bytes(object.r#ref.as_ref().map_or(0, String::len))?;
    budget.bytes(object.validator.as_ref().map_or(0, Vec::len))?;
    check(object.interfaces.len(), 16_384, ResourceLimit::Nodes)?;
    for reference in &object.interfaces {
        budget.reference(reference)?;
    }
    Ok(())
 }
 pub(crate) fn interface(interface: &Interface<'_>) -> Result<(), RenderError> {
    let mut budget = Budget::default();
    let descriptor = interface.descriptor;
    budget.reference(interface.reference)?;
    budget.bytes(descriptor.format.len())?;
    budget.doc(&descriptor.documentation)?;
    check(descriptor.types.len(), 256, ResourceLimit::TypeDeclarations)?;
    // Check collection counts before traversing even empty names/expressions.
    check(descriptor.operations.len(), 16_384, ResourceLimit::Nodes)?;
    for ty in &descriptor.types {
        budget.declaration(&ty.name, &ty.documentation)?;
        budget.expr(&ty.definition, 1)?;
    }
    for operation in &descriptor.operations {
        budget.declaration(&operation.name, &operation.documentation)?;
        check(operation.parameters.len(), 16_384, ResourceLimit::Nodes)?;
        for parameter in &operation.parameters {
            budget.declaration(&parameter.name, &parameter.documentation)?;
            budget.expr(&parameter.r#type, 1)?;
        }
        budget.nodes(1)?; // Return declaration.
        budget.doc(&operation.returns.documentation)?;
        budget.expr(&operation.returns.r#type, 1)?;
    }
    Ok(())
 }
@@ -0,0 +1,334 @@
 use std::fmt::Write as _;
 use wip_protocol::{Documentation, InterfaceReference, Object, OperationDeclaration, TypeExpr};
 use crate::{Interface, Token, TokenKind};
 use TokenKind::{
    CaseName, FieldName, Indentation, Keyword, Newline, OperationName, ParameterName, Reference,
    Symbol, TypeName, Whitespace,
 };
 // Quoting a component and quoting the complete reference are separate layers.
 fn reference(reference: &InterfaceReference) -> String {
    format!(
        "{}::{}",
        component(&reference.scope, true),
        component(&reference.name, false)
    )
 }
 fn component(value: &str, scope: bool) -> String {
    if !value.is_empty()
        && value
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || b"_.-".contains(&b) || (scope && b == b'/'))
    {
        value.into()
    } else {
        quote(value, '"')
    }
 }
 fn identifier(value: &str) -> String {
    const KEYWORDS: &[&str] = &[
        "object",
        "at",
        "name",
        "description",
        "interfaces",
        "interface",
        "type",
        "operation",
        "enum",
        "union",
        "unit",
        "boolean",
        "integer",
        "number",
        "string",
        "bytes",
        "json",
        "entry",
    ];
    if value
        .bytes()
        .next()
        .is_some_and(|b| b.is_ascii_alphabetic() || b == b'_')
        && value
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || b == b'_')
        && !KEYWORDS.contains(&value)
    {
        value.into()
    } else {
        quote(value, '`')
    }
 }
 fn quote(value: &str, delimiter: char) -> String {
    let mut output = String::new();
    output.push(delimiter);
    for ch in value.chars() {
        match ch {
            '`' if delimiter == '`' => output.push_str("\\`"),
            '\\' => output.push_str("\\\\"),
            '"' => output.push_str("\\\""),
            '\u{08}' => output.push_str("\\b"),
            '\u{0c}' => output.push_str("\\f"),
            '\n' => output.push_str("\\n"),
            '\r' => output.push_str("\\r"),
            '\t' => output.push_str("\\t"),
            '\u{00}'..='\u{1f}'
            | '\u{7f}'..='\u{9f}'
            | '\u{2028}'
            | '\u{2029}'
            | '\u{061c}'
            | '\u{200e}'..='\u{200f}'
            | '\u{202a}'..='\u{202e}'
            | '\u{2066}'..='\u{2069}' => {
                write!(output, "\\u{:04x}", ch as u32).expect("String write");
            }
            _ => output.push(ch),
        }
    }
    output.push(delimiter);
    output
 }
 pub(crate) fn object(object: &Object) -> Vec<Token> {
    let mut writer = Writer(Vec::new());
    writer.word(Keyword, "object");
    writer.space();
    writer.symbol("{");
    writer.newline();
    writer.indent(1);
    writer.word(Keyword, "name");
    writer.symbol(":");
    writer.space();
    writer.word(TokenKind::String, quote(&object.name, '"'));
    writer.symbol(";");
    writer.newline();
    if let Some(description) = &object.description {
        writer.indent(1);
        writer.word(Keyword, "description");
        writer.symbol(":");
        writer.space();
        writer.word(TokenKind::String, quote(description, '"'));
        writer.symbol(";");
        writer.newline();
    }
    writer.indent(1);
    writer.word(Keyword, "interfaces");
    writer.symbol(":");
    writer.space();
    writer.symbol("[");
    for (index, interface) in object.interfaces.iter().enumerate() {
        if index > 0 {
            writer.symbol(",");
            writer.space();
        }
        writer.word(Reference, quote(&reference(interface), '"'));
    }
    writer.symbol("]");
    writer.symbol(";");
    writer.newline();
    writer.symbol("}");
    writer.newline();
    writer.0
 }
 pub(crate) fn interface(interface: &Interface<'_>) -> Vec<Token> {
    let mut writer = Writer(Vec::new());
    writer.doc(&interface.descriptor.documentation, 0);
    writer.word(Keyword, "interface");
    writer.space();
    writer.word(Reference, quote(&reference(interface.reference), '"'));
    writer.space();
    writer.symbol("{");
    writer.newline();
    for declaration in &interface.descriptor.types {
        writer.doc(&declaration.documentation, 1);
        writer.indent(1);
        writer.word(Keyword, "type");
        writer.space();
        writer.word(TypeName, identifier(&declaration.name));
        writer.space();
        writer.symbol("=");
        writer.space();
        writer.expr(&declaration.definition, 1);
        writer.symbol(";");
        writer.newline();
    }
    for operation in &interface.descriptor.operations {
        writer.operation(operation);
    }
    writer.symbol("}");
    writer.newline();
    writer.0
 }
 struct Writer(Vec<Token>);
 impl Writer {
    fn word(&mut self, kind: TokenKind, text: impl Into<String>) {
        self.0.push(Token {
            kind,
            text: text.into(),
        });
    }
    fn symbol(&mut self, text: &str) {
        self.word(Symbol, text);
    }
    fn space(&mut self) {
        self.word(Whitespace, " ");
    }
    fn newline(&mut self) {
        self.word(Newline, "\n");
    }
    fn indent(&mut self, depth: usize) {
        if depth > 0 {
            self.word(Indentation, "  ".repeat(depth));
        }
    }
    fn doc(&mut self, doc: &Option<Documentation>, depth: usize) {
        if let Some(doc) = doc {
            self.indent(depth);
            self.word(
                TokenKind::Documentation,
                format!("/// {}", quote(&doc.summary, '"')),
            );
            self.newline();
        }
    }
    fn member(&mut self, kind: TokenKind, name: &str, required: bool, ty: &TypeExpr, depth: usize) {
        self.indent(depth);
        self.word(kind, identifier(name));
        if !required {
            self.symbol("?");
        }
        self.symbol(":");
        self.space();
        self.expr(ty, depth);
        self.symbol(",");
        self.newline();
    }
    fn operation(&mut self, operation: &OperationDeclaration) {
        self.doc(&operation.documentation, 1);
        self.indent(1);
        self.word(Keyword, "operation");
        self.space();
        self.word(OperationName, identifier(&operation.name));
        self.symbol("(");
        if !operation.parameters.is_empty() {
            self.newline();
            for parameter in &operation.parameters {
                self.doc(&parameter.documentation, 2);
                self.member(
                    ParameterName,
                    &parameter.name,
                    parameter.required,
                    &parameter.r#type,
                    2,
                );
            }
            self.indent(1);
        }
        self.symbol(")");
        if operation.returns.documentation.is_some() {
            self.newline();
            self.doc(&operation.returns.documentation, 1);
            self.indent(1);
        } else {
            self.space();
        }
        self.symbol("->");
        self.space();
        self.expr(&operation.returns.r#type, 1);
        self.symbol(";");
        self.newline();
    }
    // Starts at the current cursor. Composite closing braces align with the
    // declaration/field/parameter containing this expression, not its width.
    fn expr(&mut self, expr: &TypeExpr, depth: usize) {
        match expr {
            TypeExpr::Unit => self.word(Keyword, "unit"),
            TypeExpr::Boolean => self.word(Keyword, "boolean"),
            TypeExpr::Integer => self.word(Keyword, "integer"),
            TypeExpr::Number => self.word(Keyword, "number"),
            TypeExpr::String => self.word(Keyword, "string"),
            TypeExpr::Bytes => self.word(Keyword, "bytes"),
            TypeExpr::Json => self.word(Keyword, "json"),
            TypeExpr::Entry => self.word(Keyword, "entry"),
            TypeExpr::Named { name } => self.word(TypeName, identifier(name)),
            TypeExpr::List { items } => {
                self.symbol("[");
                self.expr(items, depth);
                self.symbol("]");
            }
            TypeExpr::Record { fields } => {
                self.symbol("{");
                if !fields.is_empty() {
                    self.newline();
                    for field in fields {
                        self.doc(&field.documentation, depth + 1);
                        self.member(
                            FieldName,
                            &field.name,
                            field.required,
                            &field.r#type,
                            depth + 1,
                        );
                    }
                    self.indent(depth);
                }
                self.symbol("}");
            }
            TypeExpr::Enum { cases } => {
                self.word(Keyword, "enum");
                self.space();
                self.symbol("{");
                if !cases.is_empty() {
                    self.newline();
                    for case in cases {
                        self.doc(&case.documentation, depth + 1);
                        self.indent(depth + 1);
                        self.word(CaseName, identifier(&case.name));
                        self.symbol(",");
                        self.newline();
                    }
                    self.indent(depth);
                }
                self.symbol("}");
            }
            TypeExpr::Union { cases } => {
                self.word(Keyword, "union");
                self.space();
                self.symbol("{");
                if !cases.is_empty() {
                    self.newline();
                    for case in cases {
                        self.doc(&case.documentation, depth + 1);
                        self.indent(depth + 1);
                        self.word(CaseName, identifier(&case.name));
                        if let Some(payload) = &case.payload {
                            self.symbol("(");
                            self.expr(payload, depth + 1);
                            self.symbol(")");
                        }
                        self.symbol(",");
                        self.newline();
                    }
                    self.indent(depth);
                }
                self.symbol("}");
            }
        }
    }
 }
@@ -0,0 +1,84 @@
 //! Owned display data, independent of the Protocol wire model.
 /// Semantic display role assigned from the input structure, not from text parsing.
 ///
 /// Identifiers retain their role even when quoted or identical to a keyword.
 /// Type declarations and Named expressions both use [`Self::TypeName`]. Enum and
 /// union cases both use [`Self::CaseName`]. See [`Token`] for splitting rules.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 #[non_exhaustive]
 pub enum TokenKind {
    /// Grammar keyword, including Object property labels and primitive types.
    Keyword,
    /// Named type declaration or reference within the same Interface.
    TypeName,
    /// Operation declaration name (not an invocation target).
    OperationName,
    /// Operation parameter name.
    ParameterName,
    /// Record field name.
    FieldName,
    /// Enum or union case name.
    CaseName,
    /// Quoted Object name or description.
    String,
    /// Entire quoted absolute Interface reference, including both quoting layers.
    Reference,
    /// Entire `/// "summary"` line content, excluding indentation and LF.
    Documentation,
    /// One punctuation mark, or the complete two-character return arrow `->`.
    Symbol,
    /// One inter-token ASCII space, never indentation or text inside quotes.
    Whitespace,
    /// One LF (`\n`), including the final signature LF.
    Newline,
    /// All leading spaces on a non-root line: two ASCII spaces per depth level.
    Indentation,
 }
 /// One owned, already escaped fragment of a Text View signature.
 ///
 /// Each keyword, identifier, quoted string and complete quoted reference is one
 /// token, including its delimiters and escapes. Documentation is one token for
 /// the `///` marker, space and quoted summary together. Symbols are individual
 /// punctuation marks except `->`, which is indivisible. Spaces between tokens,
 /// each LF, and each nonzero line indentation have separate tokens. No empty
 /// tokens are emitted; an empty value still has its quotes. Adjacent symbols are
 /// not merged. Host whitespace inside quoted data stays inside that data token.
 ///
 /// The generation APIs emit all layout: concatenating [`Self::text`] in order,
 /// without separators, produces exactly the existing plain-text signature.
 /// Tokens own their text and can outlive the input; they are display data, not
 /// an AST, lexer output, Protocol serialization or identity/call-target data.
 ///
 /// Text is escaped for **WIP Text View**, not for HTML or any other destination.
 /// Custom renderers must apply destination-specific escaping and must not treat
 /// Host documentation as markup or instructions.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Token {
    pub(crate) kind: TokenKind,
    pub(crate) text: String,
 }
 impl Token {
    /// Returns the semantic display role, without reparsing the output text.
    pub fn kind(&self) -> TokenKind {
        self.kind
    }
    /// Returns the exact output fragment, with WIP quoting and escapes applied.
    pub fn text(&self) -> &str {
        &self.text
    }
 }
 /// Concatenates token text in order, with no separators or further processing.
 ///
 /// This performs no grammar interpretation, validation, quoting, escaping or
 /// layout completion. An empty slice yields an empty string. Filtering or
 /// reordering tokens is allowed, but need not produce a complete signature.
 /// Object/Interface generation limits are checked by [`crate::tokenize_object`]
 /// and [`crate::tokenize_interface`], not by this concatenation function.
 pub fn to_plain_text(tokens: &[Token]) -> String {
    tokens.iter().map(Token::text).collect()
 }
@@ -0,0 +1,8 @@
 interface "/::example" {
  type `string` = {
    `表示名`: string,
  };
  operation `find-item`(
    `search term`: string,
  ) -> `string`;
 }
@@ -0,0 +1,22 @@
 /// "Issueの内容と関連項目を読む。"
 interface "/::issue.read" {
  type Relation = enum {
    parent,
    sibling,
    related,
  };
  type RelatedItems = {
    /// "同じWorldspace内の関連項目。"
    items: [entry],
    next_cursor?: string,
  };
  /// "本文を取得する。"
  operation read_body() -> {
    body: string,
  };
  /// "関係を指定して関連項目を取得する。"
  operation get_related_items(
    relation: Relation,
    limit?: integer,
  ) -> RelatedItems;
 }
@@ -0,0 +1,25 @@
 interface "/::example" {
  /// "type summary"
  type Z = {
    /// "field summary"
    z?: unit,
    a: [union {
      /// "case summary"
      z,
      /// ""
      a(unit),
      nested(enum {
        /// "enum summary"
        z,
        a,
      }),
    }],
  };
  operation z(
    z: unit,
    a?: unit,
  ) -> unit;
  operation a()
  /// "no params result"
  -> unit;
 }
@@ -0,0 +1,5 @@
 object {
  name: "123";
  description: "Issue 123の公開操作。本文はOperationで取得する。";
  interfaces: ["/::issue.read", "/::issue.lifecycle"];
 }
@@ -0,0 +1,18 @@
 interface "/::example" {
  type CloseResult = union {
    closed,
    blocked({
      dependencies: [entry],
    }),
  };
  operation refresh() -> unit;
  /// "対象を検索する。"
  operation search(
    /// "検索語。"
    query: string,
  )
  /// "条件に一致する項目。"
  -> {
    items: [entry],
  };
 }
@@ -1,9 +1,11 @@
 [package]
 name = "wip-tui"
-version = "0.1.0"
+version.workspace = true
-edition = "2024"
+edition.workspace = true
 rust-version.workspace = true
 description = "Interactive terminal client for exploring and operating WIP Worldspaces"
-license = "MIT OR Apache-2.0"
+license.workspace = true
 repository.workspace = true
 readme = "README.md"
 publish = false
@@ -13,10 +15,10 @@ crossterm = "0.28.1"
 ratatui = "0.29.0"
 serde_json = "1"
 ureq = "3.1.2"
-wip-client = { path = "../wip-client" }
+wip-client.workspace = true
-wip-https = { path = "../wip-https" }
+wip-http.workspace = true
-wip-protocol = { path = "../wip-protocol" }
+wip-protocol.workspace = true
 [dev-dependencies]
 tempfile = "3"
-wip-fs-server = { path = "../wip-fs-server" }
+wip-fs-server.workspace = true
@@ -8,12 +8,17 @@ owned by the client runtime.
 ## Start
-HTTPS is the normal mode:
+Supply one `http` or `https` endpoint:
 ```console
 cargo run -p wip-tui -- --endpoint https://wip.example.test/api/wip
 ```
 The same canonical endpoint is used unchanged to construct requests, perform
 HTTP I/O, and partition the client cache. WIP over HTTP does not define separate
 HTTPS and development-HTTP profiles; URL scheme, TLS, certificate, authentication,
 and proxy policy belong to the HTTP implementation and deployment.
 The endpoint may instead be supplied as `WIP_ENDPOINT`. A non-secret cache
 partition identity may be supplied with `--security-context NAME` or
 `WIP_SECURITY_CONTEXT`. The default request timeout is 30 seconds and can be
@@ -31,16 +36,6 @@ Use `--authorization-env OTHER_VARIABLE` to select another variable. The value i
 redacted from `Debug` and is never rendered. Shell and process environment security
 remain the operator's responsibility.
 Plain HTTP is rejected by default. It is available only as an explicit loopback
 development mode:
 ```console
 cargo run -p wip-tui -- http://127.0.0.1:8080/wip --allow-http
 ```
 Non-loopback HTTP remains rejected even with `--allow-http`. For production, use a
 real HTTPS endpoint and a trusted TLS deployment.
 ### Filesystem server example
 In one terminal:
@@ -52,22 +47,73 @@ cargo run -p wip-fs-server -- \
  --root /tmp/wip-example \
  --listen 127.0.0.1:8080 \
  --base-path /wip \
  --development-http \
  --read-write
 ```
 In another:
 ```console
-cargo run -p wip-tui -- http://127.0.0.1:8080/wip --allow-http
+cargo run -p wip-tui -- http://127.0.0.1:8080/wip
 ```
-Expand `/`, select `notes.txt`, focus the Interface/Operation pane, load the read
+Expand `/`, select `notes.txt`, focus the Interface/Operation pane, and choose
-interface, and choose `read`. The editor labels `offset` and `length` as optional;
+`read`; descriptors advertised by visible Objects are normally prefetched already.
-leave both blank to read the bounded file. `Bytes` results are shown as a bounded
+The editor labels `offset` and `length` as optional; leave both blank to read the
-hex preview. For `replace`, enter `contents` as RFC 4648 base64—for example,
+bounded file. `Bytes` results are shown as a bounded hex preview. For `replace`,
-`dXBkYXRlZA==` for `updated`—then review the target Entry, interface reference,
+enter `contents` as RFC 4648 base64—for example, `dXBkYXRlZA==` for
-operation, and value on the confirmation screen before pressing Enter again.
+`updated`—then review the target Entry, interface reference, operation, and value
 on the confirmation screen before pressing Enter again.
 ## Scoped reference formatting
 `wip_tui::reference::{format_interface_reference, format_qualified_operation}`
 provides labels for the existing UI from `InterfaceReference` and a separate
 operation name, following `4.2-text-view.md` reference notation (`6086f3c`).
 ```rust
 use wip_protocol::InterfaceReference;
 use wip_tui::reference::{format_interface_reference, format_qualified_operation};
 let reference = InterfaceReference { scope: "/github".into(), name: "issue#read".into() };
 assert_eq!(format_interface_reference(&reference)?, "/github::\"issue#read\"");
 assert_eq!(format_qualified_operation(&reference, "read#raw")?,
           "/github::\"issue#read\"#\"read#raw\"");
 # Ok::<(), wip_protocol::ValidationError>(())
 ```
 Both return `Result<String, ValidationError>` and reject invalid reference shape,
 including relative/omitted scope. Root is explicit `/`. Non-simple components use
 JSON string quoting with additional DEL/C1, Unicode line/paragraph separator and
 bidi-control escapes. Input values are borrowed and never normalized, case-folded,
 URL-encoded or split on delimiters. Ref, validators and `scope_ref` do not enter
 these labels. The output has no extra outer signature string quoting.
 Keep selection, cache and calls keyed by structured references and operation
 names, never display text. No parser, scope inference, identity reconstruction,
 Object/Interface signature renderer or new crate is introduced. Membership,
 ancestry, authorization and freshness remain runtime concerns. Normal Entry,
 Interface/Operation, editor, confirmation and operation-history screens use these
 qualified labels with existing bounded layout. Shortened labels never feed back
 into identity or calls.
 ### Rust API and wire migration
 Interface identities in the presentation map, action/selection rows, in-flight
 subjects and editors are now `InterfaceReference { scope, name }`, not strings.
 This is a breaking Rust API change; consumers must construct an explicit canonical
 absolute scope rather than parse a label or infer a scope from a target Entry.
 `ArgumentEditor` also retains its Entry `path`; `new` defaults to `/`, and
 `for_target(path)` fixes the chosen target before editing. Normal UI selection
 sets it automatically. Confirmation never retargets an existing editor.
 `App::operation_selection` retains the Entry and structured row through temporary
 loading gaps; the numeric cursor is only a layout position. Retaining this subject
 does not expose stale operations or authorize execution.
 The TUI uses the scoped Protocol/HTTP Client wire: Interface references are
 structured, and calls use an Interface target carrying the reference and optional
 `scope_ref`/validator preconditions. The optional identity is copied by the Client,
 not invented by the UI; no additional required ref is introduced. This wire is not
 compatible with the former string-reference request/response shape.
 ## Keyboard bindings
@@ -80,7 +126,6 @@ All required actions are keyboard-accessible.
 | `←`/`h` | Collapse a node or move to its parent |
 | `Tab` | Cycle Tree → Selected Entry → Operations → History |
 | `r` | Reobserve the selected Entry and its direct subtree |
 | `+` | Double the selected node limit and retry an incomplete/truncated tree |
 | `c` | Cancel the newest retrieval; a dispatched operation is never presented as canceled |
 | `R` | Reconnect after connection failure |
 | `?` | Open help |
@@ -93,17 +138,24 @@ a second explicit Enter (or `e`) to execute once. There is no operation auto-ret
 ## Screen model
- **Worldspace tree** starts at `/` and materializes direct children only when a
+- **Worldspace tree** starts at `/`, lazily materializes expanded nodes, and
-  node is expanded. Text labels distinguish unloaded, loading, empty, stale,
+  prefetches children for each visible Object so emptiness and the next expansion
-  failed, and truncated state; color is supplemental. A truncated node is never
+  frontier are known without selecting that Object first. Text labels distinguish
-  presented as a complete tree.
+  unloaded, loading, empty, stale, and failed state; color is supplemental. Every
  successful expansion is complete for its requested depth.
 - **Selected Entry** shows only public WIP path, object name, description, ordered
  interfaces, and freshness. Validators, credentials, Host internals, and backend
  paths are deliberately hidden. If current metadata disappears, old text is not
  presented as current.
- **Interfaces / Operations** identifies every operation by `(interface reference,
+- **Interfaces / Operations** identifies every operation by structured `(scope,
-  operation name)`. It shows descriptor documentation, ordered parameters,
+  interface name, operation name)`, displaying `scope::interface#operation` with
-  required/optional status, and result types.
+  explicit absolute scope and safely quoted components. Structured references
  remain intact in selection, acquisition, and call state; display labels are
  never parsed back into references. Descriptor lookahead follows fresh visible
  Objects, shares the
  client's in-flight/cache bounds, and never retries retained failures implicitly.
  The pane shows descriptor documentation, ordered parameters, required/optional
  status, and result types.
 - **Argument editor** supports Unit, Boolean, Integer, Number, String, base64 Bytes,
  Record, List, Entry, Enum, Union, Json, and descriptor-local named types. Record,
  List, Union, and Json values use JSON syntax. Union input is
@@ -121,12 +173,28 @@ layout.
 ## Validator and failure behavior
 Object and interface validators are observed and attached automatically by
-`wip-client`; users neither copy nor edit them. A successful operation conservatively
+`wip-client`; users neither copy nor edit them. A successful operation may update the
-marks related object observations stale because metadata may have changed.
+cached Object validator but does not by itself make the Object observation stale.
 Validator mismatch, interface mismatch, `OperationOutcomeUnknown`, undecodable
 post-dispatch responses, and post-dispatch timeout/disconnect are displayed using
 the runtime's authoritative transition.
 Every Client transition is mirrored into retained UI Object, tree and Interface
 state, including scope retirement and cache removal. An open editor/confirmation
 is bound to private Object/Interface snapshots (not displayed refs/validators).
 Changed, stale, loading, removed or retargeted observations retire the editor;
 reobservation never recreates or executes it. Descriptor rows remain identified
 by the structured reference when another Interface gains or loses operation rows.
 Explicitly select/load an Interface header to refresh a retained stale descriptor,
 then select an operation and confirm a new call. Client calls already dispatched
 retain their original immutable context and are never moved to a new scope.
 Without refs, a same-path replacement with indistinguishable public metadata
 cannot always be detected; the UI does not synthesize identity or infer deletion
 from missing tree edges. Optional refs remain optional. Typed `Entry` results are
 only observed when individually selected; the UI neither bulk-fetches result
 paths nor adds guessed parent/indexable edges.
 For an unknown outcome, the UI states that execution or side effects may have
 occurred, marks the related Entry stale, and tells the user to refresh. Refreshing
 does not recreate the call: the user must select the operation, review fresh input,
@@ -3,7 +3,7 @@
 use std::collections::{BTreeMap, BTreeSet};
 use wip_client::{InterfaceObservation, ObjectObservation, ObservationState, TreeObservation};
-use wip_protocol::{InterfaceDescriptor, Object, Value};
+use wip_protocol::{InterfaceDescriptor, InterfaceReference, Object, Value};
 use crate::editor::ArgumentEditor;
@@ -31,8 +31,6 @@ pub enum InputKey {
    Backspace,
    /// Refresh the selected Entry.
    Refresh,
    /// Retry a truncated tree with a larger limit.
    IncreaseLimit,
    /// Cancel the newest cancel-safe retrieval.
    CancelRead,
    /// Show key help.
@@ -123,14 +121,10 @@ pub struct EntryView {
    pub tree_state: ViewState,
    /// Whether the user expanded this row.
    pub expanded: bool,
    /// Whether the observed child list is incomplete.
    pub truncated: bool,
    /// Current bounded expansion limit.
    pub limit: u32,
 }
 impl EntryView {
-    fn placeholder(path: impl Into<String>, default_limit: u32) -> Self {
+    fn placeholder(path: impl Into<String>) -> Self {
        Self {
            path: path.into(),
            object: None,
@@ -138,8 +132,6 @@ impl EntryView {
            children: Vec::new(),
            tree_state: ViewState::Unloaded,
            expanded: false,
            truncated: false,
            limit: default_limit,
        }
    }
 }
@@ -147,8 +139,8 @@ impl EntryView {
 /// Cached interface descriptor state used by presentation.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InterfaceView {
-    /// Opaque interface reference.
+    /// Structured interface reference.
-    pub reference: String,
+    pub reference: InterfaceReference,
    /// Descriptor when accepted by the client runtime.
    pub descriptor: Option<InterfaceDescriptor>,
    /// Descriptor observation state.
@@ -195,13 +187,13 @@ pub enum InFlightKind {
    /// Tree expansion or refresh.
    Tree(String),
    /// Descriptor fetch.
-    Interface(String),
+    Interface(InterfaceReference),
    /// Explicit operation call.
    Operation {
        /// Target path.
        path: String,
        /// Interface reference.
-        interface: String,
+        interface: InterfaceReference,
        /// Operation name.
        operation: String,
        /// Whether the transport dispatch boundary was crossed.
@@ -242,24 +234,20 @@ pub enum Action {
    Expand {
        /// Tree root path.
        path: String,
        /// Maximum returned nodes.
        limit: u32,
    },
    /// Reobserve an Entry and its direct children.
    Refresh {
        /// Selected path.
        path: String,
        /// Current tree limit.
        limit: u32,
    },
    /// Retrieve one interface descriptor.
-    FetchInterface(String),
+    FetchInterface(InterfaceReference),
    /// Execute only after explicit confirmation.
    Execute {
        /// Entry target.
        path: String,
        /// Interface reference.
-        interface: String,
+        interface: InterfaceReference,
        /// Operation name.
        operation: String,
        /// Descriptor-validated arguments.
@@ -267,7 +255,7 @@ pub enum Action {
    },
    /// Cancel the newest safe retrieval.
    CancelRead,
-    /// Reconnect and fetch the root.
+    /// Reconnect and observe the root.
    Reconnect,
    /// Navigate to a descriptor-declared Entry result.
    NavigateEntry(String),
@@ -288,10 +276,13 @@ pub struct App {
    pub selected_path: String,
    /// Focused pane.
    pub focus: Focus,
-    /// Interface descriptor views by opaque reference.
+    /// Interface descriptor views by structured reference.
-    pub interfaces: BTreeMap<String, InterfaceView>,
+    pub interfaces: BTreeMap<InterfaceReference, InterfaceView>,
    /// Selected row in the flattened interface/operation view.
    pub operation_cursor: usize,
    /// Retained Entry and structured row while current operation rows are hidden.
    /// This is selection identity only, never authority to execute a stale row.
    pub operation_selection: Option<(String, OperationRow)>,
    /// Selected recent-history row.
    pub history_cursor: usize,
    /// Active overlay.
@@ -302,8 +293,6 @@ pub struct App {
    pub history: Vec<HistoryItem>,
    /// Maximum retained presentation history.
    pub history_limit: usize,
    /// Default node limit for lazy expansion.
    pub default_tree_limit: u32,
    /// One-line status for local action feedback.
    pub status: String,
 }
@@ -312,9 +301,10 @@ impl App {
    /// Creates a disconnected model with `/` selected.
    #[must_use]
    pub fn new(endpoint: impl Into<String>) -> Self {
        let default_tree_limit = 64;
        let mut entries = BTreeMap::new();
-        entries.insert("/".into(), EntryView::placeholder("/", default_tree_limit));
+        let mut root = EntryView::placeholder("/");
        root.expanded = true;
        entries.insert("/".into(), root);
        Self {
            endpoint: endpoint.into(),
            connection: ConnectionState::Disconnected,
@@ -323,12 +313,12 @@ impl App {
            focus: Focus::Tree,
            interfaces: BTreeMap::new(),
            operation_cursor: 0,
            operation_selection: None,
            history_cursor: 0,
            modal: Modal::None,
            in_flight: BTreeMap::new(),
            history: Vec::new(),
            history_limit: 64,
            default_tree_limit,
            status: "press ? for help".into(),
        }
    }
@@ -376,7 +366,7 @@ impl App {
                }
                InputKey::Enter | InputKey::Character('e') => {
                    let action = Action::Execute {
-                        path: self.selected_path.clone(),
+                        path: editor.path.clone(),
                        interface: editor.interface.clone(),
                        operation: editor.operation.name.clone(),
                        arguments,
@@ -441,14 +431,11 @@ impl App {
                let node = self
                    .entries
                    .entry(self.selected_path.clone())
-                    .or_insert_with(|| {
+                    .or_insert_with(|| EntryView::placeholder(&self.selected_path));
                        EntryView::placeholder(&self.selected_path, self.default_tree_limit)
                    });
                node.expanded = true;
-                if !matches!(node.tree_state, ViewState::Fresh) || node.truncated {
+                if !matches!(node.tree_state, ViewState::Fresh) {
                    return vec![Action::Expand {
                        path: node.path.clone(),
                        limit: node.limit,
                    }];
                }
            }
@@ -464,18 +451,6 @@ impl App {
                }
            }
            InputKey::Refresh => return vec![self.refresh_action()],
            InputKey::IncreaseLimit => {
                let node = self
                    .entries
                    .get_mut(&self.selected_path)
                    .expect("selected exists");
                node.limit = node.limit.saturating_mul(2).max(1);
                node.expanded = true;
                return vec![Action::Expand {
                    path: node.path.clone(),
                    limit: node.limit,
                }];
            }
            _ => {}
        }
        self.operation_cursor = 0;
@@ -493,17 +468,21 @@ impl App {
                if let Some(row) = rows.get(self.operation_cursor) {
                    if let Some(operation_name) = &row.operation {
                        if let Some(interface) = self.interfaces.get(&row.interface)
                            && interface.state == ViewState::Fresh
                            && let Some(descriptor) = &interface.descriptor
                            && let Some(operation) = descriptor
                                .operations
                                .iter()
                                .find(|operation| operation.name == *operation_name)
                        {
-                            self.modal = Modal::Editor(ArgumentEditor::new(
+                            self.modal = Modal::Editor(
-                                row.interface.clone(),
+                                ArgumentEditor::new(
-                                descriptor.clone(),
+                                    row.interface.clone(),
-                                operation.clone(),
+                                    descriptor.clone(),
-                            ));
+                                    operation.clone(),
                                )
                                .for_target(self.selected_path.clone()),
                            );
                        }
                    } else {
                        return vec![Action::FetchInterface(row.interface.clone())];
@@ -537,18 +516,17 @@ impl App {
    }
    fn refresh_action(&self) -> Action {
        let limit = self
            .entries
            .get(&self.selected_path)
            .map_or(self.default_tree_limit, |entry| entry.limit);
        Action::Refresh {
            path: self.selected_path.clone(),
            limit,
        }
    }
    /// Records a pending request separately by interaction type.
    pub fn request_started(&mut self, id: u64, kind: InFlightKind) {
        // Object/Interface loading can remove all rows before completion. Keep
        // the exact subject now rather than recovering identity from a cursor.
        let selected = self.operation_rows().get(self.operation_cursor).cloned();
        self.restore_operation_selection(selected);
        match &kind {
            InFlightKind::Object(path) => {
                self.ensure_entry(path).state = ViewState::Loading(id);
@@ -591,9 +569,7 @@ impl App {
        let children = observation.children.clone();
        let entry = self.ensure_entry(&observation.path);
        entry.children = children.clone();
        entry.truncated = observation.truncated;
        entry.tree_state = ViewState::from(&observation.state);
        entry.expanded = true;
        for path in children {
            self.ensure_entry(&path);
        }
@@ -648,6 +624,30 @@ impl App {
        visible
    }
    /// Returns interface references advertised by fresh visible Objects in display
    /// and per-Object declaration order, with duplicates removed.
    #[must_use]
    pub fn visible_interface_references(&self) -> Vec<InterfaceReference> {
        let mut references = Vec::new();
        let mut seen = BTreeSet::new();
        for path in self.visible_paths() {
            let Some(object) = self
                .entries
                .get(&path)
                .filter(|entry| entry.state == ViewState::Fresh)
                .and_then(|entry| entry.object.as_ref())
            else {
                continue;
            };
            for reference in &object.interfaces {
                if seen.insert(reference.clone()) {
                    references.push(reference.clone());
                }
            }
        }
        references
    }
    fn collect_visible(&self, path: &str, seen: &mut BTreeSet<String>, visible: &mut Vec<String>) {
        if !seen.insert(path.to_owned()) {
            return;
@@ -695,6 +695,37 @@ impl App {
        rows
    }
    /// Preserves a selected structured subject across descriptor/row movement.
    pub(crate) fn restore_operation_selection(&mut self, selected: Option<OperationRow>) {
        if let Some(selected) = selected {
            self.operation_selection = Some((self.selected_path.clone(), selected));
        } else if self
            .operation_selection
            .as_ref()
            .is_some_and(|(path, _)| path != &self.selected_path)
        {
            self.operation_selection = None;
        }
        let rows = self.operation_rows();
        self.operation_cursor = self
            .operation_selection
            .as_ref()
            .and_then(|(_, selected)| {
                rows.iter().position(|row| row == selected).or_else(|| {
                    rows.iter().position(|row| {
                        row.interface == selected.interface && row.operation.is_none()
                    })
                })
            })
            .unwrap_or(0);
        // Keep identity through a temporarily empty (loading/stale) view. Once
        // rows are current, the retained identity follows the actual selection,
        // falling back to its own Interface header if the Operation was retired.
        if let Some(row) = rows.get(self.operation_cursor) {
            self.operation_selection = Some((self.selected_path.clone(), row.clone()));
        }
    }
    fn ensure_entry(&mut self, path: &str) -> &mut EntryView {
        if !self.entries.contains_key(path) && self.entries.len() >= MAX_PRESENTATION_ENTRIES {
            let candidate = self
@@ -725,10 +756,10 @@ impl App {
        }
        self.entries
            .entry(path.to_owned())
-            .or_insert_with(|| EntryView::placeholder(path, self.default_tree_limit))
+            .or_insert_with(|| EntryView::placeholder(path))
    }
-    fn ensure_interface(&mut self, reference: &str) -> &mut InterfaceView {
+    fn ensure_interface(&mut self, reference: &InterfaceReference) -> &mut InterfaceView {
        if !self.interfaces.contains_key(reference)
            && self.interfaces.len() >= MAX_PRESENTATION_INTERFACES
        {
@@ -769,7 +800,7 @@ impl App {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OperationRow {
    /// Interface reference, which participates in operation identity.
-    pub interface: String,
+    pub interface: InterfaceReference,
    /// Operation name, or `None` for the interface heading.
    pub operation: Option<String>,
 }
@@ -785,6 +816,12 @@ pub fn parent_path(path: &str) -> String {
 #[cfg(test)]
 mod tests {
    fn root_reference(name: &str) -> wip_protocol::InterfaceReference {
        wip_protocol::InterfaceReference {
            scope: "/".into(),
            name: name.into(),
        }
    }
    use super::*;
    use wip_protocol::{INTERFACE_FORMAT_V1, OperationDeclaration, ReturnDeclaration, TypeExpr};
@@ -792,33 +829,123 @@ mod tests {
        Object {
            name: name.into(),
            description: Some(format!("{name} description")),
-            interfaces: interfaces.iter().map(|value| (*value).into()).collect(),
+            interfaces: interfaces
                .iter()
                .map(|value| root_reference(value))
                .collect(),
            r#ref: None,
            validator: None,
        }
    }
    #[test]
-    fn tree_navigation_expansion_parent_and_limit_are_pure() {
+    fn tree_navigation_and_lazy_expansion_are_pure() {
        let mut app = App::new("https://example.test/wip");
        app.apply_tree(TreeObservation {
            path: "/".into(),
            children: vec!["/a".into(), "/b".into()],
            truncated: true,
            revision: request_id(),
            state: ObservationState::Fresh,
        });
        assert_eq!(app.visible_paths(), ["/", "/a", "/b"]);
        app.reduce(InputKey::Down);
        assert_eq!(app.selected_path, "/a");
        app.reduce(InputKey::Left);
        assert_eq!(app.selected_path, "/");
        assert!(matches!(
-            app.reduce(InputKey::IncreaseLimit).as_slice(),
+            app.reduce(InputKey::Right).as_slice(),
-            [Action::Expand { path, limit: 128 }] if path == "/"
+            [Action::Expand { path }] if path == "/a"
        ));
    }
    #[test]
    fn visible_interface_references_are_ordered_deduplicated_and_fresh() {
        let mut app = App::new("https://example.test/wip");
        app.apply_tree(TreeObservation {
            path: "/".into(),
            children: vec!["/a".into(), "/stale".into()],
            revision: request_id(),
            state: ObservationState::Fresh,
        });
        app.apply_object(ObjectObservation {
            path: "/".into(),
            object: Some(object("", &["root", "shared"])),
            validator: None,
            state: ObservationState::Fresh,
        });
        app.apply_object(ObjectObservation {
            path: "/a".into(),
            object: Some(object("a", &["shared", "child"])),
            validator: None,
            state: ObservationState::Fresh,
        });
        app.apply_object(ObjectObservation {
            path: "/stale".into(),
            object: Some(object("stale", &["ignored"])),
            validator: None,
            state: ObservationState::Stale,
        });
        app.apply_tree(TreeObservation {
            path: "/a".into(),
            children: vec!["/a/hidden".into()],
            revision: request_id(),
            state: ObservationState::Fresh,
        });
        app.apply_object(ObjectObservation {
            path: "/a/hidden".into(),
            object: Some(object("hidden", &["hidden"])),
            validator: None,
            state: ObservationState::Fresh,
        });
        assert_eq!(
            app.visible_interface_references(),
            [
                root_reference("root"),
                root_reference("shared"),
                root_reference("child")
            ]
        );
    }
    #[test]
    fn presentation_retains_equal_names_in_distinct_scopes() {
        let mut app = App::new("https://example.test/wip");
        let root = root_reference("shared#::操作");
        let local = InterfaceReference {
            scope: "/a".into(),
            name: root.name.clone(),
        };
        let mut value = object("a", &[]);
        value.interfaces = vec![root.clone(), local.clone()];
        app.navigate_entry("/a");
        app.apply_object(ObjectObservation {
            path: "/a".into(),
            object: Some(value),
            validator: None,
            state: ObservationState::Fresh,
        });
        for reference in [&root, &local] {
            app.apply_interface(InterfaceObservation {
                reference: reference.clone(),
                descriptor: None,
                validator: None,
                scope_ref: None,
                state: ObservationState::Fresh,
            });
        }
        assert_eq!(app.interfaces.len(), 2);
        assert_eq!(
            app.visible_interface_references(),
            vec![root.clone(), local.clone()]
        );
        assert_eq!(
            app.operation_rows()
                .iter()
                .map(|row| row.interface.clone())
                .collect::<Vec<_>>(),
            vec![root, local]
        );
    }
    #[test]
    fn focus_modal_and_explicit_confirmation_gate_execution() {
        let mut app = App::new("https://example.test/wip");
@@ -843,7 +970,8 @@ mod tests {
            }],
        };
        app.apply_interface(InterfaceObservation {
-            reference: "iface".into(),
+            scope_ref: None,
            reference: root_reference("iface"),
            descriptor: Some(descriptor),
            validator: None,
            state: ObservationState::Fresh,
@@ -872,7 +1000,8 @@ mod tests {
        for index in 0..(MAX_PRESENTATION_INTERFACES + 50) {
            app.apply_interface(InterfaceObservation {
-                reference: format!("interface-{index}"),
+                scope_ref: None,
                reference: root_reference(&format!("interface-{index}")),
                descriptor: None,
                validator: None,
                state: ObservationState::Fresh,
@@ -908,7 +1037,7 @@ mod tests {
        // A request identity has no public constructor; derive one through the runtime.
        let mut client = wip_client::Client::new(
            wip_client::ClientLimits::new(1, 4, 4, 4, 4).unwrap(),
-            wip_https::Limits::new(1024, 1024, 8, 8).unwrap(),
+            wip_http::Limits::new(1024, 1024, 8).unwrap(),
        );
        let session = client
            .open_session(
@@ -916,6 +1045,6 @@ mod tests {
                wip_client::SecurityContext::new("test"),
            )
            .unwrap();
-        client.prepare_fetch(&session, "/").unwrap().id
+        client.refresh_object(&session, "/").unwrap().id
    }
 }
@@ -1,10 +1,10 @@
-//! Secure-by-default command-line and environment configuration.
+//! Command-line and environment configuration for the HTTP client.
 use std::error::Error;
 use std::fmt::{self, Debug, Display, Formatter};
 use std::time::Duration;
-use wip_https::url::Url;
+use wip_http::Endpoint;
 /// Credential wrapper whose debug output is always redacted.
 #[derive(Clone)]
@@ -25,45 +25,33 @@ impl Debug for Secret {
 /// Validated runtime configuration.
 #[derive(Clone)]
 pub struct Config {
-    /// Canonical logical HTTPS endpoint used by `wip-client`.
+    /// Canonical endpoint used for request construction, transport, and cache partitioning.
-    logical_endpoint: String,
+    endpoint: String,
    /// Actual request origin; differs only for explicit loopback development HTTP.
    transport_endpoint: String,
    /// Non-secret cache partition identity.
    security_context: String,
    /// Bounded network timeout.
    timeout: Duration,
    /// Optional complete Authorization header value, never rendered or logged.
    authorization: Option<Secret>,
    /// Whether loopback request URIs are deliberately downgraded to HTTP.
    development_http: bool,
 }
 impl Debug for Config {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Config")
-            .field("logical_endpoint", &self.logical_endpoint)
+            .field("endpoint", &self.endpoint)
            .field("transport_endpoint", &self.transport_endpoint)
            .field("security_context", &self.security_context)
            .field("timeout", &self.timeout)
            .field("authorization", &self.authorization)
            .field("development_http", &self.development_http)
            .finish()
    }
 }
 impl Config {
-    /// Returns the canonical HTTPS endpoint used for protocol request construction.
+    /// Returns the canonical endpoint used by the client and HTTP transport.
    #[must_use]
-    pub fn logical_endpoint(&self) -> &str {
+    pub fn endpoint(&self) -> &str {
-        &self.logical_endpoint
+        &self.endpoint
    }
    /// Returns the validated effective transport endpoint shown in the UI.
    #[must_use]
    pub fn transport_endpoint(&self) -> &str {
        &self.transport_endpoint
    }
    /// Returns the non-secret session cache partition identity.
@@ -78,12 +66,6 @@ impl Config {
        self.timeout
    }
    /// Whether explicit loopback development HTTP is enabled.
    #[must_use]
    pub const fn development_http(&self) -> bool {
        self.development_http
    }
    pub(crate) fn authorization(&self) -> Option<&Secret> {
        self.authorization.as_ref()
    }
@@ -115,7 +97,6 @@ impl Config {
        F: FnMut(&str) -> Option<String>,
    {
        let mut endpoint = None;
        let mut allow_http = false;
        let mut timeout = Duration::from_secs(30);
        let mut security_context = security_context_env.unwrap_or_else(|| "anonymous".into());
        let mut authorization_env = "WIP_AUTHORIZATION".to_owned();
@@ -123,7 +104,6 @@ impl Config {
        while let Some(argument) = iter.next() {
            match argument.as_str() {
                "--endpoint" => endpoint = Some(next_value(&mut iter, "--endpoint")?),
                "--allow-http" => allow_http = true,
                "--security-context" => {
                    security_context = next_value(&mut iter, "--security-context")?;
                }
@@ -149,52 +129,22 @@ impl Config {
                _ => return Err(ConfigError::Invalid("multiple endpoints supplied".into())),
            }
        }
-        let endpoint = endpoint
+        let supplied = endpoint
            .or(endpoint_env)
            .ok_or_else(|| ConfigError::Invalid("endpoint is required".into()))?;
-        let mut actual = Url::parse(&endpoint)
+        let endpoint =
-            .map_err(|_| ConfigError::Invalid("endpoint is not a valid absolute URL".into()))?;
+            Endpoint::parse(&supplied).map_err(|error| ConfigError::Invalid(error.to_string()))?;
-        if actual.query().is_some()
+        if !endpoint.as_url().username().is_empty() || endpoint.as_url().password().is_some() {
            || actual.fragment().is_some()
            || actual.host_str().is_none()
            || !actual.username().is_empty()
            || actual.password().is_some()
        {
            return Err(ConfigError::Invalid(
-                "endpoint must be an absolute URL without userinfo, query, or fragment".into(),
+                "endpoint userinfo is not accepted; supply credentials through the configured environment variable"
                    .into(),
            ));
        }
-        if !actual.path().ends_with('/') {
+        if !matches!(endpoint.as_url().scheme(), "http" | "https") {
-            let path = format!("{}/", actual.path());
+            return Err(ConfigError::Invalid(
-            actual.set_path(&path);
+                "this HTTP client supports http and https endpoint schemes".into(),
            ));
        }
        let development_http = actual.scheme() == "http";
        match actual.scheme() {
            "https" => {}
            "http" if allow_http && loopback_host(&actual) => {}
            "http" if !allow_http => {
                return Err(ConfigError::Invalid(
                    "plain HTTP requires the explicit --allow-http development option".into(),
                ));
            }
            "http" => {
                return Err(ConfigError::Invalid(
                    "development HTTP is restricted to loopback endpoints".into(),
                ));
            }
            _ => return Err(ConfigError::Invalid("endpoint must use HTTPS".into())),
        }
        let transport_endpoint = actual.to_string();
        let mut logical = actual;
        if development_http {
            logical
                .set_scheme("https")
                .expect("http and https are interchangeable hierarchical schemes");
        }
        // Let the binding enforce all remaining canonical endpoint rules.
        let logical_endpoint = wip_https::Endpoint::parse(logical.as_str())
            .map_err(|error| ConfigError::Invalid(error.to_string()))?
            .to_string();
        if security_context.is_empty() {
            return Err(ConfigError::Invalid(
                "security context must not be empty".into(),
@@ -204,20 +154,18 @@ impl Config {
            .filter(|value| !value.is_empty())
            .map(Secret);
        Ok(Self {
-            logical_endpoint,
+            endpoint: endpoint.to_string(),
            transport_endpoint,
            security_context,
            timeout,
            authorization,
            development_http,
        })
    }
    /// Returns concise command usage without mentioning credential values.
    #[must_use]
    pub const fn usage() -> &'static str {
-        "usage: wip-tui [--endpoint] URL [--allow-http] [--security-context NAME] [--authorization-env VAR] [--timeout SECONDS]\n\
+        "usage: wip-tui [--endpoint] URL [--security-context NAME] [--authorization-env VAR] [--timeout SECONDS]\n\
-         URL may also be supplied as WIP_ENDPOINT; HTTPS is required unless loopback HTTP is explicitly enabled."
+         URL may also be supplied as WIP_ENDPOINT; the HTTP adapter supports http and https."
    }
 }
@@ -229,15 +177,6 @@ fn next_value(
        .ok_or_else(|| ConfigError::Invalid(format!("{option} requires a value")))
 }
 fn loopback_host(url: &Url) -> bool {
    match url.host() {
        Some(wip_https::url::Host::Ipv4(address)) => address.is_loopback(),
        Some(wip_https::url::Host::Ipv6(address)) => address.is_loopback(),
        Some(wip_https::url::Host::Domain(name)) => name.eq_ignore_ascii_case("localhost"),
        None => false,
    }
 }
 /// Startup configuration failure.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ConfigError {
@@ -263,7 +202,7 @@ mod tests {
    use super::*;
    #[test]
-    fn https_is_default_and_secrets_are_redacted() {
+    fn endpoint_is_canonical_and_secrets_are_redacted() {
        let config = Config::parse(
            ["https://example.test/wip", "--authorization-env", "TOKEN"],
            None,
@@ -271,7 +210,7 @@ mod tests {
            |name| (name == "TOKEN").then(|| "Bearer secret-value".into()),
        )
        .unwrap();
-        assert_eq!(config.logical_endpoint(), "https://example.test/wip/");
+        assert_eq!(config.endpoint(), "https://example.test/wip/");
        let debug = format!("{config:?}");
        assert!(debug.contains("[REDACTED]"));
        assert!(!debug.contains("secret-value"));
@@ -279,37 +218,22 @@ mod tests {
    #[test]
    fn endpoint_userinfo_is_rejected_before_it_can_reach_debug_or_render_state() {
-        for arguments in [
+        for endpoint in [
-            vec!["https://user:password@example.test/wip"],
+            "https://user:password@example.test/wip",
-            vec!["http://user:password@localhost:3000/wip", "--allow-http"],
+            "http://user:password@localhost:3000/wip",
        ] {
-            let error = Config::parse(arguments, None, None, |_| None).unwrap_err();
+            let error = Config::parse([endpoint], None, None, |_| None).unwrap_err();
-            assert!(error.to_string().contains("without userinfo"));
+            assert!(error.to_string().contains("userinfo"));
            assert!(!error.to_string().contains("password"));
        }
    }
    #[test]
-    fn http_requires_explicit_loopback_development_mode() {
+    fn http_and_https_are_preserved_as_the_single_endpoint() {
-        assert!(Config::parse(["http://localhost:3000/wip"], None, None, |_| None).is_err());
+        for expected in ["http://example.test:3000/wip/", "https://example.test/wip/"] {
-        let config = Config::parse(
+            let supplied = expected.trim_end_matches('/');
-            ["http://127.0.0.1:3000/wip", "--allow-http"],
+            let config = Config::parse([supplied], None, None, |_| None).unwrap();
-            None,
+            assert_eq!(config.endpoint(), expected);
-            None,
+        }
            |_| None,
        )
        .unwrap();
        assert_eq!(config.logical_endpoint(), "https://127.0.0.1:3000/wip/");
        assert_eq!(config.transport_endpoint(), "http://127.0.0.1:3000/wip/");
        assert!(config.development_http());
        assert!(
            Config::parse(
                ["http://example.test/wip", "--allow-http"],
                None,
                None,
                |_| None,
            )
            .is_err()
        );
    }
 }
@@ -4,7 +4,9 @@ use std::collections::BTreeMap;
 use base64::Engine as _;
 use base64::engine::general_purpose::STANDARD;
-use wip_protocol::{InterfaceDescriptor, OperationDeclaration, TypeExpr, Value};
+use wip_protocol::{
    InterfaceDescriptor, InterfaceReference, OperationDeclaration, TypeExpr, Value,
 };
 const MAX_FIELD_INPUT_BYTES: usize = 256 * 1024;
@@ -30,8 +32,10 @@ pub struct InvalidArguments;
 /// Pure, terminal-independent editor built from an operation descriptor.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ArgumentEditor {
-    /// Opaque interface reference selected for the call.
+    /// Exact Entry target selected when editing began; never read from display text.
-    pub interface: String,
+    pub path: String,
    /// Structured interface reference selected for the call.
    pub interface: InterfaceReference,
    /// Selected operation declaration.
    pub operation: OperationDeclaration,
    /// Complete descriptor used to resolve named types.
@@ -46,7 +50,7 @@ impl ArgumentEditor {
    /// Builds an editor whose fields preserve descriptor order.
    #[must_use]
    pub fn new(
-        interface: impl Into<String>,
+        interface: InterfaceReference,
        descriptor: InterfaceDescriptor,
        operation: OperationDeclaration,
    ) -> Self {
@@ -66,7 +70,8 @@ impl ArgumentEditor {
            })
            .collect();
        Self {
-            interface: interface.into(),
+            path: "/".into(),
            interface,
            operation,
            descriptor,
            fields,
@@ -74,6 +79,13 @@ impl ArgumentEditor {
        }
    }
    /// Fixes the Entry target for the editor and subsequent confirmation.
    #[must_use]
    pub fn for_target(mut self, path: impl Into<String>) -> Self {
        self.path = path.into();
        self
    }
    /// Moves to the preceding field without wrapping.
    pub fn previous_field(&mut self) {
        self.cursor = self.cursor.saturating_sub(1);
@@ -466,6 +478,12 @@ fn json_to_untyped(json: &serde_json::Value, field: &str) -> Result<Value, Strin
 #[cfg(test)]
 mod tests {
    fn root_reference(name: &str) -> wip_protocol::InterfaceReference {
        wip_protocol::InterfaceReference {
            scope: "/".into(),
            name: name.into(),
        }
    }
    use super::*;
    use wip_protocol::{
        EnumCase, FieldDeclaration, INTERFACE_FORMAT_V1, ParameterDeclaration, ReturnDeclaration,
@@ -560,7 +578,7 @@ mod tests {
            }],
        );
        let operation = descriptor.operations[0].clone();
-        let mut editor = ArgumentEditor::new("test", descriptor, operation);
+        let mut editor = ArgumentEditor::new(root_reference("test"), descriptor, operation);
        let inputs = [
            "null",
            "true",
@@ -595,7 +613,7 @@ mod tests {
            vec![],
        );
        let operation = descriptor.operations[0].clone();
-        let mut editor = ArgumentEditor::new("test", descriptor, operation);
+        let mut editor = ArgumentEditor::new(root_reference("test"), descriptor, operation);
        editor.fields[1].input = "not-a-bool".into();
        assert_eq!(editor.validate(), Err(InvalidArguments));
        assert!(
@@ -1,10 +1,19 @@
 //! Presentation and terminal interaction for stateful WIP client sessions.
 //!
 //! Interface identity is a structured `wip_protocol::InterfaceReference` with an
 //! explicit absolute scope. Display-only [`mod@reference`] labels safely quote
 //! `scope::interface#operation`; shortened labels are never parsed for calls.
 //! This breaks the former string-reference Rust API and follows the scoped HTTP
 //! wire format. Ref and validator preconditions remain private Client metadata.
 //! Editors retain their selected Entry target and are retired when the Client's
 //! Object/Interface snapshots change; reobservation never executes an operation.
 #![deny(missing_docs)]
 pub mod app;
 pub mod config;
 pub mod editor;
 pub mod reference;
 pub mod render;
 pub mod runtime;
 pub mod terminal;
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Hare	eb92878e3c	feat: support typed in-process WIP clients without HTTP	2026-10-16 05:26:11 +09:00
Hare	53fa44da26	fix: correct protocol name in Rust documentation	2026-10-15 17:53:48 +09:00
Hare	3c3edf4c6f	chore: prepare 0.2.0 release	2026-10-09 00:35:06 +09:00
Hare	1cbe03b49e	feat: expose typed Text View tokens and plain-text conversion T-28: generate owned semantic tokens directly from Object/Interface structure, including all escaped data and layout. Preserve render APIs through the same token generation and delimiter-free concatenation; preserve input limits, validation order and errors. Document splitting, semantic roles and destination escaping boundaries. Validation: cargo fmt --all -- --check; cargo check --workspace --all-targets; cargo test --workspace (312 passing tests/doctests, including 16 Text View consumer tests and 4 Text View/README doctests); nix develop --command cargo clippy --workspace --all-targets -- -D warnings; RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps; RUSTDOCFLAGS="-D warnings" cargo test -p wip-text-view -p wip-protocol --doc; git diff --check. All passed. Existing golden files unchanged; every prior Text View case now verifies token/plain/direct equality or exact error equality. No existing crates depend on wip-text-view; full workspace validation covers adjacent consumers.	2026-10-08 18:27:04 +09:00
Hare	26cba3398f	feat: add standalone WIP Text View signatures Render one Object or paired Interface entity without path/context, lookups or wire-schema changes. Preserve declarations, summaries, optional/unit and empty distinctions; validate protocol semantics and bounded input before rendering. Add five spec/nested goldens and 13 external API tests plus a standalone doctest. Validation: cargo fmt --all -- --check; cargo check --workspace --all-targets; cargo test --workspace --all-targets; cargo test --workspace --doc; nix develop -c bash (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. All passed. Default shell lacks clippy; declared Nix dev shell supplied it.	2026-10-08 17:50:16 +09:00
Hare	d58809bdbc	docs: describe scoped consumer API and wire migration Document FS lifetime attestation and explicit names, structured TUI identity versus qualified display, optional scope refs and real HTTP conformance coverage. Acceptance suite passes including workspace docs with -D warnings.	2026-10-08 04:03:51 +09:00
Hare	84cb5904df	feat(tui): reconcile scoped selection and publication lifetimes Reuse canonical escaped absolute reference labels; retain structured operation selection across loading and row movement. Freeze editor targets and retire confirmation on Client observation invalidation. Mirror retained stale/loading Object, tree and Interface state without ref fabrication or automatic execution. Validation: 36 TUI unit tests, real filesystem HTTP workflow, 8 formatter and 6 asynchronous runtime tests, and 2 doc-tests pass. Full workspace fmt/check/all-target tests/doc-tests, Nix clippy -D warnings, rustdoc -D warnings, public example and diff check pass. Scoped regressions cover same-name dispatch, stale/ref-less/replaced/deleted scopes, old in-flight contexts and selective typed-entry observation.	2026-10-08 04:03:51 +09:00
Hare	fc52d72a01	test(public-api): exercise scoped lifetimes across real HTTP Construct example calls from fetched structured identity and scope_ref. Add exhaustive public DTO coverage and a transactional external-style provider over TCP to exercise root/self scopes, equal names in distinct scopes, optional and stale refs, deletion/republication, visibility, validator precedence and non-retry of unknown outcomes. Validation: cargo test -p wip-public-api-example (9 DTO/example tests, 4 real TCP conformance tests); Nix clippy --all-targets -D warnings.	2026-10-08 03:56:24 +09:00
Hare	a7186173b4	feat(fs): bind external scopes to current execution lineage Add fail-closed Composition lifetime attestation for non-root scopes; preserve pinned deployment-root semantics and principal visibility. Fetch and dispatch bind optional published scope refs inside the refreshed backend boundary. Validation: cargo test -p wip-fs-server (25 unit, 8 HTTP, 31 extension tests and 1 doc-test); Nix clippy for FS and public example with -D warnings; git diff --check.	2026-10-08 03:56:17 +09:00
Hare	827bef8478	feat: integrate approved client scope lifetimes	2026-10-08 03:38:00 +09:00
Hare	b2be41d540	fix: retain observed scope bindings through client refresh states Address MR review sequence 5: retain last accepted Object-ref evidence during loading, ordinary staleness and retrieval failure. Mark confirmed path unavailability separately within bounded Entry records so old lifetime evidence cannot contaminate republished ref-less descriptors. Compare retained Object refs on later replacement even when newer Interface ownership previously suppressed an older scope observation. Add accepted-descriptor and pending-first-fetch old-to-new/ref-loss matrices during Loading/Error, edge-stale evidence, and confirmed-deletion/republication/reset tracking regressions. Validation: 50 runtime + 13 adapter tests; narrow Protocol/HTTP; workspace check/tests/all-target tests; Nix Clippy -D warnings; warning-free rustdoc; fmt/diff checks.	2026-10-08 03:29:35 +09:00
Hare	cc0ec0ccc8	feat: integrate approved Host scope lifetimes	2026-10-08 03:28:07 +09:00
Hare	755e6aeb88	feat: bind Host interfaces to scope Object lifetimes Register explicit scope/name coordinates independently of Definition type. Require provider-attested current scope snapshots for fetch and dispatch, compare optional scope_ref at membership precedence, and retain the same Descriptor through result validation. Migrate FS pinned-root boundaries and public self-scope example; document provider atomicity/lifecycle and root-only FS support. Add lifecycle, ref, replacement-race, root-lineage and compile-time exposure regressions. Validation: cargo fmt --all --check; git diff --check; cargo check --workspace --all-targets; cargo test --workspace --all-targets and --doc (232 passing test-harness cases including doctests); nix develop --command cargo clippy --workspace --all-targets -- -D warnings; RUSTDOCFLAGS=-Dwarnings cargo doc --workspace --no-deps. Narrow wip-host suite also passed.	2026-10-08 03:18:13 +09:00
Hare	fe6dccda83	fix: propagate scope lifetime evidence across client observations Address MR review sequence 3: share accepted Scope Object binding evidence across Interface names, supersede older fetches on binding change/loss, and track separately observed Object refs even when Descriptor scope_ref is omitted. Private evidence stays bounded to Interface records and never replaces optional wire/call metadata; corroborated same-lifetime immutability remains enforced. Add six regressions covering sibling name updates/ref loss, first-fetch stale responses, omitted scope_ref with Object-ref replacement/loss, out-of-order evidence, eviction, immutable in-flight results and same-lifetime metadata changes. Validation: 47 runtime + 13 adapter tests; narrow Protocol/HTTP; workspace check/tests/all-target tests; Nix Clippy -D warnings; warning-free docs; fmt/diff checks.	2026-10-08 03:16:58 +09:00
Hare	8b8041cba1	feat: bind client interface cache to scope lifetimes Retire lost scope bindings and confirmed deleted scope caches without confusing edge omission or local eviction with deletion. Preserve immutable call snapshots, same-lifetime Descriptor checks, and newer fetch ownership while recovering both observations after InterfaceMismatch. Validation: 41 runtime + 13 adapter tests; client/protocol/HTTP tests; workspace check, tests and all-target tests; Nix workspace Clippy -D warnings; warning-free workspace rustdoc; format and diff checks.	2026-10-08 02:59:59 +09:00
Hare	4544bc0d8b	feat: add scoped reference formatters for the TUI Follow Text View reference notation with component quoting and complete JSON/control/bidi safety escapes. Keep protocol reference pairs and operation names separate from display labels; screen integration remains T-23. Validated: cargo fmt --all --check; cargo check -p wip-tui --all-targets; cargo test -p wip-tui -p wip-protocol -p wip-client (99 tests incl. doctests); nix develop --command cargo clippy -p wip-tui --all-targets -- -D warnings; RUSTDOCFLAGS=-Dwarnings cargo doc -p wip-tui --no-deps; git diff --check.	2026-10-08 02:56:26 +09:00
Hare	8ecc307fc9	feat: migrate protocol and HTTP to structured interface references T-20: identify interfaces by exact scope/name pairs; add optional opaque scope_ref metadata and separate shape validation from path-dependent scope compatibility. Preserve call error precedence, strict JSON, validators and transport boundaries. Mechanically migrate consumers and document API/wire compatibility and deferred lifecycle semantics. Validation: cargo fmt --all --check; git diff --check; cargo check --workspace --all-targets; cargo test -p wip-protocol -p wip-http; cargo test --workspace (221 passing tests including doctests); cargo test --workspace --all-targets; nix develop --command cargo clippy --workspace --all-targets -- -D warnings; RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps. All pass. cargo/rustc 1.95.0; development-shell Clippy/rustc 1.97.1.	2026-10-07 18:29:51 +09:00
Hare	bf5fa54f44	fix: validate resolved ancestry inside atomic projection dispatch Resolve one connected lineage and retain its root-to-parent capabilities. Backends validate ancestor identity/membership and refresh all policy metadata inside the same boundary as target validators and typed dispatch; hidden/replaced ancestors reject as NotFound without invocation or effects. Preserve pinned leaf and configured-root capabilities. Covers MR ANCESTOR_VISIBILITY_TOCTOU with HTTP memory and Linux replacement/budget/guard regressions; all T-19 workspace acceptance commands pass (Clippy via Nix shell).	2026-10-06 20:21:15 +09:00
Hare	c6528c2887	test: verify filesystem extension and principal security contracts Add 21 independent memory-backend external-style tests, both principal HTTP flows, atomic validator/target/effect checks, budgets and sanitized failures; document migration and implementer responsibilities. All T-19 acceptance commands pass; Clippy runs in the repository Nix development shell.	2026-10-06 18:12:05 +09:00
Hare	b196047b57	feat: expose extensible filesystem projection engine Separate pinned Linux backend, typed composition, coherent principal policy views and standard HTTP adapter. Refresh validators inside serialized execution and preserve default listener and effect boundaries. Linux/adapter and real-listener regressions pass.	2026-10-06 18:12:05 +09:00
Hare	ea49cb0586	feat: add principal-scoped typed publication views Restrict interface order and operation descriptors without changing registry artifacts or dispatch codecs; prune hidden-only types/docs and support typed pre-dispatch provider rejection. Validated host contracts and the dependent workspace suite for T-19.	2026-10-06 18:12:05 +09:00
Hare	da559de912	docs: document 0.1.0 crate release	2026-10-02 19:46:08 +09:00
Hare	193ca89d93	chore: prepare crates.io package metadata	2026-10-02 19:45:58 +09:00
Hare	dc9a7f0dbf	feat: remove retrieval batch over HTTP	2026-10-02 15:00:50 +09:00
Hare	3c4dbf3ad0	fix: use typed method allowance	2026-10-02 06:56:42 +09:00
Hare	df006ee706	fix(http): separate transport and protocol limits	2026-10-02 02:50:56 +09:00
Hare	65c51006ad	Correct filesystem listener transport rustdoc	2026-10-02 02:26:49 +09:00
Hare	55c784c22d	Rename transport binding to WIP over HTTP	2026-10-02 02:22:17 +09:00
Hare	511e9fef9f	feat: prefetch visible interface descriptors	2026-10-01 08:58:25 +09:00
Hare	06edf62d4e	feat: prefetch visible observation frontier	2026-09-30 19:26:50 +09:00
Hare	ea7b0f00ea	feat: unify object observation API	2026-09-30 18:19:12 +09:00
Hare	2e4196a1ec	fix: keep object observations fresh after successful calls	2026-09-30 13:44:54 +09:00