Update docs/samy.functions.md

docs/samy.functions.md

@@ -16,6 +16,9 @@ The goal of this file is to provide “daily driver” functions SAMY needs acro
 
 - Bootstrap
   - `Initialize-NuGetProvider`
+- Task + validation helpers
+  - `Test-ComputerName`
+  - `Get-TaskHandlerName`
 - Registry helpers
   - `Set-RegistryValueInHkuRoot`
   - `Set-RegistryValueForCurrentAndAllUsers`
@@ -64,6 +67,69 @@ Uses `Write-LogHybrid` with `-LogToEvent` to record bootstrap state and failures
 
 ---
 
+## Task + validation helpers
+
+### Test-ComputerName
+**Purpose**
+Validates a proposed computer name before applying it (typically from UI input).
+
+**Rules enforced**
+- Must not be null/empty/whitespace.
+- Must be **15 characters or fewer** (NetBIOS computer name limit).
+- Must match: `^[A-Za-z0-9-]+$` (letters, numbers, hyphen only).
+
+**Returns**
+- `$true` if name is valid
+- `$false` if name fails any rule
+
+**Where it’s used**
+- Typically in handlers such as rename/computer identity workflows, to prevent invalid names from being applied.
+
+**Maintenance notes**
+- If you want stricter rules (common):
+  - disallow leading or trailing hyphen
+  - disallow all-numeric names
+- Keep any rule changes consistent with your environment (AD join rules, naming standards, etc.).
+
+---
+
+### Get-TaskHandlerName
+**Purpose**
+Resolves the PowerShell function name that should execute for a given task object.
+
+This supports two patterns:
+1. **Explicit handler name** stored on the task object (preferred when set)
+2. **Convention-based handler name** derived from task `Name`
+
+**Resolution order**
+1. Checks the task object for one of these properties (first match wins):
+   - `HandlerFn`
+   - `Handler`
+   - `Fn`
+2. If none are present/usable, falls back to:
+   - `"Invoke-$Task.Name"`
+
+**Normalization**
+When a handler value is found:
+- Converts to string
+- Trims whitespace
+- Removes a leading `/` (in case the value is stored like a URL path)
+
+**Returns**
+- A string function name (e.g. `Invoke-RenameComputer`) when resolved
+- `$null` if no usable handler or name exists
+
+**Where it’s used**
+- The HTTP router / request dispatcher uses this to map a requested task route to the correct handler function.
+
+**Why it exists**
+- Allows tasks to follow a simple convention (`Invoke-<TaskName>`) while still supporting overrides for:
+  - legacy handler names
+  - special routing cases
+  - tasks that map to a shared/common handler
+
+---
+
 ## Registry Helpers
 
 ### Set-RegistryValueInHkuRoot