Implement typed RLV protocol parser (#78)

crates/libremetaverse-rlv/README.md

@@ -0,0 +1,73 @@
+# Native RLV protocol layer
+
+`libremetaverse-rlv` implements the side-effect-free protocol boundary for the
+Restrained Love Viewer support in the pinned LibreMetaverse snapshot. The
+parser converts one bounded chat message into typed commands. It does not
+mutate restrictions, move the camera, touch inventory, send replies, or invoke
+callbacks; those stateful responsibilities are separate milestone work that
+consumes this layer.
+
+## Message contract
+
+An input begins with `@` and contains at most 128 comma-separated commands in
+at most 64 KiB. A command is either the case-insensitive bare `clear` command,
+or has the form `behavior[:option]=parameter`. The first colon and first equals
+sign are structural. Empty commands, behavior names, or parameters are
+rejected.
+
+The parser preserves the original behavior and parameter spelling, option text,
+sender identity and name, and the exact byte span of each command. It also
+provides lowercase behavior and parameter fields for protocol dispatch. Option
+text is never globally trimmed or lowercased: folder paths, query separators,
+setting values, role names, and other opaque strings retain their bytes. Only
+an individual typed field applies the conversion required by the reference,
+such as case-insensitive attachment aliases or .NET-style whitespace trimming
+for a number.
+
+Parameters select one of three families:
+
+- `force` produces a typed `RlvAction` with validated UUID, numeric, folder,
+  attachment, wearable, setting, group, and teleport operands.
+- `n`/`add` and `y`/`rem` produce typed add/remove restrictions. The complete
+  table of 119 behavior spellings is exposed as `RLV_RESTRICTION_NAMES`.
+- a nonzero signed decimal channel produces a typed `RlvQuery`, including
+  camera, inventory, outfit, path, status, version, group, and environment
+  variants.
+
+Aliases remain explicit. `FarTouch` canonicalizes to `TouchFar` in a mapped
+`RlvRestriction`, while `OriginalBehavior` retains `FarTouch`. The 56 pinned
+attachment spellings and 16 wearable spellings are case-insensitive but are
+not whitespace-normalized. `root` maps to the avatar-center attachment point,
+matching the reference. Secure restriction exception rules and value-sensitive
+equality/hash behavior are implemented by the native mapped
+`RlvRestriction`; `RlvCommon` implements the last-recognized attachment tag
+rule used for inventory item names.
+
+## Errors and resource limits
+
+`RlvParseError` reports a stable `RlvParseErrorKind`, zero-based command index,
+and half-open byte span. Categories distinguish missing prefix or separators,
+empty fields, unknown actions/restrictions/queries, invalid UUIDs, numbers and
+typed options, zero query channels, and resource-limit failures. Parsing is
+linear in the message size after bounded command counting. It performs no I/O,
+does not wait, and does not retain references to caller input.
+
+The focused malformed corpus includes deterministic deletion, replacement, and
+insertion mutations of actions, restrictions, queries, UUIDs, aliases, and
+multi-command messages. Every mutation must return a value or a positioned
+error without panicking. The limits apply before large parser allocations.
+
+## Reproducible verification
+
+Run the issue-owned checks with one build job:
+
+```sh
+CARGO_BUILD_JOBS=1 cargo test -p libremetaverse-rlv --locked
+CARGO_BUILD_JOBS=1 cargo test -p libremetaverse-compat-tests --test rlv_common_semantics --locked
+CARGO_BUILD_JOBS=1 cargo clippy -p libremetaverse-rlv --all-targets --locked -- -D warnings
+RUSTDOCFLAGS='-D warnings' CARGO_BUILD_JOBS=1 cargo doc -p libremetaverse-rlv --no-deps --locked
+python3 tools/check_milestone_10_issue_78.py
+```
+
+These commands are cross-platform. The Gitea workflow runs the audit and
+workspace compile on `ubuntu-latest`.