#Requires -Version 7.0
# PIM Manager 3.0.70 -- Set-PimSqlTier.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: _pimmailsetup.ps1, _pimloopbackanswer.ps1, _pimscriptdoc.ps1, ..\..\engine\_shared\pim-tenantsizing.ps1)


<#
.SYNOPSIS
  Set the PIM Manager SQL database to the right Standard tier with a 250 GB maximum size, and optionally pin its tier.
  -WhatIf shows the change first.

.DESCRIPTION
  Set the PIM Manager SQL database to the right Standard tier with a 250 GB maximum size, and optionally pin its tier so
  updates never change it.

  Owner 2026-10-12 ("S3 at every ring 1+2 install"; PIM REQUIREMENTS 100.37 / 100.114, framework 12.15): PIM's database
  is never Basic -- the product tier is S3 (Standard), for every edition -- and every Standard database has a 250 GB
  maximum size (268435456000 bytes). Raising a tier does NOT raise the maximum size, so a database moved up from Basic kept
  Basic's 2 GB limit and stopped accepting writes ("has reached its size quota"). The installer and every update apply the
  same plan (Get-PimSqlTierPlan, engine/_shared/PIM-TenantSizing.ps1, embedded in the published file); this script applies
  it on demand:

    * without -Tier: THE PLAN -- Basic, S0, S1 or S2 -> S3 (never on a database tagged pim-sql-tier-pin: a pinned
      database below S3 is reported "database is pinned at <tier>, the new default is S3 - not changed"), any Standard
      database below 250 GB -> 250 GB. The plan NEVER LOWERS a tier or a limit (S3 and above are kept); Premium, vCore and
      elastic-pool databases are not touched.
    * -Tier S0|S1|S2|S3|...: the Standard tier you choose (never Basic), with the 250 GB maximum size. A tier below S3
      is your own decision -- add -Pin, or the next update raises it back to S3. Changing the tier of a pinned database
      needs -Pin (which re-pins it to the new tier).
    * -Pin: tags the database pim-sql-tier-pin = <its tier>, so the updater never changes its tier (the 250 GB rule still
      applies). The database's other tags are kept.

  ONE PATCH of the database (sku {name; tier 'Standard'} and/or properties.maxSizeBytes and/or tags; ARM api-version
  2021-11-01), then it reads the database back until the tier and the maximum size are confirmed and it is Online; a 404
  or 5xx answer right after the PATCH is transient (the scale is running) and is waited out. Prints before and after.
  The tier is read from properties.currentServiceObjectiveName -- never from sku.name, which for a Standard database is
  the tier name "Standard", not "S0".

  Sign-in, no PowerShell module: with -TenantId in the BROWSER as you (or the Invardia Support app with -AdminAppId +
  -AdminSecret); without -TenantId the Invardia Support-app session's REST shim (a function -- the Az PowerShell
  cmdlet of the same name is never used). Published standalone at https://invardia.com/support/pim/Set-PimSqlTier.ps1.

.EXAMPLE
  .\Set-PimSqlTier.ps1 -SubscriptionId <subscription id> -ResourceGroup <resource group> -Server <sql server> -TenantId <tenant id> -WhatIf
  Preview the plan; then the same command without -WhatIf.

.EXAMPLE
  .\Set-PimSqlTier.ps1 -SubscriptionId <subscription id> -ResourceGroup <resource group> -Server <sql server> -TenantId <tenant id> -Tier S3 -Pin
  S3 with 250 GB, pinned so updates keep it on S3 (also how a database pinned at a lower tier is moved to S3).

.NOTES
  Requirements:
    PowerShell: 7.0 or later (pwsh). Windows PowerShell 5.1 is not supported.
    Role: SQL DB Contributor (or Contributor / Owner) on the PIM SQL server or its resource group (Azure).
    Hosts: login.microsoftonline.com, management.azure.com

    PERMISSIONS AND CHANGES (from Set-PimSqlTier.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Set-PimSqlTier/)
    The person running it needs:
      - SQL DB Contributor [azureRbac, the PIM SQL server (or its resource group); Contributor or Owner work too] -- Reads the database and changes its tier, its maximum size and its tags.
      - browser sign-in to Azure (first-party public client 'Microsoft Azure PowerShell'), the Invardia Support-app session's REST shim (never the Az PowerShell cmdlet), or the Invardia Support app (-AdminAppId + -AdminSecret) [other, Azure Resource Manager in your tenant] -- No PowerShell module and no certificate. The Support app's secret is accepted only for Invardia support; a person signs in in the browser.
    What it creates, changes or grants:
      - update the SQL database -Database (default PimPlatform) on -Server: its tier (sku: Basic, S0, S1 or S2 -> S3, or the Standard tier -Tier; never Basic, never lowered by the plan, a pinned database is not changed without -Tier and -Pin) (Azure Resource Manager) @ the database only -- PIM's database is S3 (Standard) by default, so the PIM Manager stays fast on a large tenant; Basic is too small for PIM's store. Undo: Azure portal > the database > Compute + storage: set the previous tier back (a lower tier must fit the data).
      - update the SQL database's maximum size (properties.maxSizeBytes) to 250 GB when it is lower; never lowered (Azure Resource Manager) @ the database only -- Raising a tier does not raise the maximum size: a database moved up from Basic keeps a 2 GB limit and stops accepting writes when full. 250 GB is included in the Standard price. Undo: Azure portal > the database > Compute + storage > Data max size: set the previous size back (it must still hold the data).
      - update the SQL database's tag pim-sql-tier-pin = <tier> -- only with -Pin; the database's other tags are kept (Azure Resource Manager) @ the database only -- PIM's updater then never changes the database's tier (it still keeps the 250 GB maximum size). Undo: Azure portal > the database > Tags: delete the pim-sql-tier-pin tag.
    -WhatIf: Signs in, reads the database, prints its tier, maximum size and pin, and one "What if:" line with the change it would make (tier, maximum size, pin tag). Nothing is changed.
    Undo: Set the previous tier and maximum size back in the Azure portal (the database > Compute + storage), and delete the pim-sql-tier-pin tag if the script added it.

.LINK
    https://invardia.com/docs/pim/scripts/Set-PimSqlTier/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)][string]$SubscriptionId,
    [Parameter(Mandatory)][string]$ResourceGroup,
    # the SQL server name or its FQDN (sql-x or sql-x.database.windows.net)
    [Parameter(Mandatory)][string]$Server,
    [string]$Database = 'PimPlatform',
    # a Standard objective (S0, S1, S2, S3, S4, S6, S7, S9, S12); never Basic
    [ValidatePattern('^(?i)S(0|1|2|3|4|6|7|9|12)$')][string]$Tier,
    [switch]$Pin,
    [string]$TenantId,
    [string]$AdminAppId,
    [string]$AdminSecret,
    [ValidateRange(1, 120)][int]$ReadBackMinutes = 20,
    [ValidateRange(0, 300)][int]$PollSeconds = 20
)
$ErrorActionPreference = 'Stop'
# ===== BEGIN inlined helper: _PimMailSetup.ps1 =====
# _PimMailSetup.ps1 -- the pieces behind Initialize-PimMailSender.ps1 and Set-PimSmtpRelayPassword.ps1: which way the
# script signs in, the BROWSER sign-in itself, and a per-API token cache. Dot-source it; it defines functions only (no
# side effects on load).
#
# MAIL-1 (framework DOCS/REQUIREMENTS.md 12.3, owner 2026-10-08): "we dont use certificates here, either interactive login
# or secret. not certificates". So the published scripts sign in in the BROWSER (an Exchange or Global Administrator) or
# with the Invardia Support app's secret; a certificate stays accepted for old callers and is never what a page prints.
#
# NO MODULES (owner 2026-10-07: "neither pim, si or invardia must have dependencies"): plain Invoke-RestMethod + .NET.
# Sign-in is auth code + PKCE on a localhost loopback, Microsoft Edge launched explicitly (the default browser when Edge
# is missing) -- the pattern of _PimEnginePermissions.ps1 (Get-PimEpInteractiveToken), DUPLICATED here on purpose: each
# published script is ONE standalone file (tools/setup/Build-PimSupportScripts.ps1 inlines this), and isolation beats
# DRY between two scripts that ship separately. Never device code.
#
# The public clients (first-party, present in every tenant, no app registration needed):
#   * Exchange Online admin API -- "Microsoft Exchange REST API Based Powershell", the client the ExchangeOnlineManagement
#     V3 module itself signs in with; the token is for https://outlook.office365.com and drives the same
#     /adminapi/beta/<tenant>/InvokeCommand endpoint the module calls.
#   * Microsoft Graph -- "Microsoft Graph Command Line Tools" (as Grant-PimEnginePermissions.ps1).
#   * Azure Resource Manager, Azure SQL, Key Vault -- "Microsoft Azure PowerShell"; one sign-in, the other two from its
#     refresh token (the client is pre-authorised for all three).

# ---- constants --------------------------------------------------------------------------------------------------------
function Get-PimMsExchangeClientId { 'fb78d390-0c51-40cd-8e17-fdbfab77341b' }        # Microsoft Exchange REST API Based Powershell
function Get-PimMsGraphCliClientId { '14d82eec-204b-4c2f-b7e8-296a70dab67e' }        # Microsoft Graph Command Line Tools
function Get-PimMsAzurePowerShellClientId { '1950a258-227b-4e31-a9cf-717495945fc2' } # Microsoft Azure PowerShell
# The delegated Graph rights the shared-mailbox setup reads / changes with: the Exchange plan (subscribedSkus) and the
# initial domain (organization), the service principals (managed identities, Graph), the mailbox's directory user, and
# the removal of a tenant-wide Mail.Send consent (the scope rule of MAIL-1).
function Get-PimMsGraphScopes { @('Organization.Read.All', 'Application.Read.All', 'AppRoleAssignment.ReadWrite.All', 'User.Read.All') }

# ---- which way to sign in (PURE) ----------------------------------------------------------------------------------------
function Resolve-PimMailSetupAuthMode {
    <#
      Decide how the setup script authenticates, BEFORE anything is touched. Returns @{ mode; reason } where mode is
      'browser' | 'secret' | 'certificate' | 'signedIn' and a non-empty reason is a refusal:
        * nothing passed                       -> 'browser' (the person signs in; -AdminAppId is not needed)
        * -AdminSecret (+ -AdminAppId)         -> 'secret'  (the Invardia Support app)
        * -AdminCertThumbprint (+ -AdminAppId) -> 'certificate' (back-compat; never printed)
        * -UseSignedInAccount                  -> 'signedIn' (the Invardia Support session, else the browser)
      Refused: both a secret and a certificate; -UseSignedInAccount with a credential; a credential without -AdminAppId;
      -AdminAppId without a credential (ambiguous: was a secret forgotten?).
    #>
    param([string]$AdminAppId, [string]$AdminSecret, [string]$AdminCertThumbprint, [switch]$UseSignedInAccount)
    $app = "$AdminAppId".Trim(); $sec = "$AdminSecret".Trim(); $cert = "$AdminCertThumbprint".Trim()
    if ($sec -and $cert) { return @{ mode = ''; reason = 'pass EITHER -AdminSecret OR -AdminCertThumbprint, not both.' } }
    if ($UseSignedInAccount) {
        if ($sec -or $cert) { return @{ mode = ''; reason = '-UseSignedInAccount takes no -AdminSecret / -AdminCertThumbprint.' } }
        return @{ mode = 'signedIn'; reason = '' }
    }
    if ($sec -or $cert) {
        if (-not $app) { return @{ mode = ''; reason = '-AdminAppId is required with -AdminSecret / -AdminCertThumbprint (the app the credential belongs to).' } }
        return @{ mode = $(if ($sec) { 'secret' } else { 'certificate' }); reason = '' }
    }
    if ($app) { return @{ mode = ''; reason = "-AdminAppId $app was passed without its credential: add -AdminSecret (the Invardia Support app's secret), or leave -AdminAppId out to sign in in the browser." } }
    return @{ mode = 'browser'; reason = '' }
}

function Test-PimMsInteractiveHost {
    # A browser sign-in needs a person at this console. An unattended run (a deploy step, a scheduled task, a redirected
    # stdin) must be REFUSED instead -- it would otherwise open a browser nobody sees and wait five minutes.
    try { if (-not [Environment]::UserInteractive) { return $false } } catch { }
    try { if ([Console]::IsInputRedirected) { return $false } } catch { }
    return $true
}

function Get-PimMsExoAnchor {
    # X-AnchorMailbox for the Exchange admin API: the signed-in person's own UPN with a delegated token, the system
    # mailbox of the initial domain with an app-only one (what the EXO V3 module sends in each case).
    param([string]$Mode, [string]$Upn, [string]$InitialDomain)
    if ($Mode -eq 'browser' -and "$Upn".Trim()) { return "UPN:$("$Upn".Trim())" }
    return "UPN:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@$("$InitialDomain".Trim())"
}

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

# The claims of a JWT (claims read only, the resource validates the token; tid / upn / exp are read). $null when not a readable JWT.
function ConvertFrom-PimMsJwtClaims {
    param([AllowEmptyString()][string]$Token)
    if (-not $Token) { return $null }
    $parts = $Token -split '\.'
    if ($parts.Count -lt 2) { return $null }
    $s = $parts[1].Replace('-', '+').Replace('_', '/')
    switch ($s.Length % 4) { 2 { $s += '==' } 3 { $s += '=' } }
    try { [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($s)) | ConvertFrom-Json } catch { $null }
}

function New-PimMsPkcePair {
    $bytes = New-Object byte[] 32
    [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
    $verifier = ConvertTo-PimMsB64Url $bytes
    $challenge = ConvertTo-PimMsB64Url ([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::ASCII.GetBytes($verifier)))
    [pscustomobject]@{ Verifier = $verifier; Challenge = $challenge }
}

# The delegated scope string: bare Graph names are qualified, OIDC basics appended once.
function Get-PimMsScopeString {
    param([Parameter(Mandatory)][string[]]$Scopes)
    $q = @($Scopes | Where-Object { $_ } | ForEach-Object { if ($_ -match '^(https?://|openid$|profile$|offline_access$)') { $_ } else { "https://graph.microsoft.com/$_" } })
    (@($q) + @('openid', 'profile', 'offline_access') | Select-Object -Unique) -join ' '
}

function New-PimMsAuthorizeUrl {
    param(
        [Parameter(Mandatory)][string]$Tenant, [Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][string]$RedirectUri,
        [Parameter(Mandatory)][string]$Scope, [Parameter(Mandatory)][string]$State, [Parameter(Mandatory)][string]$CodeChallenge,
        [string]$LoginHint
    )
    $u = "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/authorize" +
        "?client_id=$ClientId&response_type=code&response_mode=query" +
        "&redirect_uri=$([uri]::EscapeDataString($RedirectUri))" +
        "&scope=$([uri]::EscapeDataString($Scope))&state=$State" +
        "&code_challenge=$CodeChallenge&code_challenge_method=S256"
    if ($LoginHint) { $u += "&login_hint=$([uri]::EscapeDataString($LoginHint))" } else { $u += '&prompt=select_account' }
    $u
}

function Get-PimMsEdgePath {
    @(
        $(if (${env:ProgramFiles(x86)}) { Join-Path ${env:ProgramFiles(x86)} 'Microsoft\Edge\Application\msedge.exe' }),
        $(if ($env:ProgramFiles) { Join-Path $env:ProgramFiles 'Microsoft\Edge\Application\msedge.exe' }),
        $(if ($env:LOCALAPPDATA) { Join-Path $env:LOCALAPPDATA 'Microsoft\Edge\Application\msedge.exe' })
    ) | Where-Object { $_ -and (Test-Path -LiteralPath $_) } | Select-Object -First 1
}

function Get-PimMsSignInFailureHint {
    # PURE: one sentence for a sign-in error the person can act on ('' when there is nothing specific to say).
    param([string]$ErrorText)
    $e = "$ErrorText"
    if ($e -match 'AADSTS50011|redirect') { return 'This tenant refuses the local sign-in answer address for this Microsoft client. Run the script with the Invardia Support app instead: -AdminAppId <support app id> -AdminSecret <its secret>.' }
    if ($e -match 'AADSTS65001|consent') { return 'The sign-in needs an administrator''s consent: sign in as a Global Administrator once, or run with the Invardia Support app (-AdminAppId + -AdminSecret).' }
    if ($e -match 'AADSTS50105|AADSTS50020|not assigned|does not exist in tenant') { return 'Sign in with an account of THIS tenant (an Exchange Administrator or Global Administrator).' }
    return ''
}

# Interactive sign-in: auth code + PKCE on a loopback TcpListener (works without elevation), Edge launched explicitly,
# the default browser when Edge is missing. Returns the token response (access_token, refresh_token, expires_in).
function Get-PimMsInteractiveToken {
    param(
        [Parameter(Mandatory)][string]$ClientId,
        [Parameter(Mandatory)][string[]]$Scopes,
        [string]$Tenant = 'organizations',
        [bool]$UseEdge = $true,
        [string]$LoginHint,
        [string]$What = 'sign-in'
    )
    $pkce  = New-PimMsPkcePair
    $state = [guid]::NewGuid().ToString('N')
    $scope = Get-PimMsScopeString -Scopes $Scopes
    $tcp = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0)
    $tcp.Start(); $tcps = @($tcp); try { if ([System.Net.Sockets.Socket]::OSSupportsIPv6) { $tcp6 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::IPv6Loopback, ([System.Net.IPEndPoint]$tcp.LocalEndpoint).Port); $tcp6.Start(); $tcps += $tcp6 } } catch { }   # a customer 2026-10-21: "localhost" may be [::1] -- BOTH loopbacks, same port
    $redirect = "http://localhost:$(([System.Net.IPEndPoint]$tcp.LocalEndpoint).Port)/"
    $authUrl  = New-PimMsAuthorizeUrl -Tenant $Tenant -ClientId $ClientId -RedirectUri $redirect -Scope $scope -State $state -CodeChallenge $pkce.Challenge -LoginHint $LoginHint
    $query = $null
    try {
        $edge = if ($UseEdge) { Get-PimMsEdgePath } else { $null }
        Write-Host "Signing in for $What -- the browser answers to $redirect ..." -ForegroundColor Yellow
        if ($edge) { Start-Process -FilePath $edge -ArgumentList @('--new-window', $authUrl) -WhatIf:$false }
        else {
            if ($UseEdge) { Write-Host 'Microsoft Edge not found -- using the default browser.' -ForegroundColor DarkYellow }
            Start-Process $authUrl -WhatIf:$false
        }
        Write-Host "If no browser opened, open this address yourself:`n  $authUrl" -ForegroundColor DarkGray
        # SIGNIN-PAGE (owner 2026-10-31): only the answer (code / error) ends the wait; every request gets a page; the page
        # keeps answering 10 s after it (PIM-LoopbackAnswer.ps1; tools/setup/_PimLoopbackAnswer.ps1 is its identical copy for the tools).
        if (-not (Get-Command Wait-PimLoopbackAnswer -ErrorAction SilentlyContinue)) {
# ===== BEGIN inlined helper: _PimLoopbackAnswer.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: _PimLoopbackAnswer.ps1 =====
        }
        $query = Wait-PimLoopbackAnswer -Listeners $tcps -Seconds 300 -TimeoutMessage 'Timed out (5 minutes) waiting for the browser to finish the sign-in.'
    } finally { foreach ($tcpL in $tcps) { try { $tcpL.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']) {
        $hint = Get-PimMsSignInFailureHint -ErrorText "$($kv['error']) $($kv['error_description'])"
        throw "Sign-in failed: $($kv['error']) -- $($kv['error_description'])$(if ($hint) { " $hint" })"
    }
    if ($kv['state'] -ne $state) { throw 'The browser answer did not come from this sign-in attempt. Close ALL browser windows and run the script again.' }
    if (-not $kv['code'])        { throw 'The browser answer carried no authorization code.' }
    Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id     = $ClientId
        grant_type    = 'authorization_code'
        code          = $kv['code']
        redirect_uri  = $redirect
        code_verifier = $pkce.Verifier
        scope         = $scope
    }
}

