#Requires -Version 7.0
# PIM Manager 3.0.70 -- Initialize-PimSqlAdminGroup.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: ..\..\engine\_shared\pim-rest.ps1, pim-loopbackanswer.ps1, _pimsignedin.ps1, _pimsqladmingroup.ps1, _pimsigninidentity.ps1, ..\..\engine\_shared\pim-installnames.ps1, _pimscriptdoc.ps1)


<#
.SYNOPSIS
    Make a role-assignable security group (default grp-pim-sql-admins) the Microsoft Entra admin of a PIM Manager
    environment's Azure SQL server, with the environment's managed identities and the nightly updater as its members.
    The Invardia Support app is never added. One command, idempotent, every change read back; -WhatIf shows every
    change first. Signs in in the browser as the person running it (or, inside an Invardia support session, as the
    Invardia Support app), or uses a certificate identity from the repository -- never a client secret, no other tools
    or modules.

.DESCRIPTION
    Makes a security group (default 'grp-pim-sql-admins') the SQL server's Microsoft Entra admin, with
    these members:
      * the environment's user-assigned identity  (id-pim-<token>; found in the resource group, or named)
      * the SQL identity id-pim-sql-<token>, when the environment has one (private SQL)
      * the nightly updater's system-assigned identity (ca-pim-update), when the job exists
      * the application a build runs as (-SetupIdentityAppId), for the length of that build
      * any -ExtraMemberObjectIds
      * the CURRENT admin, so converging never takes access away from whoever has it now
    The Invardia Support app is NOT a member: its one standing database right is its read-only database user
    (Grant-PimSupportAccess.ps1); admin rights only inside an open support session. Named with -SupportAppId or
    -SupportObjectId, it is not added and the run says so. A membership an earlier version gave is left as found.
    Entra-only authentication is left as it is and verified afterwards. Existing contained database users
    are not touched. Every change is read back; a second run reports no changes.

    -ReleaseOwnMembership takes the APPLICATION this run signs in as (-ClientId with -CertThumbprint, or the Invardia
    Support session) out of the group again, and reads it back. Only that one membership: no other member is touched.
    The one-shot MSP build uses it at its end when its setting releaseOwnBuildMembership is on (off by default).

    Why: the unattended updater checks the database schema before it rolls a release. It can only do that
    if its managed identity can log in, and a group that holds every identity that must administer the
    store is the one arrangement that survives an identity being added later without a database login
    being created by hand. See docs/DESIGN.md (the SQL admin group) and the framework contract in the
    repository's DOCS/REQUIREMENTS.md section 4.5.

.PARAMETER SupportAppId
    The application (client) id of the Invardia Support app. It is NOT added as a member (no standing database
    administrator); the run says so. The old name -TroubleshootingAppId still works.

.PARAMETER SupportObjectId
    The Invardia Support app's service principal object id, instead of -SupportAppId (also not added).
    The old name -TroubleshootingObjectId still works.

.PARAMETER SetupIdentityAppId
    The application (client) id a build runs as: added as a member for the length of that build.

.PARAMETER ReleaseOwnMembership
    Take the application this run signs in as out of the group and read it back; nothing else is changed. Needs
    -ClientId with -CertThumbprint (or the Invardia Support session in this window).

.PARAMETER MembersOnly
    Do not create the group or move the admin: only add the members, and only when the group already IS
    the server's admin. This is what Deploy-PimUpdateJob.ps1 does on every run.

.PARAMETER PlanOnly
    Read everything and print the plan. Changes nothing. (-WhatIf does the same and prints each change as a
    "What if:" line.)

.PARAMETER TenantId
    The tenant of the environment. Required for the browser sign-in (the sign-in and every token are pinned to it).

.PARAMETER ClientId
    Automation from the repository only: with -CertThumbprint, a certificate identity in the local store instead of
    the browser sign-in. Not needed for the downloaded script.

.EXAMPLE
    # A browser window opens: sign in as yourself (an administrator of the tenant).
    .\Initialize-PimSqlAdminGroup.ps1 -SubscriptionId <subscription id> -ResourceGroup <resource group> -SqlServerName <sql server> `
        -TenantId <tenant id> -SupportAppId <Invardia Support app id> -WhatIf
    Preview, then run the same command without -WhatIf.

.NOTES
    Requirements:
      PowerShell: 7.0 or later (pwsh). Windows PowerShell 5.1 is not supported.
      Role: Privileged Role Administrator (Microsoft Entra; the group is role-assignable); Contributor or Owner on the
            SQL server and Reader on the environment's resource group (Azure).
      Hosts: login.microsoftonline.com, graph.microsoft.com, management.azure.com

    PERMISSIONS AND CHANGES (from Initialize-PimSqlAdminGroup.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Initialize-PimSqlAdminGroup/)
    The person running it needs:
      - Privileged Role Administrator [entraRole, tenant] -- The group is role-assignable (tier 0): only a Privileged Role Administrator or a Global Administrator can create such a group or change its members. Without it the group is not created and the current SQL admin is left as it is.
      - Contributor [azureRbac, the Azure SQL server (or its resource group); Owner works too] -- Sets the server's Microsoft Entra admin (Microsoft.Sql/servers/administrators/write) and reads it back.
      - Reader [azureRbac, the environment's resource group] -- Finds the environment's user-assigned identities (id-pim-*) and the updater job's identity.
      - The person running it, signed in in the browser (or the Invardia Support app inside an Invardia support session) [other, the subscription named with -SubscriptionId] -- The script takes its Microsoft Graph and Azure Resource Manager tokens from that sign-in (pinned to -TenantId) and refuses a token for another tenant. A certificate identity (-ClientId + -CertThumbprint) is for automation from the repository only; it then needs the Graph application permissions Group.Create and GroupMember.ReadWrite.All (or Group.ReadWrite.All), Directory.Read.All and RoleManagement.ReadWrite.Directory.
    What it creates, changes or grants:
      - create security group grp-pim-sql-admins (or -GroupName), role-assignable (isAssignableToRole = true), only when it does not exist (Microsoft Graph) @ tenant -- One group as the SQL admin means every identity that must administer the store gets access by membership, without a database login created by hand. Role-assignable so that a Groups Administrator, a User Administrator or a group owner cannot add themselves to it. Undo: Delete the group in the Entra admin center (Groups) -- only after another Microsoft Entra admin has been set on the SQL server, or nobody can administer the database.
      - grant member of grp-pim-sql-admins: the environment identity (id-pim-<token>), the SQL identity (id-pim-sql-<token>, private SQL only), the nightly updater's identity (ca-pim-update), a build's own application (-SetupIdentityAppId) for the length of that build, every -ExtraMemberObjectIds, and the previous SQL admin (kept, so nobody loses access). Never the Invardia Support app: named with -SupportAppId / -SupportObjectId it is not added, and the run says so. (Microsoft Graph): group member of the SQL server's Microsoft Entra admin group = administrator of the SQL server and every database on it @ the environment's Azure SQL server -- The updater checks the database schema before it rolls a release, and a setup or build administers the store while it runs. Undo: Remove the member from the group (Entra admin center > Groups > grp-pim-sql-admins > Members). Removing the PIM identities stops PIM Manager.
      - remove with -ReleaseOwnMembership: the application this run signs in as (-ClientId with -CertThumbprint, or the Invardia Support session) leaves grp-pim-sql-admins; read back. No other member is touched, and nothing else is changed. (Microsoft Graph) @ the environment's Azure SQL server -- A build's identity is a member for the length of the build only. Undo: Run the script again with -SetupIdentityAppId <that application id>.
      - update Microsoft Entra admin of the Azure SQL server (Microsoft.Sql/servers/administrators/ActiveDirectory) set to the group (Azure Resource Manager) @ the Azure SQL server named with -SqlServerName -- Azure SQL allows exactly one Microsoft Entra admin; making it the group gives every member access. Entra-only authentication is not changed (only read before and after). Existing contained database users are not touched. Undo: Set the previous admin back (the script prints it): Azure portal > the SQL server > Microsoft Entra ID > Set admin.
    -WhatIf: Signs in and reads everything, prints the plan, then one "What if:" line per change it would make: create the role-assignable group, add each member (by name and object id), make the group the SQL server's Microsoft Entra admin (and who the admin was). Nothing is created or changed.
    Undo: Set the previous Microsoft Entra admin back on the SQL server, then remove the members the script added (or delete the group if the script created it). Nothing else is changed by the script.

.LINK
    https://invardia.com/docs/pim/scripts/Initialize-PimSqlAdminGroup/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)][string]$SubscriptionId,
    [Parameter(Mandatory)][string]$ResourceGroup,
    [Parameter(Mandatory)][string]$SqlServerName,
    [string]$SqlResourceGroup,
    [string]$TenantId,
    [string]$GroupName = 'grp-pim-sql-admins',
    [string]$GroupObjectId,
    [string]$EnvironmentIdentityName,
    [string]$SqlAdminIdentityName,
    [string]$UpdateJobName = 'ca-pim-update',
    # The Invardia Support app. The old names (-TroubleshootingAppId / -TroubleshootingObjectId) still bind.
    [Alias('TroubleshootingAppId')][string]$SupportAppId,
    [Alias('TroubleshootingObjectId')][string]$SupportObjectId,
    # the application a build runs as: a member for the length of that build
    [string]$SetupIdentityAppId,
    [string[]]$ExtraMemberObjectIds = @(),
    # Certificate auth from the local store. Omit both to sign in in the browser (or use the Invardia support session).
    [string]$ClientId,
    [string]$CertThumbprint,
    [switch]$MembersOnly,
    [switch]$DoNotKeepCurrentAdmin,
    [switch]$PlanOnly,
    # take the application this run signs in as out of the group again (its OWN membership only), read back
    [switch]$ReleaseOwnMembership
)
$ErrorActionPreference = 'Stop'
# ===== BEGIN inlined helper: ..\..\engine\_shared\PIM-Rest.ps1 =====
<#
  PIM4EntraPS -- pure-REST auth + data plane (NO Graph/Az/MSAL modules).

  One place the whole solution gets tokens and calls Microsoft REST APIs, so the
  engine runs identically on Windows PowerShell 5.1, PowerShell 7, a VM, or a Linux
  container -- with nothing to Install-Module and no Azure.Core/Graph version clash.

  Token acquisition (auto-detected, override per call):
    * Managed Identity  -- App Service / Container Apps ($env:IDENTITY_ENDPOINT + IDENTITY_HEADER), an Azure Arc-enabled
                           server (IDENTITY_ENDPOINT + IMDS_ENDPOINT, 401 key-file challenge) or IMDS (VM)
    * Client secret     -- SPN client_credentials (v2 token endpoint)
    * Client certificate-- SPN, signed RS256 JWT client_assertion (no secret, no MSAL)
    * Signed-in source  -- a registered $global:PIM_TokenProvider (tools\setup\_PimSignedIn.ps1): the Invardia
                           Support session, else the person's browser sign-in (auth code + PKCE). No CLI, no module.

  Resolution order for credentials (all overridable via params):
    explicit params -> $global:PIM_* -> Managed Identity -> the signed-in token source -> (opt-in) browser sign-in.

  Data plane: Invoke-PimGraph / -PimArm / -PimPowerBI / -PimRest with @odata/nextLink
  paging (-All) and 429/Retry-After backoff. PS 5.1 + 7 compatible (cert signing uses
  X509 GetRSAPrivateKey, NOT RSA.ImportFromPem which is PS7-only).
#>

Set-StrictMode -Off

# resource (audience) per logical API. Built by a FUNCTION so any scope can re-seed it --
# see the trap note in Resolve-PimRestResource: a dot-sourced function's $script: follows
# the CALLER's scope, so a script that loaded PIM-SqlStore without this file found these
# tables null and silently ended up with no SQL credential at all.
function Get-PimRestResourceMap {
  @{
    graph    = 'https://graph.microsoft.com'
    arm      = 'https://management.azure.com'
    powerbi  = 'https://analysis.windows.net/powerbi/api'
    fabric   = 'https://api.fabric.microsoft.com'     # PIM 100.142b: Fabric workspace role assignments (the engine adds the PIM group)
    defender = 'https://api.securitycenter.microsoft.com'
    exo      = 'https://outlook.office365.com'   # Exchange Online REST admin API (app-only ManageAsApp)
  }
}
$script:PimRestResources = Get-PimRestResourceMap
$script:PimTokenCache = @{}   # "audience|tenant|clientId|credentialKind" -> @{ token; expiresUtc }

function Clear-PimRestTokenCache {
    <#
      Drop every cached token. The cache is keyed by full identity (BUG-22), so this is
      NOT needed to switch tenants any more -- it exists for an explicit "forget
      everything" (a rotated credential mid-process, or a test).
    #>
    [CmdletBinding()] param()
    $script:PimTokenCache = @{}
}

function Add-PimRestSessionToken {
    <#
      97.1 -- hand a token the CALLER already holds (a setup script's browser sign-in: auth code + PKCE, no modules) to
      the token cache, so every Invoke-PimGraph / Invoke-PimArm / Invoke-PimRest / SQL call in THIS process uses it.
      Only for the attended interactive mode ($global:PIM_Interactive): the key is exactly the one Get-PimRestToken
      computes for that mode, so the engine's own identities (managed identity, certificate) can never pick it up.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)][string]$Resource, [Parameter(Mandatory)][string]$Token, [datetime]$ExpiresUtc = ((Get-Date).ToUniversalTime().AddMinutes(50)), [string]$TenantId)
    $aud = Resolve-PimRestResource -Resource $Resource
    $tenant = Get-PimTenantId -TenantId $TenantId
    $cid = if ($global:PIM_ClientId) { $global:PIM_ClientId } elseif ($env:AZURE_CLIENT_ID) { $env:AZURE_CLIENT_ID } else { $null }
    if (-not $script:PimTokenCache) { $script:PimTokenCache = @{} }
    $script:PimTokenCache[("$aud|$tenant|$cid|interactive").ToLowerInvariant()] = [pscustomobject]@{ token = $Token; expiresUtc = $ExpiresUtc.ToUniversalTime() }
}

function Resolve-PimRestResource {
  param([Parameter(Mandatory)][string]$Resource)
  # 🪤 $script: IS NOT A CLOSURE FOR A DOT-SOURCED FUNCTION. It binds to the script scope
  # the function is CALLED from, so when another script dot-sources PIM-SqlStore (or the
  # downlink) WITHOUT this file, these tables are $null there and `.ContainsKey()` throws
  # "You cannot call a method on a null-valued expression". New-PimSqlConnection catches
  # that, tries the next credential, and ends up presenting NO credential -- Azure SQL then
  # answers "Login failed for user ''", which sends everyone looking at permissions.
  # Re-seeding here makes the alias table work from any scope; the value is a constant map,
  # so there is nothing to lose by rebuilding it.
  if (-not $script:PimRestResources) { $script:PimRestResources = Get-PimRestResourceMap }
  if ($script:PimRestResources.ContainsKey($Resource)) { return $script:PimRestResources[$Resource] }
  return ($Resource -replace '/+$','')   # already a full audience URL
}

function ConvertTo-PimBase64Url {
  param([Parameter(Mandatory)][byte[]]$Bytes)
  [Convert]::ToBase64String($Bytes).TrimEnd('=').Replace('+','-').Replace('/','_')
}

function Get-PimTenantId {
  param([string]$TenantId)
  if ($TenantId) { return $TenantId }
  if ($global:PIM_TenantId) { return $global:PIM_TenantId }
  if ($env:PIM_TenantId) { return $env:PIM_TenantId }
  if ($env:AZURE_TENANT_ID) { return $env:AZURE_TENANT_ID }
  return $null
}

# ---- Managed Identity (App Service / IMDS) --------------------------------
function ConvertTo-PimTokenExpiry {
  param($ExpiresOn)
  # App Service IDENTITY_ENDPOINT -> unix seconds; older MSI/some -> a date string.
  try { if ("$ExpiresOn" -match '^\d+$') { return ([datetimeoffset]::FromUnixTimeSeconds([int64]$ExpiresOn)).UtcDateTime } } catch {}
  try { return ([datetimeoffset]"$ExpiresOn").UtcDateTime } catch {}
  return (Get-Date).ToUniversalTime().AddMinutes(50)
}
function Set-PimManagedIdentityHomeTenant {
  # LIC anti-copy (2026-10-03): the tid claim of a MANAGED IDENTITY token = the tenant this environment really runs in.
  # Recorded once per process in $global:PIM_ManagedIdentityTenantId; PIM-License.ps1 checks the licence against it, so a
  # licence cannot be made valid elsewhere by editing PIM_TenantId. Never throws.
  param([string]$Token)
  try {
    $seg = "$Token".Split('.')[1].Replace('-', '+').Replace('_', '/'); while ($seg.Length % 4) { $seg += '=' }
    $tid = "$(([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($seg)) | ConvertFrom-Json).tid)".Trim().ToLowerInvariant()
    if ($tid -match '^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$') { $global:PIM_ManagedIdentityTenantId = $tid }
  } catch { }
}
# ---- Azure Arc-enabled server (§100.63(b), the on-premises hybrid worker) ---------------------------------------------
# The Arc agent (himds) serves the machine's system-assigned identity on http://localhost:40342 and sets IDENTITY_ENDPOINT
# + IMDS_ENDPOINT machine-wide -- but NO IDENTITY_HEADER (that is App Service / Container Apps). Its token call is a
# CHALLENGE: the first GET answers 401 with `WWW-Authenticate: Basic realm=<path to a .key file>`; the caller proves it may
# use the identity by READING that file (only local Administrators and the local group "Hybrid agent extension
# applications" can) and retries with `Authorization: Basic <file content>`. The file is single-use and short-lived.
# 🔒 The realm is checked before anything is read: a .key file directly under %ProgramData%\AzureConnectedMachineAgent\Tokens,
# at most 4 KB -- an endpoint that names any other file is refused (else a rogue local listener could make us send it the
# content of an arbitrary file we can read).
$script:PimArcDefaultEndpoint = 'http://localhost:40342/metadata/identity/oauth2/token'
function Get-PimArcTokenDirectory {
  if ("$($global:PIM_ArcTokenDirectory)".Trim()) { return "$($global:PIM_ArcTokenDirectory)".Trim() }   # offline test seam
  $pd = if ("$env:ProgramData".Trim()) { $env:ProgramData } else { 'C:\ProgramData' }
  return (Join-Path $pd 'AzureConnectedMachineAgent\Tokens')
}
function Get-PimArcIdentityEndpoint {
  # '' = not an Arc host. Arc = IDENTITY_ENDPOINT + IMDS_ENDPOINT set and no IDENTITY_HEADER / MSI_SECRET, or (env not yet
  # visible to this process -- a service started before the agent was installed) the himds service is present.
  if ($global:PIM_ArcIdentityEndpoint) { return "$($global:PIM_ArcIdentityEndpoint)" }   # offline test seam
  if ("$env:IDENTITY_HEADER".Trim() -or "$env:MSI_SECRET".Trim()) { return '' }
  if ("$env:IDENTITY_ENDPOINT".Trim() -and "$env:IMDS_ENDPOINT".Trim()) { return "$env:IDENTITY_ENDPOINT".Trim() }
  if ($global:PIM_NoManagedIdentity -or $global:PIM_NoArcProbe) { return '' }
  if ($null -eq $script:PimArcHimdsPresent) {
    $script:PimArcHimdsPresent = $false
    if ("$env:OS" -eq 'Windows_NT') { try { $script:PimArcHimdsPresent = [bool](Get-Service -Name 'himds' -ErrorAction Stop) } catch { $script:PimArcHimdsPresent = $false } }
  }
  if ($script:PimArcHimdsPresent) { return $script:PimArcDefaultEndpoint }
  return ''
}
function Test-PimArcKeyFilePath {
  # PURE. Is this realm path a file the Arc agent would hand out? Directly under the token directory, *.key, no traversal.
  param([AllowEmptyString()][string]$Path, [Parameter(Mandatory)][string]$TokenDirectory)
  $p = "$Path".Trim().Trim('"')
  if (-not $p -or $p -match '\.\.' -or $p -notmatch '(?i)\.key$') { return $false }
  $full = $null; $dir = $null
  try { $full = [IO.Path]::GetFullPath($p); $dir = [IO.Path]::GetFullPath($TokenDirectory).TrimEnd('\', '/') } catch { $full = $null }
  if (-not $full -or -not $dir) { return $false }
  return ([IO.Path]::GetDirectoryName($full).TrimEnd('\', '/') -ieq $dir)
}
function Invoke-PimArcIdentityHttp {
  # ONE GET against the local Arc endpoint that never throws on an HTTP status: returns status, WWW-Authenticate, body.
  # No proxy (on-premises servers often have a system proxy; localhost must never go through it). Seam: PIM_ArcIdentityHttpStub.
  param([Parameter(Mandatory)][string]$Uri, [hashtable]$Headers = @{}, [int]$TimeoutSec = 30)
  if ($global:PIM_ArcIdentityHttpStub -is [scriptblock]) { return (& $global:PIM_ArcIdentityHttpStub $Uri $Headers) }
  $req = [System.Net.HttpWebRequest][System.Net.WebRequest]::Create($Uri)
  $req.Method = 'GET'; $req.Proxy = $null; $req.Timeout = $TimeoutSec * 1000; $req.ReadWriteTimeout = $TimeoutSec * 1000
  foreach ($k in $Headers.Keys) { $req.Headers[$k] = "$($Headers[$k])" }
  $resp = $null
  try { $resp = $req.GetResponse() }
  catch [System.Net.WebException] { $resp = $_.Exception.Response; if (-not $resp) { throw } }
  catch { if ($_.Exception.InnerException -is [System.Net.WebException] -and $_.Exception.InnerException.Response) { $resp = $_.Exception.InnerException.Response } else { throw } }
  $out = $null
  try {
    $sr = New-Object System.IO.StreamReader($resp.GetResponseStream())
    $body = $sr.ReadToEnd(); $sr.Close()
    $out = [pscustomobject]@{ status = [int]$resp.StatusCode; wwwAuthenticate = "$($resp.Headers['WWW-Authenticate'])"; body = $body }
  } finally { $resp.Close() }
  return $out
}
function Get-PimArcManagedIdentityToken {
  param([Parameter(Mandatory)][string]$Audience, [string]$Endpoint = '')
  $ep = if ("$Endpoint".Trim()) { "$Endpoint".Trim() } else { Get-PimArcIdentityEndpoint }
  if (-not $ep) { throw 'not an Azure Arc-enabled server (no IDENTITY_ENDPOINT/IMDS_ENDPOINT and no himds service)' }
  $u = "$($ep)?resource=$([uri]::EscapeDataString($Audience))&api-version=2020-06-01"
  $first = Invoke-PimArcIdentityHttp -Uri $u -Headers @{ Metadata = 'true' }
  $r = $first
  if ($first.status -eq 401) {
    $m = [regex]::Match("$($first.wwwAuthenticate)", '(?i)Basic\s+realm\s*=\s*"?([^"]+?)"?\s*$')
    if (-not $m.Success) { throw "Arc identity endpoint answered 401 without a Basic realm (WWW-Authenticate: '$($first.wwwAuthenticate)')" }
    $keyPath = $m.Groups[1].Value
    $dir = Get-PimArcTokenDirectory
    if (-not (Test-PimArcKeyFilePath -Path $keyPath -TokenDirectory $dir)) { throw "Arc identity endpoint named a key file outside '$dir' ('$keyPath') -- refusing to read it" }
    $len = -1; try { $len = (New-Object IO.FileInfo($keyPath)).Length } catch { $len = -1 }
    if ($len -gt 4096) { throw "Arc key file '$keyPath' is $len bytes (more than 4 KB) -- refusing" }
    $secret = $null; $readErr = $null
    try { $secret = [IO.File]::ReadAllText($keyPath).Trim() } catch { $readErr = $_.Exception }
    if ($readErr -is [System.UnauthorizedAccessException] -or ($readErr -and $readErr.InnerException -is [System.UnauthorizedAccessException])) {
      throw "cannot read the Arc key file '$keyPath' as $([Security.Principal.WindowsIdentity]::GetCurrent().Name) -- add this account to the local group 'Hybrid agent extension applications' (or run as a local administrator), then start a new process"
    }
    if ($readErr) { throw "cannot read the Arc key file '$keyPath': $($readErr.Message)" }
    if (-not $secret) { throw "the Arc key file '$keyPath' is empty" }
    $r = Invoke-PimArcIdentityHttp -Uri $u -Headers @{ Metadata = 'true'; Authorization = "Basic $secret" }
    $secret = $null
  }
  if ($r.status -ne 200) { throw "Arc identity endpoint answered HTTP $($r.status) for $Audience : $("$($r.body)".Substring(0, [Math]::Min(300, "$($r.body)".Length)))" }
  $j = "$($r.body)" | ConvertFrom-Json
  if (-not "$($j.access_token)") { throw "Arc identity endpoint returned no access_token for $Audience" }
  return [pscustomobject]@{ token = "$($j.access_token)"; expiresUtc = (ConvertTo-PimTokenExpiry $j.expires_on) }
}

function Test-PimMiTokenRetryable {
  <# PURE. MI-TOKEN-TRANSIENT: is a failed identity-endpoint call worth another try? No HTTP status (a timeout or a
     connection fault), 429 or 5xx = yes; any other status (400 identity not found, 401, 403, 404) = no. #>
  param([AllowNull()][object]$StatusCode)
  if ($null -eq $StatusCode -or "$StatusCode" -eq '' -or [int]$StatusCode -eq 0) { return $true }
  $s = [int]$StatusCode
  return ($s -eq 429 -or ($s -ge 500 -and $s -le 599))
}

function Get-PimManagedIdentityToken {
  param([Parameter(Mandatory)][string]$Audience)
  $res = [uri]::EscapeDataString($Audience)
  # App Service / Functions (current): IDENTITY_ENDPOINT + IDENTITY_HEADER (api 2019-08-01)
  if ($env:IDENTITY_ENDPOINT -and $env:IDENTITY_HEADER) {
    $u = "$($env:IDENTITY_ENDPOINT)?resource=$res&api-version=2019-08-01"
    # 🔴 BUG-76 -- THIS BRANCH IGNORED THE CONFIGURED MI CLIENT ID, AND THE IMDS BRANCH BELOW DOES
    # NOT. That asymmetry is the whole defect: with a USER-ASSIGNED-ONLY identity there is nothing
    # for the endpoint to default to, so no token is issued and the caller ends up presenting no
    # credential at all. Azure SQL then answers "Login failed for user '<token-identified
    # principal>'", which reads as a missing database user -- and it is not.
    # MEASURED on the greenfield slave 2026-08-27: ca-pim-tick carries `SystemAssigned,
    # UserAssigned` and logs "[mi] token via IDENTITY_ENDPOINT" happily, while ca-pim-downlink-s6
    # carries UserAssigned ALONE and logs that line NOT AT ALL -- the absence was the clue. Its
    # engine apply failed every run on `Preflight FAILED: ... no SELECT 1`, which sent the search
    # to contained users and grants (where a user was duly created, and changed nothing).
    # Container Apps is exactly the host that attaches a user-assigned identity on its own.
    $miCid = if ($global:PIM_ManagedIdentityClientId) { "$($global:PIM_ManagedIdentityClientId)".Trim() }
             elseif ($env:PIM_ManagedIdentityClientId) { "$($env:PIM_ManagedIdentityClientId)".Trim() } else { '' }
    if ($miCid) { $u += "&client_id=$([uri]::EscapeDataString($miCid))" }
    # MI-TOKEN-TRANSIENT (SUP-2026-00323, internal rfa-sync 2026-10-27 02:16Z): ONE GET, no retry, so a single fault of the
    # endpoint failed the whole run while every other token of that window was issued. Retry a timeout / connection fault /
    # 429 / 5xx after a short wait; a 4xx (e.g. 400 "identity not found") is an answer, not a fault, and is thrown at once.
    # MANAGER-REFRESH-DEGRADES-CACHE (2026-10-27): on internal the endpoint was out for ~7 s twice in one day (02:16Z,
    # 20:00Z), longer than 2 s + 5 s -- a third try after 15 s covers that (22 s in all).
    $delays = if ($null -ne $global:PIM_MiTokenRetryDelaysSec) { @($global:PIM_MiTokenRetryDelaysSec) } else { @(2, 5, 15) }
    $r = $null
    for ($try = 0; ; $try++) {
      try { $r = Invoke-RestMethod -Method GET -Uri $u -Headers @{ 'X-IDENTITY-HEADER' = $env:IDENTITY_HEADER } -TimeoutSec 60; break }
      catch {
        $st = $null; try { if ($_.Exception.Response) { $st = [int]$_.Exception.Response.StatusCode } } catch {}
        if ($try -ge $delays.Count -or -not (Test-PimMiTokenRetryable -StatusCode $st)) {
          throw "the identity endpoint did not issue a token after $($try + 1) attempt(s): $($_.Exception.Message)"
        }
        try { [System.Console]::Out.WriteLine("  [mi] identity endpoint attempt $($try + 1) failed ($(if ($st) { "HTTP $st" } else { 'no answer' })) -- retrying in $($delays[$try]) s") } catch {}
        Start-Sleep -Seconds ([int]$delays[$try])
      }
    }
    # §100.46: in the tick this is a start-up diagnostic (printed with the start-up block: on change / first of the day / PIM_LOG_VERBOSE=1)
    if ("$($r.access_token)") { $__mil = "  [mi] token via IDENTITY_ENDPOINT (len $($r.access_token.Length))"; if ($global:PIM_LogQuiet -and (Get-Command Write-PimStartupLine -ErrorAction SilentlyContinue)) { Write-PimStartupLine -Message $__mil } else { try { [System.Console]::Out.WriteLine($__mil) } catch {} } }  # Console.Out (not Write-Host): headless-safe from any scope (App Service has no console buffer; Write-Host throws there even from module scope)
    Set-PimManagedIdentityHomeTenant -Token "$($r.access_token)"; return [pscustomobject]@{ token = $r.access_token; expiresUtc = (ConvertTo-PimTokenExpiry $r.expires_on) }
  }
  # App Service (older / some Linux SKUs): MSI_ENDPOINT + MSI_SECRET (api 2017-09-01, header 'Secret')
  if ($env:MSI_ENDPOINT -and $env:MSI_SECRET) {
    $u = "$($env:MSI_ENDPOINT)?resource=$res&api-version=2017-09-01"
    $r = Invoke-RestMethod -Method GET -Uri $u -Headers @{ 'Secret' = $env:MSI_SECRET } -TimeoutSec 60
    if ("$($r.access_token)") { try { [System.Console]::Out.WriteLine("  [mi] token via MSI_ENDPOINT (len $($r.access_token.Length))") } catch {} }  # Console.Out: headless-safe from any scope
    Set-PimManagedIdentityHomeTenant -Token "$($r.access_token)"; return [pscustomobject]@{ token = $r.access_token; expiresUtc = (ConvertTo-PimTokenExpiry $r.expires_on) }
  }
  # Azure Arc-enabled server (on-premises hybrid worker, §100.63(b)): IDENTITY_ENDPOINT without IDENTITY_HEADER, 401 challenge
  if (Get-PimArcIdentityEndpoint) {
    $a = Get-PimArcManagedIdentityToken -Audience $Audience
    try { [System.Console]::Out.WriteLine("  [mi] token via the Azure Arc agent (len $($a.token.Length))") } catch {}
    Set-PimManagedIdentityHomeTenant -Token "$($a.token)"; return $a
  }
  # IMDS (Azure VM)
  $u = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$res"
  if ($global:PIM_ManagedIdentityClientId) { $u += "&client_id=$($global:PIM_ManagedIdentityClientId)" }
  $r = Invoke-RestMethod -Method GET -Uri $u -Headers @{ Metadata = 'true' } -TimeoutSec 5
  Set-PimManagedIdentityHomeTenant -Token "$($r.access_token)"; return [pscustomobject]@{ token = $r.access_token; expiresUtc = (ConvertTo-PimTokenExpiry $r.expires_on) }
}

# ---- SPN client secret ----------------------------------------------------
function Get-PimClientSecretToken {
  param([Parameter(Mandatory)][string]$TenantId,[Parameter(Mandatory)][string]$ClientId,[Parameter(Mandatory)][string]$ClientSecret,[Parameter(Mandatory)][string]$Audience)
  $body = @{ grant_type='client_credentials'; client_id=$ClientId; client_secret=$ClientSecret; scope="$Audience/.default" }
  $r = Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body $body -TimeoutSec 60
  return [pscustomobject]@{ token = $r.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$r.expires_in - 60) }
}

# ---- SPN certificate (signed JWT assertion) -------------------------------
function Get-PimClientCertToken {
  param([Parameter(Mandatory)][string]$TenantId,[Parameter(Mandatory)][string]$ClientId,[Parameter(Mandatory)][System.Security.Cryptography.X509Certificates.X509Certificate2]$Certificate,[Parameter(Mandatory)][string]$Audience)
  $tokenUrl = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
  $now = [DateTimeOffset]::UtcNow
  $x5t = ConvertTo-PimBase64Url -Bytes $Certificate.GetCertHash()   # SHA1 thumbprint bytes
  $header = @{ alg='RS256'; typ='JWT'; x5t=$x5t } | ConvertTo-Json -Compress
  $claims = @{ aud=$tokenUrl; iss=$ClientId; sub=$ClientId; jti=([guid]::NewGuid().ToString())
              nbf=$now.ToUnixTimeSeconds(); exp=$now.AddMinutes(10).ToUnixTimeSeconds() } | ConvertTo-Json -Compress
  $h = ConvertTo-PimBase64Url -Bytes ([Text.Encoding]::UTF8.GetBytes($header))
  $c = ConvertTo-PimBase64Url -Bytes ([Text.Encoding]::UTF8.GetBytes($claims))
  $unsigned = "$h.$c"
  $rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($Certificate)
  if (-not $rsa) { throw "Certificate has no usable RSA private key for JWT signing." }
  $sigBytes = $rsa.SignData([Text.Encoding]::UTF8.GetBytes($unsigned), [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
  $jwt = "$unsigned." + (ConvertTo-PimBase64Url -Bytes $sigBytes)
  $body = @{ grant_type='client_credentials'; client_id=$ClientId; scope="$Audience/.default"
            client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer'; client_assertion=$jwt }
  $r = Invoke-RestMethod -Method POST -Uri $tokenUrl -ContentType 'application/x-www-form-urlencoded' -Body $body -TimeoutSec 60
  return [pscustomobject]@{ token = $r.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$r.expires_in - 60) }
}

function Get-PimTokenTenantId {
    <#
      SEC-12 -- read the tenant a JWT actually belongs to, from its own claims.

      🔑 ASKING FOR A TENANT IS NOT THE SAME AS BEING GIVEN ONE, and until this existed there was
      no way to tell the difference: a token for the wrong directory is a perfectly valid string
      that succeeds at the call site and fails somewhere else as a permissions error. One
      `Split('.')[1]` turns that into a fact.

      PURE: no network, no validation of the signature (that is the resource's job) -- this only
      reads what the token SAYS about itself, which is exactly what is needed to catch "you asked
      for A and something handed you B". Returns the lowercased `tid`, or '' when the string is
      not a readable JWT -- never throws, because a caller reaching for a sanity check must not be
      broken BY the sanity check.
    #>
    [CmdletBinding()] param([string]$Token)
    try {
        $parts = "$Token".Split('.')
        if ($parts.Count -lt 2) { return '' }
        $p = $parts[1].Replace('-', '+').Replace('_', '/')
        while ($p.Length % 4) { $p += '=' }
        $claims = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json
        return "$($claims.tid)".Trim().ToLowerInvariant()
    } catch { return '' }
}

function Get-PimTokenAppId {
    <# SEC-12 companion: the appid a JWT claims. Same contract as Get-PimTokenTenantId. #>
    [CmdletBinding()] param([string]$Token)
    try {
        $parts = "$Token".Split('.')
        if ($parts.Count -lt 2) { return '' }
        $p = $parts[1].Replace('-', '+').Replace('_', '/')
        while ($p.Length % 4) { $p += '=' }
        $claims = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json
        return "$($claims.appid)".Trim().ToLowerInvariant()
    } catch { return '' }
}

function Resolve-PimCertificate {
  param([string]$Thumbprint)
  $tp = if ($Thumbprint) { $Thumbprint } elseif ($global:PIM_CertThumbprint) { $global:PIM_CertThumbprint } else { $null }
  if (-not $tp) { return $null }
  $tp = ($tp -replace '\s','').ToUpperInvariant()
  foreach ($store in @('Cert:\CurrentUser\My','Cert:\LocalMachine\My')) {
    $c = Get-ChildItem $store -ErrorAction SilentlyContinue | Where-Object { $_.Thumbprint -eq $tp } | Select-Object -First 1
    if ($c) { return $c }
  }
  return $null
}

# ---- interactive (delegated) -- BREAK-GLASS / emergency on a client PC ----
# Dependency-free auth-code + PKCE loopback. No MSAL, no Graph/Az modules.
# Used when there is no MI and no SPN credential (a cloud-only admin PC running
# the emergency edition): the operator signs in as THEMSELVES, so the resulting
# SQL/Graph/ARM action is audited under the human identity, not a shared app.
# Returns a raw access token for $Audience. Edge is launched explicitly to avoid
# the system-default-browser state-mismatch bug; any first-party public client
# accepts an arbitrary localhost redirect port.
function Get-PimInteractiveClientId {
  <# PURE. The first-party public client for a browser sign-in to -Audience: Graph -> the Microsoft Graph CLI client
     (pre-authorised for Graph only); everything else (ARM, Azure SQL, Key Vault, Storage) -> the Microsoft Azure CLI
     client APP ID (an app registration id used over REST, not the az program). AADSTS650057 on ARM, 2026-10-10. #>
  param([string]$Audience)
  # ONE client for every audience (2026-10-10, a customer's install stalled on a hidden SECOND sign-in window when Graph
  # used a different client): the Azure CLI first-party public client is pre-authorised for Graph AND ARM / SQL / Key
  # Vault / Storage in every tenant, so ONE browser sign-in serves all of them through its refresh token.
  return '04b07795-8ddb-461a-bbee-02f9e1bf7b46'
}

# REQ 100.76 (2026-10-11, a new customer's hosting step: "Login failed for user '<token-identified principal>'"): a signed-in
# build hands its step processes the person's REFRESH token(s) for the target tenant in $env:PIM_HANDOFF_REFRESH
# ({ "<tenant>|<public client id>": "<refresh token>" }, that process's environment only), instead of a pre-minted Azure SQL
# ACCESS token. The step creates the SQL server, sets its Entra admin and adds the person to the SQL admin group AFTER the
# build minted, so only a token minted at connect time carries that right. Entries for another tenant are never taken.
function Import-PimHandoffRefresh {
  param([string]$TenantId, [string]$Json = "$env:PIM_HANDOFF_REFRESH")
  if (-not "$Json".Trim()) { return 0 }
  if (-not ($global:PimInteractiveRefresh -is [hashtable])) { $global:PimInteractiveRefresh = @{} }
  $want = "$TenantId".Trim().ToLowerInvariant(); $n = 0
  try { $o = "$Json" | ConvertFrom-Json } catch { Write-Verbose "PIM_HANDOFF_REFRESH unreadable: $($_.Exception.Message)"; return 0 }
  foreach ($p in @($o.PSObject.Properties)) {
    $k = "$($p.Name)".Trim().ToLowerInvariant(); $v = "$($p.Value)".Trim()
    if (-not $v -or $k -notmatch '^[^|]+\|[^|]+$') { continue }
    if ($want -and $k.Split('|')[0] -ne $want) { continue }
    if (-not $global:PimInteractiveRefresh.ContainsKey($k)) { $global:PimInteractiveRefresh[$k] = $v; $n++ }
  }
  return $n
}

# REQ 100.76: the refresh tokens a signed-in build hands a step for -TenantId, as the JSON for $env:PIM_HANDOFF_REFRESH
# ('' when there are none). Pure over -Map (default: this process's in-memory refresh map).
function Get-PimHandoffRefreshJson {
  param([Parameter(Mandatory)][string]$TenantId, [object]$Map = $global:PimInteractiveRefresh)
  if (-not ($Map -is [hashtable]) -or -not $Map.Count) { return '' }
  $want = "$TenantId".Trim().ToLowerInvariant(); $out = [ordered]@{}
  foreach ($k in @($Map.Keys)) { $kl = "$k".ToLowerInvariant(); if ($kl.Split('|')[0] -eq $want -and "$($Map[$k])".Trim()) { $out[$kl] = "$($Map[$k])" } }
  if (-not $out.Count) { return '' }
  return ($out | ConvertTo-Json -Compress)
}

function New-PimLoopbackListeners {
  # The browser sign-in's redirect listeners: the IPv4 loopback on a free port AND the IPv6 loopback on the SAME port when
  # the machine has IPv6 (a "localhost" redirect may resolve to either). Loopback only. A port the IPv6 side cannot take
  # is retried on a new one (a few times); no IPv6 at all = the IPv4 listener alone, as before.
  for ($try = 0; $try -lt 5; $try++) {
    $v4 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0)
    $v4.Start()
    if (-not [System.Net.Sockets.Socket]::OSSupportsIPv6) { return $v4 }
    $p = ([System.Net.IPEndPoint]$v4.LocalEndpoint).Port
    try {
      $v6 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::IPv6Loopback, $p)
      $v6.Start()
      return @($v4, $v6)   # the caller wraps it in @(): one flat list
    } catch { $v4.Stop() }
  }
  $only = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0); $only.Start()
  return $only
}

