fix: align protocol model with canonical WIP

crates/wip-protocol/src/lib.rs

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