# Contract: `Edit-PersonaEngineConfig.ps1`

Configuration validation, interactive editing, synthetic rule testing, and pipeline enforcement
(FR-023 – FR-026).

## Signature

```powershell
[CmdletBinding(SupportsShouldProcess = $true)]
param(
    [Parameter(Mandatory)][string] $ConfigPath,
    [Parameter()][switch] $ValidateOnly,
    [Parameter()][switch] $NonInteractive,
    [Parameter()][string] $SchemaPath,
    [Parameter()][string] $OutputPath,
    [Parameter()][switch] $TreatWarningsAsErrors,
    [Parameter()][string] $TestDataPath
)
```

## Parameter contract

| Parameter | Behaviour |
| --- | --- |
| `-ConfigPath` | Required. Configuration to validate or edit. |
| `-ValidateOnly` | Validate and report; never enter the editor. |
| `-NonInteractive` | Pipeline mode. **MUST NOT prompt and MUST NOT hang** (SC-010). Returns an exit code. |
| `-SchemaPath` | Override the shipped schema. |
| `-OutputPath` | Save-As target; leaves the input file untouched. |
| `-TreatWarningsAsErrors` | Escalates `Warning` findings to blocking (VR-005). |
| `-TestDataPath` | Synthetic sample users for offline rule testing (FR-025). No tenant connectivity. |

## Validation layers (VR-001, ordered, fail-fast between layers)

| Layer | Mechanism | Example findings |
| --- | --- | --- |
| 1. Syntax | `ConvertFrom-Json` | Malformed JSON |
| 2. Schema | `Test-Json -SchemaFile` (draft-07, OTD-005) | Missing required field, wrong type, bad enum |
| 3. Semantic | PowerShell checks | Every condition in VR-002 |
| 4. Safety | PowerShell checks | Every condition in VR-003 |

A layer that produces `Error` findings stops the sequence — running semantic checks over a
structurally invalid document yields noise, not signal.

### Layer 2 error-handling requirement

`Test-Json` reports schema failure by writing errors rather than returning `$false` in several
PowerShell versions. The wrapper MUST invoke it with `-ErrorAction SilentlyContinue -ErrorVariable`
and convert collected errors into `ValidationFinding` objects, so layer 2 emits the same structured
shape as every other layer (VR-004).

## Finding contract

Every finding carries `Severity`, `Code`, `Location` (JSON path or rule ID), `Description`,
`SuggestedResolution`, and `Layer`. Finding codes are stable and namespaced by layer:

```text
PE-SYN-nnn   syntax
PE-SCH-nnn   schema
PE-SEM-nnn   semantic  (one code per VR-002 condition)
PE-SAF-nnn   safety    (one code per VR-003 condition)
```

Stability matters: pipelines and runbooks will match on these codes.

## Exit codes

| Code | Condition |
| --- | --- |
| `0` | Valid; no blocking findings |
| `1` | One or more `Error` findings |
| `2` | `Warning` findings present with `-TreatWarningsAsErrors` |
| `3` | Configuration file not found or unreadable |
| `4` | Schema file not found or itself invalid |

## Save contract (FR-026)

1. Re-validate the edited document in full.
2. Block the save on any `Error` finding.
3. Write a timestamped backup — or require `-OutputPath` — before replacing an existing file.
4. Overwriting the only valid configuration without a backup is a safety finding (VR-003), not
   merely a warning.

## Invariants (test-asserted)

| Invariant | Assertion |
| --- | --- |
| Non-interactive never prompts | Runs to completion with stdin closed; no prompt, no hang (SC-010) |
| Every VR-002/VR-003 condition detected | One test per condition, each asserting code, severity, and location (SC-009) |
| Offline | Full validation and synthetic rule testing complete with no network access (SC-008) |