function Get-PimInteractiveToken {
  param([Parameter(Mandatory)][string]$Audience,[string]$TenantId,[string]$ClientId,
        # section 9 account sign-in clarity: force a brand-new credential prompt (prompt=login)
        # instead of reusing a cached account. -ExpectedAccount, if the cached account
        # differs, also forces a fresh prompt so a stale account is never used silently.
        [switch]$ForceFreshAccount,[string]$ExpectedAccount,
        # REQ 100.76: only the silent refresh-token exchange -- $null instead of a browser window when there is none.
        [switch]$RefreshOnly)
  $tenant = if ($TenantId) { $TenantId } elseif (Get-PimTenantId) { Get-PimTenantId } else { 'organizations' }
  # Default public client PER AUDIENCE (2026-10-10, a customer's managed install failed with AADSTS650057 "Invalid
  # resource" for ARM): the Microsoft Graph CLI client (14d82eec-...) is pre-authorised for GRAPH only. Azure Resource
  # Manager, Azure SQL, Key Vault and Storage use the Microsoft Azure CLI first-party public client APP ID
  # (04b07795-..., an app registration id used over REST -- not the az program), pre-authorised for those in every tenant.
  $cid = if ($ClientId) { $ClientId } elseif ($global:PIM_InteractiveClientId) { $global:PIM_InteractiveClientId } else { Get-PimInteractiveClientId -Audience $Audience }

  # ONE sign-in: a refresh token from an earlier browser sign-in (same tenant + client) is exchanged for this audience --
  # no second window. Falls through to the browser only when there is none or the exchange is refused.
  if (-not $global:PimInteractiveRefresh) { $global:PimInteractiveRefresh = @{} }
  $rtKey = "$tenant|$cid".ToLowerInvariant()
  if (-not $global:PimInteractiveRefresh.ContainsKey($rtKey)) { [void](Import-PimHandoffRefresh -TenantId $tenant) }
  if ($global:PimInteractiveRefresh.ContainsKey($rtKey) -and -not $ForceFreshAccount) {
    try {
      $rr = Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id = $cid; grant_type = 'refresh_token'; refresh_token = $global:PimInteractiveRefresh[$rtKey]
        scope = "$Audience/.default offline_access openid profile" }
      if ($rr.refresh_token) { $global:PimInteractiveRefresh[$rtKey] = $rr.refresh_token }
      if ($rr.access_token) { return [pscustomobject]@{ token = $rr.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$rr.expires_in - 60) } }
    } catch { Write-Verbose "refresh-token exchange for $Audience refused: $($_.Exception.Message) -- browser sign-in" }
  }
  if ($RefreshOnly) { return $null }

  $bytes = New-Object byte[] 32
  [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
  $verifier  = ConvertTo-PimBase64Url -Bytes $bytes
  $sha       = [System.Security.Cryptography.SHA256]::Create()
  $challenge = ConvertTo-PimBase64Url -Bytes ($sha.ComputeHash([System.Text.Encoding]::ASCII.GetBytes($verifier)))
  $state     = [guid]::NewGuid().ToString('N')

  # The redirect says "localhost" (what Entra's public clients accept on any port), and a browser may resolve it to the IPv4
  # OR the IPv6 loopback: listen on BOTH, on the same port (a customer 2026-10-21: an IPv4-only listener, the jump host's browser
  # went to [::1] -> "localhost refused to connect"). Loopback only -- never another interface.
  $tcps = @(New-PimLoopbackListeners)
  $port     = ([System.Net.IPEndPoint]$tcps[0].LocalEndpoint).Port
  $redirect = "http://localhost:$port/"

  # section 9 prompt clarity: select_account (always show the picker so a stale cached account
  # is never reused silently) unless a fresh sign-in is forced -> login. ConvertTo-
  # PimAuthCodePrompt is in PIM-AuthDiagnostics; fall back if it isn't dot-sourced.
  if (Get-Command ConvertTo-PimAuthCodePrompt -ErrorAction SilentlyContinue) {
    $prompt = ConvertTo-PimAuthCodePrompt -ForceFresh:$ForceFreshAccount -KnownStaleAccount $ExpectedAccount
  } else { $prompt = if ($ForceFreshAccount) { 'login' } else { 'select_account' } }

  $scope   = "$Audience/.default offline_access openid profile"
  $authUrl = "https://login.microsoftonline.com/$tenant/oauth2/v2.0/authorize" +
             "?client_id=$cid&response_type=code&response_mode=query" +
             "&redirect_uri=$([uri]::EscapeDataString($redirect))" +
             "&scope=$([uri]::EscapeDataString($scope))&state=$state" +
             "&code_challenge=$challenge&code_challenge_method=S256&prompt=$prompt"
  if ("$ExpectedAccount".Trim()) { $authUrl += "&login_hint=$([uri]::EscapeDataString($ExpectedAccount.Trim()))" }

  $edge = @(
    (Join-Path ${env:ProgramFiles(x86)} 'Microsoft\Edge\Application\msedge.exe'),
    (Join-Path $env:ProgramFiles 'Microsoft\Edge\Application\msedge.exe')
  ) | Where-Object { $_ -and (Test-Path $_) } | Select-Object -First 1
  Write-Host "  [interactive] sign-in required for $Audience (loopback $redirect)" -ForegroundColor Yellow
  # 2026-10-10: tell the installer's progress feed BEFORE a browser window opens (a hidden window waited silently and the
  # customer saw "nothing happening"); the installer registers $global:PIM_SignInNotify.
  if ($global:PIM_SignInNotify -is [scriptblock]) { try { & $global:PIM_SignInNotify $Audience $tenant } catch { } }
  # A person whose browser opens in the wrong profile can paste the address into the right one (2026-10-10).
  Write-Host "  If the browser opens in the wrong profile or account, open this address in the browser profile of an admin of tenant ${tenant}:" -ForegroundColor Yellow
  Write-Host "  $authUrl" -ForegroundColor DarkGray
  # 2026-10-10 (a customer's install): a normal Edge window opens the DEFAULT profile, whose saved account signs in silently
  # -- the person never got a credential prompt and landed in the wrong tenant. An InPrivate window has no saved account,
  # so the sign-in form always appears. PIM_SIGNIN_BROWSER=none: open nothing, the person pastes the address above.
  $mode = "$env:PIM_SIGNIN_BROWSER".Trim().ToLowerInvariant()
  if ($mode -eq 'none') { Write-Host '  (PIM_SIGNIN_BROWSER=none: no browser opened -- paste the address above into the right browser)' -ForegroundColor Yellow }
  elseif ($edge) { Start-Process -FilePath $edge -ArgumentList @('--inprivate', '--new-window', $authUrl) -WhatIf:$false }
  else { Start-Process $authUrl -WhatIf:$false }   # fall back to default browser if Edge absent

  $query = $null
  try {
    # SIGNIN-PAGE (owner 2026-10-31, Invardia's Wait-AuthCode fix): only the answer (code / error) ends the wait, every
    # request gets a page, and the page keeps answering 10 s after it (engine/_shared/PIM-LoopbackAnswer.ps1).
    if (-not (Get-Command Wait-PimLoopbackAnswer -ErrorAction SilentlyContinue)) {
# ===== BEGIN inlined helper: PIM-LoopbackAnswer.ps1 =====
# PIM-LoopbackAnswer.ps1 -- the ONE wait for a browser sign-in's answer on the localhost loopback (auth code + PKCE).
# Used by every PIM browser sign-in: the REST library's own (signed-in setup scripts), the mail setup (Initialize-PimMailSender,
# Set-PimSmtpRelayPassword, Set-PimSqlTier), the engine-permissions grant and the Activator deploy scripts. The tools load the
# identical copy in tools\setup (they may not load engine files). Build-PimSupportScripts inlines it into each published script.
#
# Owner 2026-10-30/31 ("people are reporting this error" -- "This site can't be reached"; "yes fix the sign-in page in all
# scripts"), the same fix as Invardia's Wait-AuthCode: the old loops took the FIRST request -- often the browser's preload
# of the address or its icon request -- and a request that never sent a line held the loop, and once the answer came the
# listener stopped at once, so the browser's real load or a reload got "This site can't be reached". Now:
#   1. only a request whose query carries code= or error= is the answer; the loop goes on until one comes;
#   2. EVERY request gets a page (waiting / signed in / failed), never a closed connection;
#   3. after the answer the listener keeps answering for -GraceSeconds (10), so a second load shows "Signed in" too;
#   4. it throws only when no answer came within -Seconds.
# A connection that sends nothing (a speculative preconnect) is dropped after -ReadTimeoutMs and never blocks the loop.

function Test-PimLoopbackAnswerQuery {
    # PURE. Is this request line the sign-in's answer? Returns the query string ('' when not).
    param([AllowEmptyString()][AllowNull()][string]$RequestLine)
    $m = [regex]::Match("$RequestLine", '^GET /[^?\s]*\?(?<q>\S+) HTTP')
    if (-not $m.Success) { return '' }
    $q = $m.Groups['q'].Value
    if ($q -match '(^|&)(code|error)=') { return $q }
    return ''
}

function Get-PimLoopbackPage {
    # PURE. The page for one request: before the answer 'waiting', after it 'done' (or 'failed' when the answer is an error).
    param([ValidateSet('waiting', 'done', 'failed')][string]$Kind, [string]$ReturnTo = 'PowerShell', [string]$ErrorText = '')
    $body = switch ($Kind) {
        'waiting' { '<h3>Waiting for the sign-in...</h3>Finish the sign-in in the other tab.' }
        'done'    { "<h3>Sign-in complete.</h3>You can close this tab and return to $([System.Net.WebUtility]::HtmlEncode($ReturnTo))." }
        'failed'  { "<h3>Sign-in failed</h3>$([System.Net.WebUtility]::HtmlEncode($ErrorText))<br>Return to $([System.Net.WebUtility]::HtmlEncode($ReturnTo))." }
    }
    "<html><head><meta charset=`"utf-8`"></head><body style=`"font-family:sans-serif`">$body</body></html>"
}

function Wait-PimLoopbackAnswer {
    <#
      Waits on the loopback listener(s) (TcpListener, started by the caller; both loopbacks may share one port) for the
      sign-in's answer and returns its raw query string. Throws only when no answer came within -Seconds. The caller still
      checks state / error / code and stops the listeners (this function does not stop them).
    #>
    param([Parameter(Mandatory)][object[]]$Listeners, [int]$Seconds = 300, [int]$GraceSeconds = 10, [int]$ReadTimeoutMs = 2000,
          [string]$ReturnTo = 'PowerShell', [string]$TimeoutMessage = '')
    $deadline = [DateTime]::UtcNow.AddSeconds($Seconds); $graceEnd = $null
    $answer = $null; $kind = 'waiting'; $errText = ''
    while ($true) {
        $now = [DateTime]::UtcNow
        if ($answer) { if ($now -ge $graceEnd) { break } } elseif ($now -ge $deadline) { break }
        $ready = @($Listeners | Where-Object { $_.Pending() })[0]
        if (-not $ready) { Start-Sleep -Milliseconds 100; continue }
        $client = $null
        try {
            $client = $ready.AcceptTcpClient()
            $client.ReceiveTimeout = $ReadTimeoutMs
            $stream = $client.GetStream()
            $reader = New-Object System.IO.StreamReader($stream)
            $line = $null
            try { $line = $reader.ReadLine() } catch { $line = $null }   # a connection that sends nothing: dropped, never waited on
            if ($null -eq $line) { continue }
            if (-not $answer) {
                $q = Test-PimLoopbackAnswerQuery -RequestLine $line
                if ($q) {
                    $answer = $q; $graceEnd = [DateTime]::UtcNow.AddSeconds($GraceSeconds)
                    if ($q -match '(^|&)error=') {
                        $kind = 'failed'
                        $d = [regex]::Match($q, '(^|&)error_description=(?<d>[^&]*)')
                        $errText = if ($d.Success) { [uri]::UnescapeDataString(($d.Groups['d'].Value -replace '\+', ' ')) } else { '' }
                    } else { $kind = 'done' }
                }
            }
            $html = Get-PimLoopbackPage -Kind $kind -ReturnTo $ReturnTo -ErrorText $errText
            $bytes = [Text.Encoding]::UTF8.GetBytes($html)
            $head = [Text.Encoding]::ASCII.GetBytes("HTTP/1.1 200 OK`r`nContent-Type: text/html; charset=utf-8`r`nContent-Length: $($bytes.Length)`r`nConnection: close`r`n`r`n")
            $stream.Write($head, 0, $head.Length); $stream.Write($bytes, 0, $bytes.Length); $stream.Flush()
        } catch { }   # a browser that closed the connection itself: nothing to answer
        finally { if ($client) { try { $client.Close() } catch { } } }
    }
    if (-not $answer) {
        throw $(if ("$TimeoutMessage".Trim()) { $TimeoutMessage } else { "Timed out ($([int]($Seconds / 60)) minutes) waiting for the browser to finish the sign-in." })
    }
    return $answer
}

# ===== END inlined helper: PIM-LoopbackAnswer.ps1 =====
    }
    $query = Wait-PimLoopbackAnswer -Listeners $tcps -Seconds 300 -TimeoutMessage 'Timed out (5 min) waiting for the sign-in to come back to this window -- nothing was changed. Run the same command again and finish the sign-in within 5 minutes.'
  } finally { foreach ($t in $tcps) { try { $t.Stop() } catch { } } }

  $kv = @{}
  foreach ($pair in ($query -split '&')) { $k,$v = $pair -split '=',2; $kv[$k] = if ($null -ne $v) { [uri]::UnescapeDataString(($v -replace '\+',' ')) } else { '' } }
  if ($kv['error'])            { throw "Sign-in failed: $($kv['error']) -- $($kv['error_description'])" }
  if ($kv['state'] -ne $state) { throw 'State mismatch on the loopback redirect -- close ALL browser windows and retry.' }
  if (-not $kv['code'])        { throw 'Sign-in redirect carried no authorization code.' }

  $r = Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
    client_id     = $cid
    grant_type    = 'authorization_code'
    code          = $kv['code']
    redirect_uri  = $redirect
    code_verifier = $verifier
    scope         = $scope
  }
  # The account must belong to the TARGET tenant: a token from another tenant (wrong browser profile / account) stops here,
  # before any call is made with it.
  if ($tenant -match '^[0-9a-fA-F-]{36}$') {
    $tid = ''
    try {
      $pp = "$($r.access_token)".Split('.')[1].Replace('-', '+').Replace('_', '/'); while ($pp.Length % 4) { $pp += '=' }
      $tid = "$(([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($pp)) | ConvertFrom-Json).tid)".Trim()
    } catch { $tid = '' }
    if ($tid -and $tid -ne $tenant) { throw "You signed in to tenant $tid, but this is for tenant $tenant -- sign in with an account of $tenant (use that admin's browser profile)." }
  }
  if ($r.refresh_token) { $global:PimInteractiveRefresh["$tenant|$cid".ToLowerInvariant()] = $r.refresh_token }   # in memory only, never written
  return [pscustomobject]@{ token = $r.access_token; expiresUtc = (Get-Date).ToUniversalTime().AddSeconds([int]$r.expires_in - 60) }
}

# ---- framework 8.13 INSTALL-HANDOFF: one sign-in across Invardia's bootstrap and the product installer ----
# Invardia's bootstrap (Install-Invardia) signs the person in ONCE (browser PKCE, or the Cloud Shell user token) and, in
# the SAME process, just before it calls Install-PimManager, sets $env:PIM_HANDOFF_TOKENS =
#   { "https://management.azure.com/": { "access_token": "...", "expires_on": <epoch seconds> }, "https://graph.microsoft.com/": {...},
#     "https://database.windows.net/": {...} }
# ACCESS tokens only (no refresh token crosses the boundary); an audience it could not get is simply absent; it removes
# the variable in a finally block. Install-PimManager reads it ONCE (Import-PimHandoffTokens), clears it, and keeps only
# the tokens that pass the checks below in $global:PimHandoffTokens -- memory only, never a file, log, transcript or event.
# Every check is on the token's OWN claims (claims read only: this is our own process boundary, and the resource still
# validates the signature on every call).
#   tid       == the installation's tenant (config.tenantId). A mismatch on ANY audience refuses the WHOLE handoff: the
#                bootstrap signed in to a different tenant than the answers name, so none of it is trusted.
#   a USER    the token must be DELEGATED: Entra puts 'scp' only in delegated (user) tokens and 'roles' only (no scp) in
#                application tokens; 'idtyp' is an OPTIONAL claim, so 'idtyp = app' refuses but its absence proves nothing.
#                Rule: idtyp is not 'app' AND scp is present AND oid is a GUID. ('roles' beside scp is allowed: a user can
#                hold app roles.)
#   expiry    the earlier of expires_on and the JWT's exp must be more than 5 minutes away.
# A token failing a check (other than the tenant) is refused for ITS audience only; that audience falls back to PIM's own
# browser sign-in (Get-PimInteractiveToken, pinned to the tenant) when it is first needed, and that sign-in's in-memory
# refresh token then covers the other audiences PIM needs later.

function Get-PimHandoffAudienceKey {
  # PURE. The comparison key of an audience: 'https://management.azure.com/' and 'https://management.azure.com' are one.
  param([string]$Audience)
  return "$Audience".Trim().TrimEnd('/').ToLowerInvariant()
}

function ConvertFrom-PimHandoffJwt {
  # PURE. The payload claims of a JWT, or $null for anything that is not one. Never throws; never returns the token.
  param([string]$Token)
  try {
    $parts = "$Token".Split('.')
    if ($parts.Count -ne 3 -or -not $parts[1]) { return $null }
    $p = $parts[1].Replace('-', '+').Replace('_', '/')
    while ($p.Length % 4) { $p += '=' }
    $c = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json -ErrorAction Stop
    if ($null -eq $c -or $c -is [string] -or $c -is [ValueType]) { return $null }
    return $c
  } catch { return $null }
}