# A token for another resource (or a fresh one) from a refresh token of the same public client -- no second browser tab.
function Get-PimMsRefreshedToken {
    param([Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][string]$RefreshToken, [Parameter(Mandatory)][string[]]$Scopes, [string]$Tenant = 'organizations')
    Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id = $ClientId; grant_type = 'refresh_token'; refresh_token = $RefreshToken; scope = (Get-PimMsScopeString -Scopes $Scopes)
    }
}

# ---- the per-API token cache -------------------------------------------------------------------------------------------
function Get-PimMsBrowserApi {
    <#
      PURE: which public client + scopes serve a resource, and which sign-in it shares.
      Returns @{ api; clientId; scopes; family } -- family is the refresh-token group: 'azure' covers ARM, SQL and Key
      Vault (one sign-in), 'graph' and 'exchange' have their own.
    #>
    param([Parameter(Mandatory)][string]$Resource)
    $r = "$Resource".Trim().TrimEnd('/').ToLowerInvariant()
    switch -regex ($r) {
        '^(graph|https://graph\.microsoft\.com)$'          { return @{ api = 'graph'; clientId = (Get-PimMsGraphCliClientId); scopes = @(Get-PimMsGraphScopes); family = 'graph' } }
        '^(exchange|https://outlook\.office365\.com)$'     { return @{ api = 'exchange'; clientId = (Get-PimMsExchangeClientId); scopes = @('https://outlook.office365.com/.default'); family = 'exchange' } }
        '^(arm|https://management\.azure\.com)$'           { return @{ api = 'arm'; clientId = (Get-PimMsAzurePowerShellClientId); scopes = @('https://management.azure.com/.default'); family = 'azure' } }
        '^(sql|https://database\.windows\.net)$'           { return @{ api = 'sql'; clientId = (Get-PimMsAzurePowerShellClientId); scopes = @('https://database.windows.net/.default'); family = 'azure' } }
        '^(keyvault|https://vault\.azure\.net)$'           { return @{ api = 'keyvault'; clientId = (Get-PimMsAzurePowerShellClientId); scopes = @('https://vault.azure.net/.default'); family = 'azure' } }
    }
    throw "no browser sign-in is defined for '$Resource'"
}

function Get-PimMsBrowserToken {
    <#
      An access token for -Resource as the person who signed in, cached per API for the run. The first call of a family
      opens the browser (the next ones carry the first sign-in's account as the login hint, so the browser does not ask
      again); a family's other APIs and an expiring token are served from its refresh token.
      Test seam: $script:PimMsAcquire = { param($ClientId, $Scopes, $Tenant, $LoginHint, $RefreshToken) <token response> }.
    #>
    param([Parameter(Mandatory)][string]$Resource, [Parameter(Mandatory)][string]$TenantId)
    if (-not $script:PimMsTokens) { $script:PimMsTokens = @{} }
    if (-not $script:PimMsRefresh) { $script:PimMsRefresh = @{} }
    $spec = Get-PimMsBrowserApi -Resource $Resource
    $now = (Get-Date).ToUniversalTime()
    $hit = $script:PimMsTokens[$spec.api]
    if ($hit -and $hit.expires -gt $now.AddMinutes(5)) { return $hit.token }
    $acquire = $script:PimMsAcquire
    $rt = $script:PimMsRefresh[$spec.family]
    $resp = $null
    if ($rt) {
        try {
            $resp = if ($acquire) { & $acquire $spec.clientId $spec.scopes $TenantId $script:PimMsLoginHint $rt }
                    else { Get-PimMsRefreshedToken -ClientId $spec.clientId -RefreshToken $rt -Scopes $spec.scopes -Tenant $TenantId }
        } catch { $resp = $null }
    }
    if (-not $resp) {
        if (-not $acquire -and -not (Test-PimMsInteractiveHost)) { throw 'a browser sign-in needs a person at this console, and this session is not interactive -- run the command in a PowerShell window, or pass -AdminAppId + -AdminSecret (the Invardia Support app).' }
        $what = switch ($spec.family) { 'graph' { 'Microsoft Graph' } 'exchange' { 'Exchange Online' } default { 'Azure' } }
        $resp = if ($acquire) { & $acquire $spec.clientId $spec.scopes $TenantId $script:PimMsLoginHint $null }
                else { Get-PimMsInteractiveToken -ClientId $spec.clientId -Scopes $spec.scopes -Tenant $TenantId -LoginHint $script:PimMsLoginHint -What $what }
    }
    $tok = "$($resp.access_token)"
    if (-not $tok) { throw "the sign-in returned no access token for $($spec.api)" }
    $claims = ConvertFrom-PimMsJwtClaims -Token $tok
    if ($claims -and "$($claims.tid)".Trim() -and "$($claims.tid)".Trim() -ine "$TenantId".Trim()) {
        throw "you signed in to tenant $($claims.tid), not $TenantId -- sign in with an account of the tenant this environment runs in."
    }
    if ($claims -and -not $script:PimMsLoginHint) {
        $u = "$(if ($claims.upn) { $claims.upn } elseif ($claims.preferred_username) { $claims.preferred_username } else { $claims.unique_name })".Trim()
        if ($u) { $script:PimMsLoginHint = $u }
    }
    if ("$($resp.refresh_token)".Trim()) { $script:PimMsRefresh[$spec.family] = "$($resp.refresh_token)" }
    $secs = 3000; try { if ([int]$resp.expires_in -gt 0) { $secs = [int]$resp.expires_in } } catch { }
    $script:PimMsTokens[$spec.api] = @{ token = $tok; expires = $now.AddSeconds($secs) }
    return $tok
}

function Get-PimMsSignedInUpn {
    # The person who signed in (the first token's upn), '' before any sign-in.
    "$($script:PimMsLoginHint)".Trim()
}

function Get-PimMsAppToken {
    # An app-only token for -Resource as the Invardia Support app (client credentials, its secret). No module.
    param([Parameter(Mandatory)][string]$TenantId, [Parameter(Mandatory)][string]$ClientId, [Parameter(Mandatory)][string]$ClientSecret, [Parameter(Mandatory)][string]$Resource)
    $spec = Get-PimMsBrowserApi -Resource $Resource
    $scope = (@($spec.scopes) | Where-Object { $_ -match '^https://' } | Select-Object -First 1)
    if (-not $scope) { $scope = 'https://graph.microsoft.com/.default' }
    $scope = ($scope -replace '/[^/]+$', '/.default')
    (Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id = $ClientId; client_secret = $ClientSecret; grant_type = 'client_credentials'; scope = $scope }).access_token
}

# ---- the SMTP relay password in Key Vault (PURE pieces; Set-PimSmtpRelayPassword.ps1 does the calls) -------------------
function Get-PimKvRoleId {
    # Built-in Azure roles by name (the ids are the same in every tenant).
    param([Parameter(Mandatory)][ValidateSet('SecretsUser', 'SecretsOfficer')][string]$Role)
    switch ($Role) { 'SecretsUser' { '4633458b-17de-408a-b874-0445c86b69e6' } 'SecretsOfficer' { 'b86a8fe4-44ce-4948-aee5-eccb2c155cd7' } }
}

function Select-PimKvVault {
    # PURE: the ONE vault called -Name in a subscription's vault list (ARM value[]), or @{ vault = $null; reason }.
    param([object[]]$Vaults = @(), [Parameter(Mandatory)][string]$Name)
    $hits = @(@($Vaults) | Where-Object { $_ -and "$($_.name)" -ieq "$Name".Trim() })
    if ($hits.Count -eq 1) { return @{ vault = $hits[0]; reason = '' } }
    if ($hits.Count -gt 1) { return @{ vault = $null; reason = "more than one Key Vault is called $Name -- refusing to pick one" } }
    return @{ vault = $null; reason = "no Key Vault called $Name in this subscription" }
}

function Get-PimKvSecretScope {
    # PURE: the Azure RBAC scope of ONE secret -- the read right is granted on the secret, never on the whole vault.
    param([Parameter(Mandatory)][string]$VaultId, [Parameter(Mandatory)][string]$SecretName)
    "$("$VaultId".TrimEnd('/'))/secrets/$SecretName"
}

