Add v5 release notes

docs/developers/operations-api/databases-and-tables.md

@@ -26,7 +26,7 @@ Returns the definitions of all databases and tables within the database. Record
 		"dog": {
 			"schema": "dev",
 			"name": "dog",
-			"hash_attribute": "id",
+			"primary_key": "id",
 			"audit": true,
 			"schema_defined": false,
 			"attributes": [
@@ -82,7 +82,7 @@ Returns the definitions of all tables within the specified database.
 	"dog": {
 		"schema": "dev",
 		"name": "dog",
-		"hash_attribute": "id",
+		"primary_key": "id",
 		"audit": true,
 		"schema_defined": false,
 		"attributes": [
@@ -137,7 +137,7 @@ Returns the definition of the specified table.
 {
 	"schema": "dev",
 	"name": "dog",
-	"hash_attribute": "id",
+	"primary_key": "id",
 	"audit": true,
 	"schema_defined": false,
 	"attributes": [

docs/developers/operations-api/index.md

@@ -34,6 +34,7 @@ The operations API reference is available below and categorized by topic:
 - [Configuration](operations-api/configuration)
 - [Certificate Management](operations-api/certificate-management)
 - [Token Authentication](operations-api/token-authentication)
+- [Impersonation](../security/impersonation)
 - [SQL Operations](operations-api/sql-operations)
 - [Advanced JSON SQL Examples](operations-api/advanced-json-sql-examples)
 - [Analytics](operations-api/analytics)

docs/developers/replication/index.md

@@ -225,6 +225,23 @@ replication:
 
 When using controlled flow replication, you will typically have different route configurations for each node to every other node. In that case, typically you do want to ensure that you are _not_ replicating the `system` database, since the `system` database containes the node configurations, and replicating the `system` database will cause all nodes to be replicated and have identical route configurations.
 
+The `replicates` property also allows you to specify routes with more granularity by specifying `sendsTo` and/or `receivesFrom` properties, which each can have an array with node and database names.
+
+```yaml
+replication:
+  databases:
+    - data
+  routes:
+    - host: node-two
+      replicates:
+        sendsTo:
+          - target: node-three
+            database: data
+        receivesFrom:
+          - source: node-four
+            database: system
+```
+
 #### Explicit Subscriptions
 
 By default, Harper automatically handles connections and subscriptions between nodes, ensuring data consistency across your cluster. It even uses data routing to manage node failures. However, you can manage these connections manually by explicitly subscribing to nodes. This should _not_ be used for production replication and should be avoided and exists only for testing, debugging, and legacy migration. This will likely be removed in V5. If you choose to manage subscriptions manually, Harper will no longer handle data consistency for you. This means there’s no guarantee that all nodes will have consistent data if subscriptions don’t fully replicate in all directions. If a node goes down, it’s possible that some data wasn’t replicated before the failure. If you want single direction replication, you can use controlled replication flow described above.

docs/developers/security/impersonation.md

@@ -0,0 +1,154 @@
+---
+title: Impersonation
+---
+
+# Impersonation
+
+Impersonation allows a `super_user` to execute operations API requests as if they were a different, less-privileged user. This is useful for testing permissions, debugging access issues, and building admin tools that preview what a given user or role can see and do — all without needing that user's credentials.
+
+## How It Works
+
+Add an `impersonate` property to any operations API request body. Harper will authenticate the request normally (the caller must be a `super_user`), then **downgrade** the effective permissions for that request to match the impersonated identity.
+
+```http
+POST https://my-harperdb-server:9925/
+Authorization: Basic <super_user credentials>
+Content-Type: application/json
+
+{
+    "operation": "search_by_hash",
+    "database": "dev",
+    "table": "dog",
+    "hash_values": ["1"],
+    "impersonate": {
+        "username": "test_user"
+    }
+}
+```
+
+The request above runs the `search_by_hash` as if `test_user` had made it — subject to that user's role permissions.
+
+## Security Constraints
+
+- **Super user only** — only users with `super_user` permissions can use `impersonate`. All other users receive a `403` error.
+- **Downgrade only** — impersonation can never escalate privileges. The `super_user` and `cluster_user` flags are always forced to `false` on the impersonated identity.
+- **Audit trail** — every impersonated request is logged, recording who initiated the impersonation and which identity was assumed.
+
+## Impersonation Modes
+
+There are three ways to specify the impersonated identity, depending on what you want to test.
+
+### Impersonate an Existing User
+
+Provide a `username` to run the request with that user's current role and permissions.
+
+```json
+{
+    "operation": "search_by_hash",
+    "database": "dev",
+    "table": "dog",
+    "hash_values": ["1"],
+    "impersonate": {
+        "username": "test_user"
+    }
+}
+```
+
+The target user must exist and be active. If the user is not found, a `404` error is returned. If the user is inactive, a `403` error is returned.
+
+### Impersonate an Existing Role
+
+Provide a `role_name` to run the request with that role's permissions. You can optionally include a `username` to set the effective username (defaults to the caller's username).
+
+```json
+{
+    "operation": "search_by_value",
+    "database": "dev",
+    "table": "dog",
+    "search_attribute": "name",
+    "search_value": "Penny",
+    "impersonate": {
+        "role_name": "developer"
+    }
+}
+```
+
+The role must exist. If the role is not found, a `404` error is returned.
+
+### Impersonate with Inline Permissions
+
+Provide a `role` object with a `permission` property to test with an ad-hoc set of permissions. This is useful for previewing the effect of a role you haven't created yet.
+
+```json
+{
+    "operation": "sql",
+    "sql": "SELECT * FROM dev.dog",
+    "impersonate": {
+        "username": "preview_user",
+        "role": {
+            "permission": {
+                "dev": {
+                    "tables": {
+                        "dog": {
+                            "read": true,
+                            "insert": false,
+                            "update": false,
+                            "delete": false,
+                            "attribute_permissions": []
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+The `username` field is optional and defaults to the caller's username. The `permission` object follows the same structure as [role permissions](users-and-roles#role-permissions).
+
+You can also restrict the impersonated identity to a specific set of operations API calls using the `operations` field inside `permission`:
+
+```json
+{
+    "operation": "search_by_hash",
+    "database": "dev",
+    "table": "dog",
+    "hash_values": ["1"],
+    "impersonate": {
+        "role": {
+            "permission": {
+                "operations": ["read_only"],
+                "dev": {
+                    "tables": {
+                        "dog": {
+                            "read": true,
+                            "insert": false,
+                            "update": false,
+                            "delete": false,
+                            "attribute_permissions": []
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Impersonate Payload Reference
+
+| Field | Type | Description |
+|---|---|---|
+| `username` | string | Target username. Required for existing-user mode. Optional for role-based modes (defaults to the caller's username). |
+| `role_name` | string | Name of an existing role to assume. |
+| `role` | object | Inline role definition. Must include a `permission` object. |
+| `role.permission` | object | Permission object following the standard [role permissions](users-and-roles#role-permissions) structure. |
+
+Exactly one of `username` (alone), `role_name`, or `role` must be provided. If `role` is present, it takes precedence.
+
+## Use Cases
+
+- **Admin dashboards** — preview what a user sees without switching accounts.
+- **Permission testing** — verify that a role grants (or denies) the expected access before assigning it to users.
+- **Debugging** — reproduce access issues reported by a user by impersonating them directly.
+- **CI/CD** — automated tests can verify permission configurations by impersonating different roles against a single `super_user` credential.

docs/developers/security/index.md

@@ -21,3 +21,4 @@ Harper uses role-based, attribute-level security to ensure that users can only g
 
 - [Configuration](security/configuration) - Security configuration and settings
 - [Users and Roles](security/users-and-roles) - Role-based access control and permissions
+- [Impersonation](security/impersonation) - Execute operations as a different user or role