From 7673969176123fa22244b792e176a353eb2f38d7 Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Wed, 1 Apr 2026 01:58:16 +0000
Subject: [PATCH] add development conventions

---
 CONVENTIONS.md | 184 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 CONVENTIONS.md

diff --git a/CONVENTIONS.md b/CONVENTIONS.md
new file mode 100644
index 0000000..b2d14e3
--- /dev/null
+++ b/CONVENTIONS.md
@@ -0,0 +1,184 @@
+# Yonexus.Server — Development Conventions
+
+This document defines implementation conventions for the server repository.
+
+## 1. Naming Conventions
+
+### Files
+- use `camelCase.ts` for source files
+- use descriptive module names matching responsibility
+- avoid generic names like `utils.ts` unless the scope is extremely narrow and justified
+
+Examples:
+- `registry.ts`
+- `pairing.ts`
+- `heartbeat.ts`
+- `onGatewayStart.ts`
+
+### Types / Interfaces
+- use `PascalCase`
+
+Examples:
+- `ClientRecord`
+- `PairingState`
+- `ServerRuntime`
+
+### Functions
+- use `camelCase`
+
+Examples:
+- `loadRegistry`
+- `verifyAuthProof`
+- `sendPairingNotification`
+
+### Constants
+- use `UPPER_SNAKE_CASE` for exported constants
+
+Examples:
+- `HEARTBEAT_INTERVAL_MS`
+- `AUTH_WINDOW_SECONDS`
+
+---
+
+## 2. Module Boundaries
+
+### `plugin/index.ts`
+- wiring only
+- no business logic
+
+### `plugin/core/`
+- reusable domain logic
+- state transitions
+- validation
+- auth/pairing/heartbeat rules
+
+### `servers/`
+- network/runtime bootstrapping
+- WebSocket transport lifecycle
+- active connection management
+
+### `plugin/hooks/`
+- OpenClaw lifecycle integration
+- should call into core/runtime modules, not reimplement logic
+
+### `plugin/tools/`
+- thin wrappers over core/runtime capabilities
+- do not duplicate business rules already implemented in core
+
+### `plugin/commands/`
+- operator-facing orchestration layer
+- no core logic duplication
+
+---
+
+## 3. Error Conventions
+
+### Error Shape
+Use structured errors rather than throwing untyped strings.
+
+Recommended shape:
+
+```ts
+interface YonexusServerError extends Error {
+  code: string;
+  details?: Record<string, unknown>;
+}
+```
+
+### Error Code Style
+- uppercase snake case
+- stable once published in logs/tools/docs
+
+Examples:
+- `INVALID_CONFIG`
+- `IDENTIFIER_NOT_ALLOWED`
+- `PAIRING_EXPIRED`
+- `NONCE_COLLISION`
+
+### Error Messages
+- concise
+- operator-readable
+- do not leak secrets, tokens, raw proofs, or private internal state
+
+---
+
+## 4. Logging Conventions
+
+### General Rule
+Logs should be useful for operators and safe for production.
+
+### Must Never Log in Plaintext
+- `notifyBotToken`
+- client `secret`
+- raw pairing code after issuance
+- raw signed proof payload
+- any private key material
+
+### Preferred Log Fields
+When possible, log structured context such as:
+- `identifier`
+- event type
+- status transition
+- reason code
+- timestamp
+
+### Example Good Logs
+- `pairing started for identifier=client-a`
+- `auth failed for identifier=client-a reason=NONCE_COLLISION`
+- `status changed identifier=client-a online->unstable`
+
+---
+
+## 5. Protocol Usage Conventions
+
+- treat `protocol/` submodule as the source of truth
+- do not fork protocol semantics locally without updating `Yonexus.Protocol`
+- if implementation pressure suggests protocol change, change protocol repo first or in the same coordinated step
+
+---
+
+## 6. Persistence Conventions
+
+- prefer explicit versionable JSON structures for initial persistence
+- keep persisted schema clear and documented
+- do not mix transient socket/session state into long-lived persisted records unless intentional
+- keep rolling replay/rate-limit windows separate from durable trust records where practical
+
+---
+
+## 7. State Machine Conventions
+
+- keep state transitions explicit
+- avoid hidden/implicit mutations across unrelated modules
+- centralize transitions for pairing/auth/liveness when possible
+- treat `re_pair_required` as a first-class transition, not an ad-hoc side effect
+
+---
+
+## 8. Command / Tool Conventions
+
+- commands and tools should surface operator-safe summaries
+- raw internal state should be exposed carefully
+- commands should call core/runtime services, not manipulate registry internals directly
+
+---
+
+## 9. Testing Conventions
+
+- write narrow unit tests for deterministic logic first
+- reserve integration tests for protocol flow and socket lifecycle
+- test negative paths deliberately:
+  - invalid pairing code
+  - stale timestamp
+  - nonce collision
+  - excessive handshake attempts
+  - heartbeat timeout
+
+---
+
+## 10. Change Discipline
+
+When implementing:
+- update docs when architecture/protocol behavior changes
+- avoid silent divergence from `PLAN.md`, `TASKS.md`, and `protocol/PROTOCOL.md`
+- prefer fewer clear modules over many shallow wrappers