function New-PimKvRoleAssignmentRequest {
    # PURE: the ARM PUT of one role assignment (deterministic name per scope + principal + role, so a re-run is the same
    # request and ARM answers "already exists" instead of creating a second one).
    param([Parameter(Mandatory)][string]$Scope, [Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$RoleId,
          [Parameter(Mandatory)][string]$PrincipalId, [ValidateSet('ServicePrincipal', 'User', 'Group')][string]$PrincipalType = 'ServicePrincipal')
    $md5 = [Security.Cryptography.MD5]::Create()
    $bytes = $md5.ComputeHash([Text.Encoding]::UTF8.GetBytes(("{0}|{1}|{2}" -f $Scope.ToLowerInvariant(), $PrincipalId.ToLowerInvariant(), $RoleId.ToLowerInvariant())))
    $name = ([guid]::new($bytes)).ToString()
    @{
        path = "$Scope/providers/Microsoft.Authorization/roleAssignments/$name`?api-version=2022-04-01"
        body = @{ properties = @{ roleDefinitionId = "/subscriptions/$SubscriptionId/providers/Microsoft.Authorization/roleDefinitions/$RoleId"; principalId = $PrincipalId; principalType = $PrincipalType } }
    }
}

# ===== END inlined helper: _PimMailSetup.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 =====
# ===== BEGIN inlined helper: ..\..\engine\_shared\PIM-TenantSizing.ps1 =====
<#
.SYNOPSIS
    PIM REQUIREMENTS 100.31 / framework DOCS/REQUIREMENTS.md 12.15 TENANT-SIZING-1 -- PIM's engine jobs are sized for
    the tenant, by the ONE rule every product uses (SI ships it as Get-SITenantSizedJobResources; mirrored here, never
    imported -- isolation beats DRY between solutions).

.DESCRIPTION
    WHY (2026-10-09, live on a production tenant of ~10.8k identity objects: 1,640 users, 4,476 groups, 4,705 service
    principals): ca-pim-tick ran at 0.5 CPU / 1 GiB and the active-assignments snapshot died with
    "Exception of type 'System.OutOfMemoryException' was thrown." The job had the size every tenant got.

    THE RULE (per job, on that job's object count; Azure Container Apps Consumption pairs only):
        any size (0 - 14,999) -> 2.0 CPU / 4.0Gi   (the FLOOR -- OPEN-27, framework section 0 "SIZING: NEW INSTALLS START AT
                                                   THE LEARNED SIZES", owner 2026-11-04: the tick at 0.5 / 1 on 6 installs,
                                                   one ran out of memory at that size; a new install never starts small)
        >= 15,000             -> 4.0 CPU / 8.0Gi   (the largest Consumption pair -- the cap)
      (Before 3.0.50: < 5,000 objects kept the tick at 0.5 CPU / 1.0Gi, and 2 / 4 started at 5,000.)
      Other PIM jobs (pull / publish, db-init, support SQL, as-built, the updater) are not sized here: 0.5 CPU / 1.0Gi.
      * THE RUN LIMIT IS NOT SIZED (framework 12.24 JOB-RUN-LIMIT, owner 2026-10-15: *"job limit must be ... 7 days ... we
        can not limit cap session runtime"*): every job's replicaTimeout is Azure's maximum, $script:PimJobRunLimitSeconds
        (604,800 s = 7 days), at every band, on every update, whatever was set before. PIM_Bootstrap_ReplicaTimeout_<Job> is
        ignored with a note. A dead run is found by its lease / execution status, never by the timeout.
      * It only ever RAISES: never below the job's default, never below what the job already runs.
      * A size the customer set wins: PIM_Bootstrap_Cpu_<Job> / PIM_Bootstrap_Memory_<Job>
        (<Job> as Get-PimJobSettingSuffix spells it: ca-pim-tick -> Tick). An invalid value is ignored with a note.
      * PIM's engine jobs (ca-pim-tick, and the active-assignments snapshot that runs INSIDE the tick) count
        users + groups + service principals.
      * Counts: Microsoft Graph $count (ConsistencyLevel: eventual), read at install and on every update; when that read
        fails, the counts RECORDED on the job (its pim-sizing-* tags) stand.
      * SELF-CORRECT: a job whose execution ran out of memory or hit its time limit since it was last sized is raised ONE
        band by the next update (its replicaTimeout is already the 7-day maximum).

    THE MANAGER WEB APP AND THE DATABASE (owner 2026-10-12, framework 12.15 "CHANGED FOR PIM", PIM REQUIREMENTS 100.114):
    the rule above sized JOBS only -- the product's web app was sized by nothing. Two product defaults, defined HERE and
    read by every creator (the installer) and by the updater (framework 12.16 CONVERGE-DEFAULTS):
        the Manager web app (ca-pim-manager)  4.0 CPU / 8.0Gi   ($script:PimManagerAppSizeDefault)
        the main database                     S3, 250 GB max    ($script:PimSqlTierDefault / $script:PimSqlMaxSizeBytesDefault)
      * RAISE ONLY: a Manager below 4 / 8 is raised, one at or above it is untouched; a database below S3 is raised to S3,
        one at or above it is untouched. Automation never lowers either.
      * OPEN-27 (3.0.50): the UPDATER's database tier raise is unchanged (owner 2026-10-12) and now behind one named switch,
        $script:PimSqlTierUpdaterRaiseEnabled ($true); support may set it $false -- a database below S3 is then REPORTED only.
      * A size the customer set wins: PIM_Bootstrap_Cpu_Manager / PIM_Bootstrap_Memory_Manager (the installer's or the
        update job's environment; recorded on the app as its pim-sizing-override tag so a later update keeps it).
      * A database tagged pim-sql-tier-pin keeps its tier. The tag holds only a tier name -- it cannot tell "the customer
        pinned it" from "it was pinned at the product's earlier default" -- so a pin is NEVER overridden; a pin below the
        default is REPORTED ("database is pinned at <tier>, the new default is S3 - not changed") for support to act on.
      * Every Standard database has a 250 GB max size (100.37; never lowered).

    Everything here is PURE except Get-PimTenantObjectCounts, whose Graph read is a scriptblock seam. PS 5.1 + 7, no modules.
#>

Set-StrictMode -Off

# framework 12.24 JOB-RUN-LIMIT (owner 2026-10-15): EVERY PIM Container Apps job runs with Azure's maximum run limit, 7 days.
# No product-chosen cap -- the installer, every job definition and the updater (Invoke-PimJobRunLimitUpdate) use this one value.
$script:PimJobRunLimitSeconds = 604800
$script:PimJobSizeDefaults = @{
    # OPEN-27 (owner 2026-11-04, framework section 0 SIZING): the tick starts at 2 CPU / 4 GiB at ANY tenant size (was 0.5 / 1).
    Tick = @{ Cpu = '2.0'; Memory = '4.0Gi'; ReplicaTimeout = $script:PimJobRunLimitSeconds }
}
# THE MANAGER WEB APP'S DEFAULT SIZE. Owner 2026-10-12: "4 CPU / 8 GB at all ring 1+2 installs" -- "lets give everyone a
# good experience for now" -- "we can always lower it". Why: at 0.5 CPU / 1 GiB the Manager ran out of memory reading a
# large tenant's stored snapshot (100.112). A person lowers it (PIM_Bootstrap_Cpu_Manager / _Memory_Manager); automation never.
$script:PimManagerAppSizeDefault = @{ Cpu = '4.0'; Memory = '8.0Gi' }
$script:PimManagerSizeSuffix = 'Manager'     # the <Job> part of PIM_Bootstrap_Cpu_<Job> / PIM_Bootstrap_Memory_<Job> for the web app
# THE DATABASE'S DEFAULT TIER. Owner 2026-10-12: "S3 at every ring 1+2 install" (same decision, same words as above).
# Standard, with the 250 GB max size of every Standard database (100.37). Raise only; a pinned database keeps its tier.
$script:PimSqlTierDefault = 'S3'
$script:PimSqlMaxSizeBytesDefault = [int64]268435456000     # 250 GB
# THE UPDATER RAISES AN EXISTING DATABASE BELOW S3 TO S3 (owner 2026-10-12 "S3 at every ring 1+2 install"; unchanged by
# OPEN-27, 3.0.50): raise only, a pim-sql-tier-pin tag wins and is reported. OPEN-27 made it ONE named switch so support can
# turn it off where needed: $false = an existing database below S3 is only REPORTED on every update (the sizing line in
# yellow + the run record UpdateState.setupFacts sqlTier), its 250 GB max size still set (included in every Standard tier).
# New installs are created at S3 / 250 GB either way (New-PimHostingPrerequisites).
$script:PimSqlTierUpdaterRaiseEnabled = $true
# The bands, in order. Band 0 = the job's default. Band 1 starts at 0 objects: the floor for every tenant (OPEN-27).
$script:PimJobSizeBands = @(
    [pscustomobject]@{ Band = 1; MinObjects = 0;     Cpu = '2.0'; Memory = '4.0Gi'; ReplicaTimeout = $script:PimJobRunLimitSeconds }
    [pscustomobject]@{ Band = 2; MinObjects = 15000; Cpu = '4.0'; Memory = '8.0Gi'; ReplicaTimeout = $script:PimJobRunLimitSeconds }
)
$script:PimJobSizeMaxCpu = 4.0
$script:PimJobSizeMaxMemoryGi = 8.0
$script:PimTenantSizingTagPrefix = 'pim-sizing-'

function Get-PimJobSettingSuffix {
    <# PURE. The per-job suffix of a PIM_Bootstrap_*_<Job> setting: ca-pim-tick -> Tick, ca-pim-downlink-s6 -> DownlinkS6, Tick -> Tick. #>
    param([Parameter(Mandatory)][string]$Job)
    # CR5 step 1 (PIM 100.149): THIS install's engine job is 'Tick' whatever it is named (ca-pim-tick today, ca-pim-engine
    # at a new install) -- its stored size settings keep their keys
    if ((Get-Command Get-PimInstallName -ErrorAction SilentlyContinue) -and "$Job".Trim() -ieq (Get-PimInstallName -Role engine)) { return 'Tick' }
    # JOB-RENAME 3.0.68: any name the ENGINE role carries (ca-pim-tick, caj-pim-engine, ca-pim-engine) is 'Tick' too -- a
    # renamed engine keeps its stored size settings even where the record is not read yet
    if ((Get-Command Test-PimInstallNameIsRole -ErrorAction SilentlyContinue) -and (Test-PimInstallNameIsRole -Role engine -Name "$Job")) { return 'Tick' }
    # CR5 step 2: THIS install's managed-tenant pull job keeps its DownlinkS6 keys whatever it is named (caj-pim-downlink at
    # a new install); a caj-pim-<purpose> job loses its prefix like a ca-pim-<purpose> one
    if ((Get-Command Get-PimInstallName -ErrorAction SilentlyContinue) -and "$Job".Trim() -ieq (Get-PimInstallName -Role downlink)) { return 'DownlinkS6' }
    $j = "$Job".Trim() -replace '^(?i)caj?-pim-', ''
    $parts = @(($j -split '[-_]') | Where-Object { $_ } | ForEach-Object { $_.Substring(0, 1).ToUpperInvariant() + $_.Substring(1).ToLowerInvariant() })
    return ($parts -join '')
}

function ConvertTo-PimJobCpu {
    <# PURE. '0.5' / 1 / '2.0' -> [double]; $null when it is not a number. #>
    param([AllowNull()][object]$Value)
    if ($null -eq $Value) { return $null }
    $c = 0.0
    if ([double]::TryParse(("$Value".Trim()), [Globalization.NumberStyles]::Float, [Globalization.CultureInfo]::InvariantCulture, [ref]$c)) { return $c }
    return $null
}

function ConvertTo-PimJobMemoryGi {
    <# PURE. '1Gi' / '1.0Gi' / '4.0Gi' / 2 -> [double] GiB; $null when unreadable. #>
    param([AllowNull()][object]$Value)
    if ($null -eq $Value) { return $null }
    $s = ("$Value".Trim() -replace '(?i)\s*gi$', '')
    $m = 0.0
    if ([double]::TryParse($s, [Globalization.NumberStyles]::Float, [Globalization.CultureInfo]::InvariantCulture, [ref]$m)) { return $m }
    return $null
}

function Format-PimJobCpu { param([double]$Cpu) $Cpu.ToString('0.0#', [Globalization.CultureInfo]::InvariantCulture) }
function Format-PimJobMemory { param([double]$Gi) ('{0}Gi' -f $Gi.ToString('0.0#', [Globalization.CultureInfo]::InvariantCulture)) }

function Get-PimTenantObjectTotal {
    <# PURE. The object count PIM's engine jobs are sized on: users + groups + service principals (a missing count is 0). #>
    param([AllowNull()]$Counts)
    if ($null -eq $Counts) { return 0L }
    $g = {
        param($k)
        $v = $null
        if ($Counts -is [System.Collections.IDictionary]) { if ($Counts.Contains($k)) { $v = $Counts[$k] } }
        elseif ($Counts.PSObject.Properties[$k]) { $v = $Counts.$k }
        $n = 0L; if ($null -ne $v -and [long]::TryParse("$v", [ref]$n) -and $n -gt 0) { return $n }
        return 0L
    }
    return ((& $g 'Users') + (& $g 'Groups') + (& $g 'ServicePrincipals'))
}

function Get-PimTenantSizedJobResources {
    <#
      PURE. A PIM engine job's size for THIS tenant -- the framework 12.15 rule (SI: Get-SITenantSizedJobResources).
      -Counts: Users, Groups, ServicePrincipals ($count). Returns @{ Cpu; Memory; ReplicaTimeout; Band; Objects } --
      since OPEN-27 (3.0.50) band 1 (2.0 / 4.0Gi) is the floor at ANY size (no counts = 0 objects = the floor), band 2 from
      15,000. $null only if no band is defined.
    #>
    param([string]$Job = 'ca-pim-tick', [AllowNull()]$Counts)
    $n = Get-PimTenantObjectTotal -Counts $Counts
    $hit = $null
    foreach ($b in $script:PimJobSizeBands) { if ($n -ge $b.MinObjects) { $hit = $b } }
    if (-not $hit) { return $null }
    return [pscustomobject]@{ Cpu = $hit.Cpu; Memory = $hit.Memory; ReplicaTimeout = $hit.ReplicaTimeout; Band = $hit.Band; Objects = $n }
}

function Get-PimJobBandOf {
    <# PURE. The band a size is in: 0 below band 1's CPU AND memory, else the highest band both reach. #>
    param([double]$Cpu, [double]$MemoryGi)
    $band = 0
    foreach ($b in $script:PimJobSizeBands) { if ($Cpu -ge [double]$b.Cpu -and $MemoryGi -ge (ConvertTo-PimJobMemoryGi $b.Memory)) { $band = $b.Band } }
    return $band
}

function Get-PimJobDefaultSize {
    <# PURE. The default of a job kind (Tick), with -DefaultReplicaTimeout overriding the default timeout (the install's -TickReplicaTimeout). #>
    param([string]$Job = 'ca-pim-tick', [int]$DefaultReplicaTimeout = 0)
    $sfx = Get-PimJobSettingSuffix -Job $Job
    $d = if ($script:PimJobSizeDefaults.ContainsKey($sfx)) { $script:PimJobSizeDefaults[$sfx] } else { $script:PimJobSizeDefaults['Tick'] }
    # framework 12.24: the timeout is never below the 7-day run limit -- a shorter -DefaultReplicaTimeout is not a cap.
    $t = [Math]::Max([int]$DefaultReplicaTimeout, [int]$script:PimJobRunLimitSeconds)
    return [pscustomobject]@{ Cpu = "$($d.Cpu)"; Memory = "$($d.Memory)"; ReplicaTimeout = $t }
}

# =====================================================================================================================
# THE MANAGER WEB APP + THE DATABASE DEFAULT (owner 2026-10-12; framework 12.15 "CHANGED FOR PIM"; PIM 100.114).
# The values live in $script:PimManagerAppSizeDefault / $script:PimSqlTierDefault at the top of this file. The getters
# carry a literal floor ONLY because a $script: variable reads $null when this file was loaded in another scope than the
# caller's (BUG-79-6b) -- a null default must never become "0 CPU" or "no tier".
# =====================================================================================================================
function Get-PimManagerAppDefaultSize {
    <# PURE. The Manager web app's product size: @{ Cpu = '4.0'; Memory = '8.0Gi' } (owner 2026-10-12). #>
    $d = $script:PimManagerAppSizeDefault
    $c = '4.0'; $m = '8.0Gi'
    if ($d -and "$($d.Cpu)".Trim() -and "$($d.Memory)".Trim()) { $c = "$($d.Cpu)".Trim(); $m = "$($d.Memory)".Trim() }
    return [pscustomobject]@{ Cpu = $c; Memory = $m }
}

function Get-PimSqlDefaultTier {
    <# PURE. The main database's product tier: 'S3' (owner 2026-10-12). #>
    $t = "$($script:PimSqlTierDefault)".Trim()
    if ($t -notmatch '^(?i)S\d+$') { $t = 'S3' }
    return $t.ToUpperInvariant()
}

function Test-PimSqlTierUpdaterRaiseEnabled {
    <# PURE. OPEN-27: may the UPDATER raise an existing database's tier? $true (owner 2026-10-12) unless
       $script:PimSqlTierUpdaterRaiseEnabled is exactly $false. A $null read in another scope (BUG-79-6b) keeps the product
       behaviour: on. #>
    return (-not ($script:PimSqlTierUpdaterRaiseEnabled -is [bool] -and -not $script:PimSqlTierUpdaterRaiseEnabled))
}

function Get-PimSqlDefaultMaxSizeBytes {
    <# PURE. The max size of every Standard database: 250 GB (100.37). #>
    $b = [int64]0
    if ($null -ne $script:PimSqlMaxSizeBytesDefault) { [void][int64]::TryParse("$($script:PimSqlMaxSizeBytesDefault)", [ref]$b) }
    if ($b -le 0) { $b = [int64]268435456000 }
    return $b
}

function Get-PimManagerAppResources {
    <#
      PURE. THE ONE DECISION for the Manager web app's CPU and memory (creators and the updater both ask here):
        1. the product size (Get-PimManagerAppDefaultSize: 4.0 CPU / 8.0Gi)
        2. -Current (@{ Cpu; Memory }: what the app runs now) -- RAISE ONLY: below the product size in CPU or memory ->
           raised to it; at or above it -> untouched (a bigger app is never lowered)
        3. the customer's PIM_Bootstrap_Cpu_Manager / PIM_Bootstrap_Memory_Manager (-Settings: name -> value) WINS, as for
           the jobs (also below the product size). One of the two alone sets the other to its Consumption pair
           (memory = 2 x CPU). An invalid value is ignored with a note.
      Returns @{ Cpu; Memory; Source ('default'|'raised'|'kept'|'customer'); Changed; Have; Notes; Override }.
      Changed is $true only when -Current was READ and differs from the result: an unread size is never written over.
    #>
    param([AllowNull()]$Current, [hashtable]$Settings = @{})
    $notes = New-Object System.Collections.Generic.List[string]
    $d = Get-PimManagerAppDefaultSize
    $dc = [double](ConvertTo-PimJobCpu $d.Cpu); $dm = [double](ConvertTo-PimJobMemoryGi $d.Memory)
    $cpu = $dc; $mem = $dm; $source = 'default'
    $cc = $null; $cm = $null
    if ($null -ne $Current) {
        $gc = { param($n) if ($Current -is [System.Collections.IDictionary]) { if ($Current.Contains($n)) { $Current[$n] } } elseif ($Current.PSObject.Properties[$n]) { $Current.$n } }
        $rc = & $gc 'Cpu'; $rm = & $gc 'Memory'
        if ("$rc".Trim()) { $cc = ConvertTo-PimJobCpu $rc }
        if ("$rm".Trim()) { $cm = ConvertTo-PimJobMemoryGi $rm }
    }
    $haveCur = ($null -ne $cc -and $null -ne $cm -and $cc -gt 0 -and $cm -gt 0)
    $have = ''
    if ($haveCur) {
        $have = ('{0} CPU / {1}' -f (Format-PimJobCpu $cc), (Format-PimJobMemory $cm))
        if ($cc -ge $dc -and $cm -ge $dm) {
            $cpu = $cc; $mem = $cm
            if ($cc -gt $dc -or $cm -gt $dm) { $source = 'kept'; $notes.Add(("the Manager web app already runs {0} -- kept (never lowered)" -f $have)) }
        } else {
            $cpu = [Math]::Max($dc, $cc); $mem = [Math]::Max($dm, $cm); $source = 'raised'
            $notes.Add(("the Manager web app runs {0}, below the product size {1} CPU / {2} -- raised (never lowered)" -f $have, $d.Cpu, $d.Memory))
        }
    }
    # 3. the customer's own size wins
    $sfx = "$($script:PimManagerSizeSuffix)".Trim(); if (-not $sfx) { $sfx = 'Manager' }
    $gv = { param($n) if ($Settings -and $Settings.ContainsKey($n) -and -not [string]::IsNullOrWhiteSpace([string]$Settings[$n])) { "$($Settings[$n])".Trim() } else { $null } }
    $override = [ordered]@{}
    $oc = $null; $om = $null
    $n = 'PIM_Bootstrap_Cpu_{0}' -f $sfx; $v = & $gv $n
    if ($null -ne $v) {
        $c = ConvertTo-PimJobCpu $v
        if ($null -ne $c -and $c -ge 0.25 -and $c -le 4 -and (($c * 4) % 1) -eq 0) { $oc = $c }
        else { $notes.Add(("{0} = '{1}' is not a CPU size (0.25 to 4, in steps of 0.25) -- ignored" -f $n, $v)) }
    }
    $n = 'PIM_Bootstrap_Memory_{0}' -f $sfx; $v = & $gv $n
    if ($null -ne $v) {
        $m = ConvertTo-PimJobMemoryGi $v
        if ($null -ne $m -and $m -ge 0.5 -and $m -le 8 -and (($m * 2) % 1) -eq 0) { $om = $m }
        else { $notes.Add(("{0} = '{1}' is not a memory size (0.5Gi to 8Gi, in steps of 0.5Gi) -- ignored" -f $n, $v)) }
    }
    if ($null -ne $oc -or $null -ne $om) {
        if ($null -eq $om) { $om = $oc * 2; $notes.Add(("PIM_Bootstrap_Memory_{0} is not set -- memory follows the CPU: {1}" -f $sfx, (Format-PimJobMemory $om))) }
        if ($null -eq $oc) { $oc = $om / 2; $notes.Add(("PIM_Bootstrap_Cpu_{0} is not set -- CPU follows the memory: {1}" -f $sfx, (Format-PimJobCpu $oc))) }
        $cpu = $oc; $mem = $om; $source = 'customer'
        $override['Cpu'] = (Format-PimJobCpu $oc); $override['Memory'] = (Format-PimJobMemory $om)
        $notes.Add(("the customer's size wins: PIM_Bootstrap_Cpu_{0}={1}, PIM_Bootstrap_Memory_{0}={2}" -f $sfx, $override['Cpu'], $override['Memory']))
    }
    $changed = ($haveCur -and ($cc -ne $cpu -or $cm -ne $mem))
    return [pscustomobject]@{ Cpu = (Format-PimJobCpu $cpu); Memory = (Format-PimJobMemory $mem); Source = $source; Changed = [bool]$changed
                              Have = $have; Notes = @($notes.ToArray()); Override = $override }
}

function Get-PimManagerSizingTags {
    <# PURE. The tags that RECORD the Manager web app's sizing on the app (the override so a later update keeps the customer's choice). #>
    param([Parameter(Mandatory)][object]$Size, [datetime]$NowUtc = [datetime]::UtcNow)
    $p = $script:PimTenantSizingTagPrefix; if (-not $p) { $p = 'pim-sizing-' }
    $t = [ordered]@{}
    $t["${p}size"] = ('{0}/{1}' -f $Size.Cpu, $Size.Memory)
    $t["${p}source"] = "$($Size.Source)"
    $ov = $Size.Override
    # 'Cpu:2.0+Memory:4.0Gi' -- the same shape the jobs use (ConvertFrom-PimTenantSizingTags reads it back)
    $t["${p}override"] = $(if ($ov -and $ov.Count) { (@($ov.Keys | ForEach-Object { "$($_):$($ov[$_])" }) -join '+') } else { '' })
    $t["${p}utc"] = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
    return $t
}

function Get-PimManagerAppResize {
    <#
      PURE. What ONE write of the Manager web app must carry for its size -- the -Resize answer of Set-PimAcaAppImage /
      Invoke-PimAcaRoll (engine/_shared/PIM-ArmContainerApps.ps1) and of Invoke-PimManagerAppSizeUpdate below.
      -Container: the app's container as ARM returned it (resources.cpu / resources.memory). -App: the app (its tags carry a
      recorded customer override). -Environment: name -> value (PIM_Bootstrap_Cpu_Manager / PIM_Bootstrap_Memory_Manager).
      Returns @{ change; Cpu; Memory; Tags; detail; notes; size }. change = $false -> the write must leave the resources
      exactly as they are. Tags (only when change) = the app's OWN tags plus the pim-sizing-* record, for the SAME write.
    #>
    param([AllowNull()][object]$Container, [AllowNull()][object]$App, [hashtable]$Environment = @{}, [datetime]$NowUtc = [datetime]::UtcNow)
    $cur = $null
    $res = $null; if ($Container) { $res = $Container.resources }
    if ($res -and "$($res.cpu)".Trim() -and "$($res.memory)".Trim()) { $cur = @{ Cpu = "$($res.cpu)"; Memory = "$($res.memory)" } }
    $appTags = $null; if ($App) { $appTags = $App.tags }
    $rec = ConvertFrom-PimTenantSizingTags -Tags $appTags -Job 'Manager'
    $settings = Get-PimJobSizingSettings -Environment $Environment -Recorded $rec.settings
    $size = Get-PimManagerAppResources -Current $cur -Settings $settings
    # CR7 (framework 12.11g, live 2026-10-18 on the ring-1 test install: ContainerAppInvalidResourceTotal): behind the sign-in
    # front the app's containers SHARE the Consumption maximum (4.0 CPU / 8.0Gi) -- the Manager gets what the front leaves
    # (3.75 / 7.5Gi beside a 0.25 / 0.5Gi front). Every resize path (the updater's roll, the size update, setup) asks here,
    # so no update ever raises the Manager past what the app may hold. Without a front: exactly as before.
    $sfc = $null; if ($App -and $App.properties -and $App.properties.template) { $sfc = @(@($App.properties.template.containers) | Where-Object { $_ -and "$($_.name)" -eq 'signin-front' })[0] }
    if ($sfc -and $sfc.resources) {
        $fcCpu = ConvertTo-PimJobCpu $sfc.resources.cpu; $fcMem = ConvertTo-PimJobMemoryGi $sfc.resources.memory
        if ($null -ne $fcCpu -and $null -ne $fcMem) {
            $roomCpu = [double]$script:PimJobSizeMaxCpu - [double]$fcCpu; $roomMem = (2 * [double]$script:PimJobSizeMaxCpu) - [double]$fcMem
            $wCpu = [double](ConvertTo-PimJobCpu $size.Cpu); $wMem = [double](ConvertTo-PimJobMemoryGi $size.Memory)
            if ($wCpu -gt $roomCpu -or $wMem -gt $roomMem) {
                $nCpu = [Math]::Min($wCpu, $roomCpu); $nMem = [Math]::Min($wMem, $roomMem)
                $size.Cpu = Format-PimJobCpu $nCpu; $size.Memory = Format-PimJobMemory $nMem
                $haveC = $null; $haveM = $null; if ($cur) { $haveC = ConvertTo-PimJobCpu $cur.Cpu; $haveM = ConvertTo-PimJobMemoryGi $cur.Memory }
                $size.Changed = [bool]($null -ne $haveC -and ($haveC -ne $nCpu -or $haveM -ne $nMem))
                $size.Notes = @(@($size.Notes) + ("behind the sign-in front ({0} CPU / {1}) the Manager may hold at most {2} CPU / {3} -- the app's total is capped at {4} CPU" -f (Format-PimJobCpu $fcCpu), (Format-PimJobMemory $fcMem), $size.Cpu, $size.Memory, (Format-PimJobCpu $script:PimJobSizeMaxCpu)))
            }
        }
    }
    $tags = $null
    if ($size.Changed) {
        $tags = @{}
        if ($appTags) {
            if ($appTags -is [System.Collections.IDictionary]) { foreach ($k in @($appTags.Keys)) { $tags["$k"] = "$($appTags[$k])" } }
            else { foreach ($tp in @($appTags.PSObject.Properties)) { $tags["$($tp.Name)"] = "$($tp.Value)" } }
        }
        $mine = Get-PimManagerSizingTags -Size $size -NowUtc $NowUtc
        foreach ($k in @($mine.Keys)) { if ("$($mine[$k])".Trim()) { $tags["$k"] = "$($mine[$k])" } elseif ($tags.ContainsKey("$k")) { $tags.Remove("$k") } }
    }
    $detail = ''
    if ($null -eq $cur) { $detail = 'the Manager web app''s size could not be read -- not changed' }
    elseif ($size.Changed) { $detail = ('the Manager web app: {0} -> {1} CPU / {2} ({3})' -f $size.Have, $size.Cpu, $size.Memory, $size.Source) }
    else { $detail = ('the Manager web app: {0} -- unchanged ({1})' -f $size.Have, $size.Source) }
    return [pscustomobject]@{ change = [bool]$size.Changed; Cpu = $size.Cpu; Memory = $size.Memory; Tags = $tags; detail = $detail; notes = @($size.Notes); size = $size }
}

function Get-PimManagerFrontRoom {
    <#
      PURE. CR7: behind the sign-in front the app's containers share the Consumption maximum, so the Manager may hold at most
      what the front leaves. -App: the container app as ARM returned it. Returns @{ Cpu; MemoryGi } (doubles) or $null when
      there is no front (or its size is unreadable). The literal 4.0 is the floor if $script:PimJobSizeMaxCpu is not set in
      the caller's scope ($script: is the CALLER's script scope -- trial install 11a17b54, 2026-10-21).
    #>
    param([AllowNull()][object]$App)
    $sfc = $null; if ($App -and $App.properties -and $App.properties.template) { $sfc = @(@($App.properties.template.containers) | Where-Object { $_ -and "$($_.name)" -eq 'signin-front' })[0] }
    if (-not $sfc -or -not $sfc.resources) { return $null }
    $fcCpu = ConvertTo-PimJobCpu $sfc.resources.cpu; $fcMem = ConvertTo-PimJobMemoryGi $sfc.resources.memory
    if ($null -eq $fcCpu -or $null -eq $fcMem) { return $null }
    $max = $(if ($script:PimJobSizeMaxCpu) { [double]$script:PimJobSizeMaxCpu } else { 4.0 })
    return @{ Cpu = ($max - [double]$fcCpu); MemoryGi = ((2 * $max) - [double]$fcMem); FrontCpu = [double]$fcCpu; FrontMemoryGi = [double]$fcMem }
}

function Test-PimManagerAppUndersized {
    <#
      PURE. Is the Manager web app below its size? @{ readable; undersized; have; want; source; reason; fix }.
      want = Get-PimManagerAppResources for what it runs (-Cpu / -Memory) and the override recorded on it (-Tags), so a
      customer's own smaller size is NOT flagged. An unread size is not judged.
      -App (2026-10-21, trial install 11a17b54 flagged "CPU 4.0, memory 8.0Gi" on a Manager behind the sign-in front): the
      app as ARM returned it -- behind a front, want is capped at what the front leaves (Get-PimManagerFrontRoom), exactly as
      every resize caps it, so a Manager that already holds all the room it may is never called undersized.
    #>
    param([AllowNull()][object]$Cpu, [AllowNull()][object]$Memory, [AllowNull()]$Tags, [string]$AppName = 'ca-pim-manager', [AllowNull()][object]$App)
    $d = Get-PimManagerAppDefaultSize
    $rec = ConvertFrom-PimTenantSizingTags -Tags $Tags -Job 'Manager'
    $cur = $null; if ("$Cpu".Trim() -and "$Memory".Trim()) { $cur = @{ Cpu = "$Cpu"; Memory = "$Memory" } }
    $size = Get-PimManagerAppResources -Current $cur -Settings $rec.settings
    $room = Get-PimManagerFrontRoom -App $App
    if ($room) {
        $wCpu = [double](ConvertTo-PimJobCpu $size.Cpu); $wMem = [double](ConvertTo-PimJobMemoryGi $size.Memory)
        if ($wCpu -gt $room.Cpu) { $size.Cpu = Format-PimJobCpu $room.Cpu }
        if ($wMem -gt $room.MemoryGi) { $size.Memory = Format-PimJobMemory $room.MemoryGi }
    }
    $want = ('{0} CPU / {1}' -f $size.Cpu, $size.Memory)
    if (-not "$($size.Have)".Trim()) { return [pscustomobject]@{ readable = $false; undersized = $false; have = ''; want = $want; source = $size.Source; fix = ''; reason = 'the Manager web app''s size could not be read' } }
    $hc = [double](ConvertTo-PimJobCpu $Cpu); $hm = [double](ConvertTo-PimJobMemoryGi $Memory)
    $low = ($hc -lt [double](ConvertTo-PimJobCpu $size.Cpu) -or $hm -lt [double](ConvertTo-PimJobMemoryGi $size.Memory))
    $what = $(if ($size.Source -eq 'customer') { 'the size the customer set' } else { 'the product size' })
    $reason = $(if ($low) { ('the Manager web app runs {0}; {1} is {2}' -f $size.Have, $what, $want) } else { ('the Manager web app runs {0} ({1} {2} CPU / {3})' -f $size.Have, $(if ($size.Source -eq 'customer') { 'the customer''s size; the product size is' } else { 'the product size is' }), $d.Cpu, $d.Memory) })
    $fix = $(if ($low) { ("Azure portal > Container app $AppName > Containers > Edit and deploy: CPU {0}, memory {1} (the next update raises it by itself)" -f $size.Cpu, $size.Memory) } else { '' })
    return [pscustomobject]@{ readable = $true; undersized = [bool]$low; have = $size.Have; want = $want; source = $size.Source; fix = $fix; reason = $reason }
}

function Test-PimSqlTierBelowDefault {
    <#
      PURE. Is the main database below the product tier? @{ readable; below; pinned; current; want; reason; fix }, from THE plan
      (Get-PimSqlTierPlan): below = the plan would raise it, OR it is pinned below the default (reported, never changed).
      Premium / vCore / an elastic pool / an unread tier are not judged.
    #>
    param([AllowNull()][string]$Current, [AllowNull()][string]$Pin, [AllowNull()][string]$ElasticPool, [AllowNull()][object]$CurrentMaxSizeBytes = $null, [string]$Database = 'PimPlatform')
    $plan = Get-PimSqlTierPlan -Current $Current -Pin $Pin -ElasticPool $ElasticPool -CurrentMaxSizeBytes $CurrentMaxSizeBytes
    $c = "$Current".Trim()
    if (-not $c) { return [pscustomobject]@{ readable = $false; below = $false; pinned = [bool]$plan.pinned; current = ''; want = $plan.defaultTier; fix = ''; reason = 'the database tier could not be read' } }
    $below = ($plan.action -eq 'raise' -or [bool]$plan.pinnedBelowDefault -or $plan.maxSizeAction -eq 'set')
    $reason = $(if ($plan.pinnedBelowDefault) { "$($plan.pinNote)" } else { "database $Database`: $($plan.reason)" })
    $fix = ''
    if ($plan.pinnedBelowDefault) { $fix = "Set-PimSqlTier.ps1 -Tier $($plan.defaultTier) -Pin moves a pinned database (https://invardia.com/support/pim/Set-PimSqlTier.ps1); leave it when the pin is the customer's choice" }
    elseif ($below -and $plan.action -eq 'raise' -and -not (Test-PimSqlTierUpdaterRaiseEnabled)) { $fix = 'Set-PimSqlTier.ps1 applies it (https://invardia.com/support/pim/Set-PimSqlTier.ps1); the updater''s tier raise is switched off here' }
    elseif ($below) { $fix = 'Set-PimSqlTier.ps1 applies it now (https://invardia.com/support/pim/Set-PimSqlTier.ps1); the next update does it by itself' }
    return [pscustomobject]@{ readable = $true; below = [bool]$below; pinned = [bool]$plan.pinned; current = $c; want = $plan.defaultTier; fix = $fix; reason = $reason }
}

function Get-PimSqlTierFact {
    <#
      PURE. OPEN-27: the run-record fact for the database tier, from Invoke-PimSqlTierUpdate's result (-Result; $null = not
      read this run). Returns [ordered]@{ sqlTier; sqlTierCurrent; sqlTierDetail }:
        sqlTier  ok            at or above the product tier
                 raised        raised to the product tier by this run (owner 2026-10-12)
                 below         below the product tier, NOT raised (support switched the updater's raise off)
                 pinned-below  pinned (pim-sql-tier-pin) below the product tier -- never changed
                 n/a           not a Standard DTU database the rule judges (Premium, vCore, an elastic pool)
                 unknown       not read (no result, a failed read, an unreadable tier) -- never a guessed ok
      sqlTierDetail is the update's own line, one line, at most 200 characters.
    #>
    param([AllowNull()][object]$Result)
    $f = [ordered]@{ sqlTier = 'unknown'; sqlTierCurrent = ''; sqlTierDetail = 'not read: the database tier was not checked this run' }
    if ($null -eq $Result) { return $f }
    $gp = { param($n) if ($Result -is [System.Collections.IDictionary]) { if ($Result.Contains($n)) { $Result[$n] } } elseif ($Result.PSObject.Properties[$n]) { $Result.$n } }
    $d = (("$(& $gp 'detail')") -replace '\s+', ' ').Trim()
    if ($d.Length -gt 200) { $d = $d.Substring(0, 197) + '...' }
    $cur = "$(& $gp 'tierBefore')".Trim(); $aft = "$(& $gp 'tierAfter')".Trim()
    $f.sqlTierCurrent = $(if ($aft) { $aft } else { $cur })
    if ($d) { $f.sqlTierDetail = $d }
    if ([bool](& $gp 'pinnedBelowDefault')) { $f.sqlTier = 'pinned-below'; return $f }
    if ([bool](& $gp 'tierRaiseHeld') -or [bool](& $gp 'belowDefault')) { $f.sqlTier = 'below'; return $f }
    if ([bool](& $gp 'tierRaised')) { $f.sqlTier = 'raised'; return $f }
    if (-not $cur) { $f.sqlTier = 'unknown'; return $f }
    if ($cur -notmatch '^(?i)(basic|S\d+)$' -or $d -match '(?i)elastic pool') { $f.sqlTier = 'n/a'; return $f }
    $rank = { param($s) if ($s -match '^(?i)basic$') { 0 } elseif ($s -match '^(?i)S(\d+)$') { 1 + [int]$Matches[1] } else { -1 } }
    $want = "$(& $gp 'defaultTier')".Trim(); if (-not $want) { $want = Get-PimSqlDefaultTier }
    $end = $(if ($aft) { $aft } else { $cur })
    $f.sqlTier = $(if ((& $rank $end) -ge (& $rank $want)) { 'ok' } elseif ((& $rank $end) -ge 0) { 'below' } else { 'unknown' })
    return $f
}

function Test-PimJobRunOutOfResources {
    <#
      PURE. Is this run record evidence the job ran OUT of memory or time? Returns '' (no), 'memory' or 'timeout'.
      Evidence (the job-lane causes, PIM-JobLanes Get-PimInterruptedRunVerdict, and the failure catalog):
        memory  -- the run's text classifies ENGINE-OUT-OF-MEMORY (PIM-FailureCatalog), or names OutOfMemoryException /
                   OOMKilled / exit code 137, or the execution 'ended in Failed ... (out of memory or a crash)' ('crashed')
        timeout -- 'stopped at the execution time limit' ('time-limit'), or the platform's replica timeout text
    #>
    param([AllowNull()][object]$Run)
    if ($null -eq $Run) { return '' }
    $st = "$($Run.status)".Trim()
    if ($Run.PSObject.Properties['ok'] -and [bool]$Run.ok -and $st -ne 'failed') { return '' }
    $txt = "$($Run.detail) $($Run.error) $($Run.cause)"
    if ($txt -match '(?i)stopped at the execution time limit|\btime-limit\b|replica ?timeout|exceeded (the )?(replica )?timeout|DeadlineExceeded') { return 'timeout' }
    $code = ''
    if (Get-Command Get-PimFailureClassification -ErrorAction SilentlyContinue) { try { $code = "$((Get-PimFailureClassification -Message $txt).code)" } catch { $code = '' } }
    if ($code -eq 'ENGINE-OUT-OF-MEMORY' -or $txt -match '(?i)OutOfMemoryException|\bOOMKilled\b|exit code 137\b|out of memory or a crash|\bcrashed\b') { return 'memory' }
    return ''
}

function Get-PimJobSelfCorrection {
    <#
      PURE. The self-correction an update makes for ONE job: any run (from pim.Settings JobRunHistory, newest first) that
      started after -SinceUtc (when the job was last sized) and ran out of memory or time.
      Returns @{ raise; kind ('memory'|'timeout'|''); evidence[]; reason }.
      -JobRunNames: the run names that ran IN this job (default: all -- every scheduled job of the tick runs in ca-pim-tick).
    #>
    param([object[]]$Runs = @(), [AllowNull()][object]$SinceUtc, [string[]]$JobRunNames = @())
    $since = $null
    if ($SinceUtc) { try { $since = ([datetime]"$SinceUtc").ToUniversalTime() } catch { $since = $null } }
    $ev = New-Object System.Collections.Generic.List[object]
    foreach ($r in @($Runs | Where-Object { $_ })) {
        if ($JobRunNames.Count -and ($JobRunNames -notcontains "$($r.name)")) { continue }
        $at = $null; try { if ("$($r.startedUtc)".Trim()) { $at = ([datetime]"$($r.startedUtc)").ToUniversalTime() } } catch { $at = $null }
        if ($since -and $at -and $at -le $since) { continue }
        $k = Test-PimJobRunOutOfResources -Run $r
        if ($k) { $ev.Add([pscustomobject]@{ kind = $k; name = "$($r.name)"; startedUtc = "$($r.startedUtc)"; detail = ("$($r.detail)" -replace '\s+', ' ').Substring(0, [Math]::Min(200, ("$($r.detail)" -replace '\s+', ' ').Length)) }) }
    }
    if (-not $ev.Count) { return [pscustomobject]@{ raise = $false; kind = ''; evidence = @(); reason = 'no run ran out of memory or time since the job was last sized' } }
    $kind = if (@($ev | Where-Object { $_.kind -eq 'memory' }).Count) { 'memory' } else { 'timeout' }
    $first = $ev[0]
    return [pscustomobject]@{ raise = $true; kind = $kind; evidence = @($ev.ToArray())
        reason = ("{0} run(s) ran out of {1} since the job was last sized (latest: '{2}' at {3})" -f $ev.Count, $(if ($kind -eq 'memory') { 'memory' } else { 'time' }), $first.name, $first.startedUtc) }
}

function Step-PimJobSize {
    <# PURE. One band up (capped at 4 CPU / 8 GiB); the replicaTimeout is always the 7-day run limit (framework 12.24). #>
    param([Parameter(Mandatory)][double]$Cpu, [Parameter(Mandatory)][double]$MemoryGi, [int]$ReplicaTimeout = 0)
    $band = Get-PimJobBandOf -Cpu $Cpu -MemoryGi $MemoryGi
    $next = @($script:PimJobSizeBands | Where-Object { $_.Band -eq ($band + 1) }) | Select-Object -First 1
    $c = $Cpu; $m = $MemoryGi
    if ($next) { $c = [Math]::Max($Cpu, [double]$next.Cpu); $m = [Math]::Max($MemoryGi, (ConvertTo-PimJobMemoryGi $next.Memory)) }
    $t = [int]$script:PimJobRunLimitSeconds
    return [pscustomobject]@{ Cpu = [Math]::Min($c, $script:PimJobSizeMaxCpu); MemoryGi = [Math]::Min($m, $script:PimJobSizeMaxMemoryGi); ReplicaTimeout = $t
                              Band = (Get-PimJobBandOf -Cpu ([Math]::Min($c, $script:PimJobSizeMaxCpu)) -MemoryGi ([Math]::Min($m, $script:PimJobSizeMaxMemoryGi))) }
}

function Get-PimContainerJobResources {
    <#
      PURE. THE ONE DECISION: a PIM engine job's CPU, memory and replicaTimeout.
        1. the job's default (-DefaultReplicaTimeout = the install's -TickReplicaTimeout)
        2. the tenant tier for -Counts (raise only)
        3. -Current: what the job runs now -- never lowered (an update never shrinks a job someone raised)
        4. -SelfCorrect (Get-PimJobSelfCorrection): one band + one timeout step up
        5. the customer's PIM_Bootstrap_Cpu/Memory/ReplicaTimeout_<Job> (-Settings: name -> value; env, the update job's env,
           or the override RECORDED on the job) WINS, also downwards. Invalid -> ignored with a note.
      Capped at 4.0 CPU / 8.0Gi. Returns @{ Cpu; Memory; ReplicaTimeout; Band; Objects; Source; Notes; Override }.
    #>
    param([string]$Job = 'ca-pim-tick', [AllowNull()]$Counts, [hashtable]$Settings = @{}, [AllowNull()]$Current, [AllowNull()]$SelfCorrect,
          [int]$DefaultReplicaTimeout = 0)
    $inv = [Globalization.CultureInfo]::InvariantCulture
    $notes = New-Object System.Collections.Generic.List[string]
    $d = Get-PimJobDefaultSize -Job $Job -DefaultReplicaTimeout $DefaultReplicaTimeout
    $cpu = [double](ConvertTo-PimJobCpu $d.Cpu); $mem = [double](ConvertTo-PimJobMemoryGi $d.Memory); $to = [int]$d.ReplicaTimeout
    $source = 'default'
    $objects = Get-PimTenantObjectTotal -Counts $Counts
    $sized = Get-PimTenantSizedJobResources -Job $Job -Counts $Counts
    if ($sized) {
        $sc = [double](ConvertTo-PimJobCpu $sized.Cpu); $sm = [double](ConvertTo-PimJobMemoryGi $sized.Memory)
        if ($sm -gt $mem -or $sc -gt $cpu) { $cpu = [Math]::Max($cpu, $sc); $mem = [Math]::Max($mem, $sm); $source = 'tenant-size' }
        if ([int]$sized.ReplicaTimeout -gt $to) { $to = [int]$sized.ReplicaTimeout }
        if ($null -eq $Counts) { $notes.Add(('no tenant count -> the floor for every tenant: {0} CPU / {1}, replicaTimeout {2} s' -f (Format-PimJobCpu $sc), (Format-PimJobMemory $sm), $sized.ReplicaTimeout)) }
        else { $notes.Add(('sized for this tenant: {0:N0} objects (users + groups + service principals) -> {1} CPU / {2}, replicaTimeout {3} s' -f $objects, (Format-PimJobCpu $sc), (Format-PimJobMemory $sm), $sized.ReplicaTimeout)) }
    }
    if ($null -ne $Current) {
        $gc = { param($n) if ($Current -is [System.Collections.IDictionary]) { if ($Current.Contains($n)) { $Current[$n] } } elseif ($Current.PSObject.Properties[$n]) { $Current.$n } }
        $cc = ConvertTo-PimJobCpu (& $gc 'Cpu'); $cm = ConvertTo-PimJobMemoryGi (& $gc 'Memory'); $ct = 0; [void][int]::TryParse("$(& $gc 'ReplicaTimeout')", [ref]$ct)
        if ($null -ne $cc -and $null -ne $cm -and ($cm -gt $mem -or $cc -gt $cpu)) { $cpu = [Math]::Max($cpu, $cc); $mem = [Math]::Max($mem, $cm); $source = 'kept'; $notes.Add(('the job already runs {0} CPU / {1} -- kept (never lowered)' -f (Format-PimJobCpu $cc), (Format-PimJobMemory $cm))) }
        if ($ct -gt $to) { $to = $ct }
    }
    if ($SelfCorrect -and [bool]$SelfCorrect.raise) {
        $s = Step-PimJobSize -Cpu $cpu -MemoryGi $mem -ReplicaTimeout $to
        $notes.Add(('self-correct: {0} -> {1} CPU / {2}, replicaTimeout {3} s' -f $SelfCorrect.reason, (Format-PimJobCpu $s.Cpu), (Format-PimJobMemory $s.MemoryGi), $s.ReplicaTimeout))
        $cpu = $s.Cpu; $mem = $s.MemoryGi; $to = $s.ReplicaTimeout; $source = 'self-correct'
    }
    $cpu = [Math]::Min($cpu, $script:PimJobSizeMaxCpu); $mem = [Math]::Min($mem, $script:PimJobSizeMaxMemoryGi)

    # 5. the customer's own size wins
    $sfx = Get-PimJobSettingSuffix -Job $Job
    $gv = { param($n) if ($Settings -and $Settings.ContainsKey($n) -and -not [string]::IsNullOrWhiteSpace([string]$Settings[$n])) { "$($Settings[$n])".Trim() } else { $null } }
    $override = [ordered]@{}
    # framework 12.24 JOB-RUN-LIMIT: the run limit is always Azure's maximum -- a customer value is not a size and is ignored.
    $n = 'PIM_Bootstrap_ReplicaTimeout_{0}' -f $sfx; $v = & $gv $n
    if ($null -ne $v) { $notes.Add(("{0} = '{1}' is ignored -- every PIM job runs with the 7-day maximum run limit ({2} s)" -f $n, $v, $script:PimJobRunLimitSeconds)) }
    $to = [Math]::Max([int]$to, [int]$script:PimJobRunLimitSeconds)
    $n = 'PIM_Bootstrap_Cpu_{0}' -f $sfx; $v = & $gv $n
    if ($null -ne $v) {
        $c = ConvertTo-PimJobCpu $v
        if ($null -ne $c -and $c -ge 0.25 -and $c -le 4 -and (($c * 4) % 1) -eq 0) { $cpu = $c; $override['Cpu'] = (Format-PimJobCpu $c); $source = 'customer' }
        else { $notes.Add(("{0} = '{1}' is not a CPU size (0.25 to 4, in steps of 0.25) -- using {2}" -f $n, $v, (Format-PimJobCpu $cpu))) }
    }
    $n = 'PIM_Bootstrap_Memory_{0}' -f $sfx; $v = & $gv $n
    if ($null -ne $v) {
        $m = ConvertTo-PimJobMemoryGi $v
        if ($null -ne $m -and $m -ge 0.5 -and $m -le 8 -and (($m * 2) % 1) -eq 0) { $mem = $m; $override['Memory'] = (Format-PimJobMemory $m); $source = 'customer' }
        else { $notes.Add(("{0} = '{1}' is not a memory size (0.5Gi to 8Gi, in steps of 0.5Gi) -- using {2}" -f $n, $v, (Format-PimJobMemory $mem))) }
    }
    if ($override.Count) { $notes.Add(('the customer''s size wins: {0}' -f (@($override.Keys | ForEach-Object { "PIM_Bootstrap_$($_)_$sfx=$($override[$_])" }) -join ', '))) }
    return [pscustomobject]@{ Cpu = (Format-PimJobCpu $cpu); Memory = (Format-PimJobMemory $mem); ReplicaTimeout = $to; Band = (Get-PimJobBandOf -Cpu $cpu -MemoryGi $mem)
                              Objects = $objects; Source = $source; Notes = @($notes.ToArray()); Override = $override }
}

