Security hardening, multi-site portability, and a documentation and API-surface sweep

plugins/geenforce/client/Invoke-ShopdbShadow.ps1

@@ -20,10 +20,30 @@
 # Runs as SYSTEM under GE-Enforce, from an entry gated to the test bays.
 # Fail-safe: exits 0 on every path - shadowing must never stop a bay enforcing.
 
+param(
+    # This site's ShopDB. Optional: a bay that already carries a BaseUrl in the
+    # registry keeps it, so the fleet needs this only on the first cycle or when
+    # the address changes. There is deliberately NO default - see below.
+    [string] $BaseUrl = ''
+)
+
 $ErrorActionPreference = 'Continue'
 
+# RE-ENTRANCY GUARD. This entry lives IN the manifest the shadow run enforces,
+# so without it the thing recurses without bound: engine runs the manifest ->
+# reaches this entry -> we invoke the runner -> the runner runs the engine
+# against the SAME manifest -> reaches this entry again. Measured on the test
+# bays 2026-08-13: 347 nested cycles in 36 minutes, one every five seconds,
+# until the share unmounted. The task-based predecessor never hit this because
+# it registered a task instead of invoking the runner.
+#
+# An environment variable, because it is inherited by every child process and
+# therefore covers the nested engine and runner without a file to clean up or a
+# stale lock to age out. Set for THIS process tree only.
+if ($env:SHOPDB_SHADOW_ACTIVE -eq '1') { exit 0 }
+$env:SHOPDB_SHADOW_ACTIVE = '1'
+
 $InstallDir = 'C:\Program Files\GE\Shopfloor'
-$BaseUrl    = 'https://tsgwp00525.wjs.geaerospace.net/shopdb'
 $LegacyTask = 'ShopDB GE-Enforce (shadow)'
 
 function Write-ShadowLog {
@@ -66,12 +86,30 @@ try {
         }
     }
 
-    # BaseUrl only when it differs, so a hand-set value is not churned.
+    # THE BAY'S OWN VALUE WINS. This used to hold one site's ShopDB URL as a
+    # compiled-in constant and write it whenever the registry disagreed. At the
+    # site it was written for that reads as "heal drift"; anywhere else it reads
+    # as "overwrite this site's address on every enforce cycle", and the site
+    # cannot win because the cycle repeats. A second plant could not point its
+    # own bays at its own server.
+    #
+    # So: an explicitly passed -BaseUrl seeds the value, an existing registry
+    # value is never touched, and with neither there is nothing honest to write.
     $regPath = 'HKLM:\SOFTWARE\GE\ShopDB'
     if (-not (Test-Path $regPath)) { New-Item -Path $regPath -Force | Out-Null }
-    if ((Get-ItemProperty -Path $regPath -Name BaseUrl -ErrorAction SilentlyContinue).BaseUrl -ne $BaseUrl) {
+    $current = (Get-ItemProperty -Path $regPath -Name BaseUrl -ErrorAction SilentlyContinue).BaseUrl
+    if (-not $current) {
+        if (-not $BaseUrl) {
+            Write-ShadowLog "no BaseUrl in $regPath and none passed - set it, or pass -BaseUrl in the manifest entry. Skipping this cycle."
+            exit 0
+        }
         Set-ItemProperty -Path $regPath -Name BaseUrl -Value $BaseUrl
-        Write-ShadowLog "BaseUrl set to $BaseUrl"
+        Write-ShadowLog "BaseUrl seeded as $BaseUrl"
+    } elseif ($BaseUrl -and $BaseUrl -ne $current) {
+        # Say it, do not do it. A changed address is a real event, and it should
+        # be a deliberate one, not a side effect of whatever the manifest last
+        # carried.
+        Write-ShadowLog "BaseUrl in registry is $current; -BaseUrl passed $BaseUrl. Keeping the registry value."
     }
 
     Write-ShadowLog "shadowing $scope against $shareManifest"
@@ -83,3 +121,8 @@ catch {
     Write-ShadowLog "FAILED: $_"
     exit 0
 }
+finally {
+    # Clear it so the NEXT enforce cycle shadows again. Without this the guard
+    # would latch for the life of the process tree and shadow would run once.
+    $env:SHOPDB_SHADOW_ACTIVE = $null
+}