feat: formalize runbook topology contract (#1905)

Author: Agent Runner

docs/schemas/integration-runbook-v1.schema.json

@@ -26,11 +26,62 @@
             ]
           },
             "status": { "type": "string", "enum": ["Passed", "Failed", "Skipped"] },
-            "details": { "type": "object" }
+            "details": {
+              "type": "object",
+              "properties": {
+                "exitCode": { "type": ["integer", "null"] },
+                "error": { "type": "string" },
+                "loopIterations": { "type": "integer", "minimum": 0 },
+                "finalStatusPath": { "type": "string" },
+                "finalStatusReadError": { "type": "string" },
+                "finalStatusMissing": { "type": "boolean" },
+                "harness": {
+                  "type": "object",
+                  "properties": {
+                    "runtimeSurface": { "const": "windows-native-teststand" },
+                    "processModelClass": {
+                      "type": "string",
+                      "enum": ["sequential-process-model", "parallel-process-model"]
+                    },
+                    "windowsOnly": { "type": "boolean" },
+                    "requestedSimultaneous": { "type": "boolean" },
+                    "cellClass": { "type": ["string", "null"] },
+                    "executionCellLeasePath": { "type": "string" },
+                    "executionCellId": { "type": "string" },
+                    "executionCellLeaseId": { "type": "string" },
+                    "harnessInstanceLeasePath": { "type": "string" },
+                    "harnessInstanceLeaseId": { "type": "string" },
+                    "harnessInstanceId": { "type": "string" }
+                  },
+                  "additionalProperties": true
+                },
+                "executionTopology": {
+                  "type": "object",
+                  "properties": {
+                    "runtimeSurface": { "const": "windows-native-teststand" },
+                    "processModelClass": {
+                      "type": "string",
+                      "enum": ["sequential-process-model", "parallel-process-model"]
+                    },
+                    "windowsOnly": { "type": "boolean" },
+                    "requestedSimultaneous": { "type": "boolean" },
+                    "cellClass": { "type": ["string", "null"] },
+                    "executionCellLeasePath": { "type": "string" },
+                    "executionCellId": { "type": "string" },
+                    "executionCellLeaseId": { "type": "string" },
+                    "harnessInstanceLeasePath": { "type": "string" },
+                    "harnessInstanceLeaseId": { "type": "string" },
+                    "harnessInstanceId": { "type": "string" }
+                  },
+                  "additionalProperties": true
+                }
+              },
+              "additionalProperties": true
+            }
         },
         "additionalProperties": false
       }
     }
   },
   "additionalProperties": true
-}
+}

tests/IntegrationRunbook.Tests.ps1

@@ -11,6 +11,7 @@ Describe 'IntegrationRunbook - Phase Selection & JSON' -Tag 'Unit' {
     $global:runRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
     $global:runScript = Resolve-Path $scriptPath
     $global:schemaFile = Resolve-Path $schemaPath
+    . "$PSScriptRoot/TestHelpers.Schema.ps1"
   }
 
   It 'emits JSON with expected schema id and core properties (subset phases)' {
@@ -31,6 +32,7 @@ Describe 'IntegrationRunbook - Phase Selection & JSON' -Tag 'Unit' {
     Test-Path $tmp | Should -BeTrue
     $json = Get-Content $tmp -Raw | ConvertFrom-Json
     $json.schema | Should -Be 'integration-runbook-v1'
+    Assert-JsonShape -Path $tmp -Spec 'IntegrationRunbook' | Should -BeTrue
     $json.phases.Count | Should -Be 2
     ($json.phases | ForEach-Object name) | Should -Be @('Prereqs','ViInputs')
     $json.overallStatus | Should -Match 'Passed|Failed'
@@ -166,6 +168,7 @@ exit 0
 
     Test-Path $tmp | Should -BeTrue
     $json = Get-Content $tmp -Raw | ConvertFrom-Json
+    Assert-JsonShape -Path $tmp -Spec 'IntegrationRunbook' | Should -BeTrue
     $loopPhase = $json.phases | Where-Object name -eq 'Loop'
     $loopPhase.status | Should -Be 'Passed'
     $loopPhase.details.loopIterations | Should -Be 2

tests/TestHelpers.Schema.ps1

@@ -102,6 +102,17 @@ $script:JsonShapeSpecs['LoopEvent'] = [pscustomobject]@{
   }
 }
 
+$script:JsonShapeSpecs['IntegrationRunbook'] = [pscustomobject]@{
+  Required = @('schema','generated','phases','overallStatus')
+  Optional = @()
+  Types = @{
+    schema        = { param($v) $v -is [string] -and $v -eq 'integration-runbook-v1' }
+    generated     = { param($v) ($v -is [string]) -or ($v -is [datetime]) }
+    overallStatus = { param($v) $v -is [string] -and $v -match '^(Passed|Failed)$' }
+    phases        = { param($v) $v -is [object[]] }
+  }
+}
+
 function Assert-JsonShape {
   [CmdletBinding()] param(
     [Parameter(Mandatory)][string]$Path,