function Get-PimJobSizingSettings {
    <#
      PURE. The customer's PIM_Bootstrap_Cpu/Memory/ReplicaTimeout_* settings: -Environment (name -> value; the installer's or
      the update job's environment) over -Recorded (the override recorded on the job at its last sizing, so an update without
      the variable keeps what the customer chose). Non-empty values only.
    #>
    param([hashtable]$Environment = @{}, [hashtable]$Recorded = @{})
    $out = @{}
    foreach ($src in @($Recorded, $Environment)) {
        if (-not $src) { continue }
        foreach ($k in @($src.Keys)) { if ("$k" -match '^(?i)PIM_Bootstrap_(Cpu|Memory|ReplicaTimeout)_[A-Za-z0-9]+$' -and -not [string]::IsNullOrWhiteSpace([string]$src[$k])) { $out["$k"] = "$($src[$k])".Trim() } }
    }
    return $out
}

function Get-PimJobSizeCommand {
    <# PURE. The exact az command that sets a job to a size. #>
    param([string]$SubscriptionId, [string]$ResourceGroup, [string]$JobName = 'ca-pim-tick', [Parameter(Mandatory)][string]$Cpu, [Parameter(Mandatory)][string]$Memory, [int]$ReplicaTimeout = 0)
    $m = ConvertTo-PimJobMemoryGi $Memory
    $ms = if ($null -ne $m) { ('{0}Gi' -f $m.ToString('0.##', [Globalization.CultureInfo]::InvariantCulture)) } else { $Memory }
    $c = ConvertTo-PimJobCpu $Cpu; $cs = if ($null -ne $c) { Format-PimJobCpu $c } else { $Cpu }
    $sub = if ("$SubscriptionId".Trim()) { " --subscription $SubscriptionId" } else { '' }
    $rg = if ("$ResourceGroup".Trim()) { $ResourceGroup } else { '<resource group>' }
    $t = if ($ReplicaTimeout -gt 0) { " --replica-timeout $ReplicaTimeout" } else { '' }
    return ("az containerapp job update$sub -g $rg -n $JobName --cpu $cs --memory $ms$t")
}