function ConvertTo-PimHandoffExpiry {
  # PURE. expires_on as a bootstrap hands it over -- epoch seconds (number or digit string: the MSAL / managed-identity /
  # Cloud Shell shape) or a date -- as a UTC [datetime], or $null when it cannot be read.
  param($Value)
  if ($null -eq $Value) { return $null }
  if ($Value -is [datetime]) { return $Value.ToUniversalTime() }
  if ($Value -is [DateTimeOffset]) { return $Value.UtcDateTime }
  $s = "$Value".Trim()
  if (-not $s) { return $null }
  if ($s -match '^\d{9,11}(\.\d+)?$') { try { return [DateTimeOffset]::FromUnixTimeSeconds([long][math]::Floor([double]$s)).UtcDateTime } catch { return $null } }
  $d = [DateTimeOffset]::MinValue
  if ([DateTimeOffset]::TryParse($s, [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::AssumeUniversal, [ref]$d)) { return $d.UtcDateTime }
  return $null
}

function Test-PimHandoffToken {
  <#
    PURE given -NowUtc. Check ONE handed-over access token (see the block above). Returns
    @{ ok; tenantMismatch; reason; expiresUtc; userName }. The reason never contains token text.
  #>
  param([string]$Token, $ExpiresOn, [Parameter(Mandatory)][string]$TenantId, [datetime]$NowUtc = [datetime]::UtcNow, [int]$MinValidityMinutes = 5,
        # APP-IDENTITY INSTALL (owner via Invardia 2026-10-21, Install-Invardia -ViaSupportApp): an APPLICATION token is
        # accepted ONLY when its appid is exactly this app -- the Invardia Support app of the session open in this process.
        # Empty (the default) = the user rule below, unchanged.
        [string]$AllowedAppId = '')
  $no = { param($why, [bool]$mismatch = $false) @{ ok = $false; tenantMismatch = $mismatch; reason = $why; expiresUtc = $null; userName = ''; kind = '' } }
  if (-not "$Token".Trim()) { return (& $no 'no access token was handed over') }
  $c = ConvertFrom-PimHandoffJwt -Token $Token
  if (-not $c) { return (& $no 'it is not a readable access token') }
  $want = "$TenantId".Trim().ToLowerInvariant()
  $tid = "$($c.tid)".Trim().ToLowerInvariant()
  if (-not $tid) { return (& $no 'it names no tenant (no tid claim)') }
  if ($tid -ne $want) { return (& $no "it is for tenant $tid, not this installation's tenant $want" $true) }
  $idtyp = "$($c.idtyp)".Trim().ToLowerInvariant()
  $kind = 'user'
  if ($idtyp -eq 'app' -or -not "$($c.scp)".Trim()) {
    $appid = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim().ToLowerInvariant()
    if (-not "$AllowedAppId".Trim() -or $appid -ne "$AllowedAppId".Trim().ToLowerInvariant()) { return (& $no 'it is an application token, not a signed-in user''s (idtyp=app or no delegated scp claim)') }
    $kind = 'app'
  }
  if ("$($c.oid)".Trim() -notmatch '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$') { return (& $no $(if ($kind -eq 'app') { 'it carries no object id (oid) of the application' } else { 'it carries no user object id (oid)' })) }
  $given = ConvertTo-PimHandoffExpiry -Value $ExpiresOn
  $jwtExp = $null
  if ("$($c.exp)".Trim() -match '^\d+$') { try { $jwtExp = [DateTimeOffset]::FromUnixTimeSeconds([long]"$($c.exp)".Trim()).UtcDateTime } catch { $jwtExp = $null } }
  $eff = @(@($given, $jwtExp) | Where-Object { $_ } | Sort-Object) | Select-Object -First 1
  if (-not $eff) { return (& $no 'it carries no expiry (no expires_on and no exp claim)') }
  if ($eff -le $NowUtc.ToUniversalTime().AddMinutes($MinValidityMinutes)) {
    return (& $no ("it expires at {0:yyyy-MM-dd HH:mm} UTC -- less than {1} minutes left" -f $eff, $MinValidityMinutes))
  }
  $upn = if ($kind -eq 'app') { '' } else { "$(if ($c.upn) { $c.upn } elseif ($c.unique_name) { $c.unique_name } elseif ($c.preferred_username) { $c.preferred_username } else { '' })".Trim() }
  return @{ ok = $true; tenantMismatch = $false; reason = ''; expiresUtc = $eff; userName = $upn; kind = $kind }
}

function Import-PimHandoffTokens {
  <#
    PURE given -NowUtc. Read the bootstrap's PIM_HANDOFF_TOKENS JSON and check every audience against -TenantId.
    Returns @{ present; refused; reason; accepted = @{ <audience key> = @{ token; expiresUtc } }; fallback = @(@{ audience; reason }) }.
      refused = a token for ANOTHER tenant was handed over: NOTHING is accepted (reason names the audience and both tenants).
      fallback = audiences that were handed over but refused (each falls back to the browser sign-in when it is needed).
    The values in 'accepted' are the only place the tokens go; the caller keeps them in memory and never prints them.
  #>
  param([string]$Json, [Parameter(Mandatory)][string]$TenantId, [datetime]$NowUtc = [datetime]::UtcNow,
        # APP-IDENTITY INSTALL: the Invardia Support app of the session open in this process ('' = users only, as before)
        [string]$AllowedAppId = '')
  $out = @{ present = $false; refused = $false; reason = ''; accepted = @{}; fallback = @(); kind = '' }
  if (-not "$Json".Trim()) { return $out }
  $out.present = $true
  $o = $null
  try { $o = $Json | ConvertFrom-Json -ErrorAction Stop } catch { $o = $null }
  if ($null -eq $o -or $o -is [string] -or $o -is [ValueType] -or $o -is [System.Array]) {
    $out.fallback = @(@{ audience = '(all)'; reason = 'the handed-over sign-in could not be read (not a JSON object)' })
    return $out
  }
  $mismatch = @()
  foreach ($p in $o.PSObject.Properties) {
    $v = $p.Value
    $tok = ''; $exp = $null
    if ($v -is [string]) { $tok = $v }
    elseif ($null -ne $v -and $v.PSObject.Properties['access_token']) { $tok = "$($v.access_token)"; if ($v.PSObject.Properties['expires_on']) { $exp = $v.expires_on } }
    $t = Test-PimHandoffToken -Token $tok -ExpiresOn $exp -TenantId $TenantId -NowUtc $NowUtc -AllowedAppId $AllowedAppId
    if ($t.tenantMismatch) { $mismatch += "$($p.Name): $($t.reason)" }
    elseif ($t.ok) { $out.accepted[(Get-PimHandoffAudienceKey $p.Name)] = @{ token = $tok; expiresUtc = $t.expiresUtc; userName = $t.userName; kind = $t.kind } }
    else { $out.fallback += @{ audience = "$($p.Name)"; reason = $t.reason } }
    $tok = $null
  }
  # One principal per handoff: a person's tokens beside an application's would make "who did this" a guess -- refused whole.
  $kinds = @($out.accepted.Values | ForEach-Object { "$($_.kind)" } | Select-Object -Unique)
  if ($kinds.Count -gt 1) {
    $out.refused = $true; $out.accepted = @{}
    $out.reason = 'the sign-in handed over by Invardia''s installer is REFUSED as a whole -- it mixes a person''s tokens with an application''s; nothing from it is used.'
    return $out
  }
  $out.kind = "$(@($kinds)[0])"
  if ($mismatch.Count) {
    $out.refused = $true
    $out.accepted = @{}
    $out.reason = ('the sign-in handed over by Invardia''s installer is REFUSED as a whole -- ' + ($mismatch -join '; ') +
                   '. It signed in to a different tenant than the installation answers name; nothing from it is used.')
  }
  return $out
}

function Get-PimHandoffToken {
  <# The validated handed-over access token for -Audience in -TenantId ($global:PimHandoffTokens, memory only), or '' when
     there is none, it is for another tenant, or it has under 2 minutes left (then the normal sign-in answers). #>
  param([string]$Audience, [string]$TenantId)
  $h = $global:PimHandoffTokens
  if (-not ($h -is [hashtable]) -or -not ($h.tokens -is [hashtable]) -or -not $h.tokens.Count) { return '' }
  if (-not "$TenantId".Trim() -or "$($h.tenantId)".Trim().ToLowerInvariant() -ne "$TenantId".Trim().ToLowerInvariant()) { return '' }
  $e = $h.tokens[(Get-PimHandoffAudienceKey $Audience)]
  if (-not $e -or -not "$($e.token)".Trim()) { return '' }
  if ($e.expiresUtc -le [datetime]::UtcNow.AddMinutes(2)) { return '' }
  return "$($e.token)"
}

# ---- the one entry point: get a token for a resource ----------------------
function Get-PimRestToken {
  [CmdletBinding()]
  param(
    [string]$Resource = 'graph',
    [string]$TenantId,[string]$ClientId,[string]$ClientSecret,
    [System.Security.Cryptography.X509Certificates.X509Certificate2]$Certificate,[string]$CertThumbprint,
    [switch]$UseManagedIdentity,[switch]$Interactive,[switch]$Force
  )
  $aud = Resolve-PimRestResource -Resource $Resource

  # The identity is resolved BEFORE the cache is consulted, because it is part of the
  # cache key. See BUG-22 below -- this ordering is the fix, do not move the lookup back
  # above these lines.
  $tenant = Get-PimTenantId -TenantId $TenantId
  $cid    = if ($ClientId) { $ClientId } elseif ($global:PIM_ClientId) { $global:PIM_ClientId } elseif ($env:AZURE_CLIENT_ID) { $env:AZURE_CLIENT_ID } else { $null }
  $sec    = if ($ClientSecret) { $ClientSecret } elseif ($global:PIM_ClientSecret) { $global:PIM_ClientSecret } elseif ($env:AZURE_CLIENT_SECRET) { $env:AZURE_CLIENT_SECRET } else { $null }
  # Cert thumbprint: explicit -CertThumbprint, else the engine SPN global / env. This is
  # the engine's real app-only auth (SPN + certificate, no secret) -- e.g. the
  # PIM4EntraPS-Engine cert in LocalMachine\My / CurrentUser\My.
  $thumb  = if ($CertThumbprint) { $CertThumbprint } elseif ($global:PIM_CertThumbprint) { $global:PIM_CertThumbprint } elseif ($env:PIM_CERT_THUMBPRINT) { $env:PIM_CERT_THUMBPRINT } else { $null }
  $cert   = if ($Certificate) { $Certificate } else { Resolve-PimCertificate -Thumbprint $thumb }

  # 🔴 SEC-12 -- WHAT THE CALLER ASKED FOR, which is NOT the same as what resolution produced.
  # Deliberately keyed on $thumb (the thumbprint that was REQUESTED), never on $cert (the object
  # that was RESOLVED): a certificate that was named and could not be loaded is a FAILURE TO
  # HONOUR the request, not the absence of one. Reading $cert here is exactly how a missing cert
  # became "no explicit identity was asked for" and slid onto the (since removed) ambient command-line fallback.
  $explicitIdentity = [bool]("$tenant".Trim()) -and [bool]("$cid".Trim()) -and
                      ([bool]("$sec".Trim()) -or [bool]("$thumb".Trim()) -or [bool]$Certificate)

  # BUG-22 (2026-08-06): this cache was keyed by the AUDIENCE ALONE -- no tenant, no client
  # id. In any process that touches TWO tenants, the second one silently reused the first
  # one's token, so every call meant for tenant B went to tenant A. That is precisely the
  # MSP master->slave fanout this product exists to run, and the failure is invisible: the
  # calls SUCCEED, against the wrong directory.
  #
  # Proven live: an S6 (local-slave) run targeting a tenant with ZERO PIM groups reported
  # "Groups live=85" -- the MASTER's group count -- and the verifier then found all six
  # groups missing from the managed tenant it was supposed to be managing. A write-shaped run would
  # have applied the customer's desired state to the MSP's own tenant.
  #
  # The key is now the full identity: audience + tenant + client + credential KIND (and the
  # cert thumbprint, so rotating a cert re-mints rather than serving the old token). No
  # secret material goes into the key.
  $mode = if ($Interactive -or $global:PIM_Interactive) { 'interactive' }
          elseif ($UseManagedIdentity -or $global:PIM_UseManagedIdentity -or ($env:IDENTITY_ENDPOINT -and -not $cid)) { 'mi' }
          elseif ($sec) { 'secret' }
          elseif ($cert) { "cert:$thumb" }
          elseif ($global:PIM_TokenProvider -is [scriptblock]) { 'signed-in' }
          else { 'unknown' }
  $key = ("$aud|$tenant|$cid|$mode").ToLowerInvariant()
  # same cross-scope guard as Resolve-PimRestResource: an unseeded cache must mean "cache
  # miss", never a thrown method call that the caller reads as "authentication failed".
  if (-not $script:PimTokenCache) { $script:PimTokenCache = @{} }
  if (-not $Force -and $script:PimTokenCache.ContainsKey($key)) {
    $e = $script:PimTokenCache[$key]
    if ($e.expiresUtc -gt (Get-Date).ToUniversalTime().AddMinutes(2)) { return $e.token }
  }

  # Framework 8.13 INSTALL-HANDOFF (REQ 100.66): the sign-in Invardia's bootstrap handed this process, already validated by
  # Import-PimHandoffTokens (this tenant, a USER, >5 min left) and held in memory only, answers FIRST for its audiences --
  # but never for a caller that named an explicit identity, and never for an explicit browser request (-Interactive, which
  # may need scopes the handed-over token does not carry). An audience it does not cover falls through to the sign-in below.
  # 🔴 2026-10-11 (a managed-tenant install, live): NEVER for Azure SQL. The handed-over database token is minted by the bootstrap
  # BEFORE this run creates the SQL server and makes the signed-in admin (or its group) the server's Entra admin -- that token
  # carries no such membership, and the schema step failed "Login failed for user '<token-identified principal>'". The
  # database audience always comes from a sign-in made now (after the assignment).
  if (-not $explicitIdentity -and -not ($Interactive -or $global:PIM_Interactive) -and "$aud" -notmatch '(?i)database\.windows\.net') {
    $hk = Get-PimHandoffToken -Audience $aud -TenantId $tenant
    if ($hk) { return $hk }
  }

  $res = $null
  # Explicit interactive request (break-glass): sign in as the human up front.
  if ($Interactive -or $global:PIM_Interactive) {
    try { $res = Get-PimInteractiveToken -Audience $aud -TenantId $tenant } catch { Write-Verbose "PIM-Rest interactive auth failed for ${Resource}: $($_.Exception.Message)" }
  }
  $primaryErr = $null
  if (-not $res) {
    try {
      if ($UseManagedIdentity -or $global:PIM_UseManagedIdentity -or ($env:IDENTITY_ENDPOINT -and -not $cid)) {
        $res = Get-PimManagedIdentityToken -Audience $aud
      }
      elseif ($tenant -and $cid -and $sec) {
        $res = Get-PimClientSecretToken -TenantId $tenant -ClientId $cid -ClientSecret $sec -Audience $aud
      }
      elseif ($tenant -and $cid -and $cert) {
        $res = Get-PimClientCertToken -TenantId $tenant -ClientId $cid -Certificate $cert -Audience $aud
      }
    } catch {
      # 🔴 SEC-12: KEEP the reason. This was Write-Verbose only, so the one fact that explained
      # everything downstream was discarded at the moment it was known.
      $primaryErr = "$($_.Exception.Message)"
      Write-Verbose "PIM-Rest primary auth failed for ${Resource}: $primaryErr"
    }
  }

  # =====================================================================================
  # 🔴 SEC-12 -- AN EXPLICIT IDENTITY THAT CANNOT BE HONOURED IS AN ERROR, NOT A CUE TO
  # BECOME SOMEBODY ELSE.
  #
  # MEASURED 2026-08-28: a caller asked for the internal tenant + the PIM engine
  # client id + its certificate thumbprint, and got back a token for ANOTHER company's tenant
  # (A DIFFERENT COMPANY's tenant) with a different appid. Nothing in the return value
  # said so. The certificate had failed to resolve, the failure went to Write-Verbose, and the
  # "dev convenience" command-line fallback (since removed, REQ 100.42) then minted a token for whatever
  # subscription happened to be that tool's DEFAULT context -- which on the dev machine is frequently another
  # tenant entirely.
  #
  # 🔑 THE POINT IS NOT THAT THE FALLBACK EXISTS. It is that it ran AFTER the caller had named a
  # tenant, a client id and a credential. That caller has said exactly who it wants to be, and
  # answering with a different principal is WORSE than answering with an error: the token works,
  # so the failure surfaces far away as "Login failed" or "permission denied" and reads like an
  # RBAC problem. It cost a session's time to chase, and the answer was three layers up.
  #
  # 📌 Same family as BUG-34, which fixed precisely this shape one layer down in
  # New-PimSqlConnection ("a valid-but-wrong-tenant token was taken, so the explicitly
  # configured SPN never got a turn") and left the command-line branch here standing (removed since, REQ 100.42).
  # =====================================================================================
  if (-not $res -and $explicitIdentity) {
    $why = if ("$thumb".Trim() -and -not $cert) {
             "certificate '$thumb' was not found in CurrentUser\My or LocalMachine\My, or has no usable private key"
           } elseif ($primaryErr) { $primaryErr } else { 'the credential was not accepted' }
    throw ("PIM-Rest: REFUSING to fall back to an ambient identity for '$Resource'. " +
           "An explicit identity was requested (tenant '$tenant', client '$cid') and could not be honoured: $why. " +
           'Fix the credential rather than letting the call authenticate as somebody else -- a token for the wrong ' +
           'principal succeeds and then fails far away as a permissions error.')
  }

  # §100.42 / framework §12.17 (owner 2026-10-09: "modern single connect only"): the command-line fallback ("reuse
  # whoever is signed in to the CLI") is GONE. A signed-in setup run does not borrow a tool's session any more:
  # tools\setup\_PimSignedIn.ps1 (Set-PimSignedInGlobals) REGISTERS its token source here --
  # the Invardia Support-app session's Get-InvardiaSupportToken when that session is open in the shell, otherwise the
  # person's own browser sign-in (Get-PimInteractiveToken, auth-code + PKCE). Only reached when NO explicit identity
  # was requested (the refusal above still throws for one that cannot be honoured).
  # 2026-10-10: a setup step's OWN child processes (e.g. the schema step) inherit PIM_HANDOFF_TOKENS from the build -- answer
  # from it first, so no grandchild process opens a silent browser sign-in.
  # 8.13: either shape is read -- the build's own (audience -> token string) or the bootstrap's (audience -> {access_token,
  # expires_on}) -- and a token whose tid is not the requested tenant is never returned (SEC-12).
  if (-not $res -and "$env:PIM_HANDOFF_TOKENS".Trim() -and -not $explicitIdentity) {
    try {
      $ho = "$env:PIM_HANDOFF_TOKENS" | ConvertFrom-Json
      foreach ($pp in $ho.PSObject.Properties) {
        if ("$($pp.Name)".TrimEnd('/').ToLowerInvariant() -eq "$aud".TrimEnd('/').ToLowerInvariant()) {
          # REQ 100.76: with a handed-over refresh token, Azure SQL is never answered from a pre-minted access token.
          if ("$aud" -match '(?i)database\.windows\.net' -and "$env:PIM_HANDOFF_REFRESH".Trim()) { continue }
          $hv = if ($pp.Value -is [string]) { "$($pp.Value)" } elseif ($pp.Value -and $pp.Value.PSObject.Properties['access_token']) { "$($pp.Value.access_token)" } else { '' }
          if (-not "$hv".Trim()) { continue }
          $hvTid = Get-PimTokenTenantId -Token $hv
          if ("$tenant".Trim() -and $hvTid -and $hvTid -ne "$tenant".Trim().ToLowerInvariant()) { Write-Verbose "PIM_HANDOFF_TOKENS: the token for $aud is for another tenant -- not used"; continue }
          return $hv
        }
      }
    } catch { Write-Verbose "PIM_HANDOFF_TOKENS unreadable: $($_.Exception.Message)" }
  }
  # REQ 100.76: a step's child process with no token source of its own mints from the handed-over refresh token -- silently,
  # at the moment it is asked (never a browser window from here).
  if (-not $res -and "$env:PIM_HANDOFF_REFRESH".Trim() -and -not $explicitIdentity -and -not ($global:PIM_TokenProvider -is [scriptblock])) {
    try { $res = Get-PimInteractiveToken -Audience $aud -TenantId $tenant -RefreshOnly } catch { Write-Verbose "PIM_HANDOFF_REFRESH exchange for ${Resource} failed: $($_.Exception.Message)" }
  }
  if (-not $res -and ($global:PIM_TokenProvider -is [scriptblock])) {
    $pt = $null
    try { $pt = & $global:PIM_TokenProvider $aud $tenant } catch { throw "PIM-Rest: the signed-in token source failed for '$Resource': $($_.Exception.Message)" }
    if ($pt -is [string]) { $pt = [pscustomobject]@{ token = $pt; expiresUtc = (Get-Date).ToUniversalTime().AddMinutes(30) } }
    if ($pt -and "$($pt.token)".Trim()) {
      # 🔒 VERIFY IT (SEC-12): asking for a tenant is not the same as being given one.
      $claimed = Get-PimTokenTenantId -Token "$($pt.token)"
      if ("$tenant".Trim() -and $claimed -and ($claimed -ne "$tenant".Trim().ToLowerInvariant())) {
        throw "PIM-Rest: REFUSED a signed-in token for '$Resource': it belongs to tenant $claimed, not the requested $tenant."
      }
      $res = $pt
    }
  }
  # LAST-RESORT interactive prompt — ONLY when an attended caller opts in via
  # $global:PIM_InteractiveFallback (the interactive admin tools set this; the engine /
  # headless cron NEVER does, so an unattended run still fails fast instead of hanging on
  # a browser prompt). This is what makes the admin deploy scripts "just sign me in" when
  # no MI/secret/cert token is available, rather than throwing.
  if (-not $res -and $global:PIM_InteractiveFallback) {
    Write-Host "PIM-Rest: no MI/secret/cert token for '$Resource' -- falling back to interactive sign-in..." -ForegroundColor Yellow
    try { $res = Get-PimInteractiveToken -Audience $aud -TenantId $tenant } catch { Write-Verbose "PIM-Rest interactive fallback failed for ${Resource}: $($_.Exception.Message)" }
  }
  # MI-TOKEN-TRANSIENT: carry the primary credential's own answer -- without it the record named no cause (SUP-2026-00323).
  if (-not $res) { throw ("PIM-Rest: could not acquire a token for '$Resource'. Provide a managed identity, ClientId + certificate (+TenantId), the Invardia Support-app session, or -Interactive (browser sign-in)." + $(if ($primaryErr) { " ($primaryErr)" } else { '' })) }

  $script:PimTokenCache[$key] = $res
  return $res.token
}

# ---- REST error reporting (BUG-27) ----------------------------------------
# A REST failure used to be logged as, verbatim:
#     PUT https://management.azure.com/.../roleEligibilityScheduleRequests/...
#         -> HTTP 409 :
# The colon is where the reason should be. ARM had actually answered
#     { "error": { "code": "ReadOnlyDisabledSubscription",
#                  "message": "The subscription '...' is disabled and therefore
#                              marked as read only." } }
# and the engine threw it away. Three wrong hypotheses were checked with live ARM
# queries before replaying the same PUT by hand produced the answer instantly.
#
# The whole audit rests on believing what the engine reports: a scope reporting
# "errors=1" with no cause is indistinguishable from a real code defect. In a
# customer tenant the same line is a support round-trip instead of a fix.
# ---------------------------------------------------------------------------

function Get-PimRestErrorBody {
  <#
    Read the error body from a terminating REST error, from BOTH sources.

    🪤 The old code was `if (ErrorDetails.Message) {...} else { read the stream }`. On
    Windows PowerShell 5.1 ErrorDetails.Message is frequently PRESENT BUT EMPTY, so the
    else-branch never ran and the stream -- which held the real answer -- was never read.
    Take the LONGER of the two instead of trusting either.
  #>
  [CmdletBinding()] param([Parameter(Mandatory)][object]$ErrorRecord)
  $fromDetails = ''
  try { if ($ErrorRecord.ErrorDetails) { $fromDetails = "$($ErrorRecord.ErrorDetails.Message)" } } catch {}
  $fromStream = ''
  try {
    $resp = $ErrorRecord.Exception.Response
    if ($resp) {
      $stream = $resp.GetResponseStream()
      if ($stream) {
        # The stream may already have been consumed; rewind when we are allowed to.
        try { if ($stream.CanSeek) { $stream.Position = 0 } } catch {}
        $sr = New-Object System.IO.StreamReader($stream)
        try { $fromStream = $sr.ReadToEnd() } finally { $sr.Dispose() }
      }
    }
  } catch {}
  if ("$fromStream".Trim().Length -gt "$fromDetails".Trim().Length) { return $fromStream }
  return $fromDetails
}

function Get-PimRestErrorDetail {
  <#
    PURE. Turn an ARM/Graph error body into the SHORT reason a human needs.

    Returns "<code> -- <message>", or $null when the body carries nothing usable (the
    caller must then say so explicitly rather than printing an empty reason).

    🔒 CODE + MESSAGE ONLY, NEVER THE WHOLE BODY. The raw body can carry subscription
    ids, principal ids and request ids; it is also mostly noise. code+message is the
    part that ends the diagnosis, so it is the right amount to log.

    Handles the shapes both APIs actually return:
      ARM      { "error": { "code": ..., "message": ... } }
      Graph    { "error": { "code": ..., "message": ..., "innerError": {...} } }
      flat     { "code": ..., "message": ... }
      odata    { "odata.error": { "code": ..., "message": { "value": ... } } }
      non-JSON (HTML error pages, plain text) -- returned trimmed + truncated.
  #>
  [CmdletBinding()] param([Parameter()][AllowNull()][AllowEmptyString()][string]$Body, [int]$MaxLength = 400)

  $raw = "$Body".Trim()
  if (-not $raw) { return $null }

  $obj = $null
  try { $obj = $raw | ConvertFrom-Json } catch { $obj = $null }

  # Property lookup is CASE-INSENSITIVE. `-contains` is not, and Azure is not consistent:
  # ARM/Graph send "message", some services send "Message". A case-sensitive check would
  # silently miss those and fall through to printing the raw body.
  $prop = {
    param($o, $name)
    try { foreach ($p in $o.PSObject.Properties) { if ("$($p.Name)" -ieq "$name") { return $p.Value } } } catch {}
    return $null
  }

  if ($obj) {
    $err = $null
    foreach ($k in @('error', 'odata.error')) {
      $v = & $prop $obj $k
      if ($null -ne $v) { $err = $v; break }
    }
    if ($null -eq $err) { $err = $obj }          # flat { code, message }

    $code = "$(& $prop $err 'code')".Trim()
    $m = & $prop $err 'message'
    $msg = ''
    if ($null -ne $m) {
      # odata nests the text one level deeper: message.value
      if ($m -isnot [string]) {
        $inner = & $prop $m 'value'
        $msg = if ($null -ne $inner) { "$inner".Trim() } else { "$m".Trim() }
      } else { $msg = "$m".Trim() }
    }

    if ($code -or $msg) {
      $joined = if ($code -and $msg) { "$code -- $msg" } elseif ($code) { $code } else { $msg }
      $joined = ($joined -replace '\s+', ' ').Trim()
      if ($joined.Length -gt $MaxLength) { $joined = $joined.Substring(0, $MaxLength) + '...' }
      return $joined
    }

    # Valid JSON that carries no code and no message -- e.g. "{}". Echoing it back would
    # print "HTTP 409 : {}", which is exactly as useless as the empty colon this whole
    # function exists to eliminate. Report NOTHING USABLE and let the caller say so.
    $hasAny = $false
    try { $hasAny = @($obj.PSObject.Properties).Count -gt 0 } catch {}
    if (-not $hasAny) { return $null }
  }

  # Not JSON (HTML error page, plain text), or JSON whose useful part we could not name:
  # return it trimmed + truncated. Better than nothing, and still bounded -- an error
  # page must not flood the log.
  $flat = ($raw -replace '\s+', ' ').Trim()
  if (-not $flat) { return $null }
  if ($flat.Length -gt $MaxLength) { $flat = $flat.Substring(0, $MaxLength) + '...' }
  return $flat
}

# ---- data plane -----------------------------------------------------------
# Every REST call is bounded (see Invoke-PimRest). $global:PIM_RestTimeoutSec overrides; floor 10 s, default 180 s.
function Get-PimRestTimeoutSec {
  $v = 0; if ($global:PIM_RestTimeoutSec) { [void][int]::TryParse("$($global:PIM_RestTimeoutSec)", [ref]$v) }
  if ($v -ge 10) { return $v }
  return 180
}
function Test-PimRestTimeoutError {
  # pwsh 7: HttpClient's timeout surfaces as TaskCanceledException / TimeoutException ("The request was canceled due to the
  # configured HttpClient.Timeout"); PS 5.1: WebException status Timeout ("The operation has timed out").
  param($ErrorRecord)
  $e = $null; try { $e = $ErrorRecord.Exception } catch { }
  while ($e) {
    if ($e -is [System.TimeoutException] -or $e -is [System.Threading.Tasks.TaskCanceledException]) { return $true }
    if ($e -is [System.Net.WebException] -and $e.Status -eq [System.Net.WebExceptionStatus]::Timeout) { return $true }
    $e = $e.InnerException
  }
  return ("$($ErrorRecord)" -match 'HttpClient\.Timeout|operation has timed out|request was canceled')
}
function Test-PimRestNetworkError {
  # UPDATER-ARM-RETRY (2026-10-21, internal): a call that failed BELOW HTTP (no status code) on a one-off network fault --
  # "Cannot assign requested address" (no free local port), connection refused / reset, a name that did not resolve. It failed
  # the updater's PATCH of ca-pim-manager once and nothing retried. Connect-level faults never reached the service, so any method
  # is safe to send again; a reset AFTER the request was sent is retried only for an idempotent method (never a POST).
  param($ErrorRecord, [string]$Method = 'GET')
  $connect = 'Cannot assign requested address|No connection could be made|actively refused|Connection refused|No such host is known|Name or service not known|nodename nor servname|Temporary failure in name resolution|Network is unreachable|NameResolutionFailure|ConnectFailure'
  $reset   = 'forcibly closed|Connection reset|connection was closed|transport connection|Broken pipe|An error occurred while sending the request|ReceiveFailure|SendFailure'
  $text = New-Object System.Collections.Generic.List[string]
  $e = $null; try { $e = $ErrorRecord.Exception } catch { }
  $isSock = $false
  while ($e) {
    $text.Add("$($e.Message)")
    if ($e -is [System.Net.Sockets.SocketException]) { $isSock = $true }
    if ($e -is [System.Net.WebException]) { $text.Add("$($e.Status)") }
    $e = $e.InnerException
  }
  $text.Add("$ErrorRecord")
  $all = $text -join ' | '
  if ($all -match $connect) { return $true }
  $idem = @('GET','HEAD','PUT','PATCH','DELETE','OPTIONS') -contains "$Method".ToUpperInvariant()
  if ($idem -and ($isSock -or $all -match $reset)) { return $true }
  return $false
}
function Get-PimRestNetworkRetryMax { <# PURE. Extra tries for a network fault (a literal). #> return 3 }
# §33.0 MORE TELEMETRY round 2 (owner "add relevant. i want data"): RETRIES PER HTTP CODE. Every 429 / 5xx retry of a GRAPH
# call (Invoke-PimRest's backoff loop and the $batch sub-requests) is counted in this process ($global: -- a dot-sourced
# function's $script: follows the caller's scope); the scheduler persists the counts after every job run into hourly
# buckets (pim.Settings 'GraphRetryCounts', Save-PimRestRetryCounts), and the heartbeat sends graphThrottled24h = the 429s
# of the last 24 hours. Counts only -- no URL, no tenant, no body.
function Add-PimRestRetryCount {
  param([int]$Code, [string]$Resource = 'graph')
  try {
    if ("$Resource" -ne 'graph') { return }
    $k = if ($Code -eq 429) { 'r429' } elseif ($Code -ge 500) { 'r5xx' } else { '' }
    if (-not $k) { return }
    if (-not ($global:PimRestRetryCounts -is [hashtable])) { $global:PimRestRetryCounts = @{ r429 = [long]0; r5xx = [long]0 } }
    $global:PimRestRetryCounts[$k] = [long]$global:PimRestRetryCounts[$k] + 1
  } catch { }
}
function Get-PimRestRetryCounts {
  # A COPY of this process's not-yet-persisted counts: @{ r429; r5xx } (zeros when nothing was counted).
  $c = $global:PimRestRetryCounts
  if (-not ($c -is [hashtable])) { return @{ r429 = [long]0; r5xx = [long]0 } }
  return @{ r429 = [long]$c['r429']; r5xx = [long]$c['r5xx'] }
}
function Get-PimRestRetryBucketHours { <# PURE. How many hourly buckets the record keeps (a literal). #> return 48 }
function Merge-PimRestRetryBuckets {
  <#
    PURE. The stored record (raw JSON text, or $null / '' for none) plus -Add @{ r429; r5xx } in the bucket of -NowUtc's hour
    -> the new record as JSON text: { sinceUtc; hours = { 'yyyy-MM-ddTHH:00:00Z' = { r429; r5xx } } }. Buckets older than
    Get-PimRestRetryBucketHours are dropped; sinceUtc (when counting started here) is kept. A stored value that is not
    the record's shape starts a new record. Built as text (no DateTime round-trip through ConvertFrom-Json on PS 7).
  #>
  param([AllowNull()][string]$Existing, [hashtable]$Add = @{}, [datetime]$NowUtc = [datetime]::UtcNow)
  $now = $NowUtc.ToUniversalTime()
  $cut = $now.AddHours(-1 * (Get-PimRestRetryBucketHours))
  $inv = [System.Globalization.CultureInfo]::InvariantCulture
  $styles = [System.Globalization.DateTimeStyles]::AssumeUniversal -bor [System.Globalization.DateTimeStyles]::AdjustToUniversal
  $since = $now.ToString('yyyy-MM-ddTHH:mm:ssZ', $inv)
  $hours = New-Object 'System.Collections.Generic.SortedDictionary[string,object]' ([System.StringComparer]::Ordinal)
  if ("$Existing".Trim()) {
    try {
      $o = "$Existing" | ConvertFrom-Json
      if ($null -ne $o -and $o.PSObject.Properties['hours']) {
        $sv = $o.sinceUtc
        if ($sv -is [datetime]) { $since = $sv.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', $inv) }
        elseif ("$sv".Trim()) { $d0 = [datetime]::MinValue; if ([datetime]::TryParse("$sv", [System.Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d0)) { $since = $d0.ToString('yyyy-MM-ddTHH:mm:ssZ', $inv) } }
        if ($null -ne $o.hours) {
          foreach ($p in @($o.hours.PSObject.Properties)) {
            $d = [datetime]::MinValue
            if (-not [datetime]::TryParse("$($p.Name)", [System.Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d)) { continue }
            if ($d -lt $cut) { continue }
            $a = 0L; $b = 0L
            [void][long]::TryParse("$($p.Value.r429)", [ref]$a); [void][long]::TryParse("$($p.Value.r5xx)", [ref]$b)
            $hours[$d.ToString('yyyy-MM-ddTHH:00:00Z', $inv)] = @{ r429 = [math]::Max(0L, $a); r5xx = [math]::Max(0L, $b) }
          }
        }
      }
    } catch { $hours.Clear() }
  }
  $key = $now.ToString('yyyy-MM-ddTHH:00:00Z', $inv)
  $ad = 0L; $bd = 0L; [void][long]::TryParse("$($Add['r429'])", [ref]$ad); [void][long]::TryParse("$($Add['r5xx'])", [ref]$bd)
  if ($ad -gt 0 -or $bd -gt 0) {
    $cur = if ($hours.ContainsKey($key)) { $hours[$key] } else { @{ r429 = 0L; r5xx = 0L } }
    $hours[$key] = @{ r429 = [long]$cur.r429 + [math]::Max(0L, $ad); r5xx = [long]$cur.r5xx + [math]::Max(0L, $bd) }
  }
  $parts = @(foreach ($k in $hours.Keys) { '"{0}":{{"r429":{1},"r5xx":{2}}}' -f $k, [long]$hours[$k].r429, [long]$hours[$k].r5xx })
  return ('{{"sinceUtc":"{0}","hours":{{{1}}}}}' -f $since, ($parts -join ','))
}
function Save-PimRestRetryCounts {
  <#
    Persist this process's counts into pim.Settings 'GraphRetryCounts' (compare-and-set, 5 tries -- several tick executions
    run at once) and zero what was saved. Writes ONLY when something was counted (a quiet run touches nothing -- no read,
    no write), so "no record" = no retry was ever recorded here. Never throws.
    Returns @{ saved; reason }. -Read { param($cs,$name) } / -Write { param($cs,$name,$new,$expected) -> rows }: test seams.
  #>
  param([string]$ConnectionString = '', [datetime]$NowUtc = [datetime]::UtcNow, [scriptblock]$Read = $null, [scriptblock]$Write = $null)
  try {
    $c = Get-PimRestRetryCounts
    $any = ([long]$c.r429 + [long]$c.r5xx) -gt 0
    if (-not $any) { return @{ saved = $false; reason = 'nothing counted' } }
    $cs = "$ConnectionString"
    if (-not $cs.Trim() -and (Get-Command Get-PimSqlSettingsConnectionString -ErrorAction SilentlyContinue)) { $cs = "$(Get-PimSqlSettingsConnectionString)" }
    if (-not $cs.Trim()) { return @{ saved = $false; reason = 'no SQL store' } }
    if (-not $Read) {
      if (-not (Get-Command Get-PimSqlSettingRaw -ErrorAction SilentlyContinue)) { return @{ saved = $false; reason = 'the settings reader is not loaded' } }
      $Read = { param($s, $n) Get-PimSqlSettingRaw -ConnectionString $s -Name $n }
    }
    if (-not $Write) {
      if (-not (Get-Command Set-PimSqlSettingIfUnchanged -ErrorAction SilentlyContinue)) { return @{ saved = $false; reason = 'the settings writer is not loaded' } }
      $Write = { param($s, $n, $new, $exp) Set-PimSqlSettingIfUnchanged -ConnectionString $s -Name $n -NewValueJson $new -ExpectedValueJson $exp }
    }
    for ($i = 0; $i -lt 5; $i++) {
      $raw = & $Read $cs 'GraphRetryCounts'
      $new = Merge-PimRestRetryBuckets -Existing $raw -Add $c -NowUtc $NowUtc
      $n = 0; try { $n = [int](@(& $Write $cs 'GraphRetryCounts' $new $raw) | Select-Object -Last 1) } catch { $n = 0 }
      if ($n -ge 1) {
        if ($global:PimRestRetryCounts -is [hashtable]) {
          $global:PimRestRetryCounts['r429'] = [math]::Max(0L, [long]$global:PimRestRetryCounts['r429'] - [long]$c.r429)
          $global:PimRestRetryCounts['r5xx'] = [math]::Max(0L, [long]$global:PimRestRetryCounts['r5xx'] - [long]$c.r5xx)
        }
        return @{ saved = $true; reason = '' }
      }
    }
    return @{ saved = $false; reason = 'another writer kept winning -- kept for the next run' }
  } catch { return @{ saved = $false; reason = "$($_.Exception.Message)" } }
}
function Invoke-PimRest {
  [CmdletBinding()]
  param(
    [string]$Method = 'GET',
    [Parameter(Mandatory)][string]$Url,
    [object]$Body,
    [string]$Resource = 'graph',
    [hashtable]$Headers = @{},
    [switch]$All,                # follow @odata.nextLink / nextLink, aggregate .value
    [int]$MaxRetry = 5,
    # Authenticate THIS call as the host's managed identity even when an engine SPN is configured
    # (mail send, operator decision 2026-09-13: the hosted engine sends as its managed identity).
    [switch]$UseManagedIdentity
  )
  # Keep a scheduler lease alive through a long live read (minutes of paged calls). No-op outside
  # a leased tick; time-gated in Invoke-PimSchedulerLeaseHeartbeat (PIM-Scheduler.ps1).
  if ($global:PIM_LeaseHeartbeat -and (Get-Command Invoke-PimSchedulerLeaseHeartbeat -ErrorAction SilentlyContinue)) { [void](Invoke-PimSchedulerLeaseHeartbeat) }
  $token = if ($UseManagedIdentity) { Get-PimRestToken -Resource $Resource -UseManagedIdentity } else { Get-PimRestToken -Resource $Resource }
  $h = @{ Authorization = "Bearer $token" } + $Headers
  $agg = New-Object System.Collections.Generic.List[object]
  $next = $Url
  while ($next) {
    $attempt = 0; $netTry = 0
    while ($true) {
      try {
        # 🔴 2026-10-02: NO -TimeoutSec = wait FOREVER on pwsh 7. One Graph call that never answered froze the hybrid worker's
        # continuous AD sync for 22 hours (process alive, task "Running", IgnoreNew -> never restarted). Every call is bounded now.
        $args = @{ Method = $Method; Uri = $next; Headers = $h; TimeoutSec = (Get-PimRestTimeoutSec) }
        # (see Get-PimRestErrorBody / Get-PimRestErrorDetail above for the failure path)
        if ($null -ne $Body -and $Method -ne 'GET') {
          $args.Body = if ($Body -is [string]) { $Body } else { $Body | ConvertTo-Json -Depth 20 }
          $args.ContentType = 'application/json'
        }
        $resp = Invoke-RestMethod @args
        break
      } catch {
        $code = $null; try { $code = [int]$_.Exception.Response.StatusCode } catch {}
        # BUG-27: surface the API error body. Try BOTH sources and keep the longer of the
        # two -- on 5.1 ErrorDetails.Message is frequently present but EMPTY, and the old
        # `if/else` took it and never looked at the stream, which is how a real ARM
        # explanation became the bare log line "-> HTTP 409 :" (note the empty colon).
        $body = Get-PimRestErrorBody -ErrorRecord $_
        # retry transient + freshly-created-principal replication (ARM 400 PrincipalNotFound)
        $isReplDelay = ($code -eq 400 -and "$body" -match 'PrincipalNotFound|does not exist in the directory')
        # a call that hit -TimeoutSec is retried ONCE (a second full wait is the most a stuck endpoint may cost), then fails
        $isTimeout = (-not $code) -and (Test-PimRestTimeoutError -ErrorRecord $_)
        if ($isTimeout -and $attempt -lt 1) { $attempt++; continue }
        if ($isTimeout) { throw "$Method $next -> timed out after $(Get-PimRestTimeoutSec) s (twice) -- the service did not answer" }
        # UPDATER-ARM-RETRY: a one-off network fault (no HTTP status) is tried again with a short backoff (5, 10, 20 s)
        if ((-not $code) -and (Test-PimRestNetworkError -ErrorRecord $_ -Method $Method)) {
          if ($netTry -lt (Get-PimRestNetworkRetryMax)) { Start-Sleep -Seconds ([int](5 * [Math]::Pow(2, $netTry))); $netTry++; continue }
        }
        if (($code -eq 429 -or $code -ge 500 -or $isReplDelay) -and $attempt -lt $MaxRetry) {
          if ($code -eq 429 -or $code -ge 500) { Add-PimRestRetryCount -Code ([int]$code) -Resource $Resource }   # §33.0 round 2
          $wait = [Math]::Min(60, [Math]::Pow(2, $attempt + 1))
          try { $ra = [int]("$($_.Exception.Response.Headers['Retry-After'])"); if ($ra -gt 0) { $wait = $ra } } catch {}
          Start-Sleep -Seconds $wait; $attempt++; continue
        }
        # section 9 missing-role hint: on a 403 / insufficient-privileges, append the EXACT
        # Graph app-role to grant (engine SPN, app-only) so the operator isn't left
        # guessing. Best-effort: only when the hint helper is loaded (PIM-Functions /
        # PIM-AuthDiagnostics dot-sourced) and the failure is a permissions failure.
        $hintText = ''
        if (Get-Command Get-PimMissingRoleHint -ErrorAction SilentlyContinue) {
            try {
                $appOnly = -not [bool]$global:PIM_Interactive
                $h = Get-PimMissingRoleHint -Path $next -StatusCode ([int]("$code")) -ErrorBody "$body" -AppOnly:$appOnly
                if ($h) { $hintText = "  >> $($h.Hint)" }
            } catch {}
        }
        # BUG-27: report error.code + error.message, NOT the raw body. The raw body can
        # carry ids and is usually mostly noise; code+message is the part that ends the
        # diagnosis. And a body that yields nothing usable must SAY SO -- "HTTP 409 :"
        # with an empty reason reads as "no reason exists", which sent a whole session
        # chasing three wrong hypotheses while ARM had the answer all along
        # ("ReadOnlyDisabledSubscription -- the subscription is disabled and therefore
        # marked as read only").
        $detail = Get-PimRestErrorDetail -Body $body
        # 2026-09-21 (operator: "can you provide graph or arm errors in here as i have nothing to work with"): the
        # thrown message stays code+message (above), but the full body of the LAST failure is kept for a caller that
        # needs more -- e.g. a policy-rule PATCH that adds the request-id and what it sent (Invoke-PimPolicyRulePatch).
        # 100.50: the Retry-After of that failure too (seconds; 0 = none) -- an ARM write refused with 409 OperationInProgress
        # is waited out by Invoke-PimArmBusyRetry (PIM-ArmContainerApps.ps1), which honours it when the service sent one.
        $raLast = 0
        try { $d = $_.Exception.Response.Headers.RetryAfter.Delta; if ($d) { $raLast = [int][Math]::Ceiling($d.TotalSeconds) } } catch { }
        if (-not $raLast) { try { [void][int]::TryParse("$($_.Exception.Response.Headers['Retry-After'])", [ref]$raLast) } catch { } }
        $global:PimLastRestError = [pscustomobject]@{ method = $Method; url = $next; status = $code; body = "$body"; atUtc = [datetime]::UtcNow; retryAfter = $raLast }
        if ($detail) { throw "$Method $next -> HTTP $code : $detail$hintText" }
        throw "$Method $next -> HTTP $code : (no error body returned by the service)$hintText"
      }
    }
    if (-not $All) { return $resp }
    if ($null -ne $resp.value) { foreach ($v in $resp.value) { $agg.Add($v) } } else { $agg.Add($resp) }
    $next = $null
    if ($resp.'@odata.nextLink') { $next = $resp.'@odata.nextLink' }
    elseif ($resp.nextLink)      { $next = $resp.nextLink }
  }
  return $agg.ToArray()
}

function ConvertTo-PimSdkShape {
  # Make a Graph REST object look like a Graph PowerShell SDK object: add a
  # PascalCase alias for every camelCase property (userPrincipalName ->
  # UserPrincipalName, displayName -> DisplayName, id -> Id) so existing engine
  # filters/consumers that expect SDK casing keep working over pure REST.
  param([Parameter(ValueFromPipeline)][object]$InputObject)
  process {
    if ($null -eq $InputObject) { return }
    $o = [ordered]@{}
    foreach ($p in $InputObject.PSObject.Properties) {
      $o[$p.Name] = $p.Value
      if ($p.Name.Length -ge 1) {
        $pascal = $p.Name.Substring(0,1).ToUpperInvariant() + $p.Name.Substring(1)
        if (-not $o.Contains($pascal)) { $o[$pascal] = $p.Value }
      }
    }
    [pscustomobject]$o
  }
}

function Invoke-PimGraph {
  param([string]$Method='GET',[Parameter(Mandatory)][string]$Path,[object]$Body,[switch]$All,[switch]$Beta,[hashtable]$Headers=@{},[switch]$UseManagedIdentity)
  $base = if ($Beta) { 'https://graph.microsoft.com/beta' } else { 'https://graph.microsoft.com/v1.0' }
  $url = if ($Path -match '^https?://') { $Path } else { "$base$Path" }
  Invoke-PimRest -Method $Method -Url $url -Body $Body -Resource 'graph' -All:$All -Headers $Headers -UseManagedIdentity:$UseManagedIdentity
}
function Test-PimGraphBatchReadsEnabled {
  # Kill switch for the batched live reads (pim.Settings / $global:PIM_ / env 'GraphBatchReads').
  # ON by default; 'false' makes every caller take its original one-request-per-path loop.
  $v = $null
  if (Get-Command Get-PimPolicySetting -ErrorAction SilentlyContinue) { try { $v = Get-PimPolicySetting -Name 'GraphBatchReads' -Default $null } catch { $v = $null } }
  elseif ($null -ne $global:PIM_GraphBatchReads) { $v = $global:PIM_GraphBatchReads }
  elseif ("$env:PIM_GraphBatchReads".Trim()) { $v = $env:PIM_GraphBatchReads }
  return -not ("$v".Trim() -match '^(?i)(false|0|no|off|disabled?)$')
}

function Invoke-PimGraphBatchGet {
  <#
    Run many Graph GETs through /$batch (20 per round-trip, Graph's maximum) and return ONE result per
    input path, IN INPUT ORDER: { path; ok; status; items; body; error }.
      items  = what `Invoke-PimGraph -All -Path <path>` returns: the aggregated .value across every
               @odata.nextLink page, or the body itself when it carries no .value.
      body   = what `Invoke-PimGraph -Path <path>` returns (the first page / the single object).
    A sub-request that is throttled (429), failed server-side (5xx) or came back missing is collected; the
    largest Retry-After is waited ONCE (max 30 s) and the collected items are sent again as a batch, up to 3
    rounds (§70.9). Only what is still unanswered after that is re-run on its own through Invoke-PimGraph,
    which owns the retry/backoff -- so a batch never loses a read that the sequential loop would have got.
    $script:PimBatchStats holds the counters of the last call. Any other 4xx is a final failure (ok=$false, error set), exactly
    what the sequential loop's `try { Invoke-PimGraph ... } catch { }` produced.
    A $batch response without `responses` (a proxy, a stub, a host that does not batch) falls back to
    the sequential path for that slice.
  #>
  param([Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Paths, [ValidateRange(1, 20)][int]$BatchSize = 20,
        # SCHEMA-QUIESCE-LONG-SNAPSHOT (2): a long read (the snapshot's ~36k group reads on a big tenant) says it is alive.
        # With a label, one "[graph-batch] <label>: progress ..." line at least every $script:PimBatchProgressSeconds (default
        # 300 s). No label = no line (every other caller stays as it was).
        [AllowEmptyString()][string]$ProgressLabel = '')
  $n = @($Paths).Count
  $results = New-Object object[] $n
  if ($n -eq 0) { return ,$results }
  $single = {
    param([string]$p)
    try {
      $first = Invoke-PimGraph -Path $p
      $items = New-Object System.Collections.Generic.List[object]
      $pg = $first
      while ($null -ne $pg) {
        if ($pg.PSObject -and $pg.PSObject.Properties['value']) { foreach ($v in @($pg.value)) { $items.Add($v) } } else { $items.Add($pg) }
        $nl = $null; if ($pg.PSObject -and $pg.PSObject.Properties['@odata.nextLink']) { $nl = "$($pg.'@odata.nextLink')" }
        if (-not $nl) { break }
        $pg = Invoke-PimGraph -Path $nl
      }
      [pscustomobject]@{ path = $p; ok = $true; status = 200; items = $items.ToArray(); body = $first; error = $null }
    } catch {
      [pscustomobject]@{ path = $p; ok = $false; status = 0; items = @(); body = $null; error = "$($_.Exception.Message)" }
    }
  }
  # 🔴 §70.9 (2026-09-13) -- THROTTLED ITEMS ARE WAITED OUT AND RE-BATCHED, NOT FIRED ONE BY ONE.
  # A 429 / 5xx sub-response used to be re-run IMMEDIATELY as its own single request, ignoring the Retry-After the
  # sub-response carried -- so under throttling a 20-item round-trip became up to 20 more calls into the same
  # throttle, each backing off on its own (2/4/8/16/32 s). Measured on internal: ~10 s per round-trip on the
  # group-membership read (35 round-trips, ~6 min) and the policy read (~570 s), with the cause invisible because
  # nothing counted the throttling. Now: collect the throttled items, wait the largest Retry-After once (bounded),
  # send them again AS A BATCH (up to 3 rounds), and only then fall back to the single-request path. Every call that
  # was throttled or slow says so in one [graph-batch] line.
  $sw = [System.Diagnostics.Stopwatch]::StartNew()
  $script:PimBatchStats = @{ roundTrips = 0; throttled = 0; serverErrors = 0; retryRounds = 0; waitedSeconds = 0; singles = 0; pacedSeconds = 0; batchSize = $BatchSize; progressLines = 0 }
  $progEvery = if ($null -ne $script:PimBatchProgressSeconds -and "$($script:PimBatchProgressSeconds)" -match '^\d+$') { [int]$script:PimBatchProgressSeconds } else { 300 }
  $progLast = 0.0
  $progress = {
    if (-not "$ProgressLabel".Trim()) { return }
    $el = $sw.Elapsed.TotalSeconds
    if (($el - $progLast) -lt $progEvery) { return }
    Set-Variable -Name progLast -Value $el -Scope 1
    $answered = 0; foreach ($x in $results) { if ($null -ne $x) { $answered++ } }
    $script:PimBatchStats.progressLines++
    Write-Host ("  [graph-batch] {0}: progress -- {1} of {2} reads answered, {3} round-trips, {4} throttled, {5:N1} min so far" -f $ProgressLabel, $answered, $n, $script:PimBatchStats.roundTrips, $script:PimBatchStats.throttled, ($el / 60.0)) -ForegroundColor DarkGray
  }
  # 🔴 PACING (2026-09-27, internal, measured in Log Analytics): the first pass fired every round-trip back to back, so once
  # Graph started throttling, almost every later round-trip came back 429 too -- two 712-path reads per drift snapshot
  # (group memberships, group policies) each drew ~1,240 throttled answers, ~190 single fallbacks and ~225 s. Now a
  # round-trip that came back throttled is followed by a pause (its Retry-After, at most 10 s) before the NEXT round-trip.
  # The pauses share a 120 s budget per call; once it is spent the reader behaves as before (never slower than unpaced).
  # Tunables (script scope, for measuring on a live tenant): the pause cap and the per-call budget.
  $paceCap = if ($script:PimBatchPaceMaxSeconds -gt 0) { [int]$script:PimBatchPaceMaxSeconds } else { 10 }
  $paceBudget = if ($script:PimBatchPaceBudgetSeconds -gt 0) { [int]$script:PimBatchPaceBudgetSeconds } else { 120 }
  $pace = {
    param([int]$RetryAfter)
    if ($script:PimBatchStats.pacedSeconds -ge $paceBudget) { return }
    $p = [Math]::Min($paceCap, [Math]::Max(1, $RetryAfter))
    $p = [Math]::Min($p, $paceBudget - $script:PimBatchStats.pacedSeconds)
    $script:PimBatchStats.pacedSeconds += $p; $script:PimBatchStats.waitedSeconds += $p
    if ($script:PimBatchSleep -is [scriptblock]) { & $script:PimBatchSleep $p } else { Start-Sleep -Seconds $p }
  }
  $sendBatch = {
    param([int[]]$Indexes)
    $pending = New-Object System.Collections.Generic.List[int]   # throttled / missing -> retry
    $maxRetryAfter = 0
    $requests = New-Object System.Collections.Generic.List[object]
    foreach ($i in $Indexes) {
      $rel = ("$($Paths[$i])" -replace '^https://graph\.microsoft\.com/(v1\.0|beta)', '')
      $requests.Add(@{ id = "$i"; method = 'GET'; url = $rel })
    }
    $resp = $null
    $script:PimBatchStats.roundTrips++
    try { $resp = Invoke-PimGraph -Method POST -Path 'https://graph.microsoft.com/v1.0/$batch' -Body @{ requests = $requests.ToArray() } } catch { $resp = $null }
    $subs = $null
    if ($null -ne $resp -and $resp.PSObject -and $resp.PSObject.Properties['responses']) { $subs = @($resp.responses) }
    if ($null -eq $subs) { return [pscustomobject]@{ pending = @(); maxRetryAfter = 0; batched = $false } }   # no batch support -> singles
    $want = @{}; foreach ($i in $Indexes) { $want[$i] = $true }
    foreach ($br in $subs) {
        if ($null -eq $br) { continue }
        $idx = -1; if (-not [int]::TryParse("$($br.id)", [ref]$idx)) { continue }
        if (-not $want.ContainsKey($idx)) { continue }
        $status = 0; [void][int]::TryParse("$($br.status)", [ref]$status)
        if ($status -eq 429 -or $status -ge 500) {
          if ($status -eq 429) { $script:PimBatchStats.throttled++ } else { $script:PimBatchStats.serverErrors++ }
          Add-PimRestRetryCount -Code $status -Resource 'graph'   # §33.0 round 2: graphThrottled24h
          $ra = 0
          try { if ($br.headers) { foreach ($hp in $br.headers.PSObject.Properties) { if ("$($hp.Name)" -ieq 'Retry-After') { [void][int]::TryParse("$($hp.Value)", [ref]$ra) } } } } catch { }
          if ($ra -gt $maxRetryAfter) { $maxRetryAfter = $ra }
          $pending.Add($idx)
          continue
        }
        $body = $br.body
        if ($status -ge 200 -and $status -lt 300) {
          $items = New-Object System.Collections.Generic.List[object]
          $pg = $body; $ok = $true; $err = $null
          while ($null -ne $pg) {
            if ($pg.PSObject -and $pg.PSObject.Properties['value']) { foreach ($v in @($pg.value)) { $items.Add($v) } } else { $items.Add($pg) }
            $nl = $null; if ($pg.PSObject -and $pg.PSObject.Properties['@odata.nextLink']) { $nl = "$($pg.'@odata.nextLink')" }
            if (-not $nl) { break }
            try { $pg = Invoke-PimGraph -Path $nl } catch { $ok = $false; $err = "$($_.Exception.Message)"; break }
          }
          $results[$idx] = [pscustomobject]@{ path = $Paths[$idx]; ok = $ok; status = $status; items = @(if ($ok) { $items.ToArray() }); body = $body; error = $err }
        } else {
          $code = ''; $msg = ''
          if ($body -and $body.PSObject -and $body.PSObject.Properties['error'] -and $body.error) { $code = "$($body.error.code)"; $msg = "$($body.error.message)" }
          $results[$idx] = [pscustomobject]@{ path = $Paths[$idx]; ok = $false; status = $status; items = @(); body = $null
            error = ("GET {0} -> HTTP {1} : {2}{3}" -f $Paths[$idx], $status, $code, $(if ($msg) { " -- $msg" } else { '' })) }
        }
    }
    # an id Graph did not answer at all is retried like a throttled one
    foreach ($i in $Indexes) { if ($null -eq $results[$i] -and -not $pending.Contains($i)) { $pending.Add($i) } }
    return [pscustomobject]@{ pending = @($pending.ToArray()); maxRetryAfter = $maxRetryAfter; batched = $true }
  }
  $retryQueue = New-Object System.Collections.Generic.List[int]
  $maxRa = 0
  # 🔑 SHRINK ON THROTTLE (2.4.457, measured on a test environment with 712 PIM-for-Groups schedule reads): every batch size took the same
  # 259-287 s -- the tenant's own Graph ceiling (~2.7 reads/s), which no pacing beats -- but 20 per round-trip drew 444
  # throttled answers and 49 single fallbacks, 10 drew 63 and none, 5 drew 20 and none. So a read starts at $BatchSize and
  # halves it (down to 5) after each throttled round-trip: an unthrottled read keeps full batches, a throttled one stops
  # piling 429s onto the ceiling. $script:PimBatchStats.batchSize is the size it ended on.
  $curSize = $BatchSize
  $ofs = 0
  while ($ofs -lt $n) {
    $last = [Math]::Min($ofs + $curSize, $n) - 1
    $r = & $sendBatch -Indexes @($ofs..$last)
    $ofs = $last + 1
    & $progress
    foreach ($p in @($r.pending)) { $retryQueue.Add([int]$p) }
    if ($r.maxRetryAfter -gt $maxRa) { $maxRa = $r.maxRetryAfter }
    if (@($r.pending).Count) {
      if ($curSize -gt 5) { $curSize = [Math]::Max(5, [int][Math]::Floor($curSize / 2)) }
      if ($ofs -lt $n) { & $pace $r.maxRetryAfter }   # throttled: let it clear before the next
    }
  }
  $script:PimBatchStats.batchSize = $curSize
  # Up to 3 rounds: wait out the throttle ONCE for the whole queue, then send the queue again in batches.
  $round = 0
  while ($retryQueue.Count -gt 0 -and $round -lt 3) {
    $round++
    $script:PimBatchStats.retryRounds = $round
    $wait = [Math]::Min(30, [Math]::Max($maxRa, [int][Math]::Pow(2, $round)))
    $script:PimBatchStats.waitedSeconds += $wait
    if ($script:PimBatchSleep -is [scriptblock]) { & $script:PimBatchSleep $wait } else { Start-Sleep -Seconds $wait }   # test seam
    $queue = @($retryQueue.ToArray() | Where-Object { $null -eq $results[$_] })
    $retryQueue.Clear(); $maxRa = 0
    $o = 0
    while ($o -lt $queue.Count) {
      $slice = @($queue[$o..([Math]::Min($o + $curSize, $queue.Count) - 1)])
      $o += $slice.Count
      $r = & $sendBatch -Indexes $slice
      & $progress
      foreach ($p in @($r.pending)) { $retryQueue.Add([int]$p) }
      if ($r.maxRetryAfter -gt $maxRa) { $maxRa = $r.maxRetryAfter }
      if (@($r.pending).Count) {
        if ($curSize -gt 5) { $curSize = [Math]::Max(5, [int][Math]::Floor($curSize / 2)) }
        if ($o -lt $queue.Count) { & $pace $r.maxRetryAfter }
      }
    }
  }
  $script:PimBatchStats.batchSize = $curSize
  # Anything still unanswered (still throttled after the rounds, or a host that does not batch): the single-request
  # path, which owns its own Retry-After/backoff -- so a batch never loses a read the sequential loop would have got.
  for ($i = 0; $i -lt $n; $i++) { if ($null -eq $results[$i]) { $script:PimBatchStats.singles++; $results[$i] = & $single $Paths[$i] } }
  $sw.Stop()
  $st = $script:PimBatchStats
  if ($st.throttled -or $st.serverErrors -or $st.singles -or $sw.Elapsed.TotalSeconds -ge 20) {
    Write-Host ("  [graph-batch] {0} path(s), {1} round-trip(s), {2} throttled (429), {3} server error(s), {4} retry round(s) waiting {5}s (paced {8}s), {6} single fallback(s), batch {9}->{10}, {7:N1}s" -f `
      $n, $st.roundTrips, $st.throttled, $st.serverErrors, $st.retryRounds, $st.waitedSeconds, $st.singles, $sw.Elapsed.TotalSeconds, $st.pacedSeconds, $BatchSize, $st.batchSize) -ForegroundColor DarkGray
  }
  return ,$results
}

function Get-PimArmActiveRoleAssignmentsViaArg {
  <#
    EVERY Azure RBAC role assignment visible to the engine identity, in ONE Azure Resource Graph query
    (POST /providers/Microsoft.ResourceGraph/resources, paged by $skipToken) -- management groups,
    subscriptions, resource groups and resources alike, with the role NAME joined in the same query.
    REST only: no Az module (REQUIREMENTS 67.3). Throws when the query fails, so a caller can say so
    and fall back instead of rendering an empty list as "no assignments".
    Output: { Id; Name; Scope; PrincipalId; PrincipalType; RoleDefinitionId (GUID); RoleDefinitionName }.
    -Stream (100.31 SNAPSHOT-OOM, 2026-10-09): emit each row to the pipeline as its page arrives instead of returning
    the whole set at the end, so a caller that projects rows (`... -Stream | ForEach-Object { }`) holds ONE page of
    raw rows, not every role assignment in the tenant twice.
  #>
  param([int]$PageSize = 1000, [switch]$Stream)
  $kql = @(
    'authorizationresources'
    '| where type =~ ''microsoft.authorization/roleassignments'''
    '| extend roleGuid = tolower(extract(''([^/]+)$'', 1, tostring(properties.roleDefinitionId)))'
    '| project id, name, scope = tostring(properties.scope), principalId = tostring(properties.principalId), principalType = tostring(properties.principalType), roleDefinitionId = tostring(properties.roleDefinitionId), roleGuid'
    '| join kind=leftouter (authorizationresources | where type =~ ''microsoft.authorization/roledefinitions'' | extend roleGuid = tolower(name) | summarize roleName = any(tostring(properties.roleName)) by roleGuid) on roleGuid'
    '| project id, name, scope, principalId, principalType, roleDefinitionId, roleGuid, roleName'
  ) -join ' '
  $out = New-Object System.Collections.Generic.List[object]
  $skipToken = $null
  do {
    $opts = @{ '$top' = $PageSize; resultFormat = 'objectArray' }
    if ($skipToken) { $opts['$skipToken'] = $skipToken }
    $resp = Invoke-PimArm -Method POST -Path '/providers/Microsoft.ResourceGraph/resources' -ApiVersion '2021-03-01' -Body @{ query = $kql; options = $opts }
    foreach ($r in @($resp.data)) {
      if ($null -eq $r) { continue }
      $guid = "$($r.roleGuid)"; if (-not $guid) { $guid = ("$($r.roleDefinitionId)" -split '/')[-1] }
      $o = [pscustomobject]@{
        Id = "$($r.id)"; Name = "$($r.name)"; Scope = "$($r.scope)"; PrincipalId = "$($r.principalId)"; PrincipalType = "$($r.principalType)"
        RoleDefinitionId = $guid; RoleDefinitionName = $(if ("$($r.roleName)".Trim()) { "$($r.roleName)" } else { $null })
      }
      if ($Stream) { $o } else { $out.Add($o) }
    }
    if ($resp -and $resp.PSObject.Properties['data']) { $resp.data = $null }   # the raw page goes as soon as it is projected
    $skipToken = $null
    if ($resp -and $resp.PSObject.Properties['$skipToken'] -and "$($resp.'$skipToken')".Trim()) { $skipToken = "$($resp.'$skipToken')" }
  } while ($skipToken)
  if ($Stream) { return }
  # Unrolled on purpose: `@(Get-PimArmActiveRoleAssignmentsViaArg | ForEach-Object ...)` must see ROWS, not one array.
  return $out.ToArray()
}

function Invoke-PimArm {
  param([string]$Method='GET',[Parameter(Mandatory)][string]$Path,[object]$Body,[string]$ApiVersion='2022-04-01',[switch]$All,[hashtable]$Headers=@{})
  $url = if ($Path -match '^https?://') { $Path } else { "https://management.azure.com$Path" }
  if ($url -notmatch 'api-version=') { $url += ($(if ($url -match '\?') {'&'} else {'?'}) + "api-version=$ApiVersion") }
  Invoke-PimRest -Method $Method -Url $url -Body $Body -Resource 'arm' -All:$All -Headers $Headers
}
function Invoke-PimPowerBI {
  # PIM 100.142: -MaxRetry passes through, so the admin-api client (Invoke-PimPowerBiAdminRequest, PIM-WorkloadConnectors.ps1)
  # can own the 429 handling (the admin api allows 200 requests per hour). The default (5) is unchanged for every other caller.
  param([string]$Method='GET',[Parameter(Mandatory)][string]$Path,[object]$Body,[switch]$All,[hashtable]$Headers=@{},[int]$MaxRetry=5)
  $url = if ($Path -match '^https?://') { $Path } else { "https://api.powerbi.com/v1.0/myorg$Path" }
  Invoke-PimRest -Method $Method -Url $url -Body $Body -Resource 'powerbi' -All:$All -Headers $Headers -MaxRetry $MaxRetry
}

# ---- Exchange Online (app-only, pure REST, NO ExchangeOnlineManagement) ----
# The EXO V3 PowerShell module's "REST-backed cmdlets" are thin wrappers around
# the Exchange admin REST endpoint:
#   POST https://outlook.office365.com/adminapi/beta/<tenant>/InvokeCommand
#   body { CmdletInput: { CmdletName: '<Verb-Noun>', Parameters: { ... } } }
# authenticated with an app-only token for the https://outlook.office365.com
# audience (the same Exchange.ManageAsApp consent the module needs). Calling
# this endpoint directly means the engine sets mailbox forwarding etc. with the
# engine SPN + certificate over PIM-Rest -- no module to Install-Module, no EXO
# V3 runspace-state bug, PS 5.1-safe. Anti-affinity routing (X-AnchorMailbox /
# Prefer) is unnecessary for tenant-admin cmdlets against the beta endpoint.
#
# NOTE on feasibility: NOT every EXO cmdlet is reachable this way -- some are
# session-bound or stream large result sets the InvokeCommand shape doesn't
# return cleanly. The engine's ONLY runtime EXO need is Set-Mailbox mail
# forwarding, which is a simple parameterized cmdlet and works over this path.
# Connect-ExchangeOnline itself becomes a no-op (token-per-call, no session).
function Get-PimExoTenantSegment {
  # The InvokeCommand path takes the tenant's *initial* domain or tenant GUID.
  param([string]$TenantId)
  $t = if ($TenantId) { $TenantId } elseif ($global:PIM_ExoOrganization) { $global:PIM_ExoOrganization } elseif ($global:PIM_TenantId) { $global:PIM_TenantId } else { Get-PimTenantId }
  if (-not $t) { throw "Invoke-PimExoCmdlet: no tenant/organization. Set -Organization, `$global:PIM_ExoOrganization (initial .onmicrosoft.com domain) or `$global:PIM_TenantId." }
  return $t
}
function Invoke-PimExoCmdlet {
  <#
    Run a single Exchange Online admin cmdlet app-only over REST.
      Invoke-PimExoCmdlet -CmdletName 'Set-Mailbox' -Parameters @{ Identity='u@x'; ForwardingSmtpAddress='a@b'; DeliverToMailboxAndForward=$false }
    Returns the cmdlet's .value payload (array) or the raw response.
  #>
  [CmdletBinding()]
  param(
    [Parameter(Mandatory)][string]$CmdletName,
    [hashtable]$Parameters = @{},
    [string]$Organization,
    [int]$MaxRetry = 5
  )
  $seg = Get-PimExoTenantSegment -TenantId $Organization
  $url = "https://outlook.office365.com/adminapi/beta/$seg/InvokeCommand"
  $body = @{ CmdletInput = @{ CmdletName = $CmdletName; Parameters = $Parameters } }
  $resp = Invoke-PimRest -Method POST -Url $url -Body $body -Resource 'exo' -MaxRetry $MaxRetry
  if ($null -ne $resp -and ($resp.PSObject.Properties.Name -contains 'value')) { return $resp.value }
  return $resp
}
function Test-PimMailForwardAddressIsReal {
  <#
    Shared sentinel predicate -- the engine apply path and the Manager validator
    (tools/pim-manager/_validator.ps1, PIM-DOMAIN-001) MUST agree on what counts
    as a real forwarding address. The Account-Definitions schema reuses the
    literal string 'FALSE' (and blanks / 'no' / '0' / 'none' / 'n/a') to mean
    "no forwarding address", so those values are NOT addresses and must never be
    forwarded to. Returns $true only for something shaped like an email address.
  #>
  [CmdletBinding()]
  param([AllowNull()][object]$Value)
  $s = ([string]$Value).Trim()
  if (-not $s) { return $false }
  switch ($s.ToUpperInvariant()) {
    'FALSE' { return $false }
    'NO'    { return $false }
    '0'     { return $false }
    'NONE'  { return $false }
    'N/A'   { return $false }
    default { return ($s -match '^[^@\s]+@[^@\s]+\.[^@\s]+$') }
  }
}

function Get-PimAdminMailRecipient {
  <#
    THE ONE RECIPIENT RULE for mail PIM sends about an admin account (new-admin, tap-delivery).
    Shared by the engine (PIM-EngineProviders.ps1) and the Manager (Get-PimAdminTapRecipient), so
    the screen's "Sends to" is exactly the address the engine mails.

      ForwardMailsToContact = TRUE  AND  MailForwardAddress is a real address  -> MailForwardAddress
      else the admin's SPONSOR DEPARTMENT's Owners                             -> all of them
      else ManagerEmail, if it is a real address                               -> LEGACY ONLY
      else                                                                     -> ''  (caller refuses)

    🔑 The rule, and the reason for each step, live on Get-PimAdminMailRecipientPlan below -- this is
    only the string-returning wrapper. Read that comment before changing anything here. In particular
    the sponsor is a DEPARTMENT, not a person (operator, 2026-09-16), and ManagerEmail survives solely
    so existing data keeps working; it is reported as 'manager-legacy' so callers can say "move this
    to the department".
    🔑 Operator, 2026-09-12 ("Both"): MailForwardAddress is the admin OWNER's office user. An admin
    account has no mailbox of its own, so PIM's own mail goes to that office user; and where the admin
    account DOES have a mailbox, the engine also sets Exchange forwarding to it (gated, see
    Invoke-PimAdminMailboxForwarding). The columns were retired 2026-08-12 and are un-retired with
    this meaning.
    🪤 An address that is not an address ('FALSE'/'true' -- measured as live v1 data on internal) is
    NOT a recipient. Test-PimMailForwardAddressIsReal is the shared predicate; 'true' fails its
    address shape and is rejected here explicitly as well.
    🪤 This wrapper returns only the FIRST recipient. Anything that mails a department (which can have
    several owners) must call Get-PimAdminMailRecipientPlan and use .recipients.
  #>
  [CmdletBinding()]
  param([AllowNull()][object]$Row, [hashtable]$DepartmentOwners)
  $plan = if ($PSBoundParameters.ContainsKey('DepartmentOwners')) { Get-PimAdminMailRecipientPlan -Row $Row -DepartmentOwners $DepartmentOwners }
          else { Get-PimAdminMailRecipientPlan -Row $Row }
  return "$($plan.recipient)"
}

function Split-PimMailRecipients {
  # PURE. A recipient list as the model writes it (pipe-joined UPNs per the Manager UX; ';' and ',' accepted too) --
  # the SAME parsing the group-owner path uses (Split-PimOwners), so an admin's department owners and a group's owners
  # can never be read differently.
  param([AllowNull()][string]$Raw)
  @("$Raw" -split '[|;,]' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
}

function Get-PimAdminMailRecipientPlan {
  <#
    🔑 71.19 -- THE SPONSOR IS A DEPARTMENT, NOT A PERSON (operator, 2026-09-16: *"the logic is that an admin is linked
    to a dept (sponsor) and the dept has owners ... change the code, as i think logic is wrong"*; REQUIREMENTS §62:
    *"we dont add a manager on the person"*, *"whoever is the actual manager of the dept gets the emails, approvals
    etc"*, *"otherwise you are vulnerable for org changes"*).

    Who receives PIM's mail about an admin account (new-admin notice, TAP delivery), in order:

      1. ForwardMailsToContact = TRUE AND MailForwardAddress is a real address
         -> that address. The deliberate PER-ADMIN OVERRIDE (operator 2026-09-12 "Both": the admin owner's office
            user). Kept because it is an explicit statement on the row, not a person-as-manager guess.
      2. the admin's SPONSOR DEPARTMENT's owners: Account-Definitions-Admins.Department -> the
         PIM-Definitions-Departments row for that department -> its Owners (pipe/;/,-joined UPNs)
         -> ALL of them. This is the rule.
      3. ManagerEmail, if it is a real address -> LEGACY ONLY, so existing data keeps working. It is reported as
         'manager-legacy' so the validator, the Manager and the readiness check can say "move this to the department".
      4. nothing -> '' and a reason that names the admin, its department and what to set.

    The department index is INJECTED (-DepartmentOwners: department name in lower case -> owners string) because this
    file is the transport layer and must not read the store; the engine passes Get-PimDepartmentOwnerIndex, the Manager
    and the validator pass their own. Without it, step 2 is skipped and the reason says the index was not supplied --
    never silently "no department".

    Returns @{ recipients = @(all); recipient = <first>; source = forward|department|manager-legacy|none;
               department; reason; legacy = [bool] }.
  #>
  [CmdletBinding()]
  param([AllowNull()][object]$Row, [hashtable]$DepartmentOwners = $null)
  $out = [ordered]@{ recipients = @(); recipient = ''; source = 'none'; department = ''; reason = ''; legacy = $false }
  if ($null -eq $Row) { $out['reason'] = 'no admin row'; return $out }
  $get = {
    param($name)
    if ($Row -is [System.Collections.IDictionary]) { return "$($Row[$name])".Trim() }
    $p = $Row.PSObject.Properties[$name]
    if ($p) { return "$($p.Value)".Trim() }
    return ''
  }
  $isAddr = { param($v) ("$v" -notmatch '(?i)^(true|yes|1)$') -and (Test-PimMailForwardAddressIsReal -Value $v) }
  $who = & $get 'UserPrincipalName'; if (-not $who) { $who = & $get 'UserName' }
  $dept = & $get 'Department'
  # When the caller did not inject one, use the engine's own index if this process has it loaded (the engine and the
  # Manager both do). Wrapped: a store read that fails must leave the reason "not supplied", never pretend "no owners".
  if ($null -eq $DepartmentOwners -and (Get-Command Get-PimDepartmentOwnerIndex -ErrorAction SilentlyContinue)) {
    try { $DepartmentOwners = Get-PimDepartmentOwnerIndex } catch { $DepartmentOwners = $null }
  }
  $out['department'] = $dept

  $fwdOn = ((& $get 'ForwardMailsToContact') -match '(?i)^(true|yes|1)$')
  $fwd   = & $get 'MailForwardAddress'
  if ($fwdOn -and (& $isAddr $fwd)) {
    $out['recipients'] = @($fwd); $out['recipient'] = $fwd; $out['source'] = 'forward'
    $out['reason'] = "per-admin override: ForwardMailsToContact=TRUE + MailForwardAddress on $who"
    return $out
  }

  if ($dept) {
    if ($null -eq $DepartmentOwners) {
      $out['reason'] = "the department owner index was not supplied to this call, so '$dept' could not be resolved (load the store / pass -DepartmentOwners)"
    } else {
      $key = $dept.ToLowerInvariant()
      if ($DepartmentOwners.ContainsKey($key)) {
        $owners = @(Split-PimMailRecipients ("$($DepartmentOwners[$key])")) | Where-Object { & $isAddr $_ }
        if (@($owners).Count) {
          $out['recipients'] = @($owners); $out['recipient'] = @($owners)[0]; $out['source'] = 'department'
          $out['reason'] = "sponsor department '$dept' owner(s): $(@($owners) -join ', ')"
          return $out
        }
        $out['reason'] = "the sponsor department '$dept' of $who has no usable Owners -- set Owners on that department (PIM-Definitions-Departments)"
      } else {
        $out['reason'] = "$who names department '$dept', but there is no PIM-Definitions-Departments row for it -- add the department (with Owners), or correct the admin's Department"
      }
    }
  } else {
    $out['reason'] = "$who has no Department -- an admin's mail goes to its SPONSOR DEPARTMENT's owners, so set the admin's Department and give that department Owners"
  }

  $mgr = & $get 'ManagerEmail'
  if (& $isAddr $mgr) {
    $out['recipients'] = @($mgr); $out['recipient'] = $mgr; $out['source'] = 'manager-legacy'; $out['legacy'] = $true
    $out['reason'] = "LEGACY: using ManagerEmail ($mgr) on $who. The rule is the sponsor department's owners -- $($out['reason'])"
    return $out
  }
  # 5. 2026-09-21 (operator: "i cannot set tap on managing tenant either" / "we must also get email from managed tenants when account is
  #    created/replicated down"): with no override, no department owner and no legacy manager, the mail about this admin
  #    (new-admin notice, TAP) goes to THIS tenant's ALERT RECIPIENTS (PIM_AlertRecipient + Manager > Alerting) -- the
  #    people who run the environment. Before, there was nobody to send to, so no TAP could be issued at all and a
  #    replicated admin arrived in a managed tenant without anyone being told. Reported as 'alert-recipients' so the screens
  #    still say "set a sponsor department" for the proper route.
  $alert = @()
  try {
    if (Get-Command Get-PimSafetyAlertRecipients -ErrorAction SilentlyContinue) { $alert = @(Get-PimSafetyAlertRecipients) }
    elseif (Get-Command Get-PimAlertingConfig -ErrorAction SilentlyContinue) { $alert = @((Get-PimAlertingConfig).recipients) }
  } catch { $alert = @() }
  $alert = @($alert | ForEach-Object { "$_".Trim() } | Where-Object { & $isAddr $_ } | Select-Object -Unique)
  if ($alert.Count) {
    $out['recipients'] = @($alert); $out['recipient'] = $alert[0]; $out['source'] = 'alert-recipients'
    $out['reason'] = "no sponsor department owner for $who -- sent to this tenant's alert recipients ($($alert -join ', ')). $($out['reason'])"
    return $out
  }
  return $out
}

function Test-PimAdminMailboxForwardingEnabled {
  <#
    Opt-in gate for setting Exchange mailbox forwarding on admin accounts. DEFAULT OFF, so rolling an
    image changes nothing until an operator turns it on: it needs an Exchange app permission
    (Exchange.ManageAsApp + an EXO role) whose grant model is still unresolved (§65.11).
    $global:PIM_AdminMailboxForwarding first, then $env:PIM_AdminMailboxForwarding (SEC-07 order,
    so a container-app setting is honoured). Only an explicit true/1/yes enables it.
  #>
  [CmdletBinding()]
  param([object]$Override = $null)
  $v = if ($null -ne $Override) { $Override }
       elseif (Get-Command Get-PimFeatureSetting -ErrorAction SilentlyContinue) { Get-PimFeatureSetting -Name 'AdminMailboxForwarding' }   # PIM 100.121: process -> environment -> store -> off
       elseif ($null -ne $global:PIM_AdminMailboxForwarding -and "$($global:PIM_AdminMailboxForwarding)".Trim()) { $global:PIM_AdminMailboxForwarding }
       else { $env:PIM_AdminMailboxForwarding }
  return ("$v".Trim() -match '(?i)^(true|1|yes|on)$')
}

function Invoke-PimAdminMailboxForwarding {
  <#
    BEST-EFFORT, INERT-SAFE mailbox forwarding for ONE admin account. Never throws -- an admin
    apply must not fail because forwarding could not be set.

      gate OFF                                  -> 'disabled'   (no call at all)
      account has no mailbox                    -> 'no-mailbox' (Verbose only -- the NORMAL case:
                                                                 admin accounts usually hold no licence)
      flag TRUE + real address                  -> forward to it, DeliverToMailboxAndForward=$false
      flag not TRUE, mailbox currently forwards -> clear it
      flag not TRUE, nothing forwarded          -> 'nochange'
      401/403 from Graph or EXO                 -> ONE warning per run naming the permission, 'forbidden'

    -GraphInvoker / -ExoInvoker exist for offline tests; production uses Invoke-PimGraph and
    Set-PimMailboxForwarding / Invoke-PimExoCmdlet.
  #>
  [CmdletBinding()]
  param(
    [Parameter(Mandatory)][AllowNull()][object]$Row,
    [Parameter(Mandatory)][string]$UserPrincipalName,
    [string]$UserId,
    [object]$Enabled = $null,
    [scriptblock]$GraphInvoker,
    [scriptblock]$ExoInvoker
  )
  try {
    if (-not (Test-PimAdminMailboxForwardingEnabled -Override $Enabled)) { return 'disabled' }
    $id = if ("$UserId".Trim()) { "$UserId".Trim() } else { $UserPrincipalName }
    $isForbidden = { param($err) ("$err" -match '(?i)\b(401|403)\b|Forbidden|Unauthorized|AccessDenied|Authorization_RequestDenied') }
    $warnOnce = {
      param($what)
      if (-not $script:PimAdminFwdForbiddenWarned) {
        $script:PimAdminFwdForbiddenWarned = $true
        Write-Warning ("  [AdminForwarding] $what was refused (401/403). Mailbox forwarding needs the Exchange " +
          "application permission Exchange.ManageAsApp plus an Exchange role (e.g. Mail Recipients) for the identity " +
          "the engine runs as. Skipping forwarding for every admin this run; nothing else is affected.")
      }
    }
    # 1. Does the account have a mailbox? (cheap: one GET, and the answer is usually "no")
    try {
      $null = if ($GraphInvoker) { & $GraphInvoker 'GET' "/users/$id/mailboxSettings" }
              else { Invoke-PimGraph -Method GET -Path "/users/$id/mailboxSettings" }
    } catch {
      $m = "$($_.Exception.Message) $($_.ErrorDetails.Message)"
      if ($m -match '(?i)MailboxNotEnabledForRESTAPI|MailboxNotFound|ResourceNotFound|\b404\b|not found') {
        Write-Verbose "  [AdminForwarding] $UserPrincipalName has no mailbox -- nothing to forward."
        return 'no-mailbox'
      }
      if (& $isForbidden $m) { & $warnOnce 'Reading mailboxSettings'; return 'forbidden' }
      Write-Verbose "  [AdminForwarding] $UserPrincipalName mailbox probe failed: $m"
      return 'error'
    }
    # 2. Apply or clear.
    $flagOn = ("$(if ($Row -is [System.Collections.IDictionary]) { $Row['ForwardMailsToContact'] } else { $Row.ForwardMailsToContact })".Trim() -match '(?i)^(true|yes|1)$')
    $addr   = "$(if ($Row -is [System.Collections.IDictionary]) { $Row['MailForwardAddress'] } else { $Row.MailForwardAddress })".Trim()
    $exo = {
      param($cmd, $params)
      if ($ExoInvoker) { return (& $ExoInvoker $cmd $params) }
      return (Invoke-PimExoCmdlet -CmdletName $cmd -Parameters $params)
    }
    try {
      if ($flagOn -and (Test-PimMailForwardAddressIsReal -Value $addr) -and ($addr -notmatch '(?i)^(true|yes|1)$')) {
        & $exo 'Set-Mailbox' @{ Identity = $UserPrincipalName; ForwardingSmtpAddress = $addr; DeliverToMailboxAndForward = $false } | Out-Null
        return 'forwarded'
      }
      $cur = @(& $exo 'Get-Mailbox' @{ Identity = $UserPrincipalName })
      $curFwd = if ($cur.Count) { "$($cur[0].ForwardingSmtpAddress)".Trim() } else { '' }
      if (-not $curFwd) { return 'nochange' }
      & $exo 'Set-Mailbox' @{ Identity = $UserPrincipalName; ForwardingSmtpAddress = $null; DeliverToMailboxAndForward = $false } | Out-Null
      return 'cleared'
    } catch {
      $m = "$($_.Exception.Message) $($_.ErrorDetails.Message)"
      if (& $isForbidden $m) { & $warnOnce 'Set-Mailbox'; return 'forbidden' }
      Write-Warning "  [AdminForwarding] $UserPrincipalName -- forwarding could not be set: $m (the admin account itself was applied)."
      return 'error'
    }
  } catch {
    Write-Verbose "  [AdminForwarding] $UserPrincipalName -- unexpected: $($_.Exception.Message)"
    return 'error'
  }
}

function Set-PimMailboxForwarding {
  <#
    Pure-REST equivalent of the engine's only runtime EXO call:
      Set-Mailbox -Identity <upn> -ForwardingSmtpAddress <smtp> -DeliverToMailboxAndForward:$false
    Pass -ForwardingSmtpAddress '' to CLEAR forwarding.

    Safety net: a 'FALSE'/sentinel address is treated as "no address" (clears
    forwarding) so the engine never forwards mail to the literal string 'FALSE'
    even if a caller forgets the upstream guard. Aligns with
    Test-PimMailForwardAddressIsReal in the validator.
  #>
  [CmdletBinding()]
  param(
    [Parameter(Mandatory)][string]$Identity,
    [string]$ForwardingSmtpAddress,
    [bool]$DeliverToMailboxAndForward = $false,
    [string]$Organization
  )
  $p = @{ Identity = $Identity; DeliverToMailboxAndForward = $DeliverToMailboxAndForward }
  # EXO accepts a null to clear forwarding; an empty string is rejected. A
  # sentinel ('FALSE'/'no'/'0'/...) is NOT a real address -> clear instead.
  if (-not (Test-PimMailForwardAddressIsReal -Value $ForwardingSmtpAddress)) { $p['ForwardingSmtpAddress'] = $null }
  else { $p['ForwardingSmtpAddress'] = $ForwardingSmtpAddress }
  Invoke-PimExoCmdlet -CmdletName 'Set-Mailbox' -Parameters $p -Organization $Organization | Out-Null
}

# ===== END inlined helper: ..\..\engine\_shared\PIM-Rest.ps1 =====
# ===== BEGIN inlined helper: _PimSignedIn.ps1 =====
<#
.SYNOPSIS
    71.33 -- the SIGNED-IN (interactive) identity for the one-shot MSP build and the setup steps it runs.

.DESCRIPTION
    Operator 2026-09-17: "I thought I could just do interactive login to deploy." A customer deploys by signing in
    as a human administrator; certificates are the MSP management host's automation pattern only. So every step the
    build runs inside ONE tenant accepts -UseSignedInAccount (or, where the script already had that convention, simply
    no credential) and then authenticates through the ONE sign-in rule (framework 12.17, REQ 100.42): the Invardia
    Support session open in this window (Use-PimSupportAppRestSession / Get-InvardiaSupportToken), otherwise the
    person's own browser sign-in (auth code + PKCE, never device code), registered into PIM-Rest as
    $global:PIM_TokenProvider. No command-line tool, no module, no certificate, no secret, nothing written to disk by
    this code, and no token ever printed or logged.

    WHAT IS ASSERTED BEFORE ANYTHING IS USED (a wrong default context on a multi-tenant machine is a real trap):
      * the signed-in principal is a USER (an application is refused -- that is the certificate mode's job, and a
        signed-in SPN would silently change who the audit trail names) -- or exactly the Invardia Support app;
      * its tenant equals the build config's tenantId, and the subscription is the one named explicitly and visible;
      * every token minted from it (ARM, SQL) is decoded and its tenant and user-ness checked;
      * no environment variable is set that would make a token call quietly authenticate as somebody else
        (AZURE_CLIENT_SECRET, PIM_CERT_THUMBPRINT, a managed identity endpoint ...).

    SQL: Azure SQL here is Entra-only, so the signed-in user needs database rights -- by being a MEMBER of the SQL admin
    group (grp-pim-sql-admins) that is the server's Entra admin. Invoke-PimSignedInSqlAdminMembership adds the user as a
    member (members-only: it never creates the group and never moves the admin).
    TRAP: an Entra token carries group membership as of when it was issued, and a token is reused for up to about an
    hour. A user added to the group in THIS run may be refused by SQL until their token refreshes -- the helper says so.

    Pure parts are offline-tested in tests/Test-PimMspBuild.ps1 (section S).
#>

$script:PimSignedInGuid = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
# Environment variables that make a token call authenticate as SOMEBODY ELSE than the signed-in user.
$script:PimSignedInConflictVars = @('AZURE_CLIENT_ID', 'AZURE_CLIENT_SECRET', 'AZURE_CLIENT_CERTIFICATE_PATH', 'AZURE_FEDERATED_TOKEN_FILE',
                                    'PIM_CERT_THUMBPRINT', 'IDENTITY_ENDPOINT', 'MSI_ENDPOINT')

function ConvertFrom-PimJwtClaims {
    # PURE. The claims of a JWT (never validates the signature -- this is only used to ASSERT who a token is for).
    param([string]$Token)
    try {
        $seg = "$Token".Split('.')[1].Replace('-', '+').Replace('_', '/')
        while ($seg.Length % 4) { $seg += '=' }
        return ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($seg)) | ConvertFrom-Json)
    } catch { return $null }
}

function Get-PimSupportAppSession {
    <#
      PURE given -Environment (name -> value; default: this process). The Invardia Support app session that an older
      Invardia connect script announced in THIS shell through environment variables (framework 4.1a), or $null. It is
      recognised only when the connect script's private profile folder IS the active one (INVARDIA_SUPPORT_AZCONFIG ==
      AZURE_CONFIG_DIR) -- a service principal signed in any other way is never treated as the support app. Used only to
      ACCEPT that app's token; the token itself always comes from PIM-Rest's one client.
      Returns @{ tenantId; subscriptions[]; environment } or $null.
    #>
    param([hashtable]$Environment)
    $get = { param($n) if ($Environment) { "$($Environment[$n])" } else { "$([Environment]::GetEnvironmentVariable($n))" } }
    $dir = "$(& $get 'INVARDIA_SUPPORT_AZCONFIG')".Trim(); $cur = "$(& $get 'AZURE_CONFIG_DIR')".Trim()
    if (-not $dir -or -not $cur -or $dir.TrimEnd('\', '/') -ne $cur.TrimEnd('\', '/')) { return $null }
    $tid = "$(& $get 'INVARDIA_SUPPORT_TENANT')".Trim().ToLowerInvariant()
    if ($tid -notmatch $script:PimSignedInGuid) { return $null }
    $subs = @("$(& $get 'INVARDIA_SUPPORT_SUBSCRIPTIONS')" -split '[,;\s]+' | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ -match $script:PimSignedInGuid })
    return @{ tenantId = $tid; subscriptions = $subs; environment = "$(& $get 'INVARDIA_SUPPORT_ENVIRONMENT')".Trim() }
}

function Test-PimSignedInToken {
    <#
      PURE. Assert a token belongs to a signed-in USER of -TenantId. Returns @{ ok; reason; objectId; userName; tenantId }.
      An application token (idtyp=app, or no user claims) is refused: that is a different principal wearing the same call.
    #>
    # -AllowedAppId: the Invardia Support app's appId (from Test-PimSignedInAccount); an application token is accepted
    # ONLY when its appid is exactly that app.
    param([string]$Token, [string]$TenantId, [string]$AllowedAppId = '')
    $c = ConvertFrom-PimJwtClaims -Token $Token
    if (-not $c) { return @{ ok = $false; reason = 'the token could not be decoded' } }
    $tid = "$($c.tid)".Trim().ToLowerInvariant()
    if ($tid -ne "$TenantId".Trim().ToLowerInvariant()) { return @{ ok = $false; reason = "the token is for tenant '$tid', not '$TenantId' -- REFUSING" } }
    $upn = "$(if ($c.upn) { $c.upn } elseif ($c.unique_name) { $c.unique_name } elseif ($c.preferred_username) { $c.preferred_username } else { '' })".Trim()
    $idtyp = "$($c.idtyp)".Trim().ToLowerInvariant()
    $appid = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim().ToLowerInvariant()
    if ("$AllowedAppId".Trim() -and $appid -eq "$AllowedAppId".Trim().ToLowerInvariant() -and -not $upn) {
        if ("$($c.oid)".Trim() -notmatch $script:PimSignedInGuid) { return @{ ok = $false; reason = 'the support app token carries no object id' } }
        return @{ ok = $true; reason = ''; objectId = "$($c.oid)".Trim().ToLowerInvariant(); userName = "Invardia Support app ($appid)"; tenantId = $tid; supportApp = $true }
    }
    if ($idtyp -eq 'app' -or (-not $upn -and $idtyp -ne 'user')) {
        return @{ ok = $false; reason = "the token is an APPLICATION token (appid '$($c.appid)'), not the signed-in user's -- REFUSING" }
    }
    if ("$($c.oid)".Trim() -notmatch $script:PimSignedInGuid) { return @{ ok = $false; reason = 'the token carries no user object id' } }
    return @{ ok = $true; reason = ''; objectId = "$($c.oid)".Trim().ToLowerInvariant(); userName = $upn; tenantId = $tid }
}

function Test-PimCloudShell {
    # PURE given -Environment. Azure Cloud Shell sets AZUREPS_HOST_ENVIRONMENT=cloud-shell/<ver> and ACC_CLOUD; there the
    # MSI_ENDPOINT / IDENTITY_ENDPOINT serve the SIGNED-IN USER's token (Cloud Shell's own token broker), not a machine
    # identity -- so they are no conflict there (§95.2 Cloud Shell blocker 2, guided install 2026-10-03).
    param([hashtable]$Environment)
    $get = { param($n) if ($Environment) { "$($Environment[$n])" } else { "$([Environment]::GetEnvironmentVariable($n))" } }
    return ((& $get 'AZUREPS_HOST_ENVIRONMENT') -match '^(?i)cloud-shell') -or [bool]"$(& $get 'ACC_CLOUD')".Trim()
}

function Get-PimSignedInEnvironmentConflicts {
    # PURE given -Environment (a hashtable name -> value); by default reads this process. The names that are set.
    # In Azure Cloud Shell MSI_ENDPOINT / IDENTITY_ENDPOINT are the user's own token broker and are not counted.
    param([hashtable]$Environment)
    $cloudShell = Test-PimCloudShell -Environment $Environment
    $out = @()
    foreach ($n in $script:PimSignedInConflictVars) {
        if ($cloudShell -and $n -in 'MSI_ENDPOINT', 'IDENTITY_ENDPOINT') { continue }
        $v = if ($Environment) { $Environment[$n] } else { [Environment]::GetEnvironmentVariable($n) }
        if ("$v".Trim()) { $out += $n }
    }
    return @($out)
}

function Clear-PimSignedInMachineIdentity {
    <#
      Azure Arc and the Azure VM agent set IDENTITY_ENDPOINT / MSI_ENDPOINT (+ IMDS_ENDPOINT / IDENTITY_HEADER) MACHINE-WIDE,
      so on a customer's Arc-joined jump host every signed-in script used to stop with "IDENTITY_ENDPOINT is set in this
      session" (a customer, 2026-10-21) and the admin had to clear them by hand. They name the MACHINE's identity, never the person:
      this script clears them for ITS OWN PROCESS only -- the machine and its agent are untouched -- and says so in one line.
      Not in Azure Cloud Shell, where they are the signed-in user's own token broker. Returns the names it cleared.
    #>
    param([hashtable]$Environment)
    if (Test-PimCloudShell -Environment $Environment) { return @() }
    $names = @('IDENTITY_ENDPOINT', 'MSI_ENDPOINT', 'IMDS_ENDPOINT', 'IDENTITY_HEADER', 'MSI_SECRET')
    $set = @($names | Where-Object { "$(if ($Environment) { $Environment[$_] } else { [Environment]::GetEnvironmentVariable($_) })".Trim() })
    if (-not $set.Count) { return @() }
    foreach ($n in $set) { if ($Environment) { $Environment.Remove($n) } else { [Environment]::SetEnvironmentVariable($n, $null, 'Process') } }
    Write-Host "  note: this machine's own identity ($($set -join ', '), set by Azure Arc or the Azure VM agent) is ignored for this run -- you sign in as yourself; the machine is not changed." -ForegroundColor DarkGray
    return @($set)
}

function Get-PimSignedInConflictHint {
    # PURE. How to clear the named variables for THIS session only (§73.9: on an Azure Arc / Azure VM host
    # IDENTITY_ENDPOINT is set machine-wide, and an operator had to be told how to clear it).
    param([string[]]$Names)
    $n = @($Names | Where-Object { "$_".Trim() })
    if (-not $n.Count) { return '' }
    $cmd = ($n | ForEach-Object { "`$env:$_ = `$null" }) -join '; '
    $arc = if ($n -contains 'IDENTITY_ENDPOINT' -or $n -contains 'MSI_ENDPOINT') {
        ' IDENTITY_ENDPOINT / MSI_ENDPOINT are set machine-wide by Azure Arc or an Azure VM agent: clearing them in this window affects this window only, never the machine or the agent.'
    } else { '' }
    return "Clear them for this session only, then re-run in the same window: $cmd.$arc Or use the certificate mode."
}

function Use-PimSupportAppRestSession {
    <#
      100.41 / framework 4.1a -- the Invardia Support app's REST session ($global:InvardiaSupportState, set by
      Connect-InvardiaSupport.ps1 -Environment <handle>) for -TenantId (+ an allowed -SubscriptionId): point PIM-Rest's ONE token
      client at it (client credentials with the app's secret -- the one agreed support method). Returns the app id
      (lowercase) or '' when no such session covers this tenant + subscription. Nothing is printed; the secret only moves
      into PIM-Rest's process-local global. -State is the test seam (default: the session in this shell).
    #>
    param([Parameter(Mandatory)][string]$TenantId, [string]$SubscriptionId, [object]$State)
    $s = if ($PSBoundParameters.ContainsKey('State')) { $State } else { $global:InvardiaSupportState }
    if (-not ($s -is [hashtable]) -or -not $s.Secret -or "$($s.AppId)" -notmatch $script:PimSignedInGuid) { return '' }
    if ("$($s.TenantId)".Trim().ToLowerInvariant() -ne "$TenantId".Trim().ToLowerInvariant()) { return '' }
    $subs = @(@($s.Subscriptions) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
    if ("$SubscriptionId".Trim() -and -not ($subs -contains "$SubscriptionId".Trim().ToLowerInvariant())) { return '' }
    # Owner token rule (2026-10-09): tools get TOKENS from Get-InvardiaSupportToken -- the Support app's secret NEVER leaves
    # the support session. So PIM-Rest is pointed at the session's token function (Set-PimSignedInGlobals registers
    # Get-PimSignedInToken as $global:PIM_TokenProvider), never at a copy of the secret.
    if (-not $PSBoundParameters.ContainsKey('State') -and -not (Get-Command Get-InvardiaSupportToken -ErrorAction SilentlyContinue)) { return '' }
    Set-PimSignedInGlobals -TenantId "$TenantId".Trim().ToLowerInvariant()
    foreach ($n in 'PIM_ClientSecret', 'PIM_CertThumbprint', 'PIM_UseManagedIdentity', 'PIM_Interactive', 'PIM_InteractiveFallback') { Set-Variable -Scope Global -Name $n -Value $null -WhatIf:$false }
    $global:PIM_NoManagedIdentity = $true
    return "$($s.AppId)".Trim().ToLowerInvariant()
}

function Get-PimSignedInIdentity {
    <#
      Read and ASSERT the signed-in identity for one tenant + subscription. Returns @{ ok; reason; userName; objectId;
      tenantId; subscriptionId }. The ARM token is minted only to read the user's object id and is then discarded.
      100.41 / 100.42 (NO-AZ, framework 12.17): over REST only -- the token comes from PIM-Rest's ONE client (the Invardia
      Support app's REST session when one covers this tenant, else the person's own browser sign-in), its claims are
      asserted, and the subscription is read over ARM to prove it is visible and in -TenantId. There is no second path.
      -Token / -Arm are the REST test seams: { param($Resource, $TenantId) <jwt> } and { param($Path) <ARM object> }.
    #>
    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$SubscriptionId, [scriptblock]$Token, [scriptblock]$Arm)
    [void](Clear-PimSignedInMachineIdentity); $conf = @(Get-PimSignedInEnvironmentConflicts)
    if ($conf.Count) {
        return @{ ok = $false; reason = ("REFUSED: $($conf -join ', ') $(if ($conf.Count -eq 1) { 'is' } else { 'are' }) set in this session -- a token call would authenticate as " +
                 'that identity instead of the signed-in user. ' + (Get-PimSignedInConflictHint -Names $conf)) }
    }
    return (Get-PimSignedInIdentityRest -TenantId $TenantId -SubscriptionId $SubscriptionId -Token $Token -Arm $Arm)
}

function Get-PimSignedInToken {
    <#
      REQ 100.42 / framework 12.17 (owner 2026-10-09: "modern single connect only"; owner token rule: tools get TOKENS from
      Get-InvardiaSupportToken). THE token source of a signed-in setup run, registered into PIM-Rest by
      Set-PimSignedInGlobals ($global:PIM_TokenProvider). No command-line tool, no module:
        * the Invardia Support-app session is open in this shell (Get-InvardiaSupportToken exists) -> its token;
        * otherwise the signed-in person -> Get-PimInteractiveToken (browser, auth-code + PKCE; never device code).
      Returns the token string (Support app) or PIM-Rest's @{ token; expiresUtc } (interactive). PIM-Rest verifies the tid.
    #>
    # STALE SUPPORT SESSION (framework 0 "Installer rules", item 2; 2026-11-03): Get-InvardiaSupportToken
    # stays DEFINED in a PowerShell window after an earlier run's support session, also when its token can no longer be minted
    # (the session expired, or it was for another tenant). The install then failed with "could not sign in" instead of signing
    # the person in. Now: when the support-token call THROWS and there is no live session for this tenant (+ subscription)
    # (Test-PimSupportSessionCovers -- the same test Use-PimSupportAppRestSession makes) and a person can sign in here
    # ($global:PIM_InteractiveFallback), the run falls back to the browser
    # sign-in, says so in one line, and stays there. NEVER two identities in one run: a run that got a support token keeps
    # it (a later failure is an error, never a quiet switch to the person), and a run that fell back never asks the support
    # session again. Set-PimSignedInGlobals starts each run afresh.
    param([Parameter(Mandatory)][string]$Audience, [string]$TenantId)
    if ("$script:PimSignedInSource" -ne 'browser' -and (Get-Command Get-InvardiaSupportToken -ErrorAction SilentlyContinue)) {
        try {
            $st = Get-InvardiaSupportToken -Resource ("$Audience".TrimEnd('/'))
            $script:PimSignedInSource = 'support'
            return $st
        } catch {
            $tenantNow = if ("$TenantId".Trim()) { "$TenantId".Trim() } else { "$global:PIM_TenantId".Trim() }
            # the same test as Test-PimSupportSessionCovers, written out here: this function is also registered on its own as
            # PIM-Rest's token source ($global:PIM_TokenProvider) and must not depend on another function of this file
            $ss = $global:InvardiaSupportState; $live = $false
            if ($ss -is [hashtable] -and $ss.Secret -and "$($ss.AppId)" -match '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' -and
                $tenantNow -and "$($ss.TenantId)".Trim().ToLowerInvariant() -eq $tenantNow.ToLowerInvariant()) {
                $ssSubs = @(@($ss.Subscriptions) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
                $live = (-not "$script:PimSignedInSubscriptionId".Trim()) -or ($ssSubs -contains "$script:PimSignedInSubscriptionId".Trim().ToLowerInvariant())
            }
            # ...and only where a person can sign in (PIM-Rest's own flag, set by Get-PimSignedInIdentityRest): an unattended
            # run keeps the error instead of waiting on a browser nobody sees
            if ("$script:PimSignedInSource" -eq 'support' -or $live -or -not $global:PIM_InteractiveFallback) { throw }
            Write-Host 'The Invardia Support session left in this PowerShell window can no longer sign in -- signing you in in the browser instead.' -ForegroundColor Yellow
            $script:PimSignedInSource = 'browser'
        }
    }
    if (-not (Get-Command Get-PimInteractiveToken -ErrorAction SilentlyContinue)) { throw 'Get-PimSignedInToken: engine\_shared\PIM-Rest.ps1 is not loaded.' }
    if (-not "$script:PimSignedInSource") { $script:PimSignedInSource = 'browser' }
    return (Get-PimInteractiveToken -Audience $Audience -TenantId $TenantId)
}

function Test-PimSupportSessionCovers {
    <#
      PURE given -State (default: $global:InvardiaSupportState). Is a LIVE Invardia Support session open for -TenantId (and
      -SubscriptionId when given)? The conditions Use-PimSupportAppRestSession requires: a session hashtable with its secret,
      a GUID app id, the same tenant, the subscription among its subscriptions.
    #>
    param([string]$TenantId, [string]$SubscriptionId = '', [object]$State)
    $s = if ($PSBoundParameters.ContainsKey('State')) { $State } else { $global:InvardiaSupportState }
    if (-not ($s -is [hashtable]) -or -not $s.Secret -or "$($s.AppId)" -notmatch $script:PimSignedInGuid) { return $false }
    if (-not "$TenantId".Trim() -or "$($s.TenantId)".Trim().ToLowerInvariant() -ne "$TenantId".Trim().ToLowerInvariant()) { return $false }
    $subs = @(@($s.Subscriptions) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
    if ("$SubscriptionId".Trim() -and -not ($subs -contains "$SubscriptionId".Trim().ToLowerInvariant())) { return $false }
    return $true
}

function Get-PimSignedInIdentityRest {
    <#
      100.41 -- Get-PimSignedInIdentity over REST (no az). The identity is the Invardia Support app's REST session when one
      covers -TenantId + -SubscriptionId (Use-PimSupportAppRestSession), else the person at the keyboard: PIM-Rest's own
      sign-in (the browser, auth code + PKCE). The token's claims are asserted (Test-PimSignedInToken: this tenant, a USER --
      or exactly the support app), then the subscription is read over ARM: it must be visible and belong to -TenantId.
      -Token { param($Resource, $TenantId) <jwt> } and -Arm { param($Path) <object> } are the test seams.
    #>
    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$SubscriptionId, [scriptblock]$Token, [scriptblock]$Arm)
    $want = "$TenantId".Trim().ToLowerInvariant(); $sub = "$SubscriptionId".Trim().ToLowerInvariant()
    if ($want -notmatch $script:PimSignedInGuid -or $sub -notmatch $script:PimSignedInGuid) {
        return @{ ok = $false; reason = 'the tenant id and the subscription id must both be given explicitly (GUIDs) -- a signed-in build never relies on a default context' }
    }
    $supportApp = ''
    $script:PimSignedInSubscriptionId = $sub   # the stale-session fallback checks a live session for THIS subscription
    if (-not $Token) {
        if (-not (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue)) {
            $rest = Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'engine\_shared\PIM-Rest.ps1'
            if (Test-Path -LiteralPath $rest) { . $rest } else { return @{ ok = $false; reason = 'engine\_shared\PIM-Rest.ps1 is not loaded -- the signed-in identity cannot be read' } }
        }
        $supportApp = Use-PimSupportAppRestSession -TenantId $want -SubscriptionId $sub
        if (-not $supportApp) {
            Set-PimSignedInGlobals -TenantId $want
            # the person signs in in the browser (PIM-Rest: auth code + PKCE) -- only where a person can
            $interactive = $true
            try { if (-not [Environment]::UserInteractive -or [Console]::IsInputRedirected) { $interactive = $false } } catch { }
            $global:PIM_InteractiveFallback = $interactive
        }
        $Token = { param($r, $t) Get-PimRestToken -Resource $r -TenantId $t }
    }
    $tok = ''; $why = ''
    try { $tok = "$(& $Token 'arm' $want)".Trim() } catch { $why = "$($_.Exception.Message)"; $tok = '' }
    if (-not $tok) {
        return @{ ok = $false; reason = ("could not sign in to tenant $want$(if ($why) { " ($why)" }). Run it in a PowerShell window (a browser sign-in opens), " +
                 'or in a shell connected with the Invardia Support app (Connect-InvardiaSupport.ps1 -Environment <handle>).') }
    }
    $allow = $supportApp
    if (-not $allow) {
        # an older connect script's support session, recognised by its environment variables: the token's own app id
        $sess = Get-PimSupportAppSession
        if ($sess -and $sess.tenantId -eq $want -and ($sess.subscriptions -contains $sub)) {
            $c = ConvertFrom-PimJwtClaims -Token $tok
            $allow = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim().ToLowerInvariant()
        }
    }
    $t = Test-PimSignedInToken -Token $tok -TenantId $want -AllowedAppId $allow
    $tok = $null
    if (-not $t.ok) { return $t }
    if (-not $Arm) { $Arm = { param($p) Invoke-PimArm -Method GET -Path $p -ApiVersion '2022-12-01' } }
    $s = $null; $why = ''
    try { $s = & $Arm "/subscriptions/$sub" } catch { $why = "$($_.Exception.Message)"; $s = $null }
    if (-not $s -or "$($s.subscriptionId)".Trim().ToLowerInvariant() -ne $sub) {
        return @{ ok = $false; reason = "subscription $sub is not visible to $($t.userName)$(if ($why) { " ($why)" }) -- REFUSING" }
    }
    if ("$($s.tenantId)".Trim() -and "$($s.tenantId)".Trim().ToLowerInvariant() -ne $want) {
        return @{ ok = $false; reason = "subscription $sub belongs to tenant '$($s.tenantId)', not '$want' -- REFUSING (a wrong default acts in somebody else's directory)" }
    }
    $label = if ($t.supportApp) { "signed in as the Invardia Support app $allow (tenant $want, subscription $sub)" } else { "signed in as $($t.userName) (tenant $want, subscription $sub)" }
    return @{ ok = $true; reason = $label; userName = $t.userName; objectId = $t.objectId; tenantId = $want; subscriptionId = $sub; supportAppId = "$allow" }
}

function Set-PimSignedInGlobals {
    <#
      Make the engine's token helpers (Get-PimRestToken, New-PimSqlConnection) take the signed-in token source in THIS
      process: clear every application-identity global, pin the tenant, and switch the managed-identity probe off (a
      deploy host that is an Azure VM has a managed identity of its own, and it would otherwise win).
    #>
    param([Parameter(Mandatory)][string]$TenantId)
    foreach ($n in 'PIM_ClientId', 'PIM_ClientSecret', 'PIM_CertThumbprint', 'PIM_SqlClientId', 'PIM_SqlClientSecret', 'PIM_SqlCertThumbprint', 'PIM_SqlAccessToken', 'PIM_UseManagedIdentity') {
        Set-Variable -Scope Global -Name $n -Value $null -WhatIf:$false
    }
    $global:PIM_TenantId = "$TenantId".Trim()
    $global:PIM_NoManagedIdentity = $true
    $global:PIM_UseGraphSdk = $false
    $global:PIM_SignedInAccount = $true
    # STALE SUPPORT SESSION: a new run decides its identity afresh (Get-PimSignedInToken) -- never an earlier run's choice
    $script:PimSignedInSource = ''
    # REQ 100.42: register the signed-in token source (Support app / browser) -- PIM-Rest has no other fallback.
    $global:PIM_TokenProvider = ${function:Get-PimSignedInToken}
}

function Connect-PimSignedInSql {
    <#
      Prepare THIS process to reach Azure SQL as the signed-in user, and prove the token is right before any statement
      runs. PIM-Rest.ps1 must be loaded. Returns @{ userName; objectId }. The token itself stays in the engine's
      in-memory cache and is never returned, printed or written.
    #>
    param([Parameter(Mandatory)][string]$TenantId)
    [void](Clear-PimSignedInMachineIdentity); $conf = @(Get-PimSignedInEnvironmentConflicts)
    if ($conf.Count) { throw "REFUSED: $($conf -join ', ') set in this session -- the SQL token would be minted for that identity, not the signed-in user. $(Get-PimSignedInConflictHint -Names $conf)" }
    if (-not (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue)) { throw 'Connect-PimSignedInSql: engine\_shared\PIM-Rest.ps1 is not loaded.' }
    Set-PimSignedInGlobals -TenantId $TenantId
    # 100.41 (no az): the Invardia Support app's REST session for this tenant is the identity when there is one (PIM-Rest
    # client credentials with its secret); else the person's own sign-in.
    $allowApp = Use-PimSupportAppRestSession -TenantId $TenantId
    if (-not $allowApp) {
        $interactive = $true
        try { if (-not [Environment]::UserInteractive -or [Console]::IsInputRedirected) { $interactive = $false } } catch { }
        if (-not $global:PIM_InteractiveFallback) { $global:PIM_InteractiveFallback = $interactive }
    }
    # REQ 100.76: -Force -- a token minted NOW, after this run made the person (or its group) the server's Entra admin; a
    # cached one predates that and SQL refuses it ("Login failed for user '<token-identified principal>'").
    $tok = Get-PimRestToken -Resource 'https://database.windows.net' -TenantId $TenantId -Force
    if (Get-Command Reset-PimSqlTokenCache -ErrorAction SilentlyContinue) { Reset-PimSqlTokenCache }
    if (-not $allowApp) {
        # an older connect script's support session (environment variables): accept exactly the app its token names
        $sess = Get-PimSupportAppSession
        if ($sess -and $sess.tenantId -eq "$TenantId".Trim().ToLowerInvariant()) {
            $c = ConvertFrom-PimJwtClaims -Token "$tok"
            if (-not "$(if ($c.upn) { $c.upn } else { $c.unique_name })".Trim()) { $allowApp = "$(if ($c.appid) { $c.appid } else { $c.azp })".Trim() }
        }
    }
    $t = Test-PimSignedInToken -Token "$tok" -TenantId $TenantId -AllowedAppId $allowApp
    $tok = $null
    if (-not $t.ok) { throw "SQL as the signed-in user: $($t.reason)" }
    $global:PIM_SetupActor = $(if ($t.userName) { $t.userName } else { $t.objectId })
    return @{ userName = $t.userName; objectId = $t.objectId }
}

function Get-PimSignedInSqlCreateAdmin {
    <#
      PURE. APP-IDENTITY INSTALL (owner via Invardia 2026-10-21): the SQL server's CREATE-TIME Entra admin for a signed-in
      deploy (-SignedIn = Get-PimSignedInIdentity's answer). The Invardia Support app (supportAppId set) is an APPLICATION,
      never a 'User': principalType Application with its service principal's object id -- the same shape the deploy
      application and the SQL identity already use (New-PimHostingPrerequisites). Either way the admin moves to the SQL
      admin group right after (the prerequisites' group step); this is only who holds it in between.
      @{ principalType; login; sid }.
    #>
    param([Parameter(Mandatory)][object]$SignedIn)
    $app = "$($SignedIn.supportAppId)".Trim()
    if ($app) { return @{ principalType = 'Application'; login = "invardia-support-$($app.ToLowerInvariant())"; sid = "$($SignedIn.objectId)".Trim().ToLowerInvariant() } }
    return @{ principalType = 'User'; login = "$($SignedIn.userName)"; sid = "$($SignedIn.objectId)" }
}

function Invoke-PimSignedInSqlAdminMembership {
    <#
      Make the signed-in user a MEMBER of the SQL admin group of -SqlServerName (members-only: never creates the group,
      never moves the Entra admin). Returns @{ ok; blocked; added; reason }. Blocked = the server's admin is not the
      group, so membership would grant nothing -- the caller must refuse with that reason.
    #>
    param([Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$ResourceGroup,
          [Parameter(Mandatory)][string]$SqlServerName, [Parameter(Mandatory)][string]$UserObjectId, [string]$GroupName = 'grp-pim-sql-admins',
          # APP-IDENTITY INSTALL (2026-10-21): the signed-in principal is an application -- a server whose admin was set by
          # its client id elsewhere is recognised too (a direct admin by either id)
          [string]$AppId = '',
          # test seam: @{ Graph; Arm; TenantId } instead of the signed-in session's REST invokers
          [object]$Invokers)
    # Loaded on demand through a variable path: Build-PimSupportScripts.ps1 inlines the literal dot-source-of-a-Join-Path
    # lines, and a standalone script that inlines THIS file (Initialize-PimMailSender.ps1) never calls this function.
    if (-not (Get-Command Invoke-PimSqlAdminGroupStep -ErrorAction SilentlyContinue)) { $__sag = Join-Path $PSScriptRoot '_PimSqlAdminGroup.ps1'; . $__sag }
    $inv = if ($Invokers) { $Invokers } else { New-PimSqlAdminGroupInvokers -SubscriptionId $SubscriptionId -TenantId $TenantId }
    $srv = ("$SqlServerName".Trim() -split '\.')[0]
    $sqlRg = $ResourceGroup
    if (Get-Command Resolve-PimSqlServerFromFqdn -ErrorAction SilentlyContinue) {
        try { $res = Resolve-PimSqlServerFromFqdn -Arm $inv.Arm -SubscriptionId $SubscriptionId -Server $srv; if ($res) { $sqlRg = $res.resourceGroup; $srv = $res.name } } catch { }
    }
    # §95.2 Cloud Shell blocker 5 (guided install): an installer WITHOUT Privileged Role Administrator cannot create the
    # role-assignable SQL admin group, so the prerequisites leave the server's Entra admin = the signed-in user. That user
    # already holds every SQL right; the members-only step would only fail on "group does not exist". Say so, hand the
    # group to a Privileged Role Administrator, and let the deploy continue.
    try {
        $list = & $inv.Arm -Method GET -Path "/subscriptions/$SubscriptionId/resourceGroups/$sqlRg/providers/Microsoft.Sql/servers/$srv/administrators?api-version=$($script:PimSqlApi)"
        $cur = @(@($list.value) | Where-Object { $_ }) | Select-Object -First 1
        if ($cur -and ("$($cur.properties.sid)".Trim() -ieq "$UserObjectId".Trim() -or ("$AppId".Trim() -and "$($cur.properties.sid)".Trim() -ieq "$AppId".Trim()))) {
            $action = ".\Initialize-PimSqlAdminGroup.ps1 -SubscriptionId $SubscriptionId -TenantId $TenantId -ResourceGroup $sqlRg -SqlServerName $srv -GroupName $GroupName"
            Write-Host "    the signed-in user IS the Entra admin of $srv -- SQL is reachable. The SQL admin group '$GroupName' is not the admin yet; a Privileged Role Administrator converges it with: $action" -ForegroundColor Yellow
            return @{ ok = $true; blocked = $false; added = $false; direct = $true; reason = ''; action = $action }
        }
    } catch { Write-Verbose "reading the Entra admin of $srv failed: $($_.Exception.Message) -- falling back to the group membership" }
    $r = Invoke-PimSqlAdminGroupStep -Graph $inv.Graph -Arm $inv.Arm -TenantId $inv.TenantId -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup `
            -SqlResourceGroup $sqlRg -SqlServerName $srv -GroupName $GroupName -UpdateJobName '' -NoDiscovery -Mode membersOnly `
            -ExtraMembers @([pscustomobject]@{ objectId = "$UserObjectId".Trim(); label = 'the signed-in administrator' })
    Write-PimSqlAdminGroupReport -Result $r
    $added = @(@($r.added) | Where-Object { "$($_.objectId)" -ieq "$UserObjectId".Trim() }).Count -gt 0
    if (-not $r.ok) { return @{ ok = $false; blocked = $false; added = $added; reason = "could not make the signed-in user a member of '$GroupName': $(@($r.problems) -join '; ')" } }
    if ($r.blocked) { return @{ ok = $true; blocked = $true; added = $false; reason = "the Entra admin of $srv is not '$GroupName' ($($r.blocked)) -- membership grants nothing there. Converge the server onto the group first (Initialize-PimSqlAdminGroup.ps1), or make the signed-in user the Entra admin." } }
    if ($added) {
        Write-Host ("    NOTE: you were ADDED to '$GroupName' just now. An Entra token carries group membership as of when it was issued, " +
                    'and a sign-in token is reused for up to about an hour -- if SQL refuses the next step, open a NEW PowerShell window, sign in again (browser, or Connect-InvardiaSupport.ps1) and resume.') -ForegroundColor Yellow
    }
    return @{ ok = $true; blocked = $false; added = $added; reason = '' }
}

# ===== END inlined helper: _PimSignedIn.ps1 =====
# ===== BEGIN inlined helper: _PimSqlAdminGroup.ps1 =====
<#
  PIM4EntraPS -- THE SQL ADMIN GROUP (2026-09-15). Dot-sourced by Initialize-PimSqlAdminGroup.ps1,
  Deploy-PimUpdateJob.ps1 and New-PimHostingPrerequisites.ps1; offline-tested by
  tests/Test-PimSqlAdminGroup.ps1.

  Operator, 2026-09-15: "remember we have a sql admin group where the managed identity + the
  troubleshooting spn must be member, same as in internal. the managing and the managed test tenant must be similar, and the
  updater logic must handle this so we are ready to roll this out to ring 2 very soon".

  THE MODEL
    Azure SQL allows exactly ONE Entra admin. Giving it to ONE principal (the deploy SPN on public SQL, a
    SQL user-assigned identity on private SQL) meant every other identity that must administer the
    database -- the unattended updater's schema step, the Invardia Support app -- needed a
    contained user created by that one principal, and an environment whose admin was a secret-only app
    could not be fixed unattended at all (both test tenants, UPD-15). The admin is therefore a SECURITY GROUP,
    default 'grp-pim-sql-admins'. FRAMEWORK 12.23 P5 (PIM 100.156 B, 2026-10-16) made the Invardia Support app its only
    standing member; OPEN-01 (framework SECAUDIT-1a, 2026-11-05) takes that back: nothing here ADDS the Support app any
    more (-SupportAppId / -SupportObjectId only produce a note), and its one standing database right is the read-only user.
    A membership an earlier version gave is not removed here (100.116). For the length of an install:
      * the setup identity (the signed-in person or the SQL admin application; a build's certificate application with
        -SetupIdentityAppId) -- released again at the end of the install (Invoke-PimSqlAdminGroupSetupRelease)
      * the in-VNet SQL identity id-pim-sql-<token> on private SQL, so the in-cloud bootstrap still works
      * the previous admin, so converging never takes access away from whoever had it
    NOT members any more: the environment's user-assigned identity id-pim-<token> (it only pulls the image; added only
    when named explicitly) and -- once the as-built GRANT runs through the signed procedure on a real update -- the
    updater (Get-PimSqlAdminGroupKeepsUpdater, the ONE switch below; still $true until then).
    Contained users that exist keep working; nothing here drops one.

  GRAPH / ARM FACTS THIS HANDLES, EACH MEASURED LIVE ON both test tenants 2026-09-15
    1. GET /groups/{id}/members returned 0 items for SERVICE-PRINCIPAL members with an app-only token,
       while /groups/{id}/members/microsoft.graph.servicePrincipal listed them. Membership is read
       through the TYPED casts (servicePrincipal, user, group), unioned with the untyped list.
    2. Adding a member that is already there answers an error containing "already exist" -- success.
    3. PUT .../administrators/ActiveDirectory is asynchronous (202): the new admin is POLLED on read-back.
    4. A naive "keep the current admin as a member" step added the group to ITSELF when the admin already
       was the group. The plan refuses any member whose object id is the group's.

  SEC-32 -- THE GROUP IS ROLE-ASSIGNABLE (isAssignableToRole = true), because it IS tier 0.
    It is the SQL server's Entra admin, and the database holds the desired state the engine applies with its
    directory-role rights. A plain security group can be edited by any Groups Administrator / User Administrator /
    group owner: such a person adds themselves, rewrites desired state, and the engine then grants them Global
    Administrator -- tier 1 escalating to tier 0. Only Privileged Role Administrators / Global Administrators (or an
    app holding RoleManagement.ReadWrite.Directory) can change the members of a role-assignable group.
    * NEW group: created with isAssignableToRole = true. That property can ONLY be set at creation, and creating (and
      later adding members to) such a group needs Graph RoleManagement.ReadWrite.Directory on top of Group.Create /
      GroupMember.ReadWrite.All -- the deploy identity does NOT hold it (by operator decision, SEC-33). So an
      unattended deploy is REFUSED here (permissionDenied, "needs RoleManagement.ReadWrite.Directory"), never quietly
      given a plain group instead: the caller keeps the server's previous single-principal admin and prints the
      command to converge with a privileged identity.
    * EXISTING group that is NOT role-assignable: NOTHING is deleted or recreated automatically (the SQL admin and
      every member's access hang on it). It is detected on every run and reported LOUDLY as a SECURITY finding
      (result.securityFindings / notRoleAssignable), and the run otherwise proceeds as before.
      ONE-TIME MIGRATION (operator, as a Privileged Role Administrator; order matters, nobody loses access):
        1. create a NEW role-assignable security group, e.g. 'grp-pim-sql-admins-ra' (Entra admin center: Groups ->
           New group -> "Microsoft Entra roles can be assigned to the group" = Yes; or this helper's converge run by
           an identity that holds RoleManagement.ReadWrite.Directory, with -GroupName on the new name);
        2. add the SAME members as the old group (the managed identities, the updater, the Invardia Support app);
        3. make the NEW group the SQL Entra admin: Initialize-PimSqlAdminGroup.ps1 -GroupObjectId <new group id>
           (it keeps the previous admin as a member and reads the admin back);
        4. only after the read-back, delete the OLD group; pass the new name (-SqlAdminGroupName) on later deploys.
      Contained database users are keyed by SID, not by group, so none of them changes.

  No client-secret parameter anywhere in this file: the invokers take their tokens from PIM-Rest's ONE token client --
  the identity this process is set up for (a deploy's certificate or managed identity, the Invardia Support session, or
  the signed-in person's browser sign-in; framework 12.17) -- or mint one from a certificate in the local store.
  ASCII only: read by Windows PowerShell 5.1 on deploy hosts.
#>

Set-StrictMode -Off
# ===== BEGIN inlined helper: _PimSignInIdentity.ps1 =====
<#
  _PimSignInIdentity.ps1 -- THE identity a PIM container app / job SIGNS IN AS, for every setup / repair script
  (framework IDENTITY-MOVE-1 line 8, owner 2026-11-09: "code is not reflecting the identity chg").

  Since the identity move (NAM-03, 2026-11-08) an app / job signs in as its USER-ASSIGNED identity id-pim-<role>, named by
  the container's PIM_ManagedIdentityClientId; its system-assigned identity stays attached but holds nothing. Reading
  `identity.principalId` (the SYSTEM identity) therefore names a retired identity: grants, checks and printed fix
  commands went to it (the engine's mail broke that way). The rule, the same as the engine's token call
  (PIM-Rest.ps1 Get-PimManagedIdentityToken) and PIM-ConvergeDefaults' Resolve-PimConvergeSignInOid:
    PIM_ManagedIdentityClientId set -> the attached user-assigned identity with that client id; none matches -> ''
                                       (NEVER the system identity: the caller says "could not be read")
    not set                         -> the system-assigned identity (an install not moved, or a fresh deploy)
  PURE. PS 5.1 + 7. ASCII. A tools\setup helper (dot-sourced via $PSScriptRoot) so the published standalone scripts
  inline it.
#>
Set-StrictMode -Off

function Get-PimSignInField {
    param($Object, [string]$Name)
    if ($null -eq $Object) { return $null }
    if ($Object -is [System.Collections.IDictionary]) { if ($Object.Contains($Name)) { return $Object[$Name] }; return $null }
    $p = $Object.PSObject.Properties[$Name]; if ($p) { return $p.Value }; return $null
}

function Get-PimSignInIdentity {
    <#
      PURE. -Resource = the ARM object of a container app or job (GET). Returns
      @{ principalId; clientId; kind = user|system|''; name; resourceId (user-assigned only); reason } -- principalId '' with a reason when it cannot be decided.
    #>
    param($Resource)
    $o = [ordered]@{ principalId = ''; clientId = ''; kind = ''; name = ''; resourceId = ''; reason = '' }
    if ($null -eq $Resource) { $o.reason = 'no resource'; return [pscustomobject]$o }
    $cid = ''
    foreach ($c in @(Get-PimSignInField (Get-PimSignInField (Get-PimSignInField $Resource 'properties') 'template') 'containers')) {
        if (-not $c -or "$(Get-PimSignInField $c 'name')" -eq 'signin-front') { continue }
        foreach ($e in @(Get-PimSignInField $c 'env')) {
            if ($e -and "$(Get-PimSignInField $e 'name')" -eq 'PIM_ManagedIdentityClientId' -and "$(Get-PimSignInField $e 'value')".Trim()) { $cid = "$(Get-PimSignInField $e 'value')".Trim() }
        }
        if ($cid) { break }
    }
    $idn = Get-PimSignInField $Resource 'identity'
    if ($cid) {
        $ua = Get-PimSignInField $idn 'userAssignedIdentities'
        $pairs = if ($ua -is [System.Collections.IDictionary]) { @($ua.Keys | ForEach-Object { @{ k = "$_"; v = $ua[$_] } }) } elseif ($ua) { @($ua.PSObject.Properties | ForEach-Object { @{ k = $_.Name; v = $_.Value } }) } else { @() }
        foreach ($p in $pairs) {
            if ("$(Get-PimSignInField $p.v 'clientId')".Trim() -ieq $cid -and "$(Get-PimSignInField $p.v 'principalId')".Trim()) {
                $o.principalId = "$(Get-PimSignInField $p.v 'principalId')".Trim(); $o.clientId = $cid; $o.kind = 'user'; $o.name = @("$($p.k)" -split '/')[-1]; $o.resourceId = "$($p.k)"
                return [pscustomobject]$o
            }
        }
        $o.reason = "it signs in with client id $cid, but no attached user-assigned identity has that client id"
        return [pscustomobject]$o
    }
    $sp = "$(Get-PimSignInField $idn 'principalId')".Trim()
    if ($sp) { $o.principalId = $sp; $o.kind = 'system'; $o.name = "$(Get-PimSignInField $Resource 'name') (system-assigned)"; return [pscustomobject]$o }
    $o.reason = 'it has no managed identity it signs in with'
    return [pscustomobject]$o
}

function Get-PimSignInPrincipalId {
    <# PURE. Just the object id (Get-PimSignInIdentity), '' when it cannot be decided. #>
    param($Resource)
    return "$((Get-PimSignInIdentity -Resource $Resource).principalId)"
}

# ===== END inlined helper: _PimSignInIdentity.ps1 =====

$script:PimSqlAdminGroupDefaultName = 'grp-pim-sql-admins'
$script:PimSqlApi  = '2021-11-01'
$script:PimMiApi   = '2023-01-31'
$script:PimJobApi  = '2024-03-01'
$script:PimGraphBase = 'https://graph.microsoft.com/v1.0'

function Get-PimSqlAdminGroupKeepsUpdater {
    <#
      THE ONE SWITCH (PIM 100.156 B): does the updater's identity stay a member of the SQL admin group on a NEW install?
      $true UNTIL the lane "updater out of the SQL admin group" lands (owner wizard 2026-10-16 (b): the as-built reader's
      GRANT through the signed procedure first, proven on a real update on rings 0 + 1). The updater also gets its own
      contained user (pim_updater + db_ddladmin, Deploy-PimUpdateJob) either way, so flipping this to $false is the whole
      change for new installs. Every caller (the prerequisites, Deploy-PimUpdateJob, Initialize-PimSqlAdminGroup) asks here.
      A literal in a FUNCTION, never a $script: variable (the child-scope trap: a $script: value is $null in a dot-sourcing
      caller's scope).
    #>
    return $true
}

function Test-PimSqlAdminGuid {
    param([AllowEmptyString()][AllowNull()][string]$Value)
    $g = [guid]::Empty
    return ([bool]"$Value".Trim() -and [guid]::TryParse("$Value".Trim(), [ref]$g))
}

function Test-PimSqlAdminPermissionError {
    <# PURE. Is this error text Graph/ARM refusing the CALLER (not a missing object)? #>
    param([AllowEmptyString()][string]$Text)
    return ("$Text" -match '(?i)Authorization_RequestDenied|Insufficient privileges|HTTP 403\b|AuthorizationFailed|\bForbidden\b')
}

function Get-PimSqlAdminGroupPlan {
    <#
      PURE. What converging an environment's SQL admin onto the group would change.
        -Group          : $null (absent) or { id; displayName }
        -CurrentMemberIds : object ids already in the group (typed-cast read)
        -DesiredMembers : @{ objectId; label } -- duplicates collapse, first label wins
        -CurrentAdmin   : $null (no Entra admin) or { sid; login; objectId } where objectId is the sid
                          resolved to a directory object ('' when it could not be resolved)
        -Mode           : converge     -- create the group if absent, add members, make it the admin
                          membersOnly  -- only add members, and only when the group already IS the admin
      Returns { mode; groupName; groupId; createGroup; add; present; refused; keepCurrentAdmin; adminIsGroup;
                setAdmin; blocked; changes; messages }.
    #>
    param(
        [string]$GroupName = 'grp-pim-sql-admins',
        [object]$Group,
        [AllowEmptyCollection()][string[]]$CurrentMemberIds = @(),
        [AllowEmptyCollection()][object[]]$DesiredMembers = @(),
        [object]$CurrentAdmin,
        [ValidateSet('converge', 'membersOnly')][string]$Mode = 'converge',
        [switch]$DoNotKeepCurrentAdmin
    )
    $msgs    = New-Object System.Collections.Generic.List[string]
    $add     = New-Object System.Collections.Generic.List[object]
    $present = New-Object System.Collections.Generic.List[object]
    $refused = New-Object System.Collections.Generic.List[object]
    $gid = if ($Group -and "$($Group.id)".Trim()) { "$($Group.id)".Trim() } else { '' }
    $adminSid = if ($CurrentAdmin) { "$($CurrentAdmin.sid)".Trim() } else { '' }
    $adminOid = if ($CurrentAdmin) { "$($CurrentAdmin.objectId)".Trim() } else { '' }
    $adminLogin = if ($CurrentAdmin) { "$($CurrentAdmin.login)".Trim() } else { '' }
    $adminIsGroup = [bool]($gid -and (($adminSid -and $adminSid -ieq $gid) -or ($adminOid -and $adminOid -ieq $gid)))
    $blocked = ''
    $keep = $null

    if ($Mode -eq 'membersOnly') {
        if (-not $gid) {
            $blocked = "the SQL admin group '$GroupName' does not exist -- nothing to join (Initialize-PimSqlAdminGroup.ps1 converges an environment onto it)"
        } elseif (-not $adminIsGroup) {
            $who = if ($adminLogin) { "'$adminLogin'" } elseif ($adminSid) { $adminSid } else { 'nobody' }
            $blocked = "'$GroupName' is not this SQL server's Entra admin (the admin is $who) -- membership would grant nothing, so none is added"
        }
        if ($blocked) {
            [void]$msgs.Add($blocked)
            return [pscustomobject]@{ mode = $Mode; groupName = $GroupName; groupId = $gid; createGroup = $false
                add = @(); present = @(); refused = @(); keepCurrentAdmin = $null; adminIsGroup = $adminIsGroup
                setAdmin = $false; blocked = $blocked; changes = 0; messages = @($msgs.ToArray()) }
        }
    }

    $wanted = New-Object System.Collections.Generic.List[object]
    foreach ($m in @($DesiredMembers)) { if ($null -ne $m) { [void]$wanted.Add($m) } }
    if ($Mode -eq 'converge' -and $CurrentAdmin -and -not $adminIsGroup -and -not $DoNotKeepCurrentAdmin) {
        if ($adminOid) {
            $keep = [pscustomobject]@{ objectId = $adminOid; label = "previous SQL admin ($(if ($adminLogin) { $adminLogin } else { $adminSid }))" }
            [void]$wanted.Add($keep)
        } else {
            $blocked = "the current SQL admin '$adminLogin' ($adminSid) could not be resolved to a directory object, so it cannot be kept as a member -- REFUSING to move the admin (it would lose access)"
            [void]$msgs.Add($blocked)
        }
    }

    $have = @{}
    foreach ($id in @($CurrentMemberIds)) { if ("$id".Trim()) { $have["$id".Trim().ToLowerInvariant()] = $true } }
    $seen = @{}
    foreach ($m in $wanted) {
        $oid = "$($m.objectId)".Trim()
        $label = if ("$($m.label)".Trim()) { "$($m.label)".Trim() } else { $oid }
        if (-not (Test-PimSqlAdminGuid $oid)) {
            [void]$refused.Add([pscustomobject]@{ objectId = $oid; label = $label; reason = 'not an object id' }); continue
        }
        $k = $oid.ToLowerInvariant()
        if ($seen.ContainsKey($k)) { continue }
        $seen[$k] = $true
        if ($gid -and $k -eq $gid.ToLowerInvariant()) {
            [void]$refused.Add([pscustomobject]@{ objectId = $oid; label = $label; reason = 'is the group itself -- a group is never made a member of itself' })
            continue
        }
        $entry = [pscustomobject]@{ objectId = $oid; label = $label }
        if ($have.ContainsKey($k)) { [void]$present.Add($entry) } else { [void]$add.Add($entry) }
    }
    foreach ($r in $refused) { [void]$msgs.Add("refused member $($r.label): $($r.reason)") }

    # SEC-32 (2026-10-04, as SI's Set-SISqlAdminGroup): an EXISTING group that is NOT role-assignable is never MADE the SQL
    # admin -- adopting it would hand tier-0 control to anyone who can edit a plain group. A group that already IS the
    # admin is still only reported (the access of every member hangs on it; migrating is the operator's one-time step).
    if (-not $blocked -and $Mode -eq 'converge' -and $gid -and -not $adminIsGroup -and $Group -and
        $Group.PSObject.Properties['isAssignableToRole'] -and $null -ne $Group.isAssignableToRole -and -not [bool]$Group.isAssignableToRole) {
        $blocked = "SEC-32: '$GroupName' ($gid) exists but is NOT role-assignable -- it is NOT made the SQL admin (anyone who can edit a plain group could take the store). Create a role-assignable group (a new name, or delete this one first) as a Privileged Role Administrator; the current admin stays."
        [void]$msgs.Add($blocked)
    }
    $create = ($Mode -eq 'converge' -and -not $gid)
    $setAdmin = ($Mode -eq 'converge' -and -not $adminIsGroup -and -not $blocked)
    if ($create)   { [void]$msgs.Add("create ROLE-ASSIGNABLE security group '$GroupName'") }
    foreach ($a in $add) { [void]$msgs.Add("add member $($a.label) ($($a.objectId))") }
    if ($setAdmin) { [void]$msgs.Add("make '$GroupName' the SQL server's Entra admin (was $(if ($adminLogin) { "'$adminLogin'" } else { 'none' }))") }
    $changes = [int]$create + $add.Count + [int]$setAdmin
    if (-not $changes -and -not $blocked) { [void]$msgs.Add("no changes -- '$GroupName' is the admin and holds every member") }
    return [pscustomobject]@{
        mode = $Mode; groupName = $GroupName; groupId = $gid; createGroup = $create
        add = @($add.ToArray()); present = @($present.ToArray()); refused = @($refused.ToArray())
        keepCurrentAdmin = $keep; adminIsGroup = $adminIsGroup; setAdmin = $setAdmin; blocked = $blocked
        changes = $changes; messages = @($msgs.ToArray())
    }
}

function Get-PimGraphGroupMemberIds {
    <#
      Object ids of a group's members, read through the TYPED casts (Graph fact 1: the untyped list
      returned 0 service principals app-only) and unioned with the untyped list. Follows paging.
    #>
    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$GroupId)
    $ids = New-Object System.Collections.Generic.List[string]
    $seen = @{}
    foreach ($suffix in @('/microsoft.graph.servicePrincipal', '/microsoft.graph.user', '/microsoft.graph.group', '')) {
        $path = "/groups/$GroupId/members$suffix" + '?$select=id&$top=999'
        $guard = 0
        while ($path -and $guard -lt 50) {
            $guard++
            $page = & $Graph -Method GET -Path $path
            foreach ($o in @($page.value)) {
                $id = "$($o.id)".Trim()
                if ($id -and -not $seen.ContainsKey($id.ToLowerInvariant())) { $seen[$id.ToLowerInvariant()] = $true; [void]$ids.Add($id) }
            }
            $next = ''
            if ($page -and $page.PSObject.Properties['@odata.nextLink']) { $next = "$($page.'@odata.nextLink')" }
            $path = if ($next) { $next } else { '' }
        }
    }
    return @($ids.ToArray())
}

function Resolve-PimDirectoryObjectId {
    <#
      A SQL admin 'sid' is a directory object id, or for some applications their APP id. Try the object id
      first, then the app id. Returns '' when neither resolves.
    #>
    param([Parameter(Mandatory)][scriptblock]$Graph, [AllowEmptyString()][string]$Sid)
    $s = "$Sid".Trim()
    if (-not (Test-PimSqlAdminGuid $s)) { return '' }
    try { $o = & $Graph -Method GET -Path ("/directoryObjects/$s" + '?$select=id'); if ("$($o.id)".Trim()) { return "$($o.id)".Trim() } } catch { }
    try { $o = & $Graph -Method GET -Path ("/servicePrincipals(appId='$s')" + '?$select=id'); if ("$($o.id)".Trim()) { return "$($o.id)".Trim() } } catch { }
    return ''
}

function Resolve-PimServicePrincipalObjectId {
    <# The service principal object id for an app id. Throws when it does not exist. #>
    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$AppId)
    $o = & $Graph -Method GET -Path ("/servicePrincipals(appId='$("$AppId".Trim())')" + '?$select=id,displayName')
    if (-not "$($o.id)".Trim()) { throw "no service principal for app id $AppId" }
    return "$($o.id)".Trim()
}

function Resolve-PimSqlServerFromFqdn {
    <#
      The SQL server resource for an FQDN or bare name, searched across the subscription (the server may
      live in another resource group). Returns { id; name; resourceGroup } or $null.
    #>
    param([Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$Server)
    $name = ("$Server".Trim() -replace '^tcp:', '' -replace ',\d+$', '').Split('.')[0].ToLowerInvariant()
    if (-not $name) { return $null }
    $list = & $Arm -Method GET -Path "/subscriptions/$SubscriptionId/providers/Microsoft.Sql/servers?api-version=$($script:PimSqlApi)"
    foreach ($s in @($list.value)) {
        if ("$($s.name)".ToLowerInvariant() -eq $name) {
            $rg = ''
            if ("$($s.id)" -match '(?i)/resourceGroups/([^/]+)/') { $rg = $Matches[1] }
            return [pscustomobject]@{ id = "$($s.id)"; name = "$($s.name)"; resourceGroup = $rg }
        }
    }
    return $null
}

function Invoke-PimSqlAdminGroup {
    <#
      Converge (or, -Mode membersOnly, join) an environment's SQL admin group. Reads everything first,
      plans with Get-PimSqlAdminGroupPlan, applies, then READS EVERYTHING BACK. Never throws for a Graph
      or ARM refusal -- returns { ok; applied; permissionDenied; problems } so a caller decides.
        -Graph / -Arm : scriptblocks param([string]$Method, [string]$Path, [object]$Body) that return the
                        parsed response and throw "<METHOD> <path> -> HTTP <code> : <detail>" on failure
        -Members      : @{ objectId; label }
    #>
    param(
        [Parameter(Mandatory)][scriptblock]$Graph,
        [Parameter(Mandatory)][scriptblock]$Arm,
        [Parameter(Mandatory)][string]$SubscriptionId,
        [Parameter(Mandatory)][string]$ResourceGroup,
        [Parameter(Mandatory)][string]$SqlServerName,
        [Parameter(Mandatory)][string]$TenantId,
        [string]$GroupName = 'grp-pim-sql-admins',
        [string]$GroupObjectId,
        [AllowEmptyCollection()][object[]]$Members = @(),
        [ValidateSet('converge', 'membersOnly')][string]$Mode = 'converge',
        [switch]$DoNotKeepCurrentAdmin,
        [switch]$PlanOnly,
        [int]$PollSeconds = 5,
        [int]$PollCount = 36,
        [scriptblock]$Sleep = { param([int]$Seconds) Start-Sleep -Seconds $Seconds }
    )
    $problems = New-Object System.Collections.Generic.List[string]
    $notes    = New-Object System.Collections.Generic.List[string]
    $findings = New-Object System.Collections.Generic.List[string]   # SEC-32: security findings the operator acts on (not failures)
    $state    = @{ denied = $false; roleAssignable = $null }
    $srvPath  = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.Sql/servers/$SqlServerName"
    $result = {
        param($plan, $applied, $extra)
        $o = [ordered]@{
            ok = ($problems.Count -eq 0); applied = [bool]$applied; permissionDenied = [bool]$state.denied
            groupName = $GroupName; groupId = $(if ($plan) { "$($plan.groupId)" } else { '' })
            created = $false; added = @(); present = @(); refused = @(); adminChanged = $false
            adminBefore = ''; adminIsGroup = $false; adAuthOnlyBefore = $null; adAuthOnlyAfter = $null
            blocked = $(if ($plan) { "$($plan.blocked)" } else { '' }); plan = $plan
            roleAssignable = $state.roleAssignable; notRoleAssignable = ($state.roleAssignable -eq $false)
            securityFindings = @($findings.ToArray())
            problems = @($problems.ToArray()); notes = @($notes.ToArray())
        }
        foreach ($e in @($extra)) { if ($e) { foreach ($k in @($e.Keys)) { $o[$k] = $e[$k] } } }
        [pscustomobject]$o
    }
    $fail = {
        param([string]$What, $Err)
        $t = "$Err"
        if (Test-PimSqlAdminPermissionError $t) { $state.denied = $true }
        [void]$problems.Add("$What`: $t")
    }

    # ---- read: the group --------------------------------------------------------------------------
    $group = $null
    try {
        if ("$GroupObjectId".Trim()) {
            $group = & $Graph -Method GET -Path ("/groups/$("$GroupObjectId".Trim())" + '?$select=id,displayName,securityEnabled,isAssignableToRole')
            if ($group -and "$($group.displayName)".Trim()) { $GroupName = "$($group.displayName)".Trim() }
        } else {
            $flt = [uri]::EscapeDataString("displayName eq '$($GroupName.Replace("'", "''"))'")
            $found = @((& $Graph -Method GET -Path ('/groups?$filter=' + $flt + '&$select=id,displayName,securityEnabled,isAssignableToRole')).value | Where-Object { $_ })
            if ($found.Count -gt 1) {
                [void]$problems.Add("$($found.Count) groups are named '$GroupName' -- ambiguous; pass -GroupObjectId")
                return (& $result $null $false @{})
            }
            if ($found.Count -eq 1) { $group = $found[0] }
        }
        if ($group -and $group.PSObject.Properties['securityEnabled'] -and $group.securityEnabled -eq $false) {
            [void]$problems.Add("'$GroupName' ($($group.id)) is not a SECURITY group -- Azure SQL cannot use it as an admin")
            return (& $result $null $false @{})
        }
        # SEC-32: an EXISTING group that is not role-assignable is REPORTED, never deleted or recreated here (see the header).
        if ($group) {
            if ($group.PSObject.Properties['isAssignableToRole'] -and $null -ne $group.isAssignableToRole) {
                $state.roleAssignable = [bool]$group.isAssignableToRole
                if (-not $state.roleAssignable) {
                    [void]$findings.Add(("SECURITY FINDING: '$GroupName' ($($group.id)) is the SQL admin group but is NOT role-assignable -- any Groups " +
                        "Administrator, User Administrator or owner of it can add themselves, rewrite desired state and have the engine grant them " +
                        "Global Administrator (tier 1 -> tier 0). isAssignableToRole can only be set at creation: migrate ONCE, as a Privileged Role " +
                        "Administrator, to a new role-assignable group (the steps are in the header of tools/setup/_PimSqlAdminGroup.ps1). Nothing was changed."))
                }
            } else {
                [void]$notes.Add("could not read isAssignableToRole of '$GroupName' -- whether it is protected as tier 0 is NOT known")
            }
        }
    } catch { & $fail "read group '$GroupName'" $_.Exception.Message; return (& $result $null $false @{}) }

    # ---- read: the current Entra admin and AD-only -----------------------------------------------
    $admin = $null
    try {
        $list = & $Arm -Method GET -Path "$srvPath/administrators?api-version=$($script:PimSqlApi)"
        $a = @($list.value | Where-Object { $_ }) | Select-Object -First 1
        if ($a) {
            $sid = "$($a.properties.sid)".Trim()
            $oid = if ($group -and $sid -ieq "$($group.id)") { $sid } else { Resolve-PimDirectoryObjectId -Graph $Graph -Sid $sid }
            $admin = [pscustomobject]@{ sid = $sid; login = "$($a.properties.login)"; objectId = $oid }
        }
    } catch { & $fail "read the Entra admin of $SqlServerName" $_.Exception.Message; return (& $result $null $false @{}) }
    # 33.0 item 5 (2026-10-20): membersOnly, no -GroupObjectId and NO group under the configured name: the server's Entra
    # admin, when it IS a group, is read by its object id (the admin's sid) -- a RENAMED SQL admin group is still joined.
    # Only when the name finds nothing: a group that does carry the configured name stays the one used (today's behaviour),
    # and converge never adopts another group. A user / an application as admin answers 404 here -> blocked as before.
    if (-not $group -and $Mode -eq 'membersOnly' -and -not "$GroupObjectId".Trim() -and $admin -and (Test-PimSqlAdminGuid "$($admin.sid)")) {
        $byId = $null
        try { $byId = & $Graph -Method GET -Path ("/groups/$("$($admin.sid)".Trim())" + '?$select=id,displayName,securityEnabled,isAssignableToRole') } catch { $byId = $null }
        if ($byId -and "$($byId.id)".Trim() -and -not ($byId.PSObject.Properties['securityEnabled'] -and $byId.securityEnabled -eq $false)) {
            [void]$notes.Add("no group is named '$GroupName' -- the server's Entra admin group '$("$($byId.displayName)".Trim())' ($($byId.id)) is the SQL admin group (found by its id)")
            $group = $byId
            if ("$($byId.displayName)".Trim()) { $GroupName = "$($byId.displayName)".Trim() }
            $admin.objectId = "$($byId.id)".Trim()
            if ($byId.PSObject.Properties['isAssignableToRole'] -and $null -ne $byId.isAssignableToRole) { $state.roleAssignable = [bool]$byId.isAssignableToRole }
        }
    }
    $adOnlyBefore = $null
    try {
        $ao = & $Arm -Method GET -Path "$srvPath/azureADOnlyAuthentications/Default?api-version=$($script:PimSqlApi)"
        if ($ao -and $ao.properties -and $null -ne $ao.properties.azureADOnlyAuthentication) { $adOnlyBefore = [bool]$ao.properties.azureADOnlyAuthentication }
    } catch { [void]$notes.Add("Entra-only authentication could not be read before: $($_.Exception.Message)") }

    # ---- read: members ----------------------------------------------------------------------------
    $memberIds = @()
    if ($group) {
        try { $memberIds = @(Get-PimGraphGroupMemberIds -Graph $Graph -GroupId "$($group.id)") }
        catch { & $fail "read members of '$GroupName'" $_.Exception.Message; return (& $result $null $false @{}) }
    }

    $plan = Get-PimSqlAdminGroupPlan -GroupName $GroupName -Group $group -CurrentMemberIds $memberIds -DesiredMembers $Members `
                -CurrentAdmin $admin -Mode $Mode -DoNotKeepCurrentAdmin:$DoNotKeepCurrentAdmin
    $base = @{ adminBefore = $(if ($admin) { "$($admin.login)" } else { '' }); adminIsGroup = $plan.adminIsGroup; adAuthOnlyBefore = $adOnlyBefore
               present = @($plan.present); refused = @($plan.refused) }
    if ($Mode -eq 'converge' -and $plan.blocked) { [void]$problems.Add($plan.blocked) }
    if ($PlanOnly -or ($Mode -eq 'membersOnly' -and $plan.blocked)) { return (& $result $plan $false $base) }

    # ---- apply: the group -------------------------------------------------------------------------
    $gid = "$($plan.groupId)"
    $created = $false
    if ($plan.createGroup) {
        $nick = (($GroupName -replace '[^A-Za-z0-9]', '').ToLowerInvariant())
        if (-not $nick) { $nick = 'pimsqladmins' }
        try {
            # SEC-32: ROLE-ASSIGNABLE, so only Privileged Role Administrators can change who administers the store.
            # Settable ONLY here, at creation. Needs RoleManagement.ReadWrite.Directory on top of Group.Create.
            $g = & $Graph -Method POST -Path '/groups' -Body ([ordered]@{
                    displayName = $GroupName; mailEnabled = $false; mailNickname = $nick; securityEnabled = $true
                    isAssignableToRole = $true
                    description = 'PIM4EntraPS: Entra admin of the environment SQL server (managed identities + Invardia Support app). Role-assignable: tier 0.' })
            $gid = "$($g.id)".Trim()
            if (-not $gid) { throw 'the create returned no id' }
            $created = $true
            $state.roleAssignable = $true
            # A new group is not readable everywhere at once; wait until it is before adding members.
            $seenGroup = $false
            for ($i = 0; $i -lt $PollCount; $i++) {
                try { $gr = & $Graph -Method GET -Path ("/groups/$gid" + '?$select=id'); if ("$($gr.id)" -ieq $gid) { $seenGroup = $true; break } } catch { }
                & $Sleep $PollSeconds
            }
            if (-not $seenGroup) { [void]$notes.Add("the new group $gid was not readable after $($PollCount * $PollSeconds)s -- continuing") }
        } catch {
            $why = "$($_.Exception.Message)"
            if (Test-PimSqlAdminPermissionError $why) {
                $why += ' -- creating a ROLE-ASSIGNABLE group needs Graph RoleManagement.ReadWrite.Directory in addition to Group.Create; a plain group is NOT created instead'
            }
            & $fail "create group '$GroupName'" $why
            return (& $result $plan $false @($base, @{ created = $false }))
        }
    }

    # ---- apply: members (Graph fact 2: "already exist" is success) -------------------------------
    $added = New-Object System.Collections.Generic.List[object]
    foreach ($m in @($plan.add)) {
        if ("$($m.objectId)" -ieq $gid) { continue }   # Graph fact 4, re-checked against a freshly created id
        $ok = $false; $last = ''
        foreach ($d in @(0, 5, 10, 20)) {
            if ($d) { & $Sleep $d }
            try {
                [void](& $Graph -Method POST -Path "/groups/$gid/members/`$ref" -Body @{ '@odata.id' = "$($script:PimGraphBase)/directoryObjects/$($m.objectId)" })
                $ok = $true; break
            } catch {
                $last = "$($_.Exception.Message)"
                if ($last -match '(?i)already exist') { $ok = $true; break }
                if (Test-PimSqlAdminPermissionError $last) { break }
                if ($last -notmatch '(?i)HTTP 404\b|Request_ResourceNotFound|does not exist') { break }   # only replication lag is retried
            }
        }
        if (-not $ok -and $state.roleAssignable -eq $true -and (Test-PimSqlAdminPermissionError $last)) {
            $last += ' -- members of a ROLE-ASSIGNABLE group can only be changed with RoleManagement.ReadWrite.Directory (or by a Privileged Role Administrator)'
        }
        if ($ok) { [void]$added.Add($m) } else { & $fail "add $($m.label) ($($m.objectId)) to '$GroupName'" $last }
    }

    # ---- apply: the Entra admin (ARM fact 3: asynchronous) ---------------------------------------
    $adminChanged = $false
    if ($plan.setAdmin -and -not $problems.Count) {
        try {
            [void](& $Arm -Method PUT -Path "$srvPath/administrators/ActiveDirectory?api-version=$($script:PimSqlApi)" -Body ([ordered]@{
                        properties = [ordered]@{ administratorType = 'ActiveDirectory'; login = $GroupName; sid = $gid; tenantId = $TenantId } }))
            $adminChanged = $true
        } catch { & $fail "make '$GroupName' the Entra admin of $SqlServerName" $_.Exception.Message }
    } elseif ($plan.setAdmin) {
        [void]$notes.Add("the Entra admin was NOT moved to '$GroupName' because a member could not be added -- the previous admin keeps it")
    }

    # ---- read back ------------------------------------------------------------------------------
    $adminIsGroupAfter = [bool]$plan.adminIsGroup
    if ($gid -and ($adminChanged -or $plan.adminIsGroup)) {
        $adminIsGroupAfter = $false
        for ($i = 0; $i -lt $PollCount; $i++) {
            try {
                $cur = & $Arm -Method GET -Path "$srvPath/administrators/ActiveDirectory?api-version=$($script:PimSqlApi)"
                if ("$($cur.properties.sid)".Trim() -ieq $gid) { $adminIsGroupAfter = $true; break }
            } catch { }
            if (-not $adminChanged) { break }
            & $Sleep $PollSeconds
        }
        if (-not $adminIsGroupAfter) { [void]$problems.Add("read-back: the Entra admin of $SqlServerName is not '$GroupName' ($gid)$(if ($adminChanged) { " after $($PollCount * $PollSeconds)s" })") }
    }
    if ($gid) {
        try {
            # TRAP: a member ADDED seconds ago is not listed yet (Graph replication). Measured on a test tenant 2026-09-15: the
            # POST succeeded, the immediate read-back missed it, the deploy reported "is NOT a member" and fell
            # through to the contained-user step -- while a read a minute later listed it. So when this run added
            # members, the read-back polls (same bound as the admin read-back) before calling anything missing.
            $wantIds = @(@(@($plan.add) + @($plan.present)) | Where-Object { "$($_.objectId)" -ine $gid } | ForEach-Object { "$($_.objectId)".ToLowerInvariant() })
            $after = @(); $afterSet = @{}
            for ($i = 0; $i -lt [Math]::Max(1, $PollCount); $i++) {
                $after = @(Get-PimGraphGroupMemberIds -Graph $Graph -GroupId $gid)
                $afterSet = @{}; foreach ($x in $after) { $afterSet["$x".ToLowerInvariant()] = $true }
                if (-not $added.Count -or -not @($wantIds | Where-Object { -not $afterSet.ContainsKey($_) }).Count) { break }
                & $Sleep $PollSeconds
            }
            foreach ($m in @(@($plan.add) + @($plan.present))) {
                if ("$($m.objectId)" -ieq $gid) { continue }
                if (-not $afterSet.ContainsKey("$($m.objectId)".ToLowerInvariant())) { [void]$problems.Add("read-back: $($m.label) ($($m.objectId)) is NOT a member of '$GroupName'") }
            }
            if ($afterSet.ContainsKey($gid.ToLowerInvariant())) { [void]$problems.Add("read-back: '$GroupName' is a member of ITSELF -- remove it") }
        } catch { [void]$problems.Add("read-back of the members of '$GroupName' failed: $($_.Exception.Message)") }
    }
    $adOnlyAfter = $null
    try {
        $ao2 = & $Arm -Method GET -Path "$srvPath/azureADOnlyAuthentications/Default?api-version=$($script:PimSqlApi)"
        if ($ao2 -and $ao2.properties -and $null -ne $ao2.properties.azureADOnlyAuthentication) { $adOnlyAfter = [bool]$ao2.properties.azureADOnlyAuthentication }
    } catch { }
    if ($adOnlyBefore -eq $true -and $adOnlyAfter -ne $true) { [void]$problems.Add("read-back: Entra-only authentication was ON before and is not ON now") }

    return (& $result $plan $true @($base, @{ groupId = $gid; created = $created; added = @($added.ToArray()); adminChanged = $adminChanged
                                               adminIsGroup = $adminIsGroupAfter; adAuthOnlyAfter = $adOnlyAfter }))
}

function Invoke-PimSqlAdminGroupStep {
    <#
      Resolve WHO belongs in the group for one environment, then Invoke-PimSqlAdminGroup. Used by the
      script and by both deploy scripts, so the member list cannot differ between them.
        environment identity : ONLY when -EnvironmentIdentityName names it (PIM 100.156 B / framework 12.23 P5: not discovered)
        SQL identity         : -SqlAdminIdentityName, else the one id-pim-sql-* in the group (private SQL)
        updater identity     : -UpdateJobName's system-assigned identity, when the job exists AND
                               Get-PimSqlAdminGroupKeepsUpdater (the one switch) says so
        Invardia Support app : -SupportAppId / -SupportObjectId (old names -TroubleshootingAppId / -TroubleshootingObjectId still bind)
                               OPEN-01: NEVER added -- a note says so (no standing database administrator)
        setup identity       : -SetupIdentityAppId -- the application THIS setup runs as (a build), added for the setup
        extras               : -ExtraMembers @{ objectId; label } and -ExtraMemberObjectIds
      -NoDiscovery skips the two identity look-ups (a caller that knows exactly whom to add).
      Returns the Invoke-PimSqlAdminGroup result plus { members (resolved) }.
    #>
    param(
        [Parameter(Mandatory)][scriptblock]$Graph,
        [Parameter(Mandatory)][scriptblock]$Arm,
        [Parameter(Mandatory)][string]$TenantId,
        [Parameter(Mandatory)][string]$SubscriptionId,
        [Parameter(Mandatory)][string]$ResourceGroup,
        [Parameter(Mandatory)][string]$SqlServerName,
        [string]$SqlResourceGroup,
        [string]$GroupName = 'grp-pim-sql-admins',
        [string]$GroupObjectId,
        [string]$EnvironmentIdentityName,
        [string]$SqlAdminIdentityName,
        [string]$UpdateJobName = 'ca-pim-update',
        [Alias('TroubleshootingAppId')][string]$SupportAppId,
        [Alias('TroubleshootingObjectId')][string]$SupportObjectId,
        [string]$SetupIdentityAppId,
        [AllowEmptyCollection()][object[]]$ExtraMembers = @(),
        [AllowEmptyCollection()][string[]]$ExtraMemberObjectIds = @(),
        [ValidateSet('converge', 'membersOnly')][string]$Mode = 'converge',
        [switch]$NoDiscovery,
        [switch]$DoNotKeepCurrentAdmin,
        [switch]$PlanOnly,
        [int]$PollSeconds = 5,
        [int]$PollCount = 36,
        [scriptblock]$Sleep = { param([int]$Seconds) Start-Sleep -Seconds $Seconds }
    )
    $members = New-Object System.Collections.Generic.List[object]
    $resolveProblems = New-Object System.Collections.Generic.List[string]
    $resolveNotes = New-Object System.Collections.Generic.List[string]
    $rgPath = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup"

    if (-not $NoDiscovery) {
        $uamis = @()
        try { $uamis = @((& $Arm -Method GET -Path "$rgPath/providers/Microsoft.ManagedIdentity/userAssignedIdentities?api-version=$($script:PimMiApi)").value | Where-Object { $_ }) }
        catch { [void]$resolveProblems.Add("list the user-assigned identities in $ResourceGroup`: $($_.Exception.Message)") }
        $pick = {
            param([string]$Named, [string]$Pattern, [string]$NotPattern, [string]$What)
            if ("$Named".Trim()) {
                $hit = @($uamis | Where-Object { "$($_.name)" -ieq "$Named".Trim() })
                if (-not $hit.Count) { [void]$resolveProblems.Add("$What '$Named' was not found in $ResourceGroup"); return }
            } else {
                $hit = @($uamis | Where-Object { "$($_.name)" -match $Pattern -and (-not $NotPattern -or "$($_.name)" -notmatch $NotPattern) })
                if ($hit.Count -gt 1) { [void]$resolveNotes.Add("$($hit.Count) candidates for the $What ($(@($hit.name) -join ', ')) -- pass its name explicitly; none added"); return }
                if (-not $hit.Count) { [void]$resolveNotes.Add("no $What found in $ResourceGroup"); return }
            }
            $pid0 = "$($hit[0].properties.principalId)".Trim()
            if (-not $pid0) { [void]$resolveProblems.Add("$What '$($hit[0].name)' has no principalId"); return }
            [void]$members.Add([pscustomobject]@{ objectId = $pid0; label = "$What $($hit[0].name)" })
        }
        # PIM 100.156 B (framework 12.23 P5): the environment identity id-pim-<token> only pulls the image -- it is no
        # longer discovered (re-adding it would undo the cut-over that took it out). Named explicitly, it is still added.
        if ("$EnvironmentIdentityName".Trim()) { & $pick $EnvironmentIdentityName '^(?i)id-pim-' '^(?i)id-pim-sql-' 'environment identity' }
        else { [void]$resolveNotes.Add('the environment identity id-pim-<token> is not a member (it only pulls the image; framework 12.23 P5)') }
        & $pick $SqlAdminIdentityName '^(?i)id-pim-sql-' '' 'SQL identity'
    }
    if ("$UpdateJobName".Trim() -and -not (Get-PimSqlAdminGroupKeepsUpdater)) {
        [void]$resolveNotes.Add("$("$UpdateJobName".Trim()) is not a member: the updater reaches the store as its own contained user (pim_updater + db_ddladmin; framework 12.23 P5)")
    } elseif ("$UpdateJobName".Trim()) {
        # CR5 step 2 (PIM 100.149): the updater is ca-pim-update at every install made before the new names and
        # caj-pim-updater at a new one. The named job is read first (as always); only when it is NOT there and the name is
        # one of the updater role's names is the role's other name read (never anything else).
        $updNames = @("$UpdateJobName".Trim())
        if ((Get-Command Test-PimInstallNameIsRole -ErrorAction SilentlyContinue) -and (Test-PimInstallNameIsRole -Role updater -Name $UpdateJobName)) { $updNames = @(Get-PimInstallNameCandidates -Role updater -Preferred "$UpdateJobName".Trim()) }
        for ($ui = 0; $ui -lt $updNames.Count; $ui++) {
            $UpdateJobName = $updNames[$ui]
            try {
                $job = & $Arm -Method GET -Path "$rgPath/providers/Microsoft.App/jobs/$("$UpdateJobName".Trim())?api-version=$($script:PimJobApi)"
                # IDENTITY-MOVE-1 (3.0.67): a MOVED updater (signs in as id-pim-updater) is NEVER put in the SQL admin group --
                # SEC-09: the database job is the only standing member; its retired system identity is not re-added either.
                $updSi = Get-PimSignInIdentity -Resource $job
                if ("$($updSi.kind)" -eq 'user') { Write-Verbose "$UpdateJobName signs in as $($updSi.name): not a SQL admin group member (SEC-09)" }
                elseif ("$($updSi.principalId)".Trim()) { [void]$members.Add([pscustomobject]@{ objectId = "$($updSi.principalId)".Trim(); label = "updater identity $UpdateJobName" }) }
                else { [void]$resolveProblems.Add("$UpdateJobName has no identity it signs in as ($($updSi.reason))") }
                break
            } catch {
                $m = "$($_.Exception.Message)"
                $notThere = ($m -match '(?i)HTTP 404\b|ResourceNotFound|was not found')
                if ($notThere -and $ui -lt ($updNames.Count - 1)) { continue }
                if ($notThere) { [void]$resolveNotes.Add("$($updNames[0]) does not exist yet -- Deploy-PimUpdateJob.ps1 adds its identity when it creates it") }
                else { [void]$resolveProblems.Add("read $UpdateJobName`: $m") }
            }
        }
    }
    # OPEN-01 (framework SECAUDIT-1a): the Invardia Support app is NEVER added -- not a standing SQL administrator. Its one
    # standing database right is the read-only user (Grant-PimSupportAccess / Grant-PimSupportSqlAccess); admin rights only
    # inside an open support session. Named here, it is said and left out (a membership an earlier version gave is not
    # removed here either: 100.116 -- PIM never removes the Support app).
    if ("$SupportObjectId".Trim() -or "$SupportAppId".Trim()) {
        [void]$resolveNotes.Add('the Invardia Support app is not added to the SQL admin group (no standing database administrator; its read-only database user comes from Grant-PimSupportAccess.ps1)')
    }
    # The identity THIS setup runs as (a build's certificate application): a member for the length of the setup, like the
    # deploy identity of an install. Named by its application id; the caller decides whether it is released at the end.
    if ("$SetupIdentityAppId".Trim()) {
        try { [void]$members.Add([pscustomobject]@{ objectId = (Resolve-PimServicePrincipalObjectId -Graph $Graph -AppId $SetupIdentityAppId); label = "setup identity (app $("$SetupIdentityAppId".Trim()))" }) }
        catch { [void]$resolveProblems.Add("resolve the setup identity (app $SetupIdentityAppId): $($_.Exception.Message)") }
    }
    foreach ($x in @($ExtraMembers)) { if ($x) { [void]$members.Add($x) } }
    foreach ($x in @($ExtraMemberObjectIds)) { if ("$x".Trim()) { [void]$members.Add([pscustomobject]@{ objectId = "$x".Trim(); label = 'extra member' }) } }

    $sqlRg = if ("$SqlResourceGroup".Trim()) { "$SqlResourceGroup".Trim() } else { $ResourceGroup }
    $r = Invoke-PimSqlAdminGroup -Graph $Graph -Arm $Arm -SubscriptionId $SubscriptionId -ResourceGroup $sqlRg -SqlServerName $SqlServerName `
            -TenantId $TenantId -GroupName $GroupName -GroupObjectId $GroupObjectId -Members @($members.ToArray()) -Mode $Mode `
            -DoNotKeepCurrentAdmin:$DoNotKeepCurrentAdmin -PlanOnly:$PlanOnly -PollSeconds $PollSeconds -PollCount $PollCount -Sleep $Sleep
    $allProblems = @(@($resolveProblems.ToArray()) + @($r.problems))
    $r | Add-Member -NotePropertyName members -NotePropertyValue @($members.ToArray()) -Force
    $r.problems = $allProblems
    $r.notes = @(@($resolveNotes.ToArray()) + @($r.notes))
    $r.ok = ($allProblems.Count -eq 0)
    return $r
}

function Test-PimSqlAdminMemberIsSupportApp {
    <#
      READ-ONLY. Is the directory object -ObjectId the Invardia Support app? $true (its tag 'InvardiaSupport', or a display name
      starting 'Invardia Support' -- apps made before the tag) / $false (not a service principal: 404; or another one) /
      $null (the read failed -- not proven either way). PIM 100.116: the Support app is never removed by PIM.
    #>
    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$ObjectId)
    try {
        $sp = & $Graph -Method GET -Path ("/servicePrincipals/$("$ObjectId".Trim())" + '?$select=id,appId,displayName,tags')
        if ($null -eq $sp) { return $false }
        if (@($sp.tags) -contains 'InvardiaSupport') { return $true }
        return [bool]("$($sp.displayName)" -match '^(?i)Invardia Support')
    } catch {
        if ("$($_.Exception.Message)" -match '(?i)HTTP 404\b|Request_ResourceNotFound|does not exist') { return $false }
        return $null
    }
}

function Test-PimSqlAdminMemberSide {
    <#
      3.0.53: is -ObjectId a member of -GroupId, read from the MEMBER's side (POST /directoryObjects/{id}/checkMemberGroups,
      transitive) -- the read a role-assignable group's own member list cannot hide. $true / $false; $null = not readable.
    #>
    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][string]$ObjectId, [Parameter(Mandatory)][string]$GroupId)
    try {
        $r = & $Graph -Method POST -Path "/directoryObjects/$ObjectId/checkMemberGroups" -Body @{ groupIds = @($GroupId) }
        return [bool](@(@($r.value) | ForEach-Object { "$_".ToLowerInvariant() }) -contains "$GroupId".ToLowerInvariant())
    } catch { return $null }
}

function Remove-PimSqlAdminGroupMember {
    <#
      SEC-39 -- take ONE identity OUT of the SQL admin group, and read it back. Used when an identity that only needs a
      least-privilege database user (the baseline publish job) was made a member by an earlier version: membership of
      the group is full server administration. The caller creates and VERIFIES the replacement access first.
      Never throws for a Graph refusal. Returns { ok; wasMember; removed; groupId; problem }.
        absent group / not a member -> ok, nothing written
      -OwnObjectId (OPEN-01 item 4, waits for the owner's decision; only Initialize-PimSqlAdminGroup -ReleaseOwnMembership
      passes it): the object id of the identity RUNNING this. Only when it EQUALS -MemberObjectId may a member that is the
      Invardia Support app be removed -- a build releasing its OWN temporary membership. Any other Support-app member is
      never removed (100.116), with or without it.
    #>
    param(
        [Parameter(Mandatory)][scriptblock]$Graph,
        [Parameter(Mandatory)][string]$MemberObjectId,
        [string]$OwnObjectId = '',
        [string]$GroupName = 'grp-pim-sql-admins',
        [string]$GroupObjectId,
        [string]$Label = 'member',
        [int]$PollSeconds = 5,
        [int]$PollCount = 24,
        [scriptblock]$Sleep = { param([int]$Seconds) Start-Sleep -Seconds $Seconds }
    )
    $out = [ordered]@{ ok = $false; wasMember = $false; removed = $false; groupId = ''; problem = '' }
    $oid = "$MemberObjectId".Trim()
    if (-not (Test-PimSqlAdminGuid $oid)) { $out.problem = "'$MemberObjectId' is not an object id"; return [pscustomobject]$out }
    try {
        if ("$GroupObjectId".Trim()) { $grp = & $Graph -Method GET -Path ("/groups/$("$GroupObjectId".Trim())" + '?$select=id,displayName,isAssignableToRole') }
        else {
            $flt = [uri]::EscapeDataString("displayName eq '$($GroupName.Replace("'", "''"))'")
            $found = @((& $Graph -Method GET -Path ('/groups?$filter=' + $flt + '&$select=id,displayName,isAssignableToRole')).value | Where-Object { $_ })
            if ($found.Count -gt 1) { $out.problem = "$($found.Count) groups are named '$GroupName' -- ambiguous; pass -GroupObjectId"; return [pscustomobject]$out }
            $grp = if ($found.Count) { $found[0] } else { $null }
        }
        if (-not $grp -or -not "$($grp.id)".Trim()) { $out.ok = $true; return [pscustomobject]$out }
        $gid = "$($grp.id)".Trim(); $out.groupId = $gid
        $ids = @(Get-PimGraphGroupMemberIds -Graph $Graph -GroupId $gid | ForEach-Object { "$_".ToLowerInvariant() })
        # 3.0.53 (G3A-COPY-LEFTOVER, Invardia 2026-11-07): a ROLE-ASSIGNABLE group's own member list can come back EMPTY to the
        # caller (the Invardia Support app read 0 members at two test installs while the member side showed them) -- so the
        # MEMBER side (checkMemberGroups) is asked too, and "not a member" needs both to say so ($null = not readable).
        $side = Test-PimSqlAdminMemberSide -Graph $Graph -ObjectId $oid -GroupId $gid
        if ($ids -notcontains $oid.ToLowerInvariant() -and $side -ne $true) { $out.ok = $true; return [pscustomobject]$out }
        $out.wasMember = $true
        # PIM 100.116 / framework 4.1b (owner 2026-10-18): the Invardia Support app is the group's STANDING member -- PIM never
        # removes it (only the customer's Grant-PimSupportAccess.ps1 -Remove does). A member that is not a service principal
        # (a person) answers 404 here; anything that cannot be PROVEN not to be the Support app is left a member.
        $isSupport = Test-PimSqlAdminMemberIsSupportApp -Graph $Graph -ObjectId $oid
        $ownMembership = [bool]((Test-PimSqlAdminGuid "$OwnObjectId".Trim()) -and "$OwnObjectId".Trim() -ieq $oid)
        if ($isSupport -ne $false -and -not $ownMembership) {
            $out.problem = $(if ($isSupport) { "$Label ($oid) is the Invardia Support app -- PIM never removes it from '$GroupName' (the customer ends that access with Grant-PimSupportAccess.ps1 -Remove)" }
                             else { "$Label ($oid) could not be proven NOT to be the Invardia Support app -- it was not removed from '$GroupName'" })
            return [pscustomobject]$out
        }
        # 3.0.53: on a ROLE-ASSIGNABLE (PIM-managed) group the membership is a PIM-for-Groups assignment -- removed with
        # adminRemove (members/$ref is refused there without RoleManagement.ReadWrite.Directory). A direct member (adminRemove
        # refused / not an assignment) falls back to members/$ref as before.
        $viaPim = $false
        if ($grp.PSObject.Properties['isAssignableToRole'] -and $grp.isAssignableToRole -eq $true) {
            try {
                [void](& $Graph -Method POST -Path '/identityGovernance/privilegedAccess/group/assignmentScheduleRequests' -Body @{ accessId = 'member'; principalId = $oid; groupId = $gid; action = 'adminRemove'; justification = "PIM: $Label out of the SQL admin group (its own least-privilege database user is in place)" })
                $viaPim = $true
            } catch { $viaPim = $false }
        }
        if (-not $viaPim) {
            try { [void](& $Graph -Method DELETE -Path "/groups/$gid/members/$oid/`$ref") }
            catch { if ("$($_.Exception.Message)" -notmatch '(?i)HTTP 404\b|Request_ResourceNotFound|does not exist') { throw } }
        }
        for ($i = 0; $i -lt [Math]::Max(1, $PollCount); $i++) {
            $ids = @(Get-PimGraphGroupMemberIds -Graph $Graph -GroupId $gid | ForEach-Object { "$_".ToLowerInvariant() })
            $side = Test-PimSqlAdminMemberSide -Graph $Graph -ObjectId $oid -GroupId $gid
            if ($ids -notcontains $oid.ToLowerInvariant() -and $side -ne $true) { $out.removed = $true; $out.ok = $true; return [pscustomobject]$out }
            & $Sleep $PollSeconds
        }
        $out.problem = "read-back: $Label ($oid) is STILL a member of '$GroupName' after the removal"
    } catch {
        $m = "$($_.Exception.Message)"
        if (Test-PimSqlAdminPermissionError $m) { $m += ' -- removing a member needs GroupMember.ReadWrite.All (and, on a ROLE-ASSIGNABLE group, RoleManagement.ReadWrite.Directory)' }
        $out.problem = "remove $Label ($oid) from '$GroupName': $m"
    }
    return [pscustomobject]$out
}

function Get-PimSqlAdminGroupSetupReleasePlan {
    <#
      PURE (PIM 100.156 B, framework 12.23 P5). May the setup identity leave the SQL admin group now?
        -MemberObjectId : the setup identity (the signed-in person, or the SQL admin application's service principal)
        -CurrentAdmin   : the server's Entra admin { sid; login } ($null = none / unreadable)
        -GroupId        : the SQL admin group's object id ('' = no group)
      release = $true only when the group IS the server's admin (else membership grants nothing to take back) and the setup
      identity is NOT the admin itself (taking that away would leave the server without an administrator).
      Returns { release; reason }.
    #>
    param([AllowEmptyString()][string]$MemberObjectId, [object]$CurrentAdmin, [AllowEmptyString()][string]$GroupId)
    $oid = "$MemberObjectId".Trim()
    if (-not (Test-PimSqlAdminGuid $oid)) { return [pscustomobject]@{ release = $false; reason = 'no setup identity object id -- nothing to release' } }
    $sid = if ($CurrentAdmin) { "$($CurrentAdmin.sid)".Trim() } else { '' }
    if ($sid -and $sid -ieq $oid) { return [pscustomobject]@{ release = $false; reason = 'the setup identity IS the SQL server''s Entra admin (the SQL admin group could not be made the admin) -- it is not removed; a Privileged Role Administrator converges the server onto the group (Initialize-PimSqlAdminGroup.ps1)' } }
    if (-not "$GroupId".Trim()) { return [pscustomobject]@{ release = $false; reason = 'there is no SQL admin group -- nothing to release' } }
    if (-not $sid -or $sid -ine "$GroupId".Trim()) { return [pscustomobject]@{ release = $false; reason = 'the SQL admin group is not the server''s Entra admin -- membership grants nothing, nothing to release' } }
    return [pscustomobject]@{ release = $true; reason = 'the setup identity leaves the SQL admin group (framework 12.23 P5: setup identities only for the length of an install)' }
}

function Invoke-PimSqlAdminGroupSetupRelease {
    <#
      PIM 100.156 B (framework 12.23 P5): at the END of an install, take the setup identity out of the SQL admin group again
      and read it back -- the standing member is the Invardia Support app only. Never throws; a Graph refusal (a role-
      assignable group needs RoleManagement.ReadWrite.Directory) leaves it a member and says so with the command to run.
      Returns { ok; released; skipped; reason }.
    #>
    param([Parameter(Mandatory)][scriptblock]$Graph, [Parameter(Mandatory)][scriptblock]$Arm, [Parameter(Mandatory)][string]$SubscriptionId,
          [Parameter(Mandatory)][string]$SqlResourceGroup, [Parameter(Mandatory)][string]$SqlServerName, [AllowEmptyString()][string]$MemberObjectId,
          [string]$GroupName = 'grp-pim-sql-admins', [string]$Label = 'the setup identity', [string]$OwnObjectId = '',
          [int]$PollSeconds = 5, [int]$PollCount = 24, [scriptblock]$Sleep = { param([int]$Seconds) Start-Sleep -Seconds $Seconds })
    $out = [ordered]@{ ok = $true; released = $false; skipped = $true; reason = '' }
    try {
        $srvPath = "/subscriptions/$SubscriptionId/resourceGroups/$SqlResourceGroup/providers/Microsoft.Sql/servers/$SqlServerName"
        $adm = $null
        try { $adm = @((& $Arm -Method GET -Path "$srvPath/administrators?api-version=$($script:PimSqlApi)").value | Where-Object { $_ }) | Select-Object -First 1 } catch { $adm = $null }
        $cur = if ($adm) { [pscustomobject]@{ sid = "$($adm.properties.sid)"; login = "$($adm.properties.login)" } } else { $null }
        $flt = [uri]::EscapeDataString("displayName eq '$($GroupName.Replace("'", "''"))'")
        $grp = @((& $Graph -Method GET -Path ('/groups?$filter=' + $flt + '&$select=id,displayName')).value | Where-Object { $_ }) | Select-Object -First 1
        # 33.0 item 5 (2026-10-20): NO group under the configured name -> the admin's sid read above is tried as the group's
        # object id (the release needs the group to BE the server's admin anyway) -- a RENAMED group is still released. A
        # user / an application as admin answers 404 -> no group, nothing to release (as before). A group that does carry
        # the configured name stays the one used (today's behaviour).
        if (-not $grp -and $cur -and (Test-PimSqlAdminGuid "$($cur.sid)")) {
            try { $grp = & $Graph -Method GET -Path ("/groups/$("$($cur.sid)".Trim())" + '?$select=id,displayName') } catch { $grp = $null }
            if ($grp -and "$($grp.id)".Trim()) { if ("$($grp.displayName)".Trim()) { $GroupName = "$($grp.displayName)".Trim() } } else { $grp = $null }
        }
        $plan = Get-PimSqlAdminGroupSetupReleasePlan -MemberObjectId $MemberObjectId -CurrentAdmin $cur -GroupId $(if ($grp) { "$($grp.id)" } else { '' })
        $out.reason = $plan.reason
        if (-not $plan.release) { return [pscustomobject]$out }
        $out.skipped = $false
        $rm = Remove-PimSqlAdminGroupMember -Graph $Graph -MemberObjectId $MemberObjectId -GroupObjectId "$($grp.id)" -GroupName $GroupName -Label $Label `
                 -OwnObjectId $OwnObjectId -PollSeconds $PollSeconds -PollCount $PollCount -Sleep $Sleep
        if ($rm.ok) {
            $out.released = [bool]$rm.removed
            $out.reason = $(if ($rm.removed) { "$Label left '$GroupName' (read back)" } else { "$Label was not a member of '$GroupName' -- nothing to release" })
        } else {
            $out.ok = $false
            $out.reason = "$($rm.problem) -- $Label is STILL a member of '$GroupName'. A Privileged Role Administrator removes it (Entra admin center > Groups > $GroupName > Members)."
        }
    } catch {
        $out.ok = $false; $out.skipped = $false
        $out.reason = "the setup identity's SQL admin group membership could not be checked: $($_.Exception.Message)"
    }
    return [pscustomobject]$out
}

function Write-PimSqlAdminGroupReport {
    <# Print a result the same way from every caller. -Indent keeps it inside a deploy step. #>
    param([Parameter(Mandatory)][object]$Result, [string]$Indent = '    ')
    $p = $Result.plan
    if ($p) { foreach ($m in @($p.messages)) { Write-Host "$Indent$m" -ForegroundColor DarkGray } }
    foreach ($m in @($Result.members)) { if ($m) { Write-Host "$Indent  member wanted: $($m.label) ($($m.objectId))" -ForegroundColor DarkGray } }
    foreach ($n in @($Result.notes)) { Write-Host "$Indent$n" -ForegroundColor Yellow }
    if ($Result.applied) {
        if ($Result.created) { Write-Host "$Indent[CHANGED] created '$($Result.groupName)' ($($Result.groupId))" -ForegroundColor Green }
        foreach ($a in @($Result.added)) { Write-Host "$Indent[CHANGED] member $($a.label) ($($a.objectId))" -ForegroundColor Green }
        foreach ($a in @($Result.present)) { Write-Host "$Indent[OK] member $($a.label)" -ForegroundColor DarkGray }
        if ($Result.adminChanged) { Write-Host "$Indent[CHANGED] Entra admin '$($Result.adminBefore)' -> '$($Result.groupName)' (read back)" -ForegroundColor Green }
        elseif ($Result.adminIsGroup) { Write-Host "$Indent[OK] '$($Result.groupName)' is the Entra admin" -ForegroundColor DarkGray }
    }
    foreach ($x in @($Result.problems)) { Write-Host "$Indent[FAIL] $x" -ForegroundColor Red }
    # SEC-32: a finding is not a failure (nothing was changed), but it must not be missable in a deploy log.
    foreach ($x in @($Result.securityFindings)) {
        Write-Host "$Indent[SECURITY FINDING] $x" -ForegroundColor Red
    }
    if ($Result.permissionDenied) {
        Write-Host "${Indent}the identity running this was refused by Microsoft Graph or ARM. It needs Graph Group.Create + GroupMember.ReadWrite.All" -ForegroundColor Yellow
        Write-Host "${Indent}(or Group.ReadWrite.All), Directory.Read.All, and rights to set the SQL server's Entra admin -- and, because the group is" -ForegroundColor Yellow
        Write-Host "${Indent}ROLE-ASSIGNABLE, RoleManagement.ReadWrite.Directory to create it or change its members (or run it as a" -ForegroundColor Yellow
        Write-Host "${Indent}Privileged Role Administrator)." -ForegroundColor Yellow
    }
}

function New-PimSqlAdminGroupInvokers {
    <#
      Graph + ARM callers for one subscription's tenant. Two credential sources, never a secret:
        default                         -- the identity PIM-Rest is set up for in this process (no az, 100.41)
        -ClientId + -CertThumbprint     -- a certificate in the local store, via Get-PimRestToken
      The token's tenant is checked against -TenantId (or the subscription's tenant): on a host holding
      several logins the default context is frequently another directory.
      Returns { Graph; Arm; TenantId }.
    #>
    param(
        [Parameter(Mandatory)][string]$SubscriptionId,
        [string]$TenantId,
        [string]$ClientId,
        [string]$CertThumbprint
    )
    $decodeTid = {
        param([string]$Tok)
        try {
            $p = "$Tok".Split('.')[1].Replace('-', '+').Replace('_', '/'); while ($p.Length % 4) { $p += '=' }
            "$(([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json).tid)".Trim().ToLowerInvariant()
        } catch { '' }
    }
    $want = "$TenantId".Trim().ToLowerInvariant()
    if ("$ClientId".Trim() -or "$CertThumbprint".Trim()) {
        if (-not ("$ClientId".Trim() -and "$CertThumbprint".Trim() -and $want)) { throw 'New-PimSqlAdminGroupInvokers: certificate auth needs -TenantId, -ClientId and -CertThumbprint together.' }
        $rest = Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'engine\_shared\PIM-Rest.ps1'
        if (-not (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue)) { . $rest }
        $graphTok = "$(Get-PimRestToken -Resource 'https://graph.microsoft.com' -TenantId $TenantId -ClientId $ClientId -CertThumbprint $CertThumbprint)"
        $armTok   = "$(Get-PimRestToken -Resource 'https://management.azure.com' -TenantId $TenantId -ClientId $ClientId -CertThumbprint $CertThumbprint)"
    } else {
        # 100.41 (no az): the identity PIM-Rest's ONE token client is set up for in this process (the signed-in person,
        # the Invardia Support app's REST session, or a certificate), pinned to the subscription's tenant.
        $rest = Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'engine\_shared\PIM-Rest.ps1'
        if (-not (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue) -and (Test-Path -LiteralPath $rest)) { . $rest }
        $graphTok = ''; $armTok = ''
        if (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue) {
            if (-not $want -and (Get-Command Resolve-PimArmSubscriptionTenant -ErrorAction SilentlyContinue)) { $want = "$(Resolve-PimArmSubscriptionTenant -SubscriptionId $SubscriptionId)".Trim().ToLowerInvariant() }
            if (-not $want) { $want = "$($global:PIM_TenantId)".Trim().ToLowerInvariant() }
            if ($want) {
                try { $graphTok = "$(Get-PimRestToken -Resource 'https://graph.microsoft.com' -TenantId $want)" } catch { }
                try { $armTok   = "$(Get-PimRestToken -Resource 'https://management.azure.com' -TenantId $want)" } catch { }
            }
        } else {
            # Framework 12.17 (one connect path): there is no other token source. The published standalone
            # Initialize-PimSqlAdminGroup.ps1 inlines engine\_shared\PIM-Rest.ps1 + _PimSignedIn.ps1, so it never gets here.
            throw 'New-PimSqlAdminGroupInvokers: engine\_shared\PIM-Rest.ps1 is not loaded -- the token client is missing.'
        }
    }
    if (-not $graphTok -or -not $armTok) { throw "New-PimSqlAdminGroupInvokers: no Graph/ARM token for subscription $SubscriptionId (sign in first)." }
    foreach ($t in @($graphTok, $armTok)) {
        $tid = & $decodeTid $t
        if (-not $want -or $tid -ne $want) { throw "New-PimSqlAdminGroupInvokers: a token is for tenant '$tid', not '$want' -- REFUSING." }
    }
    $mk = {
        param([string]$Base, [string]$Token)
        {
            param([string]$Method = 'GET', [string]$Path, [object]$Body)
            $uri = if ($Path -match '^https://') { $Path } else { "$Base$Path" }
            $h = @{ Authorization = "Bearer $Token" }
            try {
                if ($Method -eq 'GET' -or $Method -eq 'DELETE') { return (Invoke-RestMethod -Method $Method -Uri $uri -Headers $h -UseBasicParsing) }
                $json = if ($null -eq $Body) { '{}' } else { $Body | ConvertTo-Json -Depth 20 -Compress }
                return (Invoke-RestMethod -Method $Method -Uri $uri -Headers $h -ContentType 'application/json' -Body ([Text.Encoding]::UTF8.GetBytes($json)) -UseBasicParsing)
            } catch {
                $code = ''; try { $code = [int]$_.Exception.Response.StatusCode } catch { }
                $detail = "$($_.ErrorDetails.Message)"; if (-not $detail) { $detail = "$($_.Exception.Message)" }
                throw ("$Method $Path -> HTTP $code : $detail")
            }
        }.GetNewClosure()
    }
    return [pscustomobject]@{
        Graph = (& $mk 'https://graph.microsoft.com/v1.0' $graphTok)
        Arm   = (& $mk 'https://management.azure.com' $armTok)
        TenantId = $want
    }
}

# ===== END inlined helper: _PimSqlAdminGroup.ps1 =====
# ===== BEGIN inlined helper: ..\..\engine\_shared\PIM-InstallNames.ps1 =====
<#
  PIM-InstallNames.ps1 -- framework DOCS/REQUIREMENTS.md §12.11c NAMING (CR5) item 6, PIM REQUIREMENTS 100.149:
  EVERY resource / identity name of THIS installation is read from ONE place, never from a literal in code, so the old
  names (every install today) and the standard ones (caj-pim-engine, caj-pim-updater, ... for NEW installs, and for an
  existing install after JOB-RENAME 3.0.68 -- web apps are never renamed) work side by side.

  🔒 Owner 2026-10-14: "but remember it must work for existing customers". TODAY'S NAME IS THE DEFAULT: an install with no
  record and no variable resolves exactly the names it runs with now -- no migration, no rename, nothing to set.

  Resolution, per role (first that answers):
    1. the install record: pim.Settings 'InstallNames' { web; engine; updater; asbuilt; asbuiltIdentity; sqlAdminGroup;
       publish; downlink; requests; dbinit; dbinitIdentity; recordedUtc } -- written by the updater (New-PimInstallNamesRecord) from what it was
       deployed with, and by setup at a new install (CR5 step 2)
    2. the environment variables an install already carries (PIM_ManagerApp, PIM_TickJobName, PIM_UpdateJobName,
       PIM_SqlAdminGroupName, PIM_ENGINE_JOB_NAME, PIM_SQL_ADMIN_GROUP, the tick's id PIM_TickJobId)
    3. today's name (Get-PimInstallNameDefaults)
  A record read that fails is never an error: the next source answers (a name is never blocked by a store read).
  Seams: -Record (a hashtable / object), $global:PIM_InstallNames (preloaded record; tests).
  ASCII only; PS 5.1-safe; pure except the one cached store read.
#>
Set-StrictMode -Off

function Get-PimInstallNameDefaults {
    # PURE. Today's names -- the names every existing install runs with. A literal table in a FUNCTION (the child-scope
    # trap: a $script: table is $null when a caller dot-sources this from another scope).
    return [ordered]@{
        web             = 'ca-pim-manager'
        engine          = 'ca-pim-tick'
        updater         = 'ca-pim-update'
        asbuilt         = 'caj-pim-asbuilt'
        asbuiltIdentity = 'id-pim-asbuilt'
        sqlAdminGroup   = 'grp-pim-sql-admins'
        publish         = 'ca-pim-publish'
        downlink        = 'ca-pim-downlink-s6'
        requests        = 'ca-pim-rfa'
        dbinit          = 'ca-pim-dbinit'      # OPEN-06: the in-network database job (manual trigger), every install
        dbinitIdentity  = 'id-pim-dbinit'      # OPEN-06: its dedicated identity (created by the updater with the job)
    }
}

function Get-PimInstallNameRoles { return @((Get-PimInstallNameDefaults).Keys) }

# ---- CR5 STEP 2 (framework §12.11c items 2-4, PIM 100.149 step 2) -- THE NEW NAMES, NEW INSTALLS ONLY ---------------------
# Azure cannot rename a container app / job: an EXISTING install keeps today's names for good, and the record (above)
# tells every reader which names it runs with. A NEW install takes these only when setup's switch is on
# (-NewInstallNames / PIM_Setup_NewInstallNames, OFF by default -- with it off setup creates exactly today's names).
function Get-PimInstallNameNewDefaults {
    # PURE. The CR5 / NAMING-PROGRAMME-1 names (framework naming-standard.json, owner 2026-11-09): caj-pim-<purpose> JOBS,
    # id-pim-<role> identities, grp-pim-<purpose> groups. WEB APPS ARE NEVER RENAMED (owner 2026-11-09): the Manager stays
    # ca-pim-manager and the access request broker ca-pim-rfa -- at a new install too. The names an earlier step gave a new
    # install (ca-pim-web, ca-pim-engine, ca-pim-requests) stay RECOGNISED (Get-PimInstallNameLegacyNames). JOB-RENAME
    # (3.0.68, tools/setup/Rename-PimJobs.ps1) moves an existing install's jobs to these names.
    return [ordered]@{
        web             = 'ca-pim-manager'
        engine          = 'caj-pim-engine'
        updater         = 'caj-pim-updater'
        asbuilt         = 'caj-pim-docs'       # "Installation documentation" (framework naming-standard.json, docs role)
        asbuiltIdentity = 'id-pim-docs'        # owner 2026-11-09: the docs job runs as id-pim-docs (id-pim-asbuilt = today's name)
        sqlAdminGroup   = 'grp-pim-sql-admins'
        publish         = 'caj-pim-publish'
        downlink        = 'caj-pim-downlink'
        requests        = 'ca-pim-rfa'
        dbinit          = 'caj-pim-dbinit'
        dbinitIdentity  = 'id-pim-dbinit'
    }
}

function Get-PimInstallNameLegacyNames {
    # PURE. Names a role carried at SOME install that are neither today's nor the standard one: the CR5 step-2 names new
    # installs got 2026-11-04 .. 3.0.67 (ca-pim-web / ca-pim-engine / ca-pim-requests). A reader that FINDS a resource still
    # answers to them (an install made with them keeps working); setup never gives them to a new install.
    return @{ web = @('ca-pim-web'); engine = @('ca-pim-engine'); requests = @('ca-pim-requests') }
}

function Get-PimInstallNameSet {
    # PURE. The whole name table for a setup run: -New = the CR5 names, else today's.
    param([switch]$New)
    if ($New) { return (Get-PimInstallNameNewDefaults) }
    return (Get-PimInstallNameDefaults)
}

function Get-PimInstallNameCandidates {
    <#
      PURE. Every name -Role can carry at ANY install (today's first, then the standard name, then the legacy CR5 names) --
      for a reader that has no record and must FIND the resource (ops / support scripts, name-pattern discovery): an old
      install answers to the first, a renamed / new one to the second, an install made 2026-11-04 .. 3.0.67 to the third.
      -Preferred (a name the caller already knows) goes first.
    #>
    param([Parameter(Mandatory)][string]$Role, [AllowEmptyString()][string]$Preferred = '')
    $d = Get-PimInstallNameDefaults
    if (-not $d.Contains($Role)) { throw "Get-PimInstallNameCandidates: unknown role '$Role' (known: $((Get-PimInstallNameRoles) -join ', '))" }
    $n = Get-PimInstallNameNewDefaults
    $lg = Get-PimInstallNameLegacyNames
    $legacy = @(if ($lg.ContainsKey($Role)) { $lg[$Role] })
    $out = New-Object System.Collections.Generic.List[string]
    foreach ($x in @(@("$Preferred".Trim(), "$($d[$Role])", "$($n[$Role])") + $legacy)) { if ((Test-PimInstallNameValue $x) -and -not $out.Contains($x)) { [void]$out.Add($x) } }
    return @($out.ToArray())
}

function Test-PimInstallNameIsRole {
    # PURE. Is -Name one of the names -Role carries at any install (today's or the CR5 one; case-insensitive)?
    param([Parameter(Mandatory)][string]$Role, [AllowEmptyString()][string]$Name)
    $n = "$Name".Trim(); if (-not $n) { return $false }
    return [bool](@(Get-PimInstallNameCandidates -Role $Role | Where-Object { $_ -ieq $n }).Count)
}

function Get-PimInstallIdentityNames {
    <#
      PURE. framework §12.11c item 3: one identity per role, id-pim-<role>. RECORDED for the owner's CR8 build, NOT created
      by setup: PIM's web app, engine job and updater run as their SYSTEM-assigned identities (an identity Azure names
      after the resource -- ca-pim-web, ca-pim-engine, caj-pim-updater at a new install), and moving them to user-assigned
      identities is the CR8 "one identity per role" change (token by client id, every grant on the new principal).
    #>
    return [ordered]@{ web = 'id-pim-web'; engine = 'id-pim-engine'; updater = 'id-pim-updater'; mcp = 'id-pim-mcp' }
}

function Test-PimNewInstallNamesSwitch {
    <#
      The setup switch for CR5 step 2 -- ON BY DEFAULT since 2026-11-04 (framework §5.5 "THE AGREED LIST", owner: "fx tick ...
      we dont use that"; wizard "On now"): a NEW install gets ca-pim-manager / caj-pim-engine / caj-pim-updater (3.0.68: the
      web app is never renamed; jobs are caj-pim-<purpose>; before 3.0.68 ca-pim-web / ca-pim-engine). An EXISTING install
      keeps its names whatever this says (Resolve-PimSetupInstallNameChoice reads the resource group). -Explicit (a bound
      -NewInstallNames / a config value) wins; else $env:PIM_Setup_NewInstallNames, else $global:PIM_Setup_NewInstallNames:
      1 / true / yes / on = on, anything else given = off. Nothing given = ON.
    #>
    param([AllowNull()][object]$Explicit = $null)
    $on = { param($v) return ("$v".Trim() -match '^(?i)(1|true|yes|on)$') }
    if ($null -ne $Explicit -and "$Explicit".Trim() -ne '') { return [bool](& $on $Explicit) }
    if ("$($env:PIM_Setup_NewInstallNames)".Trim()) { return [bool](& $on $env:PIM_Setup_NewInstallNames) }
    if ($null -ne $global:PIM_Setup_NewInstallNames) { return [bool](& $on $global:PIM_Setup_NewInstallNames) }
    return $true
}

function Resolve-PimSetupInstallNameChoice {
    <#
      PURE. Which name set a setup run uses in ONE resource group, from what is already there (Azure cannot rename):
        today's web app / engine or updater job present -> today's names (an existing install; a requested switch is refused)
        a CR5 web app / engine or updater job present    -> the CR5 names (an install made with them, re-run without the switch)
        nothing of PIM present                           -> what was requested (-RequestNew)
        the resource group could not be read (-ReadOk:$false) and new names requested -> today's names (never guess "new")
      -ExistingApps / -ExistingJobs: the container app / job names in the group. Returns @{ useNew; reason; refused; existing }.
      JOB-RENAME (3.0.68): the web app is never renamed (ca-pim-manager at every install), so the JOBS decide: a standard /
      legacy-CR5 engine or updater job (caj-pim-engine, caj-pim-updater, ca-pim-engine) or the legacy web ca-pim-web = an
      install on the new names -- also a RENAMED install, whose old jobs are kept (disabled) beside the new ones. -existing
      carries the names the group really holds per role (web / engine / updater), so a re-run never makes a second one.
    #>
    param([bool]$RequestNew = $false, [string[]]$ExistingApps = @(), [string[]]$ExistingJobs = @(), [bool]$ReadOk = $true)
    $d = Get-PimInstallNameDefaults; $n = Get-PimInstallNameNewDefaults; $lg = Get-PimInstallNameLegacyNames
    $apps = @(@($ExistingApps) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
    $jobs = @(@($ExistingJobs) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
    $newEngine = @(@($n.engine) + @($lg.engine)); $newWeb = @($lg.web)
    $hasNewJobs = [bool](@($jobs | Where-Object { $newEngine -contains $_ -or $_ -eq $n.updater }).Count)
    $hasNewWeb  = [bool](@($apps | Where-Object { $newWeb -contains $_ }).Count)
    $hasToday   = ($apps -contains $d.web) -or ($jobs -contains $d.engine) -or ($jobs -contains $d.updater)
    $first = { param($have, $want) foreach ($w in @($want)) { if ($have -contains "$w".ToLowerInvariant()) { return "$w" } }; return '' }
    if ($hasNewJobs -or $hasNewWeb) {
        $ex = @{ web = (& $first $apps (@($newWeb) + @($n.web))); engine = (& $first $jobs $newEngine); updater = (& $first $jobs @($n.updater)) }
        $renamed = ($jobs -contains $d.engine) -or ($jobs -contains $d.updater)
        return @{ useNew = $true; refused = $false; existing = $ex
                  reason = $(if ($renamed) { "this install's jobs were renamed to the standard names ($($ex.engine) / $($ex.updater); the old jobs are kept, disabled) -- kept" } else { "this install already runs with the new names ($(@($ex.web, $ex.engine) | Where-Object { $_ }) -join ' / ')) -- kept" }) }
    }
    if ($hasToday) {
        if ($RequestNew) { return @{ useNew = $false; refused = $true; reason = "this resource group already runs PIM Manager under today's names ($($d.web) / $($d.engine)) -- Azure cannot rename a container app or job, so the install keeps them (Rename-PimJobs.ps1 moves its jobs)" } }
        return @{ useNew = $false; refused = $false; reason = "today's names (an existing install)" }
    }
    if ($RequestNew -and -not $ReadOk) { return @{ useNew = $false; refused = $true; reason = 'the resource group could not be read, so a new install cannot be proven -- today''s names are used' } }
    if ($RequestNew) { return @{ useNew = $true; refused = $false; reason = 'a new install with the new names (PIM_Setup_NewInstallNames)' } }
    return @{ useNew = $false; refused = $false; reason = "today's names (PIM_Setup_NewInstallNames is off)" }
}

# ---- CR5 ITEM 5 (framework §12.11c item 5) -- THE DISPLAY NAMES PEOPLE READ --------------------------------------------
# "Short code in Azure, full name where people read": the product is PIM Manager, never PIM4EntraPS. These helpers map a
# display name PIM gave an object in earlier releases to the name it carries now, and back -- so every FINDER can look for
# both (an object the update renamed must still be found by the setup scripts, and vice versa). Only names PIM itself gave
# are mapped: a name a customer chose is never one of them. Kept: the mailbox ADDRESS, mailNickname, the Exchange scope.
function Test-PimSenderOldDisplayName {
    # PURE. Is -Name a display name PIM gave a SENDER MAILBOX before the owner's 'PIM Manager' (2026-10-18)?
    # 'PIM4EntraPS Engine (notifications)', 'PIM4EntraPS Engine (<part>, notifications)', and the never-approved
    # 'PIM Manager (notifications)' / 'PIM Manager (<part>, notifications)' that 2.4.647-2.4.650 wrote.
    param([AllowEmptyString()][string]$Name)
    return [bool]("$Name".Trim() -match '^(?i)(PIM4EntraPS Engine|PIM Manager) \((.+, )?notifications\)$')
}

function ConvertTo-PimNewDisplayName {
    # PURE. The display name an object PIM named in an earlier release carries now ('' = not one of PIM's old names).
    param([AllowEmptyString()][string]$Name)
    $s = "$Name".Trim()
    # The SENDER MAILBOX (owner 2026-10-18 ~19:20Z): every one is 'PIM Manager' -- no '(notifications)', no install / ring
    # part; the address tells them apart.
    if (Test-PimSenderOldDisplayName $s) { return 'PIM Manager' }
    if ($s -match '^(?i)PIM4EntraPS Engine(?<r>( .*)?)$')  { return "PIM Manager Engine$($Matches['r'])" }
    if ($s -match '^(?i)PIM4EntraPS Deploy(?<r>( .*)?)$')  { return "PIM Manager Deploy$($Matches['r'])" }
    if ($s -match '^(?i)PIM4EntraPS Manager(?<r>( .*)?)$') { return "PIM Manager$($Matches['r'])" }
    return ''
}

function ConvertTo-PimOldDisplayName {
    # PURE. The earlier-release name of a display name PIM gives now ('' = not one of PIM's names).
    param([AllowEmptyString()][string]$Name)
    $s = "$Name".Trim()
    if ($s -match '^(?i)PIM Manager \(notifications\)$') { return 'PIM4EntraPS Engine (notifications)' }
    if ($s -match '^(?i)PIM Manager Engine(?<r>( .*)?)$')  { return "PIM4EntraPS Engine$($Matches['r'])" }
    if ($s -match '^(?i)PIM Manager Deploy(?<r>( .*)?)$')  { return "PIM4EntraPS Deploy$($Matches['r'])" }
    if ($s -match '^(?i)PIM Manager(?<r>( .*)?)$')         { return "PIM4EntraPS Manager$($Matches['r'])" }
    return ''
}

function Get-PimDisplayNameForms {
    # PURE. -Name and its other form (earlier / current release), -Name first: what a finder searches for.
    param([AllowEmptyString()][string]$Name)
    $s = "$Name".Trim()
    $out = New-Object System.Collections.Generic.List[string]
    foreach ($x in @($s, (ConvertTo-PimNewDisplayName $s), (ConvertTo-PimOldDisplayName $s))) {
        if ("$x".Trim() -and -not @($out | Where-Object { $_ -ieq "$x" }).Count) { [void]$out.Add("$x") }
    }
    return @($out.ToArray())
}

function Test-PimDisplayNameIsNewerForm {
    # PURE. Is -Current the CURRENT form of -Wanted (an old name)? A setup script that still asks for the old name must
    # then leave the object alone -- never rename it back.
    param([AllowEmptyString()][string]$Current, [AllowEmptyString()][string]$Wanted)
    $nw = ConvertTo-PimNewDisplayName $Wanted
    return [bool]($nw -and "$Current".Trim() -ieq $nw)
}

function Test-PimRenameDisplayNamesSwitch {
    <#
      The update's switch for CR5 item 5 (OFF by default until the owner switches it on): -Explicit (a stored setting the
      caller read, pim.Settings 'PIM_Update_RenameDisplayNames') wins; else $env:PIM_Update_RenameDisplayNames, else
      $global:PIM_Update_RenameDisplayNames. 1 / true / yes / on = on.
    #>
    param([AllowNull()][object]$Explicit = $null)
    $on = { param($v) return ("$v".Trim() -match '^(?i)(1|true|yes|on)$') }
    if ($null -ne $Explicit -and "$Explicit".Trim() -ne '') { return [bool](& $on $Explicit) }
    if ("$($env:PIM_Update_RenameDisplayNames)".Trim()) { return [bool](& $on $env:PIM_Update_RenameDisplayNames) }
    if ($null -ne $global:PIM_Update_RenameDisplayNames) { return [bool](& $on $global:PIM_Update_RenameDisplayNames) }
    return $false
}

function Test-PimInstallNameValue {
    # PURE. An Azure resource / group name we accept from a record or a variable: 2-90 of letters, digits, '-', '_', '.'.
    param([AllowNull()][string]$Value)
    return [bool]("$Value".Trim() -match '^[A-Za-z0-9][A-Za-z0-9._-]{1,89}$')
}

function Get-PimInstallNameFromEnvironment {
    # The value an existing install carries in its environment for -Role ('' = none). The tick's id (/.../jobs/<name>)
    # names the engine too.
    param([Parameter(Mandatory)][string]$Role)
    $vars = switch ($Role) {
        'web'           { @('PIM_ManagerApp') }
        'engine'        { @('PIM_TickJobName', 'PIM_ENGINE_JOB_NAME') }   # JOB-RENAME switches these (Rename-PimJobs.ps1)
        'updater'       { @('PIM_UpdateJobName') }
        'sqlAdminGroup' { @('PIM_SqlAdminGroupName', 'PIM_SQL_ADMIN_GROUP') }
        default         { @() }
    }
    foreach ($v in $vars) { $x = "$([Environment]::GetEnvironmentVariable($v))".Trim(); if (Test-PimInstallNameValue $x) { return $x } }
    if ($Role -eq 'engine') {
        $id = "$env:PIM_TickJobId".Trim()
        $m = [regex]::Match($id, '(?i)/providers/Microsoft\.App/jobs/([^/]+)$')
        if ($m.Success -and (Test-PimInstallNameValue $m.Groups[1].Value)) { return $m.Groups[1].Value }
    }
    return ''
}

function Get-PimInstallNamesRecord {
    <#
      The stored install record (pim.Settings 'InstallNames'), read ONCE per process and cached; $null when there is none
      or it cannot be read (never throws). $global:PIM_InstallNames, when set, is the record (preloaded / tests).
      -Refresh reads again.
    #>
    param([switch]$Refresh)
    if ($null -ne $global:PIM_InstallNames) { return $global:PIM_InstallNames }
    if (-not $Refresh -and $script:PimInstallNamesRead) { return $script:PimInstallNamesCache }
    $rec = $null
    try {
        $cs = $null
        if ("$($global:PIM_EngineSqlCs)".Trim()) { $cs = "$($global:PIM_EngineSqlCs)" }
        elseif (Get-Command Get-PimSqlSettingsConnectionString -ErrorAction SilentlyContinue) { $cs = Get-PimSqlSettingsConnectionString }
        if ("$cs".Trim() -and (Get-Command Get-PimSqlSetting -ErrorAction SilentlyContinue)) {
            $rec = Get-PimSqlSetting -ConnectionString $cs -Name 'InstallNames'
            if ($rec -is [string]) { try { $rec = $rec | ConvertFrom-Json } catch { $rec = $null } }
        }
    } catch { $rec = $null }
    $script:PimInstallNamesCache = $rec
    $script:PimInstallNamesRead = $true
    return $rec
}

function Get-PimInstallName {
    <#
      THE name of one part of this installation. -Role: web | engine | updater | asbuilt | asbuiltIdentity | sqlAdminGroup |
      publish | downlink | requests | dbinit | dbinitIdentity. Record -> environment -> today's name (see the header). -Record overrides the stored record
      (a caller that already holds it; tests). Never throws for a known role; an unknown role throws (a typo must not
      silently become someone else's resource).
    #>
    param([Parameter(Mandatory)][string]$Role, [AllowNull()][object]$Record = $null, [switch]$NoRecord)
    $defaults = Get-PimInstallNameDefaults
    if (-not $defaults.Contains($Role)) { throw "Get-PimInstallName: unknown role '$Role' (known: $((Get-PimInstallNameRoles) -join ', '))" }
    $rec = if ($NoRecord) { $null } elseif ($null -ne $Record) { $Record } else { Get-PimInstallNamesRecord }
    if ($null -ne $rec) {
        $v = ''
        if ($rec -is [System.Collections.IDictionary]) { if ($rec.Contains($Role)) { $v = "$($rec[$Role])".Trim() } }
        elseif ($rec.PSObject.Properties[$Role]) { $v = "$($rec.$Role)".Trim() }
        if (Test-PimInstallNameValue $v) { return $v }
    }
    $e = Get-PimInstallNameFromEnvironment -Role $Role
    if ($e) { return $e }
    return [string]$defaults[$Role]
}

function New-PimInstallNamesRecord {
    <#
      PURE. The record the updater stores: -Names (role -> name; empty / invalid left out) merged over -Current (what is
      stored). A role the caller does not know keeps its stored value. Returns @{ record; changed }.
    #>
    param([hashtable]$Names = @{}, [AllowNull()][object]$Current = $null, [datetime]$NowUtc = [datetime]::UtcNow)
    $out = [ordered]@{}
    foreach ($r in (Get-PimInstallNameRoles)) {
        $cur = ''
        if ($null -ne $Current) {
            if ($Current -is [System.Collections.IDictionary]) { if ($Current.Contains($r)) { $cur = "$($Current[$r])".Trim() } }
            elseif ($Current.PSObject.Properties[$r]) { $cur = "$($Current.$r)".Trim() }
        }
        $new = if ($Names.ContainsKey($r)) { "$($Names[$r])".Trim() } else { '' }
        if (Test-PimInstallNameValue $new) { $out[$r] = $new } elseif (Test-PimInstallNameValue $cur) { $out[$r] = $cur }
    }
    $changed = $false
    foreach ($r in @($out.Keys)) {
        $cur = ''
        if ($null -ne $Current) {
            if ($Current -is [System.Collections.IDictionary]) { if ($Current.Contains($r)) { $cur = "$($Current[$r])".Trim() } }
            elseif ($Current.PSObject.Properties[$r]) { $cur = "$($Current.$r)".Trim() }
        }
        if ($cur -ne $out[$r]) { $changed = $true }
    }
    $out['recordedUtc'] = $NowUtc.ToUniversalTime().ToString('o')
    return @{ record = $out; changed = $changed }
}

# ===== END inlined helper: ..\..\engine\_shared\PIM-InstallNames.ps1 =====
# ===== BEGIN inlined helper: _PimScriptDoc.ps1 =====
<#
.SYNOPSIS
    Framework 12.7 SCRIPT-DOC-1 + 12.10 item 11 -- the ONE place that knows where a PIM script's documentation page,
    download and checksum list live, the command form every surface shows (line 1 download, line 2+ run -- owner
    2026-10-11), and the run
    frame every script a person runs uses (the first line "<Script> version <x.y.z> - documentation: <page>",
    REQUIREMENTS 100.52, and a local transcript).

.DESCRIPTION
    PURE except Start-PimScriptRun / Stop-PimScriptRun (they print and start / stop a transcript in the temp folder).
    Loaded by every in-scope script (tools\setup + tools\pim-activator), by Build-PimSupportScripts.ps1 (it inlines this
    file into each standalone), by the Manager (Open-PimManager.ps1 hands the constants to the page) and by the engine
    libraries that build fix commands (PIM-PermissionHealth, PIM-MailTransport, PIM-WorkloadPrereqs).
    Change a URL HERE and only here: tests\Test-PimScriptDocs.ps1 fails on any script whose .LINK, page constant or
    manifest docUrl disagrees with it.

    The in-scope list ($script:PimScriptDocScripts) is the set of scripts a person runs that 12.7 covers: each has a
    manifest tools\setup\script-docs\<Script>.doc.json, a .LINK to its page, the Documentation line, -WhatIf, and a
    -WhatIf run case under tests\script-docs\.
#>

# --- the constants (Invardia confirmed 2026-10-09: page = <base><Script>/ with a trailing slash; index = <base>) -------
$script:PimScriptDocBaseUrl     = 'https://invardia.com/docs/pim/scripts/'
$script:PimSupportScriptBaseUrl = 'https://invardia.com/support/pim/'
# ONE-LINE-INSTALL (owner 2026-11-02): the installer launcher is a file of the public release (a release asset)
$script:PimInstallReleaseDownloadBase = 'https://github.com/KnudsenMorten/PIM4EntraPS/releases/latest/download/'
$script:PimSupportScriptSumsUrl = 'https://invardia.com/support/pim/SHA256SUMS.txt'

# --- the version the banner names (REQUIREMENTS 100.52, owner 2026-10-10: "do you provide the version in all scripts, so i
# can troubleshoot better"). Build-PimSupportScripts.ps1 rewrites the NEXT line in a standalone file to the version it was
# built from (the marker comment is what it looks for); in the repository it stays empty and Get-PimScriptVersion reads
# the solution's VERSION file next to this helper (tools\setup\..\..\VERSION).
$script:PimScriptDocVersion = '3.0.70'   # BUILD-VERSION stamped by Build-PimSupportScripts
$script:PimScriptDocHelperDir = "$PSScriptRoot"

# --- every script 12.7 covers: path relative to tools\ ; Standalone = published as one file by Build-PimSupportScripts --
$script:PimScriptDocScripts = @(
    @{ Path = 'setup/Initialize-PimSqlAdminGroup.ps1';             Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorBackend.ps1';      Standalone = $true }
    @{ Path = 'pim-activator/Publish-PimActivatorRemediation.ps1'; Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorClient.ps1';       Standalone = $true }
    @{ Path = 'setup/Grant-PimEnginePermissions.ps1';              Standalone = $true }
    @{ Path = 'setup/Initialize-PimWorkloadPrereqs.ps1';           Standalone = $true }
    @{ Path = 'setup/Initialize-PimMailSender.ps1';                Standalone = $true }
    @{ Path = 'setup/Set-PimSmtpRelayPassword.ps1';                Standalone = $true }
    @{ Path = 'setup/Set-PimSqlTier.ps1';                          Standalone = $true }
    @{ Path = 'setup/New-PimHubPrepareScript.ps1';                 Standalone = $true }
    @{ Path = 'setup/Install-PimManager.ps1';                      Standalone = $false }
    @{ Path = 'setup/Invoke-PimDeployAll.ps1';                     Standalone = $false }
    @{ Path = 'setup/Invoke-PimMspBuild.ps1';                      Standalone = $false }
    @{ Path = 'setup/Copy-PimSettings.ps1';                        Standalone = $false }
    @{ Path = 'setup/Export-PimSettings.ps1';                      Standalone = $false }   # 77.13 / 72.4 settings as code
    @{ Path = 'setup/Import-PimSettings.ps1';                      Standalone = $false }
    @{ Path = 'setup/Set-PimManagerAccess.ps1';                    Standalone = $false }
    @{ Path = 'setup/Set-PimBreakGlassAccounts.ps1';               Standalone = $false }
    @{ Path = 'setup/Set-PimEmergencyPassphrase.ps1';              Standalone = $false }
    @{ Path = 'setup/Find-PimStrayTestObjects.ps1';                Standalone = $false }
    @{ Path = 'setup/Move-PimIdentities.ps1';                      Standalone = $false }   # NAM-03 identity mover
    @{ Path = 'setup/Rename-PimJobs.ps1';                          Standalone = $false }   # JOB-RENAME 3.0.68 job rename (create, prove, switch, disable)
    @{ Path = 'setup/Set-PimLicense.ps1';                          Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorHybrid.ps1';       Standalone = $false }
    @{ Path = 'setup/Update-PimCommunity.ps1';                     Standalone = $false }
    @{ Path = 'setup/Grant-PimSupportAccess.ps1';                  Standalone = $false }
    @{ Path = 'setup/Confirm-PimInstall.ps1';                      Standalone = $false }
    @{ Path = 'setup/Set-PimManagerCustomHost.ps1';                Standalone = $false }
    @{ Path = 'setup/Deploy-PimRfaBroker.ps1';                     Standalone = $false }
    @{ Path = 'setup/Rebuild-PimEnvInternal.ps1';                  Standalone = $false }
    @{ Path = 'setup/Rebuild-PimEnvExternal.ps1';                  Standalone = $false }
    @{ Path = 'setup/Remove-PimContainerStack.ps1';                Standalone = $false }
    @{ Path = 'setup/New-PimHostingPrerequisites.ps1';             Standalone = $false }
    @{ Path = 'setup/Convert-PimToPrivate.ps1';                    Standalone = $false }
    @{ Path = 'setup/Set-PimSqlPublicAccess.ps1';                  Standalone = $false }
    @{ Path = 'setup/Grant-PimSupportSqlAccess.ps1';               Standalone = $true }
    @{ Path = 'setup/Invoke-PimSupportSqlAccessJob.ps1';           Standalone = $true }
    @{ Path = 'setup/Set-PimSigninFrontSqlState.ps1';              Standalone = $true }
    # HYBRID-DEPLOY-STANDALONE: one published file that carries the worker's other scripts (BUILD-CARRY) and runs them from a temp folder
    @{ Path = 'pim-hybrid-worker/Deploy-PimHybridWorker.ps1';      Standalone = $true }
    @{ Path = 'pim-hybrid-worker/New-PimHybridWorkerInfra.ps1';    Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Set-PimHybridWorkerPeering.ps1';  Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Set-PimHybridWorkerEgress.ps1';   Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Grant-PimHybridWorkerAccess.ps1'; Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Invoke-PimHybridWorkerRunCommand.ps1'; Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Remove-PimHybridWorker.ps1';      Standalone = $false }
    # self-contained on the machine they run on (a domain controller; the worker itself): published as one file each
    @{ Path = 'pim-hybrid-worker/Initialize-PimHybridWorkerAd.ps1'; Standalone = $true }
    @{ Path = 'pim-hybrid-worker/Install-PimHybridWorker.ps1';     Standalone = $true }
    # INSTALL-SAMPLES (owner 2026-10-29): the one-file launcher of the installation (downloads the release, runs its installer)
    @{ Path = 'setup/Start-PimManagerInstall.ps1';                 Standalone = $true }
    # V1-IMPORT-PUBLISHED (Invardia per 0.1 B, 2026-11-03): import a PIM version 1 data folder (check + preview by default)
    @{ Path = 'setup/Import-PimV1Data.ps1';                        Standalone = $true }
)

function Get-PimScriptDocName {
    # PURE. 'Grant-PimEnginePermissions.ps1' / '.\x\Grant-PimEnginePermissions' -> 'Grant-PimEnginePermissions'.
    param([Parameter(Mandatory)][string]$Script)
    $leaf = "$Script".Trim() -replace '^.*[\\/]', ''
    return ($leaf -replace '(?i)\.ps1$', '')
}

function Get-PimScriptDocUrl {
    # PURE. The script's documentation page at Invardia: <base><Script>/ (no .ps1, trailing slash).
    param([Parameter(Mandatory)][string]$Script)
    return ($script:PimScriptDocBaseUrl + (Get-PimScriptDocName -Script $Script) + '/')
}

function Get-PimSupportScriptUrl {
    # PURE. The published standalone copy: <support base><Script>.ps1 -- except the installer launcher, which is a file of
    # the public GitHub release itself (ONE-LINE-INSTALL, owner 2026-11-02: line 1 downloads it from the release, never
    # from invardia.com), under a stable name so .../releases/latest/download/<name> always answers.
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ($name -eq 'Start-PimManagerInstall') { return "$script:PimInstallReleaseDownloadBase$name.ps1" }
    return ($script:PimSupportScriptBaseUrl + $name + '.ps1')
}

function Get-PimSupportScriptCommand {
    <#
      PURE. The lines every surface shows for a published script (owner 2026-10-11, framework 12.10 item 11):
        Invoke-WebRequest <url> -OutFile <Script>.ps1        line 1: download the file from Invardia
        <-Run lines>                                          line 2 (and more if a flow needs them): the cmdlet(s)
      Never a checksum / comment line in the shown block, never pipe-to-execute: the documentation page is the link
      shown NEXT to the command; SHA256SUMS.txt stays published for whoever verifies.
      The run line is LAST on purpose: callers that append parameters to the returned text extend the run line.
      -Run: the command line(s) that run the saved file, e.g. ".\Grant-PimEnginePermissions.ps1 -TenantId '...'";
      none = ".\<Script>.ps1". Returns string[] (join with a newline to show / send).
    #>
    param([Parameter(Mandatory)][string]$Script, [string[]]$Run = @())
    $name = Get-PimScriptDocName -Script $Script
    $file = "$name.ps1"
    $lines = New-Object System.Collections.Generic.List[string]
    # Owner 2026-10-11: TWO lines only -- line 1 downloads the file, line 2 runs it (the doc page is linked next to the
    # command on every surface; SHA256SUMS.txt stays published for whoever wants to verify).
    $lines.Add("Invoke-WebRequest $(Get-PimSupportScriptUrl -Script $name) -OutFile $file")
    $runs = @(@($Run) | Where-Object { "$_".Trim() })
    if (-not $runs.Count) { $runs = @(".\$file") }
    foreach ($r in $runs) { $lines.Add("$r") }
    return $lines.ToArray()
}

function Get-PimSupportScriptDocLine {
    # PURE. REQUIREMENTS 100.77 (owner 2026-10-11, "Yes, outside block"): the ONE plain line that goes UNDER a command block
    # in PLAIN TEXT (an install event / install mail, "Send to customer", a console fix, a report), where no link can sit
    # next to the block the way the Manager page shows it: "What does this script do: <the script's doc page>".
    param([Parameter(Mandatory)][string]$Script)
    return ('What does this script do: ' + (Get-PimScriptDocUrl -Script $Script))
}

function Add-PimSupportScriptDocLines {
    <#
      PURE. REQUIREMENTS 100.77. Plain text that carries one or more published-script command blocks (the lines
      Get-PimSupportScriptCommand returns: "Invoke-WebRequest <support base><Script>.ps1 -OutFile <Script>.ps1", then the
      ".\<Script>.ps1 ..." run line(s)) -> the same text with Get-PimSupportScriptDocLine inserted directly UNDER each
      block's last run line, at the block's indentation. The block itself is never changed (it stays exactly its download
      line + run line(s), framework 12.10 item 11): the doc line is a separate line outside it. Idempotent (a block already
      followed by its doc line is left alone); text without a block comes back unchanged; the newline style is kept.
      Use it ONLY where text leaves the page as plain text -- the Manager page shows the link next to the block instead.
    #>
    param([AllowNull()][AllowEmptyString()][string]$Text)
    $t = "$Text"
    if (-not $t) { return $t }
    $nl = if ($t.Contains("`r`n")) { "`r`n" } else { "`n" }
    $lines = @($t -split "\r?\n")
    $base = [regex]::Escape($script:PimSupportScriptBaseUrl)
    $out = New-Object System.Collections.Generic.List[string]
    $i = 0
    while ($i -lt $lines.Count) {
        $l = $lines[$i]; $out.Add($l); $i++
        $m = [regex]::Match($l, "^(?<ind>\s*)Invoke-WebRequest\s+$base(?<n>[A-Za-z0-9-]+)\.ps1\s+-OutFile\s+\k<n>\.ps1\s*$")
        if (-not $m.Success) { continue }
        $n = $m.Groups['n'].Value
        $runRx = '^\s*\.\\' + [regex]::Escape($n) + '\.ps1(\s|$)'
        while ($i -lt $lines.Count -and $lines[$i] -match $runRx) { $out.Add($lines[$i]); $i++ }
        $doc = Get-PimSupportScriptDocLine -Script $n
        if ($i -lt $lines.Count -and $lines[$i].Trim() -eq $doc) { continue }
        $out.Add($m.Groups['ind'].Value + $doc)
    }
    return ($out.ToArray() -join $nl)
}

function Get-PimScriptVersion {
    # The PIM version this script is: the build stamp in a standalone file, else the solution's VERSION file (resolved
    # from this helper's folder), else 'unknown' (a copied helper with nothing around it -- never a failure).
    param([string]$Stamp = "$($script:PimScriptDocVersion)", [string]$HelperDir = "$($script:PimScriptDocHelperDir)")
    if ("$Stamp".Trim()) { return "$Stamp".Trim() }
    if ("$HelperDir".Trim()) {
        try {
            $vf = Join-Path (Split-Path (Split-Path $HelperDir -Parent) -Parent) 'VERSION'
            if (Test-Path -LiteralPath $vf -PathType Leaf) {
                $v = "$([IO.File]::ReadAllText($vf))".Trim()
                if ($v) { return $v }
            }
        } catch { }
    }
    return 'unknown'
}

function Get-PimScriptBannerText {
    # PURE. The banner line: "<Script> version <x.y.z> - documentation: <doc page>".
    param([Parameter(Mandatory)][string]$Script, [Parameter(Mandatory)][string]$Version)
    $name = Get-PimScriptDocName -Script $Script
    return ('{0} version {1} - documentation: {2}' -f $name, $Version, (Get-PimScriptDocUrl -Script $name))
}

function Write-PimScriptBanner {
    <#
      REQUIREMENTS 100.52: the FIRST line every script a person runs prints -- its own name, version and documentation
      page -- so a transcript a customer sends shows exactly what ran. Called by Start-PimScriptRun (every in-scope script
      calls that first thing after loading its helpers), so it is written once, here.
      Write-Host = the host / Information stream: Start-Transcript records it, the pipeline (JSON, -PassThru) never sees
      it, -WhatIf does not change it.
      Printed by the OUTERMOST script only: a script called by another in the same process (the owner flag is set until
      the outer one's Stop-PimScriptRun) or in a child process it started (PIM_SCRIPT_BANNER_PID names a live parent)
      prints nothing. Returns $true when it printed.
    #>
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ("$($global:PimScriptBannerOwner)") { return $false }
    $parentPid = 0
    if ([int]::TryParse("$env:PIM_SCRIPT_BANNER_PID", [ref]$parentPid) -and $parentPid -gt 0 -and $parentPid -ne $PID) {
        if (Get-Process -Id $parentPid -ErrorAction SilentlyContinue) { return $false }
    }
    $global:PimScriptBannerOwner = $name
    $env:PIM_SCRIPT_BANNER_PID = "$PID"
    Write-Host (Get-PimScriptBannerText -Script $name -Version (Get-PimScriptVersion))
    return $true
}

function Start-PimScriptRun {
    <#
      12.7 + 12.10 item 11: call it right after the param block / helper loading, BEFORE anything else prints.
      Starts a transcript in <temp>\pim-manager-logs\<Script>-<utc>.log (nothing else on disk; the temp folder is the
      one place -WhatIf may write) and prints, as the first line, the banner (Write-PimScriptBanner, REQUIREMENTS 100.52:
      "<Script> version <x.y.z> - documentation: <doc page>"; the outermost script only), then "Log: <path>".
      Nested runs (one in-scope script calling another in the same process) keep the outer transcript.
      Returns the log path ('' when the transcript could not start -- the run goes on, with a warning).
      Scripts print no secret values (SECRET-IN-OUTPUT audit), so the transcript holds none either.
    #>
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    $path = ''
    if ("$($global:PimScriptRunLog)") {
        $path = "$($global:PimScriptRunLog)"
    } elseif ("$env:PIM_SCRIPT_NO_TRANSCRIPT" -ne '1') {
        try {
            $dir = Join-Path ([IO.Path]::GetTempPath()) 'pim-manager-logs'
            if (-not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force -WhatIf:$false -Confirm:$false | Out-Null }
            $path = Join-Path $dir ('{0}-{1}.log' -f $name, [DateTime]::UtcNow.ToString('yyyyMMdd-HHmmss'))
            Start-Transcript -LiteralPath $path -Append -WhatIf:$false -Confirm:$false | Out-Null
            $global:PimScriptRunLog = $path
            $global:PimScriptRunOwner = $name
        } catch { $path = '' }
    }
    $null = Write-PimScriptBanner -Script $name   # 100.52: "<Script> version <x.y.z> - documentation: <page>" (outermost only)
    if ($path) { Write-Host "Log: $path" } elseif ("$env:PIM_SCRIPT_NO_TRANSCRIPT" -ne '1') { Write-Warning 'No transcript could be started for this run.' }
    return $path
}

function Stop-PimScriptRun {
    # Call it in the script's finally block: prints "Log written: <path>" and stops the transcript this script started.
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ("$($global:PimScriptBannerOwner)" -eq $name) {
        # 100.52: the outermost script is done -- the next script run in this session prints its banner again
        $global:PimScriptBannerOwner = $null
        if ("$env:PIM_SCRIPT_BANNER_PID" -eq "$PID") { $env:PIM_SCRIPT_BANNER_PID = $null }
    }
    if (-not "$($global:PimScriptRunLog)" -or "$($global:PimScriptRunOwner)" -ne $name) { return }
    $path = "$($global:PimScriptRunLog)"
    Write-Host "Log written: $path"
    try { Stop-Transcript | Out-Null } catch { }
    $global:PimScriptRunLog = $null
    $global:PimScriptRunOwner = $null
}

# ===== END inlined helper: _PimScriptDoc.ps1 =====
$null = Start-PimScriptRun -Script 'Initialize-PimSqlAdminGroup'
try {
# -WhatIf: read everything, print each change as a "What if:" line, change nothing (the -PlanOnly path of the helper).
if ($WhatIfPreference) { $PlanOnly = [switch]$true }

$server = ("$SqlServerName".Trim() -split '\.')[0]
Write-Host "`n=== SQL admin group: $GroupName -> $server ===" -ForegroundColor Cyan
Write-Host "    subscription $SubscriptionId / $ResourceGroup$(if ($PlanOnly) { '   (PLAN ONLY -- nothing is changed)' })" -ForegroundColor DarkGray

# Framework 12.17 -- ONE sign-in rule. Without a certificate: the Invardia Support session open in this window
# (Use-PimSupportAppRestSession), otherwise the person's own browser sign-in (Set-PimSignedInGlobals registers it in PIM-Rest;
# auth code + PKCE, never device code). Every token is pinned to -TenantId and checked.
$authLabel = "certificate ($ClientId)"
if (-not "$CertThumbprint".Trim()) {
    if ("$TenantId".Trim() -notmatch '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') { throw 'Initialize-PimSqlAdminGroup: pass -TenantId <tenant id> -- the sign-in is pinned to that tenant.' }
    $supportApp = Use-PimSupportAppRestSession -TenantId $TenantId -SubscriptionId $SubscriptionId
    if ($supportApp) { $authLabel = "the Invardia Support app $supportApp (support session)" }
    else { Set-PimSignedInGlobals -TenantId $TenantId; $authLabel = 'your browser sign-in' }
}
$inv = New-PimSqlAdminGroupInvokers -SubscriptionId $SubscriptionId -TenantId $TenantId -ClientId $ClientId -CertThumbprint $CertThumbprint
Write-Host "    auth: $authLabel in tenant $($inv.TenantId)" -ForegroundColor DarkGray

if ($ReleaseOwnMembership) {
    # OPEN-01 item 4: the run's OWN application leaves the group -- the identity it signs in as, never a name it is given
    $ownApp = if ("$CertThumbprint".Trim()) { "$ClientId".Trim() } elseif ("$supportApp".Trim()) { "$supportApp".Trim() } else { '' }
    if (-not $ownApp) { throw 'Initialize-PimSqlAdminGroup: -ReleaseOwnMembership releases the application this run signs in as (-ClientId with -CertThumbprint, or the Invardia Support session); a person''s membership is released by the installer. Nothing was changed.' }
    $ownOid = Resolve-PimServicePrincipalObjectId -Graph $inv.Graph -AppId $ownApp
    $sqlRg = if ("$SqlResourceGroup".Trim()) { "$SqlResourceGroup".Trim() } else { $ResourceGroup }
    if ($PlanOnly) {
        Write-Host "What if: take this run's own application (app $ownApp, object $ownOid) out of '$GroupName' and read it back; no other member is touched"
        Write-Host '==> OK -- plan only, nothing changed' -ForegroundColor Green
        exit 0
    }
    $rel = Invoke-PimSqlAdminGroupSetupRelease -Graph $inv.Graph -Arm $inv.Arm -SubscriptionId $SubscriptionId -SqlResourceGroup $sqlRg -SqlServerName $server `
               -MemberObjectId $ownOid -OwnObjectId $ownOid -GroupName $GroupName -Label "this run's own application (app $ownApp)"
    if ($rel.ok) { Write-Host "==> OK -- $($rel.reason)" -ForegroundColor Green; exit 0 }
    Write-Host "==> NOT RELEASED -- $($rel.reason)" -ForegroundColor Red
    exit 1
}

$r = Invoke-PimSqlAdminGroupStep -Graph $inv.Graph -Arm $inv.Arm -TenantId $inv.TenantId -SubscriptionId $SubscriptionId `
        -ResourceGroup $ResourceGroup -SqlResourceGroup $SqlResourceGroup -SqlServerName $server -GroupName $GroupName -GroupObjectId $GroupObjectId `
        -EnvironmentIdentityName $EnvironmentIdentityName -SqlAdminIdentityName $SqlAdminIdentityName -UpdateJobName $UpdateJobName `
        -SupportAppId $SupportAppId -SupportObjectId $SupportObjectId -SetupIdentityAppId $SetupIdentityAppId -ExtraMemberObjectIds $ExtraMemberObjectIds `
        -Mode $(if ($MembersOnly) { 'membersOnly' } else { 'converge' }) -DoNotKeepCurrentAdmin:$DoNotKeepCurrentAdmin -PlanOnly:$PlanOnly
Write-PimSqlAdminGroupReport -Result $r

if ($WhatIfPreference -and $r.plan) {
    # The changes the run WOULD make, as PowerShell's own "What if:" lines (ShouldProcess answers $false under -WhatIf).
    $p = $r.plan
    $sqlTarget = "SQL server $server (subscription $SubscriptionId, resource group $(if ("$SqlResourceGroup".Trim()) { $SqlResourceGroup } else { $ResourceGroup }))"
    if ($p.createGroup) { [void]$PSCmdlet.ShouldProcess("Microsoft Graph: security group '$GroupName' (tenant $($inv.TenantId))", 'create ROLE-ASSIGNABLE security group (isAssignableToRole = true)') }
    foreach ($a in @($p.add)) { [void]$PSCmdlet.ShouldProcess("group '$GroupName'", "add member $($a.label) ($($a.objectId))") }
    if ($p.setAdmin) { [void]$PSCmdlet.ShouldProcess($sqlTarget, "make '$GroupName' the Microsoft Entra admin (was $(if ($r.adminBefore) { "'$($r.adminBefore)'" } else { 'none' }))") }
    if (-not $p.changes) { Write-Host "What if: no change -- '$GroupName' is already the Entra admin of $server and holds every member." }
}

if ($r.ok) {
    $what = if ($PlanOnly) { "plan: $(@($r.plan.messages).Count) line(s), nothing changed" }
            elseif ($r.blocked) { "nothing changed: $($r.blocked)" }
            else { "'$GroupName' is the Entra admin of $server with every member (read back)" }
    Write-Host "==> OK -- $what" -ForegroundColor Green
    exit 0
}
Write-Host "==> NOT CONVERGED -- see [FAIL] above." -ForegroundColor Red
exit 1
} finally { Stop-PimScriptRun -Script 'Initialize-PimSqlAdminGroup' }