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

48
PLAN.md
View File

@@ -124,6 +124,22 @@ Semantics:
---
## 4.4 Shared Terminology Baseline
These names are normative across umbrella docs, protocol docs, and implementation repos:
- `identifier`: the unique logical name of a client/follower instance.
- `rule_identifier`: the exact-match application route key.
- `builtin`: reserved rule namespace for protocol/system frames.
- `pairingCode`: short-lived out-of-band code delivered to the human admin.
- `secret`: server-issued shared secret used for reconnect proof construction.
- `publicKey` / `privateKey`: client-held signing keypair.
- `nextAction`: server-directed next step returned by `hello_ack`.
Implementations should avoid introducing alternative synonyms for these fields unless there is a versioned migration plan.
---
## 5. Runtime Lifecycle
## 5.1 Yonexus.Server Startup
@@ -551,25 +567,39 @@ Not required in the first version unless explicitly added later:
- direct client-to-client sockets
- multi-server clustering
- distributed consensus
- offline message queues or guaranteed delivery to disconnected clients
- advanced rule matching beyond exact string match
- message ordering guarantees across reconnects
- end-to-end payload encryption beyond the pairing/authentication requirements
- management UI
- admin-side approve/deny control plane beyond human relay of pairing codes
- encryption-at-rest hardening beyond documenting current local storage limitations
---
## 16. Open Questions To Confirm Later
## 16. v1 Decisions Locked for Current Implementation
1. Exact signing algorithm:
- Ed25519 is a strong default candidate
2. Should `mainHost` accept only full WebSocket URLs or also raw `ip:port` strings?
3. Is human code relay sufficient for v1 pairing, or should admin approve/deny controls be added later?
4. On unsafe condition, should the old public key be retained or should the client generate a new keypair?
5. Should offline clients support queued outbound messages from server, or should sends fail immediately?
6. Are rule identifiers exact strings only, or should regex/prefix matching exist later?
The following implementation-boundary decisions are now treated as settled for v1:
1. Signing algorithm default: Ed25519.
2. `mainHost` should be configured as a full `ws://` or `wss://` URL in v1.
3. Human relay of the pairing code is sufficient for v1; richer admin approve/deny control can wait.
4. `heartbeat_ack` remains optional.
5. Client reconnect uses exponential backoff.
6. Rule identifiers are exact-match strings only in v1.
7. Outbound sends to offline clients fail immediately rather than queueing.
## 17. Open Questions To Confirm Later
1. On unsafe condition, should the old public key be retained or should the client generate a new keypair?
2. Should future versions support explicit key rotation without full re-pairing?
3. Should offline clients support queued outbound messages from server in a later version?
4. Are richer admin approval workflows worth adding after v1 stabilizes?
5. Should encryption-at-rest become a hard requirement in v2?
---
## 17. Immediate Next Deliverables
## 18. Immediate Next Deliverables
After this plan, the next files to create should be:
- `FEAT.md` — feature checklist derived from this plan