Milestone 5

docs/config-schema.md

@@ -0,0 +1,97 @@
+# Warppipe Configuration Schema
+
+Warppipe uses JSON for configuration persistence. The config file stores virtual nodes and routing rules using stable identifiers (names, not serial IDs).
+
+## Schema Version 1
+
+```json
+{
+  "version": 1,
+  "virtual_nodes": [
+    {
+      "name": "warppipe-gaming-sink",
+      "is_source": false,
+      "rate": 48000,
+      "channels": 2,
+      "loopback": false,
+      "target_node": ""
+    },
+    {
+      "name": "warppipe-mic-source",
+      "is_source": true,
+      "rate": 48000,
+      "channels": 2,
+      "loopback": false,
+      "target_node": ""
+    },
+    {
+      "name": "warppipe-loopback",
+      "is_source": false,
+      "rate": 48000,
+      "channels": 2,
+      "loopback": true,
+      "target_node": "alsa_output.pci-0000_00_1f.3.analog-stereo"
+    }
+  ],
+  "route_rules": [
+    {
+      "match": {
+        "application_name": "Firefox",
+        "process_binary": "firefox",
+        "media_role": ""
+      },
+      "target_node": "warppipe-gaming-sink"
+    },
+    {
+      "match": {
+        "application_name": "discord",
+        "process_binary": "",
+        "media_role": "Communication"
+      },
+      "target_node": "alsa_output.usb-headset"
+    }
+  ]
+}
+```
+
+## Field Descriptions
+
+### virtual_nodes
+
+- `name` (string, required): Unique node name (PW_KEY_NODE_NAME)
+- `is_source` (boolean, required): true for Audio/Source, false for Audio/Sink
+- `rate` (integer, default 48000): Sample rate in Hz
+- `channels` (integer, default 2): Channel count
+- `loopback` (boolean, default false): Whether node forwards to a target
+- `target_node` (string, optional): Required when loopback is true
+
+### route_rules
+
+Rules match ephemeral audio sources to target sinks by stable application metadata.
+
+- `match.application_name` (string): Match PW_KEY_APP_NAME
+- `match.process_binary` (string): Match PW_KEY_APP_PROCESS_BINARY
+- `match.media_role` (string): Match PW_KEY_MEDIA_ROLE
+- `target_node` (string, required): Destination node name
+
+All non-empty match fields must match (AND logic). At least one match field must be non-empty.
+
+## Persistence Behavior
+
+- **Auto-save**: When `ConnectionOptions::config_path` is set, config is saved after:
+  - Virtual node created/removed
+  - Routing rule added/removed
+
+- **Load on startup**: When `config_path` is set and the file exists, it is loaded during `Client::Create()` after connection is established.
+
+- **Manual**: `SaveConfig(path)` and `LoadConfig(path)` work independently of auto-save.
+
+- **Atomic writes**: Saves write to a `.tmp` file first, then rename for crash safety.
+
+## Error Handling
+
+- Missing config file on auto-load: Silently ignored (fresh start)
+- Invalid JSON syntax: `StatusCode::kInvalidArgument` with parse error details
+- Missing version field: `StatusCode::kInvalidArgument`
+- Empty path: `StatusCode::kInvalidArgument`
+- File not found on manual load: `StatusCode::kNotFound`