Add refactoring contract, terminology and behavior map

2026-10-29 22:26:25 +02:00
parent 23d6180f24
commit ede45d224a
4 changed files with 689 additions and 4 deletions
@@ -7,6 +7,44 @@ Terminology for managing device access to a WireGuard VPN.
 **Draft**:
 Changes prepared by the administrator but not yet saved through Commit.

+**Saved state**:
+The installed settings, server configuration, internal metadata, and encrypted
+vault after Commit or restoration. Saved state may differ from the running VPN.
+
+**Applied state**:
+Current knowledge that the running interface has been verified against the
+saved peer configuration. A saved file, a successful historical restart, or a
+handshake alone does not establish current applied state. After reopening, the
+current state is unknown until checked again.
+
+**Server peer record**:
+A `[Peer]` section in the authoritative server configuration, including its
+routes, comments, and any detected issues. A malformed record may have no usable
+public key and must remain available for inspection.
+
+**Manageable client**:
+A server peer that can be represented by the supported client fields and
+identified unambiguously by its public key for an allowed management action.
+Some valid peer records, such as peers with subnet routes, remain verifiable
+without being manageable.
+
+**Runtime observation**:
+A read-only measurement of the running interface and its peers, such as routes,
+last handshake, or current traffic counters. Missing observations are unknown or
+unavailable; they do not imply zero traffic or successful application.
+
+**Reserved address**:
+An address retained so that it cannot be assigned to another client while a
+deleted peer may still exist on the running interface. It is released only
+after the saved peer set is successfully verified as applied.
+
+**First delivery**:
+The one-time, password-free delivery of a newly created client's connection
+file after Commit in the same creation session. A failed file write can be
+retried in that session; later delivery requires the vault password. Until the
+saved configuration is verified as applied, delivery does not establish VPN
+access.
+
 **Commit**:
 Saving prepared changes without applying them to the running VPN.

@@ -23,5 +61,8 @@ _Avoid_: User, account
 **Client alias**:
 An administrator-friendly name for a client. A client is identified by its public key rather than its alias.

+An existing client's creation date remains unknown unless it is present in its
+managed metadata; an unknown date is not filled in with an estimated value.
+
 **Anomalous client record**:
 A record with only a server configuration entry or only a client connection file, without its corresponding counterpart. Records are matched by public key and are not automatically repaired when discovered.