docs: lock v1 scope and terminology

This commit is contained in:
nav
2026-04-09 02:33:21 +00:00
parent 8b5a8efe9a
commit 6f164db7f8
6 changed files with 149 additions and 16 deletions

View File

@@ -26,6 +26,22 @@ Important security rule:
---
## 1.1 Canonical Terminology
These names are treated as protocol-level canonical terms:
- `identifier`: unique logical identity of a Yonexus client instance.
- `rule_identifier`: exact-match routing key for application messages.
- `builtin`: reserved protocol namespace used only for Yonexus control frames.
- `pairingCode`: short-lived out-of-band code generated by the server for human-mediated pairing.
- `secret`: server-issued shared secret used in reconnect authentication proof construction.
- `publicKey` / `privateKey`: client signing keypair.
- `nextAction`: the server's directed next step in `hello_ack`.
The protocol and implementation repos should prefer these exact names over synonyms.
---
## 2. Transport
Transport is WebSocket.
@@ -35,13 +51,12 @@ Transport is WebSocket.
- protocol frames are UTF-8 text in v1
- binary frames are not required in v1
Client connects to configured `mainHost`, which may be:
Client connects to configured `mainHost`, which in v1 should be a full WebSocket URL:
- `ws://host:port/path`
- `wss://host:port/path`
- or raw `host:port` if normalized by implementation
Recommended canonical config:
- prefer full WebSocket URL
- require/prefer a full WebSocket URL in v1 rather than raw `host:port`
---
@@ -426,6 +441,9 @@ builtin::{
### `heartbeat_ack`
Optional response by `Yonexus.Server`.
v1 policy:
- `heartbeat_ack` may be enabled by the server but clients must not require it for healthy operation
Example:
```text
@@ -624,6 +642,9 @@ Dispatch algorithm:
4. invoke the first exact match
5. ignore/log if no match is found
v1 policy:
- rule matching is exact string match only; prefix, wildcard, and regex routing are out of scope
Processor input:
- on client: `${rule_identifier}::${message_content}`
- on server for client-originated messages: `${rule_identifier}::${sender_identifier}::${message_content}`