function Test-PimJobUndersized {
    <#
      PURE. Is the job below the tier for its RECORDED object count? @{ undersized; objects; want; have; command; reason }.
      want = the tier (Get-PimTenantSizedJobResources); a job at or above it in CPU, memory AND replicaTimeout is sized.
      OPEN-27 (3.0.50): the floor (2.0 CPU / 4.0Gi) holds at ANY size -- a small tenant, or no recorded count, at 0.5 / 1 IS
      undersized. A customer's own smaller size (PIM_Bootstrap_*_Tick, recorded on the job: -Settings) is NOT flagged.
    #>
    param([AllowNull()]$Counts, [AllowNull()][object]$Cpu, [AllowNull()][object]$Memory, [int]$ReplicaTimeout = 0,
          [string]$SubscriptionId, [string]$ResourceGroup, [string]$JobName = 'ca-pim-tick', [hashtable]$Settings = @{})
    $objects = Get-PimTenantObjectTotal -Counts $Counts
    $tier = Get-PimTenantSizedJobResources -Job $JobName -Counts $Counts
    $hc = ConvertTo-PimJobCpu $Cpu; $hm = ConvertTo-PimJobMemoryGi $Memory
    $have = ('{0} CPU / {1}, replicaTimeout {2} s' -f $(if ($null -ne $hc) { Format-PimJobCpu $hc } else { '?' }), $(if ($null -ne $hm) { Format-PimJobMemory $hm } else { '?' }), $ReplicaTimeout)
    $who = $(if ($null -eq $Counts) { 'no recorded tenant size -- the floor for every tenant' } else { ('{0:N0} objects' -f $objects) })
    if (-not $tier) { return [pscustomobject]@{ undersized = $false; objects = $objects; want = $null; have = $have; command = ''; reason = $(if ($objects -gt 0) { ('{0:N0} objects -- the default size is right' -f $objects) } else { 'no recorded tenant size' }) } }
    # the customer's own size wins (framework 12.16): a job at the size the customer set is never called undersized
    # (CPU / memory only: the run limit is always the 7-day maximum, framework 12.24 -- a short one is still flagged)
    $sfx = Get-PimJobSettingSuffix -Job $JobName
    if ($Settings -and ($Settings.ContainsKey("PIM_Bootstrap_Cpu_$sfx") -or $Settings.ContainsKey("PIM_Bootstrap_Memory_$sfx"))) {
        $cs = Get-PimContainerJobResources -Job $JobName -Counts $Counts -Settings $Settings
        if ($cs.Source -eq 'customer') {
            $shortTo = ($ReplicaTimeout -gt 0 -and $ReplicaTimeout -lt [int]$cs.ReplicaTimeout)
            $cmdC = $(if ($shortTo) { Get-PimJobSizeCommand -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -JobName $JobName -Cpu $cs.Cpu -Memory $cs.Memory -ReplicaTimeout $cs.ReplicaTimeout } else { '' })
            return [pscustomobject]@{ undersized = [bool]$shortTo; objects = $objects; want = ('{0} CPU / {1}, replicaTimeout {2} s (the customer''s size)' -f $cs.Cpu, $cs.Memory, $cs.ReplicaTimeout); have = $have; command = $cmdC
                reason = ('{0}; the job runs {1} -- the size the customer set (PIM_Bootstrap_*_{2}) wins{3}' -f $who, $have, $sfx, $(if ($shortTo) { "; its run limit is below the 7-day maximum ($($cs.ReplicaTimeout) s)" } else { '' })) }
        }
    }
    $want = ('{0} CPU / {1}, replicaTimeout {2} s' -f $tier.Cpu, $tier.Memory, $tier.ReplicaTimeout)
    $low = ($null -eq $hc -or $null -eq $hm -or $hc -lt [double](ConvertTo-PimJobCpu $tier.Cpu) -or $hm -lt [double](ConvertTo-PimJobMemoryGi $tier.Memory) -or ($ReplicaTimeout -gt 0 -and $ReplicaTimeout -lt [int]$tier.ReplicaTimeout))
    $cmd = Get-PimJobSizeCommand -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -JobName $JobName -Cpu $tier.Cpu -Memory $tier.Memory -ReplicaTimeout $tier.ReplicaTimeout
    return [pscustomobject]@{ undersized = [bool]$low; objects = $objects; want = $want; have = $have; command = $(if ($low) { $cmd } else { '' })
        reason = $(if ($low) { ('{0} needs {1}; the job runs {2}' -f $who, $want, $have) } else { ('{0}; the job runs {1} (tier {2})' -f $who, $have, $want) }) }
}

function Get-PimTenantSizingTags {
    <# PURE. The tags that RECORD a sizing on the job (Azure resource tags: the update, the verify and the environment report read them). #>
    param([AllowNull()]$Counts, [Parameter(Mandatory)][object]$Size, [string]$CountSource = 'graph', [datetime]$NowUtc = [datetime]::UtcNow)
    $g = { param($k) $v = $null; if ($Counts -is [System.Collections.IDictionary]) { if ($Counts.Contains($k)) { $v = $Counts[$k] } } elseif ($Counts -and $Counts.PSObject.Properties[$k]) { $v = $Counts.$k }; if ($null -eq $v) { '' } else { "$v" } }
    $p = $script:PimTenantSizingTagPrefix
    $t = [ordered]@{}
    $t["${p}users"] = & $g 'Users'; $t["${p}groups"] = & $g 'Groups'; $t["${p}sps"] = & $g 'ServicePrincipals'
    $t["${p}objects"] = $(if ($null -ne $Counts) { "$(Get-PimTenantObjectTotal -Counts $Counts)" } else { '' })
    $t["${p}counted"] = "$CountSource"
    $t["${p}size"] = ('{0}/{1}/{2}' -f $Size.Cpu, $Size.Memory, $Size.ReplicaTimeout)
    $t["${p}source"] = "$($Size.Source)"
    $ov = $Size.Override
    $t["${p}override"] = $(if ($ov -and $ov.Count) { (@($ov.Keys | ForEach-Object { "$($_):$($ov[$_])" }) -join '+') } else { '' })
    $t["${p}utc"] = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
    return $t
}

