CONTEXT.md

Ubiquitous Language

• Network quality detail (网络质量详情) — the per-server view of probe results (latency/loss per target, anomalies, traceroute). Since ADR-0001 it lives in the server detail Network tab; there is no separate admin page.
• Network tab — the server-detail tab hosting the network quality detail. Admin gets the full experience (chart, traceroute, target management, CSV export); the public status variant is the redacted summary (targets + anomalies only).
• Server detail tabs — the top-level structure of the server detail page: Metrics (default, includes the cost/traffic/uptime overview blocks), Network, Traffic, Security, IP Quality. Tab and time range are URL-driven (?tab=, ?range=); the range window is shared across tabs.
• Standalone public network page — /status/network/$serverId; exists only as a fallback for status pages configured with show_server_detail=false but show_network=true (see ADR-0001).
• Live metrics (实时指标帧) — the partial projection of a server carried by WS update frames: the fields an agent report can populate (usage, speeds, loads, connection counts), plus name kept purely for decoder compatibility. Static facts are absent from the wire; clients keep their cached values when merging (see ADR-0002). Avoid: partial status, update payload.
• Full server status — the complete ~35-field snapshot (ServerStatus) carried by full_sync and REST. The only sources allowed to seed the catalog or overwrite static facts (totals, os, tags, geo, enrollment).
• Rollup policy (降采样策略) — how raw metric records compress over time: per-column aggregation (AVG vs window MAX), the raw/hourly table switch point, and which columns alerts may read. Owned by service::rollup; declared per column in the metric column descriptor (see ADR-0003). Avoid: aggregation logic, downsampling code.
• Metric column descriptor — the one-row-per-column table (METRIC_COLUMNS) declaring a scalar metric's SQL name, rollup aggregation, alert rule type, and typed accessor. Adding a scalar metric means adding one descriptor row (plus entity/migration, which the compiler enforces). The web analogue is METRIC_CHART_SPECS for chart display.
• Enrollment code (Agent 注册码) — a short-lived, single-use credential bound to exactly one pre-created Server identity. Possession authorizes one Agent enrollment; the plaintext is shown only when the code is issued.
• Agent enrollment (Agent 注册) — the act of an Agent claiming the Server identity bound to an Enrollment code. The Agent durably stages its proposed run token before submitting the claim, so authority does not depend on receiving a once-only secret in the HTTP response. This claim protocol is a hard cut: requests without an Agent-generated run token are rejected rather than routed through a legacy server-generated-token adapter. Enrollment does not collect a machine fingerprint or discover, create, merge, or deduplicate Server identities from host-derived identifiers. Avoid: Agent fingerprint, fingerprint-based enrollment, legacy enrollment claim.
• Agent run token (Agent 运行令牌) — the persistent, per-Server credential authorizing an Agent to connect as that Server identity. The Agent generates and durably stages this high-entropy secret before enrollment; the Server accepts its hash atomically with the claim and never returns the plaintext. Re-enrollment replaces it; Agent authority revocation removes it.
• Agent authority (Agent 身份权限) — whether a Server identity is currently claimed by an Agent with a valid run token. It is either Claimed or Unclaimed, independently of whether that Agent is currently online. The Agent Authority module owns Enrollment offer transitions, run-token transitions, and the resulting connection-fencing request; it does not own Server onboarding, profile data, or online/offline connection state (see ADR-0004).
• Enrollment offer (Agent 注册许可) — the current opportunity to claim a Server identity with an Enrollment code. An offer begins Outstanding and ends in exactly one immutable outcome: Consumed, Revoked, Replaced, or Expired. Replacement identifies the successor offer; expiry takes effect from expires_at without requiring a background task. Terminal offers remain non-blocking enrollment history. Offer lifecycle is independent of Agent authority, so a Claimed or Unclaimed Server may each have an Enrollment offer.
• Enrollment offer replacement (注册码替换) — the explicit exchange of one Outstanding Enrollment offer for a new one. Replacement identifies the exact offer being superseded; a missing or stale identity is rejected instead of silently applying last-writer-wins.
• Pending Server (待接入服务器) — a UI projection for an Unclaimed Server identity, not a separate enrollment lifecycle state. Online and offline are connection facts outside the enrollment model.
• Server onboarding (Server 接入建档) — the atomic, request-idempotent creation of a new Server identity, its operator-supplied profile, its default monitoring configuration, and its first Enrollment offer. Retrying the same onboarding request identity with the same normalized input returns the same Server; reusing it with different input conflicts. Server onboarding composes enrollment but is not part of Agent enrollment itself.
• Agent re-enrollment (Agent 重新注册) — a new enrollment of an existing Server identity, used when an Agent must be reinstalled or replaced without creating another Server or losing its history. Re-enrollment is either graceful or emergency. Avoid: Agent recovery, recover.
• Graceful re-enrollment (平滑重新注册) — re-enrollment in which the current Agent remains authorized while the Enrollment code is outstanding. Consuming the code transfers authority to the newly enrolled Agent and immediately invalidates the previous run token and live connection.
• Emergency re-enrollment (紧急重新注册) — re-enrollment in which the current Agent's run token and live connection are invalidated when the Enrollment code is issued, leaving the Server unclaimed until that code is consumed.
• Agent authority revocation (Agent 身份权限撤销) — an operator action that removes the current Agent run token and fences its live connection, leaving the Server Unclaimed without creating an Enrollment offer. Restoring authority requires enrollment. Avoid: run-token rotation, token rotation.
• Agent authority event (Agent 身份权限事件) — an immutable, structured, secret-free record of an Enrollment offer or Agent authority transition, including its actor, Server snapshot, related offer, mode, request source, and time. The Agent Authority module commits the event atomically with the state transition; generic best-effort audit logs are not lifecycle history. Authority events survive Server deletion until an explicit audit-retention purge, while credential hashes and offer rows are deleted with the Server.
• Connection fencing (Agent 连接隔离) — the hard guarantee that an Agent whose authority was transferred or revoked can neither continue on its existing WebSocket nor enter through a handshake that raced with the transition. Agent Authority transitions and final WebSocket admission serialize through the same per-Server lock, and the token is revalidated immediately before admission. A transition reports success only after its durable state, authority event, and runtime fence are complete.