function ConvertFrom-PimTenantSizingTags {
    <# PURE. The recorded sizing from a job's tags: @{ recorded; counts @{Users;Groups;ServicePrincipals}; objects; size; source; counted; sizedUtc; settings }. #>
    param([AllowNull()]$Tags, [string]$Job = 'ca-pim-tick')
    $p = $script:PimTenantSizingTagPrefix
    $gt = { param($k) $v = $null; if ($null -eq $Tags) { return '' }; if ($Tags -is [System.Collections.IDictionary]) { if ($Tags.Contains($k)) { $v = $Tags[$k] } } elseif ($Tags.PSObject.Properties[$k]) { $v = $Tags.$k }; if ($null -eq $v) { '' } else { "$v".Trim() } }
    $num = { param($s) $n = 0L; if ([long]::TryParse("$s", [ref]$n)) { $n } else { $null } }
    $u = & $num (& $gt "${p}users"); $gr = & $num (& $gt "${p}groups"); $sp = & $num (& $gt "${p}sps")
    $recorded = ($null -ne $u -or $null -ne $gr -or $null -ne $sp)
    $counts = if ($recorded) { @{ Users = [long]$u; Groups = [long]$gr; ServicePrincipals = [long]$sp } } else { $null }
    $settings = @{}
    $ov = & $gt "${p}override"
    if ($ov) {
        $sfx = Get-PimJobSettingSuffix -Job $Job
        # 'Cpu:2.0+Memory:4.0Gi' -- no ';' ',' '=' or '&': the tags go through az.cmd, where cmd.exe splits on those
        foreach ($kv in @($ov -split '\+' | Where-Object { $_ -match ':' })) { $k, $v = $kv -split ':', 2; $settings[('PIM_Bootstrap_{0}_{1}' -f $k.Trim(), $sfx)] = $v.Trim() }
    }
    return [pscustomobject]@{ recorded = $recorded; counts = $counts; objects = $(if ($recorded) { Get-PimTenantObjectTotal -Counts $counts } else { $null })
        size = (& $gt "${p}size"); source = (& $gt "${p}source"); counted = (& $gt "${p}counted"); sizedUtc = (& $gt "${p}utc"); settings = $settings }
}

function Get-PimTenantObjectCounts {
    <#
      The tenant's users, groups and service principals by Microsoft Graph $count (ConsistencyLevel: eventual).
      -GraphGet { param($Path) } returns the raw answer (an integer, or text) for '/users/$count' etc. -- the caller mints the
      token and sends the ConsistencyLevel header. Never throws: @{ ok; Users; Groups; ServicePrincipals; Objects; error }.
    #>
    param([Parameter(Mandatory)][scriptblock]$GraphGet)
    $out = [ordered]@{ ok = $false; Users = $null; Groups = $null; ServicePrincipals = $null; Objects = $null; error = '' }
    try {
        foreach ($pair in @(@('Users', '/users/$count'), @('Groups', '/groups/$count'), @('ServicePrincipals', '/servicePrincipals/$count'))) {
            $raw = & $GraphGet $pair[1]
            $n = 0L
            if (-not [long]::TryParse(("$raw".Trim().Trim([char]0xFEFF)), [ref]$n)) { throw ("{0} did not answer a number ('{1}')" -f $pair[1], "$raw".Trim()) }
            $out[$pair[0]] = $n
        }
        $out.Objects = Get-PimTenantObjectTotal -Counts $out
        $out.ok = $true
    } catch { $out.error = (("$($_.Exception.Message)" -split "`n")[0]).Trim() }
    return [pscustomobject]$out
}

function Get-PimMemberCountRead {
    <#
      PURE (the Graph read is a seam). COUNT-ANOMALY-98edba45 (2026-11-05): the enabled-MEMBER count is an advanced query
      on Graph's eventually consistent index. On a tenant whose on-prem sync was still writing (day one: 6981 users, 668
      enabled members; the next day 6182, right) it read far too low, and Invardia flagged a 3x jump. Rule:
        - read once (-Read returns a number or $null);
        - SUSPECT when it is above the unfiltered -Total (impossible), or the total is >= 100 and >= 3x the members:
          read ONCE more and keep the second answer (a true low value simply reads the same again);
        - a member count above the total after the re-read is left out ($null), never recorded.
      Returns @{ value; reread; note }.
    #>
    param([Parameter(Mandatory)][scriptblock]$Read, [AllowNull()][object]$Total)
    $t = $null; $tt = 0L; if ($null -ne $Total -and [long]::TryParse("$Total", [ref]$tt)) { $t = $tt }
    $suspect = { param($m) $null -ne $m -and $null -ne $t -and ($m -gt $t -or ($t -ge 100 -and $t -ge (3 * [long]$m))) }
    $v = & $Read
    if (-not (& $suspect $v)) { return [pscustomobject]@{ value = $v; reread = $false; note = '' } }
    $first = $v
    $v = & $Read
    $note = "enabled members read $first against $t users -- read again: $v"
    if ($null -ne $v -and $null -ne $t -and $v -gt $t) { return [pscustomobject]@{ value = $null; reread = $true; note = "$note (above the total: left out)" } }
    return [pscustomobject]@{ value = $v; reread = $true; note = $note }
}

function Resolve-PimSqlServiceObjective {
    <#
      PURE. A database's REAL service objective from an ARM GET. TRAP (measured live 2026-10-09): for a DTU database
      sku.name is the TIER name ("Standard", "Basic"), not "S0"/"S1" -- comparing on it reads every Standard database as an
      unknown tier. Order: properties.currentServiceObjectiveName; else sku.name when it IS an objective (S0, P1, GP_Gen5_2);
      else sku.tier/sku.name 'Basic' -> Basic; else a Standard sku.capacity in DTU (10 S0, 20 S1, 50 S2, 100 S3, 200 S4,
      400 S6, 800 S7, 1600 S9, 3000 S12); else '' (unknown -- the plan changes nothing).
    #>
    param([AllowNull()][object]$Database)
    if ($null -eq $Database) { return '' }
    $so = "$($Database.properties.currentServiceObjectiveName)".Trim()
    if ($so) { return $so }
    $sn = "$($Database.sku.name)".Trim(); $st = "$($Database.sku.tier)".Trim()
    if ($sn -and $sn -notmatch '^(?i)(Standard|Basic|Premium|GeneralPurpose|BusinessCritical|Hyperscale)$') { return $sn }
    if ($sn -match '^(?i)basic$' -or $st -match '^(?i)basic$') { return 'Basic' }
    if ($sn -match '^(?i)standard$' -or $st -match '^(?i)standard$') {
        $map = @{ 10 = 'S0'; 20 = 'S1'; 50 = 'S2'; 100 = 'S3'; 200 = 'S4'; 400 = 'S6'; 800 = 'S7'; 1600 = 'S9'; 3000 = 'S12' }
        $cap = 0; if ([int]::TryParse("$($Database.sku.capacity)", [ref]$cap) -and $map.ContainsKey($cap)) { return $map[$cap] }
    }
    return ''
}

function Get-PimSqlTierPlan {
    <#
      PURE. The SQL main database's tier + max size (PIM REQUIREMENTS 100.31 / 100.37 / 100.114; owner 2026-10-12: "S3 at
      every ring 1+2 install" -- PIM's database is S3 (Standard) with a 250 GB max size, for every edition; the earlier
      S0 default and the "Pro = S2" rule before it are gone).
      TIER, raise only:  Basic, S0, S1, S2 -> S3 (-Target; default = the product default).  S3 and every higher Standard
        tier -> kept (never lowered, never raised).
        Premium (P*), vCore (GP_*, BC_*, HS_*), serverless, an elastic pool, or unknown -> none (not ours to change)
        PINNED (-Pin = the database's 'pim-sql-tier-pin' tag, e.g. S0): the tier is NEVER changed (not even Basic -> S3).
        The tag holds a tier name only: nothing in it tells a customer's pin from one written at the product's earlier
        default, so a pin BELOW the default is not overridden -- it is reported: pinnedBelowDefault = $true and pinNote =
        "database is pinned at <tier>, the new default is S3 - not changed" (support moves it: Set-PimSqlTier -Tier S3 -Pin).
      MAX SIZE: every Standard S-tier database (incl. the one this plan raises, and a pinned one) below 250 GB
      (268435456000 bytes) -> maxSizeAction 'set'. A tier raise does NOT grow the max size by itself (measured: an S2 with
      Basic's 2 GB limit filled up -> "has reached its size quota" on every write), so a raise FROM Basic always includes it.
      Never lowered; never on Basic staying Basic, Premium, vCore or a pool; an unread max size (not raised from Basic) ->
      not changed. -Pro is accepted and ignored (kept for callers; there is no Pro tier rule any more).
      Returns @{ action ('raise'|'none'); target; current; pinned; reason; maxSizeAction ('set'|'none'); maxSizeBytes;
                 currentMaxSizeBytes; defaultTier; pinnedBelowDefault; pinNote }.
    #>
    param([AllowNull()][string]$Current, [bool]$Pro, [string]$Target = '', [AllowNull()][string]$ElasticPool,
          [AllowNull()][object]$CurrentMaxSizeBytes = $null, [AllowNull()][string]$Pin = $null)
    $c = "$Current".Trim()
    $pinV = "$Pin".Trim()
    if (-not "$Target".Trim()) { $Target = Get-PimSqlDefaultTier }
    $Target = "$Target".Trim().ToUpperInvariant()
    $maxWant = Get-PimSqlDefaultMaxSizeBytes
    $pinLow = $false; $pinNote = ''
    $curMax = $null; $tmp = 0L; if ($null -ne $CurrentMaxSizeBytes -and [int64]::TryParse("$CurrentMaxSizeBytes", [ref]$tmp) -and $tmp -gt 0) { $curMax = $tmp }
    $out = { param($act, $tgt, $why)
        # the max size for the tier the database ends on
        $end = $(if ($act -eq 'raise') { $tgt } else { $c })
        $ms = 'none'; $mwhy = ''
        if (-not "$ElasticPool".Trim() -and $end -match '^(?i)S\d+$') {
            if ($null -ne $curMax) {
                if ($curMax -lt $maxWant) { $ms = 'set'; $mwhy = ("max size {0:N0} GB -> 250 GB (every Standard database; never lowered)" -f ($curMax / 1GB)) }
                else { $mwhy = ("max size {0:N0} GB -- kept (never lowered)" -f ($curMax / 1GB)) }
            } elseif ($act -eq 'raise' -and $c -match '^(?i)basic$') { $ms = 'set'; $mwhy = 'max size -> 250 GB (a raise from Basic keeps Basic''s 2 GB limit otherwise)' }
            else { $mwhy = 'max size not read -- not changed' }
        }
        $r = $why; if ($mwhy) { $r = "$why; $mwhy" }
        [pscustomobject]@{ action = $act; target = $tgt; current = $c; pinned = [bool]$pinV; reason = $r; maxSizeAction = $ms; maxSizeBytes = $(if ($ms -eq 'set') { $maxWant } else { $curMax }); currentMaxSizeBytes = $curMax
                           defaultTier = $Target; pinnedBelowDefault = [bool]$pinLow; pinNote = "$pinNote" }
    }
    if ("$ElasticPool".Trim()) { return (& $out 'none' $c "in the elastic pool '$ElasticPool' -- not changed") }
    $rank = { param($s) if ($s -match '^(?i)basic$') { return 0 }; if ($s -match '^(?i)S(\d+)$') { return (1 + [int]$Matches[1]) }; return -1 }
    $have = & $rank $c; $want = & $rank $Target
    if ($pinV) {
        # A pin is never overridden (the tag cannot say WHO pinned it). Below the default it is reported, in these words.
        if ($have -ge 0 -and $have -lt $want) {
            $pinLow = $true
            $pinNote = "database is pinned at $c, the new default is $Target - not changed"
            return (& $out 'none' $c "pinned at $c (pim-sql-tier-pin = '$pinV'), the new default is $Target - not changed (a pinned tier is never changed; to move it: Set-PimSqlTier.ps1 -Tier $Target -Pin)")
        }
        return (& $out 'none' $c "tier pinned to '$pinV' (pim-sql-tier-pin) -- the tier is never changed")
    }
    if ($have -lt 0) { return (& $out 'none' $c $(if ($c) { "'$c' is not a Basic/Standard objective -- not changed (never lowered)" } else { 'the current size could not be read -- not changed' })) }
    if ($have -ge $want) { return (& $out 'none' $c "$c is already at or above $Target -- kept (never lowered)") }
    return (& $out 'raise' $Target "$c -> $Target (the product default; never Basic; raise only)")
}

# =====================================================================================================================
# THE UPDATE'S HALF (ca-pim-update, tools/pim-engine/update-job-entry.ps1). Seams: -Arm { param($Method, $Path, $Body) }
# returns the parsed ARM answer (the updater passes Invoke-PimArm); -Graph { param($Path) } returns a $count answer.
# Both NEVER throw: they return @{ ok; changed; detail; log[] } so a sizing problem never turns a good roll red.
# =====================================================================================================================
$script:PimTenantSizingAcaApi = '2024-03-01'
$script:PimTenantSizingSqlApi = '2021-11-01'

function Invoke-PimJobSizingUpdate {
    <#
      Size ONE job on an update, by the same rule as the install:
        counts   -- Graph $count (-Graph), else the counts RECORDED on the job (pim-sizing-* tags), else none (default size)
        evidence -- -Runs (pim.Settings JobRunHistory) since the job was last sized: a run that ran out of memory or time
                    raises the job one band + one timeout step (Get-PimJobSelfCorrection)
        settings -- -Environment (the update job's env: PIM_Bootstrap_*_<Job>) over the override recorded on the job
      Writes ONLY when the size changes: one PATCH of the job (resources of its containers + configuration.replicaTimeout),
      then the sizing tags (Merge). Returns @{ ok; changed; size; detail; log[] }.
    #>
    param([Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$ResourceGroup, [string]$JobName = 'ca-pim-tick',
          [Parameter(Mandatory)][scriptblock]$Arm, [scriptblock]$Graph, [object[]]$Runs = @(), [hashtable]$Environment = @{},
          [datetime]$NowUtc = [datetime]::UtcNow,
          # 2.4.544: the counts the TICK recorded (pim.Settings 'TenantObjectCounts') -- used when the updater's own Graph
          # count is refused (its identity has no directory read right: HTTP 403 on every environment, 2026-10-09).
          [AllowNull()][object]$StoredCounts = $null,
          # 100.50: the job PATCH and the tags PATCH wait out "HTTP 409 ContainerAppsJobOperationInProgress" (the tick roll
          # one step earlier is still provisioning) through Invoke-PimArmBusyRetry (PIM-ArmContainerApps.ps1). -Sleep: test seam.
          [int[]]$BusyWaits = @(20, 20, 20, 20, 20, 20), [scriptblock]$Sleep)
    $log = New-Object System.Collections.Generic.List[string]
    $jobWho = $(if ($JobName -eq 'ca-pim-tick') { 'the tick job' } else { "the job $JobName" })
    $path = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.App/jobs/$JobName"
    try {
        $job = & $Arm 'GET' "$path`?api-version=$($script:PimTenantSizingAcaApi)" $null
        if (-not $job) { return [pscustomobject]@{ ok = $false; changed = $false; size = $null; detail = "job '$JobName' not found"; log = @() } }
        $containers = @($job.properties.template.containers)
        $r0 = $containers[0].resources
        $cur = @{ Cpu = "$($r0.cpu)"; Memory = "$($r0.memory)"; ReplicaTimeout = "$($job.properties.configuration.replicaTimeout)" }
        $rec = ConvertFrom-PimTenantSizingTags -Tags $job.tags -Job $JobName
        $counts = $null; $countSrc = 'none'
        if ($Graph) {
            $cnt = Get-PimTenantObjectCounts -GraphGet $Graph
            if ($cnt.ok) { $counts = @{ Users = $cnt.Users; Groups = $cnt.Groups; ServicePrincipals = $cnt.ServicePrincipals }; $countSrc = 'graph' }
            elseif ("$($cnt.error)" -match '\b403\b|Authorization_RequestDenied|Insufficient privileges') { $log.Add('the updater identity may not count tenant objects (Graph 403) -- using the counts the engine recorded') }
            else { $log.Add("Graph count failed ($($cnt.error))") }
        }
        if (-not $counts -and $StoredCounts -and $null -ne $StoredCounts.Users -and $null -ne $StoredCounts.Groups -and $null -ne $StoredCounts.ServicePrincipals) {
            $counts = @{ Users = [long]$StoredCounts.Users; Groups = [long]$StoredCounts.Groups; ServicePrincipals = [long]$StoredCounts.ServicePrincipals }; $countSrc = 'engine'
            $log.Add("counts recorded by the engine ($($StoredCounts.recordedUtc)): $($counts.Users) users, $($counts.Groups) groups, $($counts.ServicePrincipals) service principals")
        }
        if (-not $counts -and $rec.recorded) { $counts = $rec.counts; $countSrc = 'recorded'; $log.Add("using the counts recorded on the job ($($rec.sizedUtc))") }
        $sc = Get-PimJobSelfCorrection -Runs $Runs -SinceUtc $rec.sizedUtc
        $settings = Get-PimJobSizingSettings -Environment $Environment -Recorded $rec.settings
        $size = Get-PimContainerJobResources -Job $JobName -Counts $counts -Current $cur -SelfCorrect $sc -Settings $settings
        foreach ($n in @($size.Notes)) { $log.Add($n) }
        $same = ((ConvertTo-PimJobCpu $cur.Cpu) -eq (ConvertTo-PimJobCpu $size.Cpu) -and (ConvertTo-PimJobMemoryGi $cur.Memory) -eq (ConvertTo-PimJobMemoryGi $size.Memory) -and "$($cur.ReplicaTimeout)" -eq "$($size.ReplicaTimeout)")
        $tags = Get-PimTenantSizingTags -Counts $counts -Size $size -CountSource $countSrc -NowUtc $NowUtc
        if ($same) {
            # Unchanged: the tags are refreshed only when nothing is recorded yet, so the self-correct window ('pim-sizing-utc')
            # keeps meaning "since the job was last RESIZED" and old evidence is not counted twice.
            if (-not $rec.recorded -and $counts) { try { [void](Invoke-PimArmBusyRetry -Waits $BusyWaits -Sleep $Sleep -Write { & $Arm 'PATCH' "$path/providers/Microsoft.Resources/tags/default?api-version=2021-04-01" @{ operation = 'Merge'; properties = @{ tags = $tags } } }) } catch { $log.Add("tags not recorded: $($_.Exception.Message)") } }
            return [pscustomobject]@{ ok = $true; changed = $false; size = $size; selfCorrect = $sc
                detail = ("{0}: {1} CPU / {2}, replicaTimeout {3} s -- unchanged ({4}; counts: {5})" -f $JobName, $size.Cpu, $size.Memory, $size.ReplicaTimeout, $size.Source, $countSrc); log = @($log.ToArray()) }
        }
        # The PATCH body from a job object: its containers' resources + configuration.replicaTimeout, configuration WITHOUT its
        # secrets (a GET returns them without values, and sending them back would blank them).
        $sizeBody = {
            param($j)
            foreach ($c in @($j.properties.template.containers)) {
                if ($null -eq $c.resources) { $c | Add-Member -NotePropertyName resources -NotePropertyValue ([pscustomobject]@{}) -Force }
                $c.resources | Add-Member -NotePropertyName cpu -NotePropertyValue ([double](ConvertTo-PimJobCpu $size.Cpu)) -Force
                $c.resources | Add-Member -NotePropertyName memory -NotePropertyValue "$($size.Memory)" -Force
            }
            $cfg = [ordered]@{}
            foreach ($p in @($j.properties.configuration.PSObject.Properties)) { if ($p.Name -ne 'secrets') { $cfg[$p.Name] = $p.Value } }
            $cfg['replicaTimeout'] = [int]$size.ReplicaTimeout
            @{ properties = @{ configuration = $cfg; template = $j.properties.template } }
        }
        # 100.50: the tick was rolled one step earlier, so its provisioning is often still running -- wait it out, bounded.
        # After a wait the job is READ AGAIN: a template read before the roll finished must never be written back over it.
        $sizeTry = @{ n = 0 }
        [void](Invoke-PimArmBusyRetry -Waits $BusyWaits -Sleep $Sleep -Write {
            $sizeTry.n++
            $jw = $job; if ($sizeTry.n -gt 1) { $fresh = & $Arm 'GET' "$path`?api-version=$($script:PimTenantSizingAcaApi)" $null; if ($fresh) { $jw = $fresh } }
            & $Arm 'PATCH' "$path`?api-version=$($script:PimTenantSizingAcaApi)" (& $sizeBody $jw) })
        try { [void](Invoke-PimArmBusyRetry -Waits $BusyWaits -Sleep $Sleep -Write { & $Arm 'PATCH' "$path/providers/Microsoft.Resources/tags/default?api-version=2021-04-01" @{ operation = 'Merge'; properties = @{ tags = $tags } } }) } catch { $log.Add("tags not recorded: $($_.Exception.Message)") }
        return [pscustomobject]@{ ok = $true; changed = $true; size = $size; selfCorrect = $sc
            detail = ("{0}: {1} CPU / {2}, replicaTimeout {3} s -> {4} CPU / {5}, replicaTimeout {6} s ({7}; counts: {8})" -f $JobName, $cur.Cpu, $cur.Memory, $cur.ReplicaTimeout, $size.Cpu, $size.Memory, $size.ReplicaTimeout, $size.Source, $countSrc)
            log = @($log.ToArray()) }
    } catch {
        # 100.50: still busy after the bounded wait = a plain note, never "not sized: <ARM error>" and never a failed update.
        if ("$($_.Exception.Message)" -match '(?i)OperationInProgress|active provisioning operation') {
            return [pscustomobject]@{ ok = $false; changed = $false; busy = $true; size = $null; detail = "$jobWho was busy; sizing retried next update"; log = @($log.ToArray()) }
        }
        return [pscustomobject]@{ ok = $false; changed = $false; size = $null; detail = "$JobName not sized: $((("$($_.Exception.Message)") -split "`n")[0])"; log = @($log.ToArray()) }
    }
}

function Invoke-PimJobRunLimitUpdate {
    <#
      framework 12.24 JOB-RUN-LIMIT (owner 2026-10-15): EVERY PIM Container Apps job in this install's resource group gets
      Azure's maximum run limit ($script:PimJobRunLimitSeconds = 7 days) on every update -- the tick, the updater itself (its
      NEXT execution), pull / publish, db-init, support SQL, as-built. Raise only: a job already at the limit is not written.
      A job is PIM's when its name carries 'pim' (the install's own resource group; nothing else is touched).
      One PATCH per job: its configuration WITHOUT secrets (a GET returns them without values; sending them back would blank
      them) + its template as read, replicaTimeout set. Busy (OperationInProgress) is waited out, then left for the next
      update. Never throws. Returns @{ ok; changed[]; unchanged[]; failed[]; detail; log[] }.
    #>
    param([Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$ResourceGroup,
          [Parameter(Mandatory)][scriptblock]$Arm, [int[]]$BusyWaits = @(20, 20, 20, 20, 20, 20), [scriptblock]$Sleep)
    $limit = [int]$script:PimJobRunLimitSeconds
    $log = New-Object System.Collections.Generic.List[string]
    $changed = New-Object System.Collections.Generic.List[string]; $same = New-Object System.Collections.Generic.List[string]; $failed = New-Object System.Collections.Generic.List[string]
    $base = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.App/jobs"
    try { $list = & $Arm 'GET' "$base`?api-version=$($script:PimTenantSizingAcaApi)" $null }
    catch { return [pscustomobject]@{ ok = $false; changed = @(); unchanged = @(); failed = @(); detail = "run limit: the jobs could not be listed ($((("$($_.Exception.Message)") -split "`n")[0]))"; log = @() } }
    $jobs = @(@($list.value) | Where-Object { $_ -and "$($_.name)" -match '(?i)pim' })
    foreach ($j in $jobs) {
        $name = "$($j.name)"
        $cur = 0; [void][int]::TryParse("$($j.properties.configuration.replicaTimeout)", [ref]$cur)
        if ($cur -ge $limit) { $same.Add($name); continue }
        $path = "$base/$name`?api-version=$($script:PimTenantSizingAcaApi)"
        $body = {
            param($jo)
            $cfg = [ordered]@{}
            foreach ($p in @($jo.properties.configuration.PSObject.Properties)) { if ($p.Name -ne 'secrets') { $cfg[$p.Name] = $p.Value } }
            $cfg['replicaTimeout'] = $limit
            @{ properties = @{ configuration = $cfg; template = $jo.properties.template } }
        }
        $try = @{ n = 0 }
        try {
            [void](Invoke-PimArmBusyRetry -Waits $BusyWaits -Sleep $Sleep -Write {
                $try.n++
                # The full job is read for the write (a list item may be abridged), and read AGAIN after a busy wait.
                $jw = & $Arm 'GET' $path $null
                if (-not $jw) { throw "job '$name' not found" }
                & $Arm 'PATCH' $path (& $body $jw) })
            $changed.Add($name); $log.Add(("{0}: replicaTimeout {1} s -> {2} s" -f $name, $cur, $limit))
        } catch {
            $m = (("$($_.Exception.Message)") -split "`n")[0]
            $failed.Add($name)
            $log.Add($(if ($m -match '(?i)OperationInProgress|active provisioning operation') { "${name}: busy -- raised on the next update" } else { "${name}: not raised ($m)" }))
        }
    }
    $detail = ('run limit {0} s (7 days): {1} raised{2}, {3} already at it{4}' -f $limit, $changed.Count,
        $(if ($changed.Count) { " ($($changed -join ', '))" } else { '' }), $same.Count, $(if ($failed.Count) { "; NOT raised: $($failed -join ', ')" } else { '' }))
    return [pscustomobject]@{ ok = (-not $failed.Count); changed = @($changed.ToArray()); unchanged = @($same.ToArray()); failed = @($failed.ToArray()); detail = $detail; log = @($log.ToArray()) }
}

function Invoke-PimManagerAppSizeUpdate {
    <#
      The update's half of the Manager web app's size (framework 12.16 CONVERGE-DEFAULTS; PIM 100.114), for a run that did
      NOT roll the Manager (an environment ahead of its ring, or already on the target image). A run that DOES roll it
      carries the size in the roll's own write (Invoke-PimAcaRoll -Resize) -- this function then finds nothing to change.
      GET the app -> Get-PimManagerAppResize (raise only; the customer's PIM_Bootstrap_*_Manager wins) -> when the size
      changes: ONE PATCH of the whole template that came back (read-modify-write; every env var, probe and scale rule
      stays) with the app's tags + the sizing record, a busy app waited out (Invoke-PimArmBusyRetry; the app is read AGAIN
      after a wait), then the app READ BACK. A raise makes a new revision: the Manager restarts once.
      Never throws. Returns @{ ok; changed; detail; log[]; size }.
    #>
    param([Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][string]$ResourceGroup, [string]$AppName = 'ca-pim-manager',
          [string]$ContainerName, [Parameter(Mandatory)][scriptblock]$Arm, [hashtable]$Environment = @{}, [datetime]$NowUtc = [datetime]::UtcNow,
          [int[]]$BusyWaits = @(20, 20, 20, 20, 20, 20), [scriptblock]$Sleep, [int]$ReadBackAttempts = 6, [int]$ReadBackDelaySec = 10)
    $log = New-Object System.Collections.Generic.List[string]
    $path = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.App/containerApps/$AppName"
    $api = $script:PimTenantSizingAcaApi; if (-not $api) { $api = '2024-03-01' }
    $pick = {
        param($a)
        $cs = @($a.properties.template.containers)
        if ("$ContainerName".Trim()) { return (@($cs | Where-Object { "$($_.name)" -eq "$ContainerName".Trim() }) | Select-Object -First 1) }
        if ($cs.Count -eq 1) { return $cs[0] }
        return $null
    }
    try {
        $app = & $Arm 'GET' "$path`?api-version=$api" $null
        if (-not $app) { return [pscustomobject]@{ ok = $false; changed = $false; size = $null; detail = "the Manager web app '$AppName' was not found -- its size was not checked"; log = @() } }
        $target = & $pick $app
        if (-not $target) { return [pscustomobject]@{ ok = $false; changed = $false; size = $null; detail = "the Manager web app '$AppName' has $(@($app.properties.template.containers).Count) containers and none was named -- its size was not changed"; log = @() } }
        $rz = Get-PimManagerAppResize -Container $target -App $app -Environment $Environment -NowUtc $NowUtc
        foreach ($n in @($rz.notes)) { $log.Add($n) }
        if (-not $rz.change) { return [pscustomobject]@{ ok = $true; changed = $false; size = $rz.size; detail = "$($rz.detail)"; log = @($log.ToArray()) } }
        $mgrTry = @{ n = 0 }
        [void](Invoke-PimArmBusyRetry -Waits $BusyWaits -Sleep $Sleep -Write {
            $mgrTry.n++
            $aw = $app
            if ($mgrTry.n -gt 1) { $fresh = & $Arm 'GET' "$path`?api-version=$api" $null; if ($fresh) { $aw = $fresh } }
            $tw = & $pick $aw
            $rw = Get-PimManagerAppResize -Container $tw -App $aw -Environment $Environment -NowUtc $NowUtc
            if (-not $rw.change) { return $null }     # someone else sized it while this run waited
            if ($null -eq $tw.resources) { $tw | Add-Member -NotePropertyName resources -NotePropertyValue ([pscustomobject]@{}) -Force }
            $tw.resources | Add-Member -NotePropertyName cpu -NotePropertyValue ([double](ConvertTo-PimJobCpu $rw.Cpu)) -Force
            $tw.resources | Add-Member -NotePropertyName memory -NotePropertyValue "$($rw.Memory)" -Force
            $body = @{ properties = @{ template = $aw.properties.template } }
            if ($rw.Tags) { $body['tags'] = $rw.Tags }
            & $Arm 'PATCH' "$path`?api-version=$api" $body })
        # read back: the size the app declares now (a GET right after the PATCH answers the new template at once)
        $backCpu = $null; $backMem = $null
        for ($ra = 1; $ra -le [Math]::Max(1, $ReadBackAttempts); $ra++) {
            try {
                $b = & $Arm 'GET' "$path`?api-version=$api" $null
                $bt = & $pick $b
                if ($bt -and $bt.resources) { $backCpu = ConvertTo-PimJobCpu $bt.resources.cpu; $backMem = ConvertTo-PimJobMemoryGi $bt.resources.memory }
                if ($null -ne $backCpu -and $null -ne $backMem) { break }
            } catch { }
            if ($ra -lt $ReadBackAttempts -and $ReadBackDelaySec -gt 0) { Start-Sleep -Seconds $ReadBackDelaySec }
        }
        $okBack = ($null -ne $backCpu -and $null -ne $backMem -and $backCpu -eq (ConvertTo-PimJobCpu $rz.Cpu) -and $backMem -eq (ConvertTo-PimJobMemoryGi $rz.Memory))
        return [pscustomobject]@{ ok = [bool]$okBack; changed = $true; size = $rz.size; log = @($log.ToArray())
            detail = ("{0} -- one write; it restarts once{1}" -f $rz.detail, $(if ($okBack) { '; read back' } else { ' -- the size did NOT read back; the next update tries again' })) }
    } catch {
        if ("$($_.Exception.Message)" -match '(?i)OperationInProgress|active provisioning operation') {
            return [pscustomobject]@{ ok = $false; changed = $false; busy = $true; size = $null; detail = 'the Manager web app was busy; its size is set by the next update'; log = @($log.ToArray()) }
        }
        return [pscustomobject]@{ ok = $false; changed = $false; size = $null; detail = "the Manager web app's size was not checked: $((("$($_.Exception.Message)") -split "`n")[0])"; log = @($log.ToArray()) }
    }
}

function Invoke-PimSqlTierUpdate {
    <#
      The update's half of the database rules, on EVERY update: read the main database over ARM and apply Get-PimSqlTierPlan
      -- below S3 -> S3 (raise only; owner 2026-10-12; never on a database tagged 'pim-sql-tier-pin') and the 250 GB max size
      of every Standard database (100.37): ONE PATCH carrying the sku and/or properties.maxSizeBytes, then the database read
      back and the max size before/after logged. A database PINNED below the default is not changed and is REPORTED:
      pinnedBelowDefault = $true and the detail starts "database is pinned at <tier>, the new default is S3 - not changed".
      -Server is the FQDN or name (searched in the subscription). -Pro is ignored. Never throws.
      OPEN-27 (3.0.50): the TIER raise follows -AllowTierRaise (default: Test-PimSqlTierUpdaterRaiseEnabled, ON -- owner
      2026-10-12, unchanged). Switched off by support, a database the plan would raise is NOT raised: belowDefault = $true,
      tierRaiseHeld = $true, and the detail says "database <db> is <tier>, below the product tier S3 -- not raised by the
      updater ...". Its 250 GB max size is still set (every Standard tier includes 250 GB).
      Returns @{ ok; changed; detail; maxSizeBefore; maxSizeAfter; pinnedBelowDefault; belowDefault; tierRaiseHeld; tierRaised;
                 tierBefore; tierAfter; defaultTier }.
    #>
    param([Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][AllowEmptyString()][string]$Server, [string]$Database = 'PimPlatform',
          [bool]$Pro, [Parameter(Mandatory)][scriptblock]$Arm, [int]$ReadBackAttempts = 6, [int]$ReadBackDelaySec = 10,
          [AllowNull()][object]$AllowTierRaise = $null)
    $raiseOn = $(if ($AllowTierRaise -is [bool]) { [bool]$AllowTierRaise } else { [bool](Test-PimSqlTierUpdaterRaiseEnabled) })
    $name =("$Server".Trim() -replace '^tcp:', '' -replace ',\d+$', '').Split('.')[0].ToLowerInvariant()
    if (-not $name) { return [pscustomobject]@{ ok = $false; changed = $false; detail = 'no SQL server name -- database size not checked' } }
    try {
        $list = & $Arm 'GET' "/subscriptions/$SubscriptionId/providers/Microsoft.Sql/servers?api-version=$($script:PimTenantSizingSqlApi)" $null
        $srv = @(@($list.value) | Where-Object { "$($_.name)".ToLowerInvariant() -eq $name }) | Select-Object -First 1
        if (-not $srv) { return [pscustomobject]@{ ok = $false; changed = $false; detail = "SQL server '$name' is not visible to the updater -- database size not checked" } }
        $dbPath = "$($srv.id)/databases/$Database"
        $db = & $Arm 'GET' "$dbPath`?api-version=$($script:PimTenantSizingSqlApi)" $null
        $curSo = Resolve-PimSqlServiceObjective -Database $db
        $pin = $null
        if ($db.tags) { if ($db.tags -is [System.Collections.IDictionary]) { if ($db.tags.Contains('pim-sql-tier-pin')) { $pin = "$($db.tags['pim-sql-tier-pin'])" } } elseif ($db.tags.PSObject.Properties['pim-sql-tier-pin']) { $pin = "$($db.tags.'pim-sql-tier-pin')" } }
        $plan = Get-PimSqlTierPlan -Current $curSo -ElasticPool "$($db.properties.elasticPoolId)" -CurrentMaxSizeBytes $db.properties.maxSizeBytes -Pin $pin
        $before = $plan.currentMaxSizeBytes
        # A pin below the default: never overridden, said in the owner's words so support can act (the tag cannot say who pinned it).
        $pinLow = [bool]$plan.pinnedBelowDefault
        $what = $(if ($pinLow) { "$($plan.pinNote) (database $Database, tag pim-sql-tier-pin = '$pin'; to move it: Set-PimSqlTier.ps1 -Tier $($plan.defaultTier) -Pin)" } else { "database $Database`: $($plan.reason)" })
        # OPEN-27: the tier raise is held (OFF until the owner decides) -- REPORTED, never applied. The max size still follows.
        $held = ($plan.action -eq 'raise' -and -not $raiseOn)
        $raise = ($plan.action -eq 'raise' -and $raiseOn)
        # a held raise leaves the tier as it is: the 250 GB max size only on a Standard S-tier (Basic stays at its 2 GB limit)
        $setMax = ($plan.maxSizeAction -eq 'set' -and (-not $held -or $curSo -match '^(?i)S\d+$'))
        if ($held) {
            $what = "database $Database is $curSo, below the product tier $($plan.defaultTier) -- not raised by the updater (its tier raise is switched off here; Set-PimSqlTier.ps1 -Tier $($plan.defaultTier) raises it)"
            if ($setMax) { $what += '; max size -> 250 GB' }
        }
        $belowDefault = [bool]($pinLow -or $plan.action -eq 'raise')
        if (-not $raise -and -not $setMax) { return [pscustomobject]@{ ok = $true; changed = $false; detail = $what; maxSizeBefore = $before; maxSizeAfter = $before; pinnedBelowDefault = $pinLow; belowDefault = $belowDefault; tierRaiseHeld = [bool]$held; tierBefore = $curSo; tierAfter = $curSo; defaultTier = $plan.defaultTier } }
        $body = @{}
        if ($raise) { $body['sku'] = @{ name = $plan.target; tier = 'Standard' } }
        if ($setMax) { $body['properties'] = @{ maxSizeBytes = [int64]$plan.maxSizeBytes } }
        [void](& $Arm 'PATCH' "$dbPath`?api-version=$($script:PimTenantSizingSqlApi)" $body)
        # read back: the max size before -> after (a tier change is online and can take minutes; the max size is immediate).
        # A GET right after a tier PATCH can answer 404 ResourceNotFound for a few seconds while the scale runs (measured
        # live 2026-10-09) -- transient: retried -ReadBackAttempts times, -ReadBackDelaySec apart.
        $after = $null; $tierAfter = ''
        for ($ra = 1; $ra -le [Math]::Max(1, $ReadBackAttempts); $ra++) {
            try {
                $db2 = & $Arm 'GET' "$dbPath`?api-version=$($script:PimTenantSizingSqlApi)" $null
                $t2 = 0L; if ($db2 -and [int64]::TryParse("$($db2.properties.maxSizeBytes)", [ref]$t2)) { $after = $t2 }
                if ($db2) { $tierAfter = Resolve-PimSqlServiceObjective -Database $db2 }
                break
            } catch {
                if ("$($_.Exception.Message)" -notmatch '(?i)\b404\b|ResourceNotFound|NotFound') { break }
                if ($ra -lt $ReadBackAttempts -and $ReadBackDelaySec -gt 0) { Start-Sleep -Seconds $ReadBackDelaySec }
            }
        }
        $fmt = { param($b) if ($null -eq $b) { 'unknown' } else { '{0:N0} GB' -f ($b / 1GB) } }
        $ms = " (max size {0} -> {1}, read back)" -f (& $fmt $before), (& $fmt $after)
        $okMax = (-not $setMax -or ($null -ne $after -and $after -ge [int64]$plan.maxSizeBytes))
        return [pscustomobject]@{ ok = $okMax; changed = $true; maxSizeBefore = $before; maxSizeAfter = $after; pinnedBelowDefault = $pinLow; belowDefault = [bool]($pinLow -or $held); tierRaiseHeld = [bool]$held; tierRaised = [bool]$raise; tierBefore = $curSo; tierAfter = $tierAfter; defaultTier = $plan.defaultTier
            detail = "$what$ms$(if ($raise) { " (tier change online; takes effect in minutes$(if ($tierAfter) { "; the database reads $tierAfter now" }))" })$(if (-not $okMax) { ' -- the max size did NOT read back as 250 GB; the next update tries again' })" }
    } catch {
        return [pscustomobject]@{ ok = $false; changed = $false; detail = "database size not checked: $((("$($_.Exception.Message)") -split "`n")[0])" }
    }
}

# ===== END inlined helper: ..\..\engine\_shared\PIM-TenantSizing.ps1 =====
$null = Start-PimScriptRun -Script 'Set-PimSqlTier'
try {

$api = '2021-11-01'
$maxWant = [int64]268435456000   # 250 GB (= Get-PimSqlDefaultMaxSizeBytes, the plan's own value)
$defaultTier = Get-PimSqlDefaultTier   # S3 -- the product tier (PIM 100.114); the plan raises to it and never lowers
$srvName = ("$Server".Trim() -replace '^tcp:', '' -replace ',\d+$', '').Split('.')[0].ToLowerInvariant()
if ($srvName -notmatch '^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$') { throw "Set-PimSqlTier: not a SQL server name: $Server" }
if ($Database -notmatch '^[^<>*%&:\\/?]{1,128}$') { throw "Set-PimSqlTier: not a database name: $Database" }
$dbPath = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.Sql/servers/$srvName/databases/$Database"

# --- how to reach ARM ------------------------------------------------------------------------------------------------------
$mode = ''
if ("$AdminSecret".Trim() -or "$AdminAppId".Trim()) {
    $ap = Resolve-PimMailSetupAuthMode -AdminAppId $AdminAppId -AdminSecret $AdminSecret
    if ($ap.reason) { throw "Set-PimSqlTier: $($ap.reason)" }
    if (-not "$TenantId".Trim()) { throw 'Set-PimSqlTier: -TenantId is needed with -AdminAppId + -AdminSecret.' }
    $mode = 'secret'
} elseif ("$TenantId".Trim()) {
    if (-not (Test-PimMsInteractiveHost)) { throw 'Set-PimSqlTier: this run signs in in the BROWSER, and this session is not interactive -- run it in a PowerShell window, or pass -AdminAppId + -AdminSecret.' }
    $mode = 'browser'
} else {
    # REQ 100.42 (no PowerShell modules): the ONLY session path is the Invardia Support-app session's REST shim, which is a
    # FUNCTION named Invoke-AzRestMethod. The Az.Accounts CMDLET of the same name is never used: the lookup takes
    # functions only, and the call goes through the resolved command object, so it cannot resolve to the module.
    $sqtShim = Get-Command -Name ('Invoke-' + 'AzRestMethod') -CommandType Function -ErrorAction SilentlyContinue | Select-Object -First 1
    if ($sqtShim) { $mode = 'session' }
    else { throw 'Set-PimSqlTier: pass -TenantId (browser sign-in, or with -AdminAppId + -AdminSecret), or run it in an Invardia Support-app session.' }
}

function Get-SqtToken {
    $WhatIfPreference = $false   # the sign-in is a READ the preview needs
    if ($mode -eq 'secret') { return (Get-PimMsAppToken -TenantId $TenantId -ClientId $AdminAppId -ClientSecret $AdminSecret -Resource 'arm') }
    return (Get-PimMsBrowserToken -Resource 'arm' -TenantId $TenantId)
}
function Invoke-SqtArm([string]$Method = 'GET', [string]$Path, $Body) {
    # Returns @{ status; json; text } and never throws on an HTTP status (a 404 / 5xx mid-scale is the caller's call).
    $WhatIfPreference = $false
    $payload = if ($null -ne $Body) { $Body | ConvertTo-Json -Depth 8 -Compress } else { $null }
    if ($mode -eq 'session') {
        $a = @{ Method = $Method; Path = $Path }; if ($null -ne $payload) { $a.Payload = $payload }
        $r = & $sqtShim @a
        $txt = if ($r.Content -is [byte[]]) { [Text.Encoding]::UTF8.GetString($r.Content) } else { "$($r.Content)" }
        $js = $null; if ($txt.Trim()) { try { $js = $txt | ConvertFrom-Json } catch { $js = $null } }
        return [pscustomobject]@{ status = [int]$r.StatusCode; json = $js; text = $txt }
    }
    $h = @{ Authorization = "Bearer $(Get-SqtToken)"; 'Content-Type' = 'application/json' }
    try {
        $a = @{ Method = $Method; Uri = "https://management.azure.com$Path"; Headers = $h }; if ($null -ne $payload) { $a.Body = $payload }
        $js = Invoke-RestMethod @a
        return [pscustomobject]@{ status = 200; json = $js; text = '' }
    } catch {
        $code = 0; try { $code = [int]$_.Exception.Response.StatusCode } catch { $code = 0 }
        return [pscustomobject]@{ status = $(if ($code) { $code } else { 599 }); json = $null; text = ("$($_.Exception.Message) $($_.ErrorDetails.Message)" -replace '\s+', ' ').Trim() }
    }
}
function Show-SqtDb([string]$Label, $Db) {
    $p = $Db.properties
    $tg = @(); if ($Db.tags) { foreach ($t in $Db.tags.PSObject.Properties) { $tg += "$($t.Name)=$($t.Value)" } }
    Write-Host ("  {0} {1} ({2}, {3} DTU), max size {4}, status {5}, pin {6}" -f $Label, (Resolve-PimSqlServiceObjective -Database $Db), "$($Db.sku.tier)", "$($Db.sku.capacity)",
        $(if ("$($p.maxSizeBytes)" -match '^\d+$') { '{0:N0} GB' -f ([int64]$p.maxSizeBytes / 1GB) } else { 'unknown' }), "$($p.status)",
        $(if ($Db.tags -and $Db.tags.PSObject.Properties['pim-sql-tier-pin']) { "$($Db.tags.'pim-sql-tier-pin')" } else { 'none' }))
}

Write-Host ('=' * 78) -ForegroundColor Cyan
Write-Host " PIM MANAGER -- SQL DATABASE TIER + 250 GB MAX SIZE: $srvName / $Database" -ForegroundColor Cyan
Write-Host ('=' * 78) -ForegroundColor Cyan

# --- read ----------------------------------------------------------------------------------------------------------------
$g = Invoke-SqtArm -Path "$dbPath`?api-version=$api"
if ($g.status -ge 400 -or -not $g.json) { throw "Set-PimSqlTier: could not read the database $dbPath (HTTP $($g.status)): $($g.text)" }
$db = $g.json
Show-SqtDb 'before:' $db
$cur = Resolve-PimSqlServiceObjective -Database $db
$curMax = $null; if ("$($db.properties.maxSizeBytes)" -match '^\d+$') { $curMax = [int64]$db.properties.maxSizeBytes }
$pinNow = $null; if ($db.tags -and $db.tags.PSObject.Properties['pim-sql-tier-pin']) { $pinNow = "$($db.tags.'pim-sql-tier-pin')" }
$pool = "$($db.properties.elasticPoolId)"

# --- decide (the ONE plan; -Tier is your own choice of Standard tier) -----------------------------------------------------
$targetTier = $cur; $tierChange = $false
if ("$Tier".Trim()) {
    if ($pool) { throw "Set-PimSqlTier: the database is in an elastic pool ($pool) -- its tier is the pool's; not changed." }
    if ($cur -notmatch '^(?i)(Basic|S\d+)$') { throw "Set-PimSqlTier: the database is '$cur' (not Basic / Standard) -- this script sets Standard tiers only; not changed." }
    if ($pinNow -and $pinNow -ine $Tier.ToUpperInvariant() -and -not $Pin) { throw "Set-PimSqlTier: the database is pinned to '$pinNow' (pim-sql-tier-pin). Add -Pin to change its tier to $($Tier.ToUpperInvariant()) and re-pin it." }
    $targetTier = $Tier.ToUpperInvariant(); $tierChange = ($targetTier -ine $cur)
    $mp = Get-PimSqlTierPlan -Current $targetTier -Target $targetTier -CurrentMaxSizeBytes $(if ($cur -match '^(?i)basic$' -and $null -eq $curMax) { 1 } else { $curMax })
    $why = "-Tier $targetTier (your choice)"
    # A tier below the product tier that is not pinned is raised back by the next update: say so before the change.
    $belowDefault = ([int]($targetTier -replace '^(?i)S', '') -lt [int]($defaultTier -replace '^(?i)S', ''))
    if ($belowDefault -and -not $Pin) { Write-Host "  note:   $targetTier is below the product tier $defaultTier and the database is not pinned -- the next update raises it to $defaultTier. Add -Pin to keep $targetTier." -ForegroundColor Yellow }
} else {
    $mp = Get-PimSqlTierPlan -Current $cur -ElasticPool $pool -CurrentMaxSizeBytes $curMax -Pin $pinNow
    if ($mp.action -eq 'raise') { $targetTier = $mp.target; $tierChange = $true }
    $why = "$($mp.reason)"
}
$maxSet = ($mp.maxSizeAction -eq 'set')
$pinTag = $(if ($Pin) { $targetTier } else { $null })
$pinChange = ($Pin -and "$pinNow" -cne "$pinTag")
if ($Pin -and $targetTier -notmatch '^(?i)S\d+$') { throw "Set-PimSqlTier: -Pin pins a Standard tier; the database is '$targetTier'." }
Write-Host "  plan:   $why" -ForegroundColor DarkGray
if (-not "$Tier".Trim() -and $mp.pinnedBelowDefault) { Write-Host "  note:   $($mp.pinNote). To move it: -Tier $defaultTier -Pin." -ForegroundColor Yellow }

if (-not $tierChange -and -not $maxSet -and -not $pinChange) { Write-Host "`nRESULT: nothing to change -- $targetTier, max size kept$(if ($pinNow) { ", pinned to $pinNow" })." -ForegroundColor Green; exit 0 }

$body = @{}
$what = @()
if ($tierChange) { $body['sku'] = @{ name = $targetTier; tier = 'Standard' }; $what += "tier $cur -> $targetTier" }
if ($maxSet) { $body['properties'] = @{ maxSizeBytes = $maxWant }; $what += ("max size {0} -> 250 GB" -f $(if ($null -ne $curMax) { '{0:N0} GB' -f ($curMax / 1GB) } else { 'unknown' })) }
if ($pinChange) {
    $tags = @{}; if ($db.tags) { foreach ($t in $db.tags.PSObject.Properties) { $tags[$t.Name] = "$($t.Value)" } }
    $tags['pim-sql-tier-pin'] = $pinTag
    $body['tags'] = $tags; $what += "tag pim-sql-tier-pin = $pinTag"
}
if (-not $PSCmdlet.ShouldProcess("SQL database $srvName/$Database", "update: $($what -join '; ')")) { Write-Host "`nRESULT: preview only -- nothing was changed." -ForegroundColor DarkYellow; exit 0 }

# --- change: ONE PATCH ---------------------------------------------------------------------------------------------------
$p = Invoke-SqtArm -Method PATCH -Path "$dbPath`?api-version=$api" -Body $body
if ($p.status -ge 400) { throw "Set-PimSqlTier: the database update was refused (HTTP $($p.status)): $($p.text)" }
Write-Host "  update accepted (HTTP $($p.status)): $($what -join '; ')" -ForegroundColor Green

# --- read back until confirmed (a 404 / 5xx right after a tier PATCH is transient: the scale is running) ---------------
$deadline = (Get-Date).AddMinutes($ReadBackMinutes); $done = $false; $a = $null
do {
    if ($PollSeconds -gt 0) { Start-Sleep -Seconds $PollSeconds }
    $r = Invoke-SqtArm -Path "$dbPath`?api-version=$api"
    if ($r.status -eq 404 -or $r.status -ge 500 -or -not $r.json) { Write-Host "  read-back: HTTP $($r.status) -- transient while the change runs, waiting" -ForegroundColor DarkGray; continue }
    $a = $r.json
    $aMax = 0L; [void][int64]::TryParse("$($a.properties.maxSizeBytes)", [ref]$aMax)
    $done = ((Resolve-PimSqlServiceObjective -Database $a) -ieq $targetTier -and (-not $maxSet -or $aMax -ge $maxWant) -and "$($a.properties.status)" -eq 'Online' -and
             (-not $pinChange -or ($a.tags -and "$($a.tags.'pim-sql-tier-pin')" -ceq $pinTag)))
} until ($done -or (Get-Date) -gt $deadline)
if ($a) { Show-SqtDb 'after: ' $a }
if (-not $done) { Write-Host "`nRESULT: NOT CONFIRMED within $ReadBackMinutes min -- a tier change can take longer; re-run with -WhatIf to read the current state." -ForegroundColor Yellow; exit 1 }
Write-Host "`nRESULT: done -- $targetTier, max size 250 GB$(if ($pinChange) { ", pinned to $pinTag" }) (read back)." -ForegroundColor Green
exit 0
} finally { Stop-PimScriptRun -Script 'Set-PimSqlTier' }