#Requires -Version 7.0
# PIM Manager 3.0.70 -- Set-PimLicense.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: _pimscriptdoc.ps1, ..\..\engine\_shared\pim-rest.ps1, pim-loopbackanswer.ps1, ..\..\engine\_shared\pim-sqlstore.ps1, ..\..\engine\_shared\pim-license.ps1, _pimsignedin.ps1)


<#
.SYNOPSIS
  Registers an issued PIM Manager licence in the environment's store: it verifies the signed licence document first,
  stores it as the License setting, reads it back and verifies it again; optionally stores the Invardia install key
  or queues its claim.

.DESCRIPTION
  IMP-42 -- import an issued PIM Manager licence into the store (pim.Settings['License']).

  PIM v2 keeps the licence in SQL, not in a file. It used to be FOUND by scanning config/ for
  *.pimlicense / *.aitlicense -- a directory the container image excludes, so every hosted
  environment read "Missing" whatever had been issued. Nothing reads such a file any more: the
  signed document (payloadB64 + signature, byte-identical to what was issued) is stored in
  pim.Settings['License'], and both containers read it from there.

  This is the supported way to put it there.
  SAME SAFETY RULES AS THE OTHER STORE-WRITING SETUP SCRIPTS:
    * The document is VERIFIED before the store is contacted for a write (Set-PimLicense refuses a
      tampered or foreign-signed document -- nothing is stored).
    * It reads back and compares. A write that is not verified is a hope.
    * Any failure says so and exits non-zero; nothing is reported as installed that is not.

  A licence that verifies but is outside its validity window (NotYetValid / Expired / Grace) is
  stored -- it is the issued document -- and the status is shown in plain words so the operator knows.

.PARAMETER LicensePath
  The issued licence file (.pimlicense / .aitlicense). Its CONTENT is imported; the file is not kept.
.PARAMETER LicenseJson
  The issued licence document as text (JSON with payloadB64 + signature), instead of -LicensePath.
.PARAMETER ConnectionString
  A ready connection string to the store (e.g. a local SQL Server with Integrated security).
.PARAMETER SqlServer
  The store's server instead of -ConnectionString. An Azure SQL FQDN connects with a token -- as the
  admin app (-TenantId -AdminAppId with -AdminCertThumbprint or -AdminSecret) or as the signed-in person
  (-UseSignedInAccount: a browser sign-in, or the Invardia Support app session open in this window; a member of the SQL
  admin group) -- exactly like Set-PimManagerAccess.ps1. No command-line tool and no PowerShell module is needed.

  -WhatIf verifies the document, reads what the store holds now, prints the licence, what it replaces and every write it
  would make (the License setting, the install key or its claim), and writes nothing.

  Published as ONE self-contained file at https://invardia.com/support/pim/Set-PimLicense.ps1 (REQUIREMENTS 100.81): it
  runs in PowerShell 7 with nothing next to it.

.EXAMPLE
  .\Set-PimLicense.ps1 -LicensePath .\licence.pimlicense -SqlServer <server>.database.windows.net -TenantId <tenant id> -UseSignedInAccount -WhatIf
  Signs you in through the browser, verifies the licence and prints what it would store ("What if: ...") -- nothing is written.
.EXAMPLE
  .\Set-PimLicense.ps1 -LicensePath .\licence.pimlicense -SqlServer <server>.database.windows.net -TenantId <tenant id> -UseSignedInAccount
  Verifies the licence, stores it, reads it back and verifies it again.

.NOTES
  Requirements:
    PowerShell: 7.0 or later (pwsh). Windows PowerShell 5.1 is not supported.
    Role: member of the environment's SQL admin group (grp-pim-sql-admins); no Microsoft Entra or Azure role.
    Hosts: login.microsoftonline.com, *.database.windows.net (port 1433)

    PERMISSIONS AND CHANGES (from Set-PimLicense.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Set-PimLicense/)
    The person running it needs:
      - Member of the environment's SQL admin group (grp-pim-sql-admins), signed in through the browser or the Invardia Support app session (no command-line tool, no PowerShell module) [other, the environment's SQL database] -- The licence is kept in pim.Settings; only the SQL admin group may write it. With -UseSignedInAccount the person signs in through the browser (the recommended way). Alternatively, for automation, an Azure SQL access token (-SqlAccessToken), the admin application (-AdminAppId with -AdminCertThumbprint), or a ready -ConnectionString to a local SQL Server.
    What it creates, changes or grants:
      - update pim.Settings row 'License' (the signed licence document exactly as issued) (Environment SQL database) @ this environment's PIM Manager and engine -- Switches on the features the licence covers. The document is verified BEFORE the store is written (a tampered or foreign-signed document, a non-Pro licence or one not bound to this tenant is refused), then read back and verified again. Undo: Register the previous licence file again (the replaced licence id is printed as 'replaces:'), or remove the License setting to return to Community.
      - create pim.Settings row 'EditionUpgrade' (only when the environment was Community until now) (Environment SQL database) @ this environment -- Records the Community-to-Pro conversion so the update ring keeps working until the upgrade step gives the environment its Pro updater. Undo: Remove the EditionUpgrade setting.
      - update pim.Settings rows 'InvardiaInstallKey' and (with -InstallKeyPath) 'InstallKeyClaimState' -- only with -InstallKey / -InstallKeyPath (Environment SQL database) @ this environment -- Stores the install key Invardia issued with this installation so the engine does not claim another one. The key is never printed. Undo: Remove the two settings; the engine's install-key job then claims a key again.
      - update pim.Settings row 'SchedulerTriggers' (adds one 'install-key' run-now entry) -- only with -QueueInstallKeyClaim and no key given (Environment SQL database) @ this environment's engine -- So the engine claims the install key at its next run (within 5 minutes) instead of up to 6 hours later. Undo: None needed -- the entry is consumed by the next engine run.
      - create the result file named by -OutFile (licence id, status, features; never the install key) (Local file (only with -OutFile)) @ this computer -- For a caller that reads the outcome. Undo: Delete the file.
    -WhatIf: Verifies the licence document, reads what is stored now and prints the licence (id, customer, SKU, valid to, features, bound tenants, what it replaces), 'What if: Performing the operation "store the verified licence" on target "pim.Settings['License'] in <server>/<database>"' and 'What if: would store licence <id> ...' (plus the install key or its claim when asked). Nothing is written.
    Undo: Register the previous licence file again (its id is printed as 'replaces:'), or remove the License setting to return the environment to Community. Remove InvardiaInstallKey / InstallKeyClaimState to have the engine claim a key again.

.LINK
    https://invardia.com/docs/pim/scripts/Set-PimLicense/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [string]$LicensePath,
    [string]$LicenseJson,
    [string]$ConnectionString,
    [Alias('SqlServerFqdn')][string]$SqlServer,
    [Alias('SqlDatabase')][string]$Database = 'PimPlatform',
    [string]$TenantId,
    [string]$AdminAppId,
    [string]$AdminCertThumbprint,
    # Operator 2026-09-23: customer environments have no certificate for the admin app on the setup host --
    # a client secret is accepted instead (same parameter name as Initialize-PimMailSender / Initialize-PimTenantStore).
    [string]$AdminSecret,
    # 71.33 / 100.41: reach the store as the SIGNED-IN person (browser sign-in, a member of the SQL admin group) instead of -AdminAppId.
    [switch]$UseSignedInAccount,
    # An Azure SQL access token the caller already holds (minted for the resource https://database.windows.net/, e.g. by
    # the environment's own operator profile). The process's managed identity is
    # switched off for this run, so the store is reached as the token's principal -- never as the machine's MI.
    [string]$SqlAccessToken,
    # 2026-10-06 (with Invardia + SI): the install key Invardia issued with this installation (its bootstrap writes
    # `installKey` to config.json). Stored as pim.Settings['InvardiaInstallKey'] so the engine does NOT claim one --
    # a claim for an environment that already has a key is refused (409). Never printed.
    [string]$InstallKey,
    # UPLINK-ENROL (PIM 99): the install key in a FILE (the MSP build's enroll step writes the one Invardia returned into its
    # restricted per-run directory), so the key is never a command-line or step argument. Stored exactly like -InstallKey,
    # and the claim state is recorded as 'claimed' (the engine's install-key job then has nothing to do).
    [string]$InstallKeyPath,
    # 2026-10-06 (install rehearsal): with no -InstallKey, queue the engine's 'install-key' job as a "Run now" trigger (the
    # same SchedulerTriggers entry the Manager writes), so the key is claimed at the next tick (5 min) -- not up to 6 h later,
    # after the first 03:00 update has already found no key.
    [switch]$QueueInstallKeyClaim,
    # 2026-10-06 (MSP rehearsal): the MSP build's licence step names the role. A licence that does not cover MSP for this
    # tenant is REFUSED before it is stored -- tonight a managed tenant got a single-tenant licence, and only its pull job
    # found out ("the licence does not include MSP"). A managed tenant runs the managing company's MSP licence.
    [ValidateSet('', 'Master', 'Slave')][string]$RequireMspRole = '',
    [string]$OutFile
)

$ErrorActionPreference = 'Stop'
# REQUIREMENTS 100.81: published as ONE standalone file (https://invardia.com/support/pim/Set-PimLicense.ps1). Every helper
# is dot-sourced by a literal path relative to this script's folder, so Build-PimSupportScripts.ps1 can inline it -- the
# built file loads nothing and needs no repository next to it. The next line tells the build to leave out the OPTIONAL
# loads the engine libraries end with (files that sit next to them in the repository) and to fail on any load left.
# BUILD-NO-OPTIONAL-LOADS
# ===== 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-Rest.ps1 =====
<#
  PIM4EntraPS -- pure-REST auth + data plane (NO Graph/Az/MSAL modules).

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

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

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

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

Set-StrictMode -Off

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# ===== END inlined helper: ..\..\engine\_shared\PIM-Rest.ps1 =====
# ===== BEGIN inlined helper: ..\..\engine\_shared\PIM-SqlStore.ps1 =====
# PIM4EntraPS -- SQL data store (the SQL-only data layer).
# Dot-sourced by PIM-Functions.psm1 (uses PIM-ChangeQueue.ps1 for the commit
# plan) and the pim-manager.
#
# The new solution is SQL-only -- no CSV. Storage-neutral naming throughout
# (entity / row / store, never "csv"). Access is RAW ADO.NET (System.Data.
# SqlClient) -- NOT the SqlServer PowerShell module -- so there is no module
# dependency, it is PS 5.1-safe, and it never drags Azure.Core into a Graph
# process (the SqlServer-module-poisons-Connect-MgGraph trap).
#
# Row store: pim.Rows(Entity, [Key], DataJson, UpdatedUtc) -- one JSON row per
# (entity, key). The locked column structure is enforced at the app layer
# (PIM-SchemaConformance.ps1); typed per-entity tables can be layered on later.
# Commit drains the queue (pim.ChangeQueue) as a DELTA against pim.Rows.

Set-StrictMode -Off
Add-Type -AssemblyName System.Data -ErrorAction SilentlyContinue

function Resolve-PimSqlClientType {
    # The SQL driver is the one unavoidable non-REST dependency. Prefer
    # Microsoft.Data.SqlClient (cross-platform: Linux/PS7 container) and fall back to
    # the in-box System.Data.SqlClient (Windows PowerShell 5.1). Order:
    #   1. Microsoft.Data.SqlClient (already loaded)
    #   2. System.Data.SqlClient    (in-box on Windows 5.1; null on .NET Core/Linux)
    #   3. an explicit DLL via $env:PIM_SQLCLIENT_DLL
    #   4. the SqlServer module (bundles Microsoft.Data.SqlClient w/ managed SNI on Linux)
    if ($script:PimSqlClientType) { return $script:PimSqlClientType }
    $t = ('Microsoft.Data.SqlClient.SqlConnection' -as [type])
    if (-not $t) { $t = ('System.Data.SqlClient.SqlConnection' -as [type]) }   # in-box on Windows PS 5.1
    # Pinned, BUNDLED assembly (no PowerShell module): $env:PIM_SQLCLIENT_DLL points at
    # the Microsoft.Data.SqlClient.dll (or its folder). Probe the same folder for the
    # dependency closure on demand, so we Add-Type one DLL and deps resolve locally.
    if (-not $t -and $env:PIM_SQLCLIENT_DLL) {
        $p = $env:PIM_SQLCLIENT_DLL
        $script:PimSqlDllDir = if (Test-Path -LiteralPath $p -PathType Container) { $p } else { Split-Path -Parent $p }
        $main = if (Test-Path -LiteralPath $p -PathType Leaf) { $p } else { Join-Path $script:PimSqlDllDir 'Microsoft.Data.SqlClient.dll' }
        if (Test-Path -LiteralPath $main) {
            $resolver = [System.ResolveEventHandler]{
                param($s, $e)
                $n = ($e.Name -split ',')[0]
                $cand = Join-Path $script:PimSqlDllDir "$n.dll"
                if (Test-Path -LiteralPath $cand) { return [System.Reflection.Assembly]::LoadFrom($cand) }
                return $null
            }
            try {
                [System.AppDomain]::CurrentDomain.add_AssemblyResolve($resolver)
                Add-Type -Path $main -ErrorAction Stop
                $t = ('Microsoft.Data.SqlClient.SqlConnection' -as [type])
            } catch { Write-Verbose "PIM-SqlStore: Add-Type $main failed: $($_.Exception.Message)" }
        }
    }
    if (-not $t) { throw 'No SQL client available. Windows PS 5.1 has System.Data.SqlClient in-box; on Linux/PS7 bundle Microsoft.Data.SqlClient and point $env:PIM_SQLCLIENT_DLL at it (the container image does this).' }
    $script:PimSqlClientType = $t
    return $t
}

function Test-PimManagedIdentityAvailable {
    # Is a managed identity reachable from THIS process? Answers once and caches, because
    # the IMDS probe costs a real timeout when there is no MI and connections are frequent.
    # Order matters: the env-var forms (App Service / Functions) are free to check, so they
    # answer before anything touches the network. $global:PIM_UseManagedIdentity forces yes.
    # Set $global:PIM_NoManagedIdentity to force no (offline tests must never probe IMDS).
    [CmdletBinding()] param([switch]$Force)
    if ($global:PIM_NoManagedIdentity) { return $false }
    if ($global:PIM_UseManagedIdentity) { return $true }
    if ($env:IDENTITY_ENDPOINT -and $env:IDENTITY_HEADER) { return $true }
    if ($env:MSI_ENDPOINT -and $env:MSI_SECRET) { return $true }
    # §100.63(b) an Azure Arc-enabled server (the on-premises hybrid worker): its agent serves the identity on localhost,
    # never on 169.254.169.254, so the IMDS probe below would answer "no" there.
    if ((Get-Command Get-PimArcIdentityEndpoint -ErrorAction SilentlyContinue) -and (Get-PimArcIdentityEndpoint)) { return $true }
    if (-not $Force -and $null -ne $script:PimMiAvailable) { return $script:PimMiAvailable }
    $ok = $false
    try {
        $null = Invoke-RestMethod -Method GET -TimeoutSec 3 -Headers @{ Metadata = 'true' } `
                  -Uri 'http://169.254.169.254/metadata/instance?api-version=2021-02-01'
        $ok = $true
    } catch { $ok = $false }
    $script:PimMiAvailable = $ok
    return $ok
}

# REQ 100.76: forget the cached SQL token, so the next connection mints one (a setup run that has just made the signed-in
# person the server's admin must not present the token it held from before).
function Reset-PimSqlTokenCache { $script:PimSqlTokenCache = $null }

function New-PimSqlConnection {
    # Single place connections are created, so MANAGED IDENTITY (the chosen auth for
    # Azure SQL) works passwordless: an MI access token for https://database.windows.net/
    # is set on the connection (.AccessToken). If one isn't pre-minted, mint it via
    # PIM-Rest (MI / SPN / signed-in source) here. No password in the connection string. Skipped when
    # the CS uses Integrated auth (dev/on-prem) -- the two are mutually exclusive.
    param([Parameter(Mandatory)][string]$ConnectionString)
    $type = Resolve-PimSqlClientType
    $c = $type::new($ConnectionString)
    # §97.1: every connection is counted, so a commit can say how many it opened ([commit-timing]) and a test can prove a
    # bulk write does not open one per row.
    $global:PIM_SqlConnectionCount = 1 + [int]$global:PIM_SqlConnectionCount
    # A connection string that carries its own PASSWORD (a SQL login -- the shared Linux test runner's sidecar, framework 12.1)
    # never gets a token either: SqlClient refuses AccessToken together with a password, and the product never builds one.
    if ($ConnectionString -notmatch '(?i)Integrated\s*Security' -and $ConnectionString -notmatch '(?i)(^|;)\s*(Password|Pwd)\s*=') {
        # Acquire a FRESH token on EVERY connection. Get-PimRestToken caches per
        # resource with an expiry and auto-refreshes when near expiry, so this is
        # cheap (returns the still-valid cached token) AND it never hands SQL an
        # expired token. Previously the token was minted once into
        # $global:PIM_SqlAccessToken and reused forever, so a long-running Manager
        # (hosted 24/7) failed with "Login failed ... Token is expired" ~1h after
        # start. Do NOT gate acquisition on the global being empty. (Fix 2026-06-17.)
        $tok = $null
        if (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue) {
            # 0) BREAK-GLASS / emergency edition on a client PC: no MI, no SPN -- the
            #    operator signs in interactively as THEMSELVES (audited under the human).
            #    Opt in with $global:PIM_SqlInteractive or $global:PIM_Interactive.
            if ($global:PIM_SqlInteractive -or $global:PIM_Interactive) {
                try { $tok = Get-PimRestToken -Resource 'https://database.windows.net' -Interactive } catch { Write-Warning "  [sql] interactive token failed: $($_.Exception.Message)" }
            }
            # 1) MANAGED IDENTITY IS PLAN A (operator directive 2026-08-08: "use MI as plan A
            #    to connect with managed identity"), but ONLY when no SPN is explicitly
            #    configured. MI was previously gated on $env:IDENTITY_ENDPOINT -- an App
            #    Service/Functions variable NEVER set on an Azure VM -- so on a VM (the build host
            #    included) MI was silently skipped even though Get-PimManagedIdentityToken had
            #    handled IMDS all along. The gate, not the capability, was missing.
            #
            #    BUG-34: making MI unconditional then broke the CROSS-TENANT case, which is the
            #    normal one for the test estate. A managed identity can only mint tokens for
            #    ITS OWN tenant, and MI acquisition SUCCEEDS -- so a valid-but-wrong-tenant
            #    token was taken and the explicitly configured SPN never got a turn. Azure SQL
            #    then answers "Login failed for user '<token-identified principal>'. The server
            #    is not currently configured to accept this token", which reads like a
            #    permissions problem rather than "you authenticated to the wrong directory".
            #    Precedence is therefore: an EXPLICIT credential wins over ambient MI. MI stays
            #    plan A for the in-tenant/hosted case it was asked for (engine in ACA with no
            #    SPN configured), which is where it is genuinely correct.
            #    Test-PimManagedIdentityAvailable probes IMDS ONCE per process and caches the
            #    answer, so a machine with no MI does not pay a timeout on every connection.
            $sqlCid = if ($global:PIM_SqlClientId)     { $global:PIM_SqlClientId }     else { $global:PIM_ClientId }
            $sqlSec = if ($global:PIM_SqlClientSecret) { $global:PIM_SqlClientSecret } else { $global:PIM_ClientSecret }
            $sqlThumb = if ($global:PIM_SqlCertThumbprint) { $global:PIM_SqlCertThumbprint } else { $global:PIM_CertThumbprint }
            $explicitSpn = [bool]("$sqlCid".Trim()) -and ([bool]("$sqlSec".Trim()) -or [bool]("$sqlThumb".Trim()))

            # 🔴 §52.18 -- REUSE THE TOKEN, OR EVERY CONNECTION GETS ITS OWN POOL.
            # ADO.NET pools physical sessions per connection string AND per access token. Minting a
            # FRESH token for every connection therefore fragments the pool: each token opens its
            # own set of sessions instead of reusing the ones already there, and they are held for
            # the pool's lifetime. Against a Basic-tier database (300 sessions) that is a ceiling a
            # normal import can actually reach -- measured at a live customer 2026-09-09, where a
            # CSV migration failed halfway with "The session limit for the database is 300 and has
            # been reached", after the morning's deploys, the Manager and the tick job had each
            # contributed their own pools.
            # 🪤 The mint is also not free: every connection paid a token round-trip.
            # Cached per (identity, resource) for slightly less than the token's own lifetime, so a
            # long run still refreshes before expiry rather than failing mid-way.
            $tokKey = "sql|$sqlCid|$($sqlThumb)|$([bool]$sqlSec)"
            if ($script:PimSqlTokenCache -and
                $script:PimSqlTokenCache.key -eq $tokKey -and
                $script:PimSqlTokenCache.expires -gt (Get-Date).ToUniversalTime()) {
                $tok = $script:PimSqlTokenCache.token
            }

            # 🔴 BUG-77 -- SAY WHICH BRANCH RAN AND WHICH IDENTITY IT ASKED FOR, ONCE PER PROCESS.
            # Every branch below was silent on success and the MI branch is a plain `if`, so being
            # SKIPPED produced no output at all. The result: "no [mi] line, no [sql] warning, and a
            # login failure" was equally consistent with MI-skipped, MI-returned-the-wrong-identity,
            # and SPN-token-minted-from-$env:AZURE_CLIENT_SECRET (which Get-PimRestToken reads on its
            # own, so the SPN can be used even when $explicitSpn is $false). Those cannot be told
            # apart from outside, and each guess costs a rebuild. One line ends that.
            $miAvail = Test-PimManagedIdentityAvailable
            if (-not $script:PimSqlAuthLogged) {
                $script:PimSqlAuthLogged = $true
                $miIdLabel = if ($global:PIM_ManagedIdentityClientId) { "user-assigned $($global:PIM_ManagedIdentityClientId)" }
                             elseif ($env:PIM_ManagedIdentityClientId) { "user-assigned $($env:PIM_ManagedIdentityClientId)" } else { 'default (system, or the only one attached)' }
                $credKind = if ("$sqlSec".Trim()) { 'secret' } elseif ("$sqlThumb".Trim()) { "cert $sqlThumb" }
                            elseif ($env:AZURE_CLIENT_SECRET) { 'secret via $env:AZURE_CLIENT_SECRET (NOT counted by $explicitSpn)' } else { 'none' }
                $__sap = ("  [sql] auth plan: explicitSpn={0} sqlClientId='{1}' credential={2} | MI available={3} identity={4}" -f `
                                $explicitSpn, "$sqlCid", $credKind, $miAvail, $miIdLabel)
                # §100.46: in the tick a start-up diagnostic (printed on change / first of the day / PIM_LOG_VERBOSE=1)
                if (Get-Command Write-PimStartupLine -ErrorAction SilentlyContinue) { Write-PimStartupLine -Message $__sap -ForegroundColor DarkGray } else { Write-Host $__sap -ForegroundColor DarkGray }
            }
            # 🪤 ONCE PER PROCESS, NOT ONCE PER CONNECTION. The first version of this logged the
            # winning branch on EVERY connection: a single downlink run emitted ~80 identical
            # "token source: MANAGED IDENTITY" warnings, which is how a diagnostic stops being one.
            # Noise that drowns the next real warning costs more than the silence it replaced.
            # The FAILURE paths stay unconditional -- those are rare and each one matters.
            if (-not $tok -and $explicitSpn) {
                $spnErr = $null
                try { $tok = Get-PimRestToken -Resource 'https://database.windows.net' -ClientId $sqlCid -ClientSecret $sqlSec -CertThumbprint $sqlThumb
                      if ($tok -and -not $script:PimSqlSourceLogged) { $script:PimSqlSourceLogged = $true; if (Get-Command Write-PimStartupLine -ErrorAction SilentlyContinue) { Write-PimStartupLine -Message "  [sql] token source: EXPLICIT SPN $sqlCid" -ForegroundColor DarkGray } else { Write-Host -ForegroundColor DarkGray "  [sql] token source: EXPLICIT SPN $sqlCid" } } }
                catch { $spnErr = "$($_.Exception.Message)"; Write-Warning "  [sql] SPN token failed: $spnErr" }
                # =============================================================================
                # 🔴 SEC-12b -- SAME DEFECT AS SEC-12, ONE LAYER DOWN, AND IT WAS STILL LIVE.
                # BUG-34 fixed the PRECEDENCE (an explicit SPN is tried before ambient MI). It did
                # not fix the FAILURE path: when the explicit SPN's token could not be acquired,
                # control simply carried on to the MI branch below, and then to a pre-pinned
                # $global:PIM_SqlAccessToken -- either of which is a DIFFERENT PRINCIPAL.
                # 🪤 OBSERVED IN THIS SESSION'S OWN LOG, against the live store:
                #       [sql] SPN token failed: ...
                #       [sql] token source: MANAGED IDENTITY
                #    ...followed by "The SELECT permission was denied on the object 'Tenants'".
                #    That reads as an RBAC problem and is not one: the connection had silently
                #    authenticated as the machine's managed identity instead of the SPN that was
                #    explicitly configured. Every minute spent on the permission is wasted.
                # 🔑 A caller that configured an SPN has said who it wants to be. Presenting a
                # different identity SUCCEEDS at the connection and fails later, somewhere else,
                # wearing the wrong error's clothes. Refuse instead -- the failure is then one
                # line from its cause.
                # =============================================================================
                if (-not $tok) {
                    throw ("PIM store auth REFUSED: an explicit SPN ($sqlCid) is configured for SQL and its token " +
                           "could not be acquired$(if ($spnErr) { ": $spnErr" } else { '.' }) " +
                           'Refusing to fall back to the machine managed identity or a pre-pinned token -- that would ' +
                           'connect as a DIFFERENT principal and surface later as a permissions error. Fix the ' +
                           'credential, or clear $global:PIM_SqlClientId/$global:PIM_ClientId to use ambient auth on purpose.')
                }
            }
            if (-not $tok -and $miAvail) {
                try { $tok = Get-PimRestToken -Resource 'https://database.windows.net' -UseManagedIdentity
                      if ($tok -and -not $script:PimSqlSourceLogged) { $script:PimSqlSourceLogged = $true; if (Get-Command Write-PimStartupLine -ErrorAction SilentlyContinue) { Write-PimStartupLine -Message '  [sql] token source: MANAGED IDENTITY' -ForegroundColor DarkGray } else { Write-Host '  [sql] token source: MANAGED IDENTITY' -ForegroundColor DarkGray } } }
                catch { Write-Warning "  [sql] MI token failed: $($_.Exception.Message)" }
            }
            elseif (-not $tok -and -not $miAvail -and -not $script:PimSqlSourceLogged) {
                $script:PimSqlSourceLogged = $true
                Write-Warning '  [sql] MI branch SKIPPED (no managed identity detected in this process)'
            }
            # Last resort: an SPN that was not "explicit" by the test above (e.g. client id
            # present but credential resolved from the ambient cert store).
            if (-not $tok -and -not $explicitSpn) {
                # 🪤 This branch can still authenticate as the SPN even though $explicitSpn said
                # there was no explicit credential: Get-PimRestToken reads $env:AZURE_CLIENT_SECRET
                # itself. That is exactly how a container ends up presenting the ENGINE SPN to SQL
                # while every log line suggests managed identity -- so it names the source too.
                try { $tok = Get-PimRestToken -Resource 'https://database.windows.net' -ClientId $sqlCid -ClientSecret $sqlSec -CertThumbprint $sqlThumb
                      if ($tok -and -not $script:PimSqlSourceLogged) { $script:PimSqlSourceLogged = $true; Write-Host -ForegroundColor DarkGray "  [sql] token source: FALLBACK SPN $sqlCid (credential resolved inside Get-PimRestToken, e.g. \$env:AZURE_CLIENT_SECRET)" } }
                catch { Write-Warning "  [sql] SPN token failed: $($_.Exception.Message)" }
            }
            if (-not $tok) { Write-Warning '  [sql] NO TOKEN was obtained by any branch -- the connection will present no credential.' }
        }
        # Last-resort: an explicitly pre-pinned token (e.g. a caller that minted its own).
        if (-not $tok -and $global:PIM_SqlAccessToken) { $tok = $global:PIM_SqlAccessToken }
        if ($tok) {
            # 🔴 §70 (2026-09-13) -- THE POOL IS KEYED ON THE TOKEN *OBJECT*, NOT ITS TEXT.
            # This line used to be `$c.AccessToken = "$tok"`. The quotes build a NEW string on every
            # call, and System.Data.SqlClient then gives every connection its OWN pool -- so §52.18's
            # token cache (below) never actually shared a session. MEASURED against internal's store,
            # same token value, 10 open/close each: assigning the cached object -> 1 session; assigning
            # "$tok" -> 10 sessions. Live effect: the Manager held 223 sleeping sessions after one page
            # load, the Basic database hit "The session limit for the database is 300", and every query
            # paid a full TLS + Entra login, which is why Home/Admins took ~3 minutes.
            # 🔑 So: ONE string instance per token, stored once, and that same instance is assigned
            # to every connection. Never interpolate, concatenate or re-cast it on the way in.
            $cacheHit = $script:PimSqlTokenCache -and "$($script:PimSqlTokenCache.key)" -eq "$tokKey" -and
                        [object]::ReferenceEquals($script:PimSqlTokenCache.token, $tok)
            if (-not $cacheHit) {
                # A freshly acquired token: store it ONCE. The expiry is stamped only here -- it used to
                # be re-stamped on every cache hit, so under steady use the 45-minute refresh never came
                # and a long-running Manager would eventually present an expired token.
                # 45 minutes is comfortably inside an Entra token's hour.
                $script:PimSqlTokenCache = @{ key = "$tokKey"; token = $tok
                                              expires = (Get-Date).ToUniversalTime().AddMinutes(45) }
            }
            try { $c.AccessToken = $script:PimSqlTokenCache.token } catch { Write-Warning "  [sql] set AccessToken failed: $($_.Exception.Message)" }
            $global:PIM_SqlAccessToken = $script:PimSqlTokenCache.token   # freshest token, for diagnostics/last-resort
        }
        else {
            # BUG-33: name the CAUSE. The common one is not "auth failed" but "the token provider
            # was never loaded" -- a caller that dot-sources PIM-SqlStore without PIM-Rest skips
            # the whole block above, presents no credential, and Azure SQL reports
            # "Login failed for user ''", which points at permissions and wastes the search there.
            if (-not (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue)) {
                Write-Warning "  [sql] NO SQL access token: Get-PimRestToken is NOT LOADED -- dot-source engine/_shared/PIM-Rest.ps1 BEFORE PIM-SqlStore.ps1. (Azure SQL will report: Login failed for user '')"
            } else {
                Write-Warning "  [sql] NO SQL access token acquired (MI and SPN both failed; connection would present no credential)"
            }
        }
    }
    return $c
}

function Get-PimAzureSqlConnectionString {
    # Passwordless Azure SQL connection string (no credentials) -- auth is the MI
    # AccessToken set by New-PimSqlConnection. Launcher builds this + mints the token.
    param([Parameter(Mandatory)][string]$Fqdn, [string]$Database = 'PimPlatform')   # the v2 platform database (lead, 2026-09-18: PimPlatform is the default everywhere else)
    return "Server=tcp:$Fqdn,1433;Database=$Database;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30"
}

function Get-PimSqlSecretFromKeyVault {
    # Fetch a secret (the connection string, or a password) from Key Vault via the
    # KV REST API with a Bearer token. Prefers a launcher-pre-minted token
    # ($global:PIM_KeyVaultToken); otherwise PIM-Rest mints it (§100.42: the ONE connect path -- no Az module
    # fallback). NEVER cached to disk.
    param([Parameter(Mandatory)][string]$VaultName, [Parameter(Mandatory)][string]$SecretName, [string]$ApiVersion = '7.4')
    $token = $global:PIM_KeyVaultToken
    if (-not $token) {
        if (Get-Command Get-PimRestToken -ErrorAction SilentlyContinue) {
            # 🔴 REQ-F (2026-09-19): the hosted containers ship NO Az module, so Get-AzAccessToken does not exist
            # there and every vault read through this function failed -- the emergency passphrase in particular
            # (Resolve-PimEmergencyExpectedHash), which made break-glass activation impossible on every hosted
            # Manager. PIM-Rest mints the vault token from the same identity the container already uses for
            # Graph/ARM (its managed identity, or the engine SPN certificate).
            $token = Get-PimRestToken -Resource 'https://vault.azure.net'
        } else {
            throw 'no way to obtain a Key Vault token in this runtime (PIM-Rest.ps1 is not loaded -- dot-source it first)'
        }
    }
    $uri = "https://$VaultName.vault.azure.net/secrets/$SecretName" + "?api-version=$ApiVersion"
    return (Invoke-RestMethod -Method GET -Uri $uri -Headers @{ Authorization = "Bearer $token" } -ErrorAction Stop).value
}

function Get-PimSqlConnectionString {
    # Resolve the connection string WITHOUT persisting any secret to a file.
    # Priority:
    #   1. explicit -Server         -> build passwordless (Integrated) [dev/test]
    #   2. $global:PIM_SqlConnectionString  -> in-memory (launcher-set from KV)
    #   3. KV pointer ($global:PIM_SqlConnStringVault + ...Secret) -> fetch from KV
    #   4. passwordless build from $global:PIM_SqlServer + db (Integrated / AAD-MI)
    # The connection string / secret is NEVER read from a JSON/config file.
    #
    # SEC-03: every local/on-prem path below uses `Encrypt=True;TrustServerCertificate=True`.
    # It previously used `Encrypt=False`, which put privileged desired-state data and the SQL
    # session on the wire in CLEAR TEXT. §31 accepts `TrustServerCertificate` "until a real
    # cert" for hybrid -- but that concession is about not VALIDATING the certificate, not
    # about dropping encryption entirely. `Encrypt=True;TrustServerCertificate=True` keeps the
    # wire encrypted while still tolerating a self-signed cert, which is what that note
    # actually intended. The Azure SQL path (above) stays fully strict:
    # `Encrypt=True;TrustServerCertificate=False`.
    param([string]$Server, [string]$Database)
    if (-not $Database) { $Database = if ($global:PIM_SqlDatabase) { "$($global:PIM_SqlDatabase)" } else { 'PimPlatform' } }   # v2 platform database name (was the v1 'PIM4EntraPS')
    # BUG-30 (2026-08-08): an explicit -Server naming AZURE SQL must get the passwordless
    # token connection string, exactly like the ambient path below (:170) and the scenario
    # path (:159) already do. This branch used to return the Integrated string
    # unconditionally, which cannot work against Azure SQL -- PaaS has no Windows auth, and
    # New-PimSqlConnection SKIPS token acquisition entirely when the CS matches
    # /Integrated\s*Security/, so no AAD token was ever minted either. It also silently
    # downgraded TrustServerCertificate from False to True. Since -Server is the parameter
    # every harness and PIM-SqlStore.ps1:217 itself use, the ONLY supported store (Azure SQL
    # PaaS) was unreachable from the explicit path -- which is why every live scenario matrix
    # so far ran against .\SQLEXPRESS, a store the product does not ship. Test the FQDN first.
    if ($Server) {
        if ($Server -match '(?i)database\.windows\.net') { return (Get-PimAzureSqlConnectionString -Fqdn $Server -Database $Database) }
        return "Server=$Server;Database=$Database;Integrated Security=SSPI;Encrypt=True;TrustServerCertificate=True;Connection Timeout=15"
    }
    if ($global:PIM_SqlConnectionString) { return $global:PIM_SqlConnectionString }
    # §31.3 HOSTING RESOLUTION (opt-in by scenario). When a deployment scenario is
    # active AND its resolved hostingLocation names a concrete store (central MSP
    # Azure SQL for S5 / local SQL for S6), pick that server here instead of relying
    # only on the ambient $global:PIM_SqlServer. in-tenant (S1-S4) and the
    # no-scenario case return server='' so the existing ambient logic below wins.
    # Lowest precedence after the explicit overrides above so nothing already wired
    # changes; default behaviour is identical when no scenario is set.
    if ($global:PIM_ActiveScenario -and (Get-Command Resolve-PimScenarioHostingStore -ErrorAction SilentlyContinue)) {
        try {
            $hostStore = Resolve-PimScenarioHostingStore -Scenario "$($global:PIM_ActiveScenario)"
            if ($hostStore -and "$($hostStore.server)".Trim()) {
                $ssrv2 = "$($hostStore.server)".Trim()
                if ($ssrv2 -match '(?i)database\.windows\.net') { return (Get-PimAzureSqlConnectionString -Fqdn $ssrv2 -Database $Database) }
                return "Server=$ssrv2;Database=$Database;Integrated Security=SSPI;Encrypt=True;TrustServerCertificate=True;Connection Timeout=15"
            }
        } catch { Write-Verbose "PIM-SqlStore: scenario hosting resolution skipped: $($_.Exception.Message)" }
    }
    if ($global:PIM_SqlConnStringVault -and $global:PIM_SqlConnStringSecret) {
        return (Get-PimSqlSecretFromKeyVault -VaultName "$($global:PIM_SqlConnStringVault)" -SecretName "$($global:PIM_SqlConnStringSecret)")
    }
    # 🔴 NO `.\SQLEXPRESS` FALLBACK. **SQL Express is not used by this product, anywhere**
    # (operator, 2026-08-28). It was never a supported store -- the BUG-30 note four lines up
    # already called it "a store the product does not ship" -- and leaving it as the DEFAULT
    # meant an unconfigured caller did not fail: it quietly connected to whatever local
    # database happened to exist, with Integrated auth, and read desired state out of it.
    # 🪤 THAT IS NOT HYPOTHETICAL, AND IT HAS ALREADY COST THIS PROJECT A FALSE GREEN TWICE:
    #   * BUG-78 -- a `.\SQLEXPRESS` default OVERRODE a correct Azure SQL FQDN, so the live
    #     scenario matrix had been running against a local database nobody deployed;
    #   * TEST-32 -- a torn-down tenant could not make the estate matrix fail, because the
    #     local SQL Express desired state OUTLIVED the teardown. The run was green about a
    #     directory and false about the claim.
    # Both are the same shape: a default that cannot fail is a default that cannot be trusted.
    # An unset store is a CONFIGURATION ERROR, and it must be loud -- "no store" and "a store
    # with stale rows in it" are the two readings, and only the first is ever right here.
    $srv = "$($global:PIM_SqlServer)".Trim()
    if (-not $srv) {
        # 🪤 ASCII ONLY in this message. The first version used a Unicode ellipsis and Windows
        # PowerShell 5.1's console rendered it as mojibake, which makes an actionable error look
        # like an encoding fault and sends the reader hunting the wrong problem.
        throw ('PIM store is not configured: $global:PIM_SqlServer is empty. Set it to the Azure SQL ' +
               'server FQDN (<name>.database.windows.net) -- or set $global:PIM_SqlConnectionString / the ' +
               'KV pointer ($global:PIM_SqlConnStringVault + $global:PIM_SqlConnStringSecret). ' +
               'There is deliberately NO local default: SQL Express is not a store this product uses, ' +
               'and defaulting to one turns a missing configuration into a silent read of the wrong data.')
    }
    # Azure SQL (FQDN) -> passwordless token-based CS (MI AccessToken set by New-PimSqlConnection).
    # A non-FQDN server is still buildable (a named on-prem/hybrid instance per §31), but it is
    # never REACHED BY DEFAULT any more -- somebody has to have named it.
    if ($srv -match '(?i)database\.windows\.net') { return (Get-PimAzureSqlConnectionString -Fqdn $srv -Database $Database) }
    return "Server=$srv;Database=$Database;Integrated Security=SSPI;Encrypt=True;TrustServerCertificate=True;Connection Timeout=15"
}

function Assert-PimSqlIdentifier {
    # Guard a DB/object name we must string-build (CREATE DATABASE can't bind it).
    param([Parameter(Mandatory)][string]$Name)
    if ($Name -notmatch '^[A-Za-z0-9_]+$') { throw "Unsafe SQL identifier '$Name' (allowed: A-Z a-z 0-9 _)." }
    return $Name
}

function Assert-PimSqlDemoScope {
    <#
      100.68 (b): the DEMO dataset lives in its own schema (pimdemo) and NOTHING but the demo module may touch it -- the
      engine reads pim.Rows only, so demo data can never reach a tenant. Any statement naming pimdemo outside the demo
      module's scope ($global:PIM_DemoSqlScope, set only by Invoke-PimDemoSql in engine/_shared/PIM-DemoData.ps1, which no
      engine entry loads) is REFUSED before it is sent.
    #>
    param([AllowEmptyString()][string]$Sql)
    if ("$Sql" -match '(?i)\[?\bpimdemo\b\]?\s*\.' -and -not $global:PIM_DemoSqlScope) {
        throw 'REFUSED: this statement names the demo schema (pimdemo) outside the demo-data module -- demo data is never read or applied by the engine.'
    }
}

function Invoke-PimSqlQuery {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Sql, [hashtable]$Parameters = @{})
    Assert-PimSqlDemoScope -Sql $Sql
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandText = $Sql
        foreach ($k in $Parameters.Keys) { [void]$cmd.Parameters.AddWithValue("@$k", $(if ($null -eq $Parameters[$k]) { [DBNull]::Value } else { $Parameters[$k] })) }
        $rd = $cmd.ExecuteReader(); $rows = New-Object System.Collections.Generic.List[object]
        while ($rd.Read()) { $o = [ordered]@{}; for ($i = 0; $i -lt $rd.FieldCount; $i++) { $o[$rd.GetName($i)] = $(if ($rd.IsDBNull($i)) { $null } else { $rd.GetValue($i) }) }; $rows.Add([pscustomobject]$o) }
        $rd.Close(); return $rows.ToArray()
    } finally { if ($c) { $c.Close(); $c.Dispose() } }   # §52.18: Dispose, not just Close -- see Set-PimSqlEntityRows
}

function Invoke-PimSqlNonQuery {
    # -CommandTimeoutSec: 0 = the provider default (30 s). Large single-row writes (the tenant cache) pass more.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Sql, [hashtable]$Parameters = @{}, [int]$CommandTimeoutSec = 0)
    Assert-PimSqlDemoScope -Sql $Sql
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandText = $Sql
        if ($CommandTimeoutSec -gt 0) { $cmd.CommandTimeout = $CommandTimeoutSec }
        foreach ($k in $Parameters.Keys) { [void]$cmd.Parameters.AddWithValue("@$k", $(if ($null -eq $Parameters[$k]) { [DBNull]::Value } else { $Parameters[$k] })) }
        return $cmd.ExecuteNonQuery()
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
}

function Invoke-PimSqlScalar {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Sql, [hashtable]$Parameters = @{})
    Assert-PimSqlDemoScope -Sql $Sql
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandText = $Sql
        foreach ($k in $Parameters.Keys) { [void]$cmd.Parameters.AddWithValue("@$k", $(if ($null -eq $Parameters[$k]) { [DBNull]::Value } else { $Parameters[$k] })) }
        return $cmd.ExecuteScalar()
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
}

function Initialize-PimSqlDatabase {
    # Create the database if missing (connects to managing tenant). Idempotent.
    # BUG-32 (2026-08-08): the guard was `IF DB_ID('<db>') IS NULL`, which is NOT idempotent on
    # Azure SQL -- the store we actually support. Measured from managing tenant as the managed identity:
    #     DB_ID('PimScenarioTest')            -> NULL
    #     EXISTS (sys.databases WHERE name=..) -> YES
    # On Azure SQL, DB_ID() resolves only databases the principal owns/created (metadata
    # visibility), so for a PRE-PROVISIONED database -- the normal PaaS case, where the DB is
    # created by IaC and the app is only granted into it -- the guard reads "missing", runs
    # CREATE DATABASE, and throws "Database '<db>' already exists." Every caller therefore fails
    # on an existing Azure database, i.e. on every run after the first.
    # sys.databases lists every database on the logical server and is the correct existence test.
    param([string]$Server, [Parameter(Mandatory)][string]$Database)
    [void](Assert-PimSqlIdentifier -Name $Database)
    $masterCs = Get-PimSqlConnectionString -Server $Server -Database 'master'
    [void](Invoke-PimSqlNonQuery -ConnectionString $masterCs -Sql "IF NOT EXISTS (SELECT 1 FROM sys.databases WHERE name = N'$Database') CREATE DATABASE [$Database];")
}

# ---- framework 12.27 SQL-STATS (PIM SQL-STATS-ASYNC) -------------------------------------------------------------------
# SI 2026-11-05: views took 1-2 min WITH the right indexes -- statistics were never refreshed and AUTO_UPDATE_STATISTICS_ASYNC
# was OFF, so the first read after a big write rebuilt statistics SYNCHRONOUSLY inside the user's request, timed out, was
# cancelled, and the next read waited again. Two halves:
#   (1) AUTO_UPDATE_STATISTICS_ASYNC ON (Set-PimSqlStatisticsAsync): idempotent, outside any transaction (ALTER DATABASE is
#       refused inside one), read back, and a refusal is a WARNING -- never a failed install or update.
#   (2) pim.usp_RefreshStatistics (WITH EXECUTE AS OWNER): after a bulk write the job refreshes
#   WHO SETS THEM (Initialize-PimSqlStatistics), measured on real SQL (Test-PimSqlAccessRealSql P3/P4, 2026-11-05): the
#   least-privilege updater (pim_updater + db_ddladmin) may NOT alter the database ("User does not have permission to alter
#   database") and may NOT create an EXECUTE AS OWNER module ("Cannot execute as the user 'dbo'"). So both belong to the ADMIN
#   run (Invoke-PimSqlAccessInstall: setup, the Support-app cut-over, ca-pim-dbinit -- and dbinit's own statistics step); the
#   schema step (Initialize-PimSqlStore, inside the updater's SCHEMA-QUIESCE-818 path) does each ONLY when the probe says
#   this identity holds the right (an updater still in the admin group, the community setup identity), and otherwise leaves
#   it to the admin run without a warning -- it never sends a statement it has no right for.
#       the pim.* statistics whose modification counter is above 20 % of the rows + 500 -- SAMPLED, never FULLSCAN, at most
#       a bounded number per call (most-changed first, and a time budget), never inside a transaction, never a data change.
#       The job identities hold EXECUTE on this ONE procedure (PIM-SqlAccess.ps1 catalog) -- never ALTER, never db_ddladmin.
#       Callers use Invoke-PimSqlStatisticsRefresh, which never throws (one warning line).
function Get-PimSqlStatisticsAsyncSql {
    <# PURE. The ONE statement for half (1). Guarded: it changes the database only while the setting is still off. #>
    return "IF EXISTS (SELECT 1 FROM sys.databases WHERE database_id = DB_ID() AND is_auto_update_stats_async_on = 0)`n    ALTER DATABASE CURRENT SET AUTO_UPDATE_STATISTICS_ASYNC ON;"
}

function Get-PimSqlStatisticsAsyncReadSql {
    <# PURE. The read-back: 1 = on, 0 = off. #>
    return 'SELECT CAST(is_auto_update_stats_async_on AS int) AS asyncOn FROM sys.databases WHERE database_id = DB_ID()'
}

function Set-PimSqlStatisticsAsync {
    <#
      Half (1). NEVER throws: @{ ok; on; changed; message }. Reads the setting first (already on = nothing sent), sends the
      guarded ALTER DATABASE on its own (no transaction: Invoke-PimSqlNonQuery opens none), then READS IT BACK -- ok only
      when the read-back says on. A refusal (no ALTER DATABASE right, a lock) is one warning; the caller carries on.
      -Query: param($cs, $sql) -> rows; -Exec: param($cs, $sql) (test seams; default Invoke-PimSqlQuery / Invoke-PimSqlNonQuery).
    #>
    param([string]$ConnectionString = '', [scriptblock]$Query, [scriptblock]$Exec, [switch]$Quiet)
    if (-not $Query) { $Query = { param($cs, $sql) Invoke-PimSqlQuery -ConnectionString $cs -Sql $sql } }
    if (-not $Exec)  { $Exec  = { param($cs, $sql) [void](Invoke-PimSqlNonQuery -ConnectionString $cs -Sql $sql) } }
    $read = {
        try { $r = @(& $Query $ConnectionString (Get-PimSqlStatisticsAsyncReadSql)); if ($r.Count -and $null -ne $r[0].asyncOn -and "$($r[0].asyncOn)" -ne '') { return [int]"$($r[0].asyncOn)" } }
        catch { Write-Verbose "[store] statistics: the async setting could not be read: $($_.Exception.Message)" }
        return $null
    }
    $before = & $read
    if ($before -eq 1) { return [pscustomobject]@{ ok = $true; on = $true; changed = $false; message = 'auto update statistics async: already on' } }
    $err = ''
    try { & $Exec $ConnectionString (Get-PimSqlStatisticsAsyncSql) } catch { $err = (("$($_.Exception.Message)" -split "`n")[0]).Trim() }
    $after = & $read
    if ($after -eq 1) {
        if (-not $Quiet) { Write-Host '  statistics: auto update async turned ON (read back)' -ForegroundColor DarkGray }
        return [pscustomobject]@{ ok = $true; on = $true; changed = $true; message = 'auto update statistics async: turned on (read back)' }
    }
    $why = if ($err) { $err } elseif ($null -eq $after) { 'the setting could not be read back' } else { 'the read-back still says off' }
    $msg = "auto update statistics async is NOT on: $why -- the install / update carries on; the next schema step (or the admin job) tries again"
    Write-Warning "[store] $msg"
    return [pscustomobject]@{ ok = $false; on = $false; changed = $false; message = $msg }
}

function Get-PimSqlStatisticsMaxPerCall      { <# PURE. LITERAL. The most statistics one refresh call updates (most-changed first). #> return 50 }
function Get-PimSqlStatisticsBudgetSeconds   { <# PURE. LITERAL. One call stops starting new statistics after this. #> return 45 }

function Get-PimSqlRefreshStatisticsProcedureSql {
    <#
      PURE. Half (2): pim.usp_RefreshStatistics. WITH EXECUTE AS OWNER -- the owner of the pim schema (which owns the tables)
      runs the UPDATE STATISTICS, so a caller needs EXECUTE on this procedure and nothing else. Only user tables of the pim
      schema; only a statistic whose modification counter is above 20 % of its rows + 500; SAMPLED (never FULLSCAN); at most
      @MaxStats (1-200) per call, most-changed first, and no new statistic once @BudgetSeconds (1-600) have passed; refuses
      to run inside a caller's transaction. Changes no data. Returns ONE row: stale, selected, refreshed, failed, deferred,
      elapsedMs, inTransaction, lastError.
    #>
    $mx = Get-PimSqlStatisticsMaxPerCall; $bs = Get-PimSqlStatisticsBudgetSeconds
    return @"
CREATE OR ALTER PROCEDURE pim.usp_RefreshStatistics
    @MaxStats      INT = $mx,
    @BudgetSeconds INT = $bs
WITH EXECUTE AS OWNER
AS
BEGIN
    -- pim-stats v1 -- framework 12.27 SQL-STATS. Statistics only: never a data change, always sampled.
    SET NOCOUNT ON; SET XACT_ABORT OFF; SET LOCK_TIMEOUT 5000;
    DECLARE @start DATETIME2 = SYSUTCDATETIME();
    IF @@TRANCOUNT > 0
    BEGIN
        SELECT 0 AS stale, 0 AS selected, 0 AS refreshed, 0 AS failed, 0 AS deferred, 0 AS elapsedMs, 1 AS inTransaction,
               CAST(N'not run inside a transaction' AS NVARCHAR(400)) AS lastError;
        RETURN;
    END
    IF @MaxStats IS NULL OR @MaxStats < 1 SET @MaxStats = 1;
    IF @MaxStats > 200 SET @MaxStats = 200;
    IF @BudgetSeconds IS NULL OR @BudgetSeconds < 1 SET @BudgetSeconds = 1;
    IF @BudgetSeconds > 600 SET @BudgetSeconds = 600;
    DECLARE @todo TABLE (n INT IDENTITY(1,1) PRIMARY KEY, tbl SYSNAME NOT NULL, st SYSNAME NOT NULL, mods BIGINT NOT NULL);
    DECLARE @stale INT = (
        SELECT COUNT(*) FROM sys.stats s
        JOIN sys.tables t ON t.object_id = s.object_id
        CROSS APPLY sys.dm_db_stats_properties(s.object_id, s.stats_id) sp
        WHERE t.schema_id = SCHEMA_ID(N'pim') AND t.is_ms_shipped = 0
          AND sp.modification_counter > (sp.rows * 20 / 100) + 500);
    INSERT @todo (tbl, st, mods)
    SELECT TOP (@MaxStats) t.name, s.name, sp.modification_counter
    FROM sys.stats s
    JOIN sys.tables t ON t.object_id = s.object_id
    CROSS APPLY sys.dm_db_stats_properties(s.object_id, s.stats_id) sp
    WHERE t.schema_id = SCHEMA_ID(N'pim') AND t.is_ms_shipped = 0
      AND sp.modification_counter > (sp.rows * 20 / 100) + 500
    ORDER BY sp.modification_counter DESC;
    DECLARE @i INT = 1, @n INT = (SELECT COUNT(*) FROM @todo), @done INT = 0, @failed INT = 0, @deferred INT = 0,
            @q NVARCHAR(1000), @lastError NVARCHAR(400) = NULL;
    WHILE @i <= @n
    BEGIN
        IF DATEDIFF(SECOND, @start, SYSUTCDATETIME()) >= @BudgetSeconds BEGIN SET @deferred = @n - @i + 1; BREAK; END
        SELECT @q = N'UPDATE STATISTICS [pim].' + QUOTENAME(tbl) + N' ' + QUOTENAME(st) + N' WITH SAMPLE 20 PERCENT;' FROM @todo WHERE n = @i;
        BEGIN TRY EXEC sys.sp_executesql @q; SET @done = @done + 1; END TRY
        BEGIN CATCH SET @failed = @failed + 1; SET @lastError = LEFT(ERROR_MESSAGE(), 400); END CATCH
        SET @i = @i + 1;
    END
    SELECT @stale AS stale, @n AS selected, @done AS refreshed, @failed AS failed, @deferred AS deferred,
           DATEDIFF(MILLISECOND, @start, SYSUTCDATETIME()) AS elapsedMs, 0 AS inTransaction, @lastError AS lastError;
END
"@
}

$script:PimSqlStatsWarned = @{}
function Invoke-PimSqlStatisticsRefresh {
    <#
      Half (2), the CALL after a bulk write (engine run, tenant-cache refresh, active-assignments snapshot, v1 import).
      BEST EFFORT: NEVER throws; a failure is ONE warning line (once per process for the same reason, so a 5-minute job does
      not repeat it) and the job carries on. Cheap when nothing is stale: the procedure reads sys.stats and returns.
      Returns @{ ok; skipped; refreshed; stale; failed; deferred; elapsedMs; message }.
      -Query: param($cs, $sql, $timeoutSec) -> rows (test seam; default: its own connection with a timeout above the budget).
    #>
    param([string]$ConnectionString = '', [string]$Reason = '', [scriptblock]$Query)
    $res = { param($ok, $skip, $msg, $row)
        $g = { param($n) if ($row -and $row.PSObject.Properties[$n] -and $null -ne $row.$n -and "$($row.$n)" -ne '') { [int]"$($row.$n)" } else { 0 } }
        [pscustomobject]@{ ok = [bool]$ok; skipped = [bool]$skip; refreshed = (& $g 'refreshed'); stale = (& $g 'stale'); failed = (& $g 'failed')
                           deferred = (& $g 'deferred'); elapsedMs = (& $g 'elapsedMs'); message = "$msg" } }
    try {
        $cs = "$ConnectionString".Trim()
        if (-not $cs -and (Get-Command Get-PimTenantCacheStoreCs -ErrorAction SilentlyContinue)) { try { $cs = "$(Get-PimTenantCacheStoreCs)".Trim() } catch { $cs = '' } }
        if (-not $cs -and "$($global:PIM_EngineSqlCs)".Trim()) { $cs = "$($global:PIM_EngineSqlCs)".Trim() }
        if (-not $cs) { return (& $res $true $true 'no SQL store in this process' $null) }
        $budget = Get-PimSqlStatisticsBudgetSeconds
        if (-not $Query) {
            $Query = { param($c0, $sql, $timeoutSec)
                $c = New-PimSqlConnection -ConnectionString $c0
                try {
                    $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandText = $sql; $cmd.CommandTimeout = $timeoutSec
                    $rd = $cmd.ExecuteReader(); $rows = New-Object System.Collections.Generic.List[object]
                    while ($rd.Read()) { $o = [ordered]@{}; for ($i = 0; $i -lt $rd.FieldCount; $i++) { $o[$rd.GetName($i)] = $(if ($rd.IsDBNull($i)) { $null } else { $rd.GetValue($i) }) }; $rows.Add([pscustomobject]$o) }
                    $rd.Close(); return $rows.ToArray()
                } finally { if ($c) { $c.Close(); $c.Dispose() } }
            }
        }
        $rows = @(& $Query $cs "EXEC pim.usp_RefreshStatistics @MaxStats = $(Get-PimSqlStatisticsMaxPerCall), @BudgetSeconds = $budget;" ($budget + 90))
        $row = if ($rows.Count) { $rows[0] } else { $null }
        $r = & $res $true $false '' $row
        $why = if ("$Reason".Trim()) { " after the $("$Reason".Trim())" } else { '' }
        $r.message = "statistics$why`: $($r.refreshed) refreshed of $($r.stale) stale$(if ($r.deferred) { ", $($r.deferred) left for the next call" })$(if ($r.failed) { ", $($r.failed) failed ($($row.lastError))" }) in $($r.elapsedMs) ms"
        if ($r.refreshed -or $r.failed -or $r.deferred) { Write-Host "  $($r.message)" -ForegroundColor DarkGray } else { Write-Verbose "  $($r.message)" }
        return $r
    } catch {
        $m = (("$($_.Exception.Message)" -split "`n")[0]).Trim()
        $key = if ($m.Length -gt 80) { $m.Substring(0, 80) } else { $m }
        $msg = "statistics refresh$(if ("$Reason".Trim()) { " after the $("$Reason".Trim())" }) skipped: $m -- the job carries on (best effort; the next admin run installs the procedure, the next update converges its grant)"
        # NOT INSTALLED YET is an expected state (an install whose admin run has not created the procedure): said quietly.
        # Anything else (EXECUTE denied, a timeout) is one warning per reason per process.
        if ($m -match '(?i)Could not find stored procedure') { Write-Verbose "[store] $msg" }
        elseif (-not $script:PimSqlStatsWarned.ContainsKey($key)) { $script:PimSqlStatsWarned[$key] = $true; Write-Warning "[store] $msg" } else { Write-Verbose "[store] $msg" }
        return (& $res $false $false $msg $null)
    }
}

function Get-PimSqlStatisticsProbeSql {
    <#
      PURE. READ-ONLY. One row: asyncOn (1/0), canAlterDb (ALTER on this database), canOwner (may impersonate the schema owner
      dbo -- what CREATE ... WITH EXECUTE AS OWNER needs), procState (0 = no procedure, 1 = another version, 2 = this version).
    #>
    return @"
SELECT CAST(d.is_auto_update_stats_async_on AS int) AS asyncOn,
       ISNULL(HAS_PERMS_BY_NAME(NULL, N'DATABASE', N'ALTER'), 0) AS canAlterDb,
       ISNULL(HAS_PERMS_BY_NAME(N'dbo', N'USER', N'IMPERSONATE'), 0) AS canOwner,
       CASE WHEN OBJECT_ID(N'pim.usp_RefreshStatistics') IS NULL THEN 0
            WHEN ISNULL(OBJECT_DEFINITION(OBJECT_ID(N'pim.usp_RefreshStatistics')), N'') LIKE N'%pim-stats v1%' THEN 2 ELSE 1 END AS procState
FROM sys.databases d WHERE d.database_id = DB_ID()
"@
}

function Initialize-PimSqlStatistics {
    <#
      Framework 12.27, both halves for one database. NEVER throws. Returns @{ async; procedure; procedureError; left[] }.
        -Admin   the ADMIN run (Invoke-PimSqlAccessInstall, ca-pim-dbinit): does whatever is not done yet.
        default  the SCHEMA STEP (Initialize-PimSqlStore, the updater / setup): does a half ONLY when the probe says this
                 identity holds the right; otherwise that half is LEFT to the admin run (in .left, a quiet line, no warning) --
                 the least-privilege updater never sends ALTER DATABASE or an EXECUTE AS OWNER module (real SQL refuses both).
      A refused statement is ONE warning, never a throw. The procedure is (re)created only when missing or another version
      (CREATE OR ALTER keeps its grants); the async setting only while off (Set-PimSqlStatisticsAsync reads it back).
    #>
    # -ConnectionString may be EMPTY: the admin run (Invoke-PimSqlAccessInstall) passes its caller's own connection in -Query / -Exec.
    param([AllowEmptyString()][string]$ConnectionString = '', [scriptblock]$Query, [scriptblock]$Exec, [switch]$Admin)
    if (-not $Query) { $Query = { param($cs, $sql) Invoke-PimSqlQuery -ConnectionString $cs -Sql $sql } }
    if (-not $Exec)  { $Exec  = { param($cs, $sql) [void](Invoke-PimSqlNonQuery -ConnectionString $cs -Sql $sql) } }
    $pr = $null
    try { $pr = @(& $Query $ConnectionString (Get-PimSqlStatisticsProbeSql))[0] } catch { $pr = $null; Write-Verbose "[store] statistics: the probe could not be read: $($_.Exception.Message)" }
    $num = { param($n) if ($pr -and $pr.PSObject.Properties[$n] -and $null -ne $pr.$n -and "$($pr.$n)" -ne '') { [int]"$($pr.$n)" } else { -1 } }
    $asyncOn = & $num 'asyncOn'; $canDb = & $num 'canAlterDb'; $canOwn = & $num 'canOwner'; $pState = & $num 'procState'
    $left = New-Object System.Collections.Generic.List[string]
    # (1) async
    $a = $null
    if ($asyncOn -eq 1) { $a = [pscustomobject]@{ ok = $true; on = $true; changed = $false; message = 'auto update statistics async: already on' } }
    elseif ($Admin -or $canDb -eq 1) { $a = Set-PimSqlStatisticsAsync -ConnectionString $ConnectionString -Query $Query -Exec $Exec -Quiet }
    else { $left.Add('async'); $a = [pscustomobject]@{ ok = $false; on = $false; changed = $false; message = 'auto update statistics async is off and this identity may not change the database -- left to the admin run' } }
    # (2) the procedure
    $pOk = ($pState -eq 2); $pErr = ''
    if (-not $pOk) {
        if ($Admin -or $canOwn -eq 1) {
            try { & $Exec $ConnectionString (Get-PimSqlRefreshStatisticsProcedureSql); $pOk = $true }
            catch { $pErr = (("$($_.Exception.Message)" -split "`n")[0]).Trim(); Write-Warning "[store] pim.usp_RefreshStatistics could not be created: $pErr -- statistics are not refreshed after bulk writes until it is; nothing else is affected" }
        } else { $left.Add('procedure'); $pErr = 'this identity may not create an EXECUTE AS OWNER procedure -- left to the admin run' }
    }
    if ($left.Count) { Write-Host "  statistics: $($left -join ' + ') left to the admin run (this identity holds no right for it; framework 12.27)" -ForegroundColor DarkGray }
    return [pscustomobject]@{ async = $a; procedure = $pOk; procedureError = $pErr; left = @($left.ToArray()) }
}

function Initialize-PimSqlStore {
    # Create the pim schema + tables (pim.Rows + pim.ChangeQueue). Idempotent.
    param([Parameter(Mandatory)][string]$ConnectionString)
    $ddl = @"
IF SCHEMA_ID('pim') IS NULL EXEC ('CREATE SCHEMA pim');
IF OBJECT_ID('pim.Rows') IS NULL
CREATE TABLE pim.Rows (
    Entity      NVARCHAR(100) NOT NULL,
    [Key]       NVARCHAR(400) NOT NULL,
    DataJson    NVARCHAR(MAX) NULL,
    UpdatedUtc  DATETIME2     NOT NULL CONSTRAINT DF_Rows_Updated DEFAULT SYSUTCDATETIME(),
    CONSTRAINT PK_pim_Rows PRIMARY KEY (Entity, [Key])
);
IF OBJECT_ID('pim.Settings') IS NULL
CREATE TABLE pim.Settings (
    Name        NVARCHAR(200) NOT NULL PRIMARY KEY,
    ValueJson   NVARCHAR(MAX) NULL,
    UpdatedUtc  DATETIME2     NOT NULL CONSTRAINT DF_Settings_Updated DEFAULT SYSUTCDATETIME()
);
-- SEC-16 (§36.2). The Manager's audit trail. It used to be appended to
-- output/audit/pim-audit-YYYYMM.jsonl on the container filesystem, and the hosted app mounts
-- NO persistent volume (measured 2026-08-31: volumes=null, mounts=null) -- so every revision
-- roll destroyed the entire trail. The audit is the one record that must OUTLIVE the thing it
-- audits: desired state is already in SQL, the tenant cache rebuilds, engine logs are copied to
-- Log Analytics. "Who granted privileged access" was the only thing with no second home.
-- ActorSource is here because of the second half of SEC-16: the writer recorded the CONTAINER's
-- process identity, so every row said the same thing. Storing WHERE the actor came from makes a
-- future regression of that kind visible in the data instead of invisible.
IF OBJECT_ID('pim.AuditEvents') IS NULL
CREATE TABLE pim.AuditEvents (
    Id            BIGINT IDENTITY(1,1) PRIMARY KEY,
    Ts            DATETIME2     NOT NULL CONSTRAINT DF_PimAudit_Ts DEFAULT SYSUTCDATETIME(),
    RunId         NVARCHAR(64)  NULL,
    CorrelationId NVARCHAR(64)  NULL,
    Actor         NVARCHAR(200) NOT NULL,
    ActorSource   NVARCHAR(100) NULL,
    Action        NVARCHAR(100) NOT NULL,
    Target        NVARCHAR(400) NOT NULL,
    BeforeJson    NVARCHAR(MAX) NULL,
    AfterJson     NVARCHAR(MAX) NULL,
    Result        NVARCHAR(100) NOT NULL CONSTRAINT DF_PimAudit_Result DEFAULT 'ok',
    WhatIf        BIT           NOT NULL CONSTRAINT DF_PimAudit_WhatIf DEFAULT 0
);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AuditEvents_Ts')
CREATE INDEX IX_pim_AuditEvents_Ts ON pim.AuditEvents (Ts DESC);
-- 2026-09-13 (SQL-only). The Manager's tenant-list caches (entra-roles, aus, pim-groups,
-- azure-scopes, azure-rbac-roles, auth-methods, pim-activity, tenant-org) used to be JSON files
-- under tools/pim-manager/cache/<instance>/. One row per kind; the database IS the instance, so
-- there is no instance column. RefreshedUtc is the freshness stamp the validator reads.
IF OBJECT_ID('pim.TenantCache') IS NULL
CREATE TABLE pim.TenantCache (
    Kind          NVARCHAR(64)  NOT NULL CONSTRAINT PK_pim_TenantCache PRIMARY KEY,
    ValueJson     NVARCHAR(MAX) NULL,
    RefreshedUtc  DATETIME2     NULL,
    UpdatedUtc    DATETIME2     NOT NULL CONSTRAINT DF_TenantCache_Updated DEFAULT SYSUTCDATETIME()
);
-- Schema conformance for a table created by an earlier build: add any column it lacks (additive only).
IF COL_LENGTH('pim.TenantCache','ValueJson') IS NULL ALTER TABLE pim.TenantCache ADD ValueJson NVARCHAR(MAX) NULL;
IF COL_LENGTH('pim.TenantCache','RefreshedUtc') IS NULL ALTER TABLE pim.TenantCache ADD RefreshedUtc DATETIME2 NULL;
IF COL_LENGTH('pim.TenantCache','UpdatedUtc') IS NULL ALTER TABLE pim.TenantCache ADD UpdatedUtc DATETIME2 NOT NULL CONSTRAINT DF_TenantCache_Updated2 DEFAULT SYSUTCDATETIME();
"@
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql $ddl)
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql (Get-PimChangeQueueDdl))
    [void](Initialize-PimNamingConventionSeed -ConnectionString $ConnectionString)
    [void](Invoke-PimRingOrderMigration -ConnectionString $ConnectionString)
    [void](Invoke-PimDepartmentRowKeyMigration -ConnectionString $ConnectionString)
    # AUDIT-1.3: pim.AuditEvents is append-only IN THE DATABASE (trigger; PIM-AuditRetention.ps1). Never throws: a store
    # that cannot take the guard still opens, and says so.
    if (Get-Command Initialize-PimAuditAppendOnly -ErrorAction SilentlyContinue) { [void](Initialize-PimAuditAppendOnly -ConnectionString $ConnectionString) }
    # AUDIT-1 actor: who initiated / approved each committed row (PIM-ChangeAttribution.ps1). Never fails the store open.
    if (Get-Command Get-PimChangeAttributionDdl -ErrorAction SilentlyContinue) { try { [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql (Get-PimChangeAttributionDdl)) } catch { Write-Warning "[audit] pim.ChangeAttribution could not be created: $($_.Exception.Message)" } }
    # SEC-80: the ledger of live items PIM manages (PIM-ManagedKeys.ps1) -- a prune removes only these. Never fails the open
    # (a store without it reads as an empty ledger: nothing prunable).
    if (Get-Command Get-PimManagedKeysDdl -ErrorAction SilentlyContinue) { try { [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql (Get-PimManagedKeysDdl)) } catch { Write-Warning "[engine] pim.ManagedKeys could not be created: $($_.Exception.Message)" } }
    # CONFIG-1.1: the change journal (PIM-CommitJournal.ps1). Never fails the open -- without it every write is refused.
    if (Get-Command Initialize-PimCommitJournal -ErrorAction SilentlyContinue) { [void](Initialize-PimCommitJournal -ConnectionString $ConnectionString) }
    # CONFIG-1.1 / 96.1: the engine's applied outcome per row (PIM-CommitJournal.ps1). Never fails the open.
    if (Get-Command Initialize-PimCommitApplied -ErrorAction SilentlyContinue) { [void](Initialize-PimCommitApplied -ConnectionString $ConnectionString) }
    # Framework §12.11f item 2 / PIM 100.144a: the captured signatures (PIM-SignedRequests.ps1). Never fails the open.
    if (Get-Command Initialize-PimSignedRequestStore -ErrorAction SilentlyContinue) { [void](Initialize-PimSignedRequestStore -ConnectionString $ConnectionString) }
    # CONFIG-1.3: the configuration backup tables (PIM-ConfigBackup.ps1). Never fails the open.
    if (Get-Command Initialize-PimConfigBackupStore -ErrorAction SilentlyContinue) { [void](Initialize-PimConfigBackupStore -ConnectionString $ConnectionString) }
    # CR8 item 1 (PIM 100.152): the commit snapshot table (pim.Backups) is created HERE too -- the Manager used to create it
    # on first use, and after the cut-over it has no right to change the schema (the updater runs this before every roll).
    if (Get-Command Initialize-PimBackupStore -ErrorAction SilentlyContinue) { [void](Initialize-PimBackupStore -ConnectionString $ConnectionString) }
    # Framework §12.23 / PIM 100.156: the activation ledger (pim.ImpactActivations) was created ONLY by the engine's
    # snapshot job, right before its first insert -- the one engine DDL the updater did not already create. Created here
    # too, so the engine can lose db_ddladmin (run 2) without that job failing. Never fails the open.
    if (Get-Command Get-PimImpactActivationLedgerDdl -ErrorAction SilentlyContinue) { try { [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql (Get-PimImpactActivationLedgerDdl)) } catch { Write-Warning "[store] pim.ImpactActivations could not be created: $($_.Exception.Message)" } }
    # REQ 100.114 (2): the active-assignment rows (pim.ActiveAssignmentRows + pim.ActiveAssignmentSnapshots, below in this
    # file). Never fails the open: a store that cannot take the tables keeps the one-document snapshot, and says so.
    $aaDdl = Initialize-PimSqlActiveAssignmentRows -ConnectionString $ConnectionString
    if (-not $aaDdl.ok) { Write-Warning "[store] pim.ActiveAssignmentRows could not be created: $($aaDdl.error) -- the active-assignments snapshot stays one document in pim.TenantCache" }
    # Framework §12.23 run 2 prerequisite (PIM 100.156): the publish job's control view (REQ-Y licence row) was refreshed
    # by the MANAGER at every start -- a CREATE OR ALTER VIEW the web app may not run once it has no DDL right. The schema
    # step (the updater, before every roll) refreshes it now; a store without the view is left alone (the refresh SQL
    # itself checks). Never fails the open.
    if (Get-Command Get-PimPublishJobControlViewRefreshSql -ErrorAction SilentlyContinue) {
        try { [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql (Get-PimPublishJobControlViewRefreshSql)) }
        catch { Write-Warning "[store] the publish job's control view could not be refreshed: $($_.Exception.Message)" }
    }
    # Framework §12.23 run 2 (PIM 100.156, 2.4.645 candidate): the EMPTY demo tables (pimdemo.Meta / Principals / Assignments /
    # Activity / Tenants). Run 1 and the 2.4.644 admin batch create only the EMPTY pimdemo SCHEMA, and the web app holds no
    # DDL right, so a first demo Enable there could not create them. The schema step (the updater -- or, on a community
    # install, the setup identity's re-run) creates them here, idempotently, from the demo module's ONE definition
    # (Get-PimDemoSchemaDdl), inside the demo scope. Tables only: NEVER a row (demo data stays the owner's switch,
    # Set-PimDemoMode). Loaded only here, by the schema step -- no engine path reads the demo module. Never fails the open.
    if (-not (Get-Command Get-PimDemoSchemaDdl -ErrorAction SilentlyContinue)) {
        $__demoLib = Join-Path $PSScriptRoot 'PIM-DemoData.ps1'
        if (Test-Path -LiteralPath $__demoLib) { <# optional load of $__demoLib left out: this file is self-contained #> }
    }
    if ((Get-Command Get-PimDemoSchemaDdl -ErrorAction SilentlyContinue) -and (Get-Command Invoke-PimDemoSql -ErrorAction SilentlyContinue)) {
        try { [void](Invoke-PimDemoSql -Kind nonquery -ConnectionString $ConnectionString -Sql (Get-PimDemoSchemaDdl)) }
        catch { Write-Warning "[store] the demo tables (pimdemo) could not be created: $($_.Exception.Message) -- demo mode stays unavailable until the next update; nothing else is affected" }
    } else {
        # 2026-10-16 (Invardia): the standalone support scripts (Grant-PimSupportSqlAccess, Initialize-PimMailSender,
        # Set-PimLicense ...) carry this store code WITHOUT the demo module -- a customer must not see a warning there; the
        # updater's schema step (which has the module) creates the tables. Verbose only.
        Write-Verbose '[store] the demo module (PIM-DemoData.ps1) is not in this payload -- the demo tables are left to the updater'
    }
    # Framework 12.27 SQL-STATS (PIM SQL-STATS-ASYNC): AUTO_UPDATE_STATISTICS_ASYNC ON (read back) + pim.usp_RefreshStatistics.
    # LAST, on its own statements (ALTER DATABASE is refused inside a transaction), and never fails the open: a refusal is a
    # warning. The updater reaches this only inside its SCHEMA-QUIESCE-818 path (update-job-entry.ps1).
    [void](Initialize-PimSqlStatistics -ConnectionString $ConnectionString)
}

# ---- Framework §12.23 run 2 prerequisite (PIM 100.156): the RUNTIME never needs a DDL right ----------------------------
# Every table / column / view is created by the schema step (Initialize-PimSqlStore, run by the updater before every roll
# and by setup). A runtime path (the engine, the Manager) only CHECKS that what it is about to use is there -- read-only,
# OBJECT_ID / COL_LENGTH -- once per process and store. When something is missing (an install whose updater has not run
# since the object was added, a developer store), ONE -Fallback try of the old create is made: it works only where the
# identity still holds the right (a developer box, an install before run 2) and is refused harmlessly afterwards; still
# missing = a plain message naming the updater, never a DDL error from deep inside a job.
$script:PimSchemaReadyCache = @{}

function Get-PimSqlSchemaMissing {
    <#
      READ-ONLY. The -Objects (schema.object) and -Columns (@{ 'schema.table' = @('Col', ...) }) that are NOT in this
      store. Returns string[] ('pim.X' / 'pim.X.Col'); empty = ready. THROWS when the store cannot be read.
      -Query: param($cs, $sql, $params) -> rows (test seam; default Invoke-PimSqlQuery).
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [string[]]$Objects = @(), [hashtable]$Columns = @{}, [scriptblock]$Query)
    if (-not $Query) { $Query = { param($cs, $sql, $p) Invoke-PimSqlQuery -ConnectionString $cs -Sql $sql -Parameters $p } }
    $sel = New-Object System.Collections.Generic.List[string]; $p = @{}; $names = @{}; $i = 0
    foreach ($o in @($Objects)) { if (-not "$o".Trim()) { continue }; $sel.Add("CASE WHEN OBJECT_ID(@o$i) IS NULL THEN 0 ELSE 1 END AS [k$i]"); $p["o$i"] = "$o"; $names["k$i"] = "$o"; $i++ }
    foreach ($t in @($Columns.Keys)) {
        foreach ($c in @($Columns[$t])) { if (-not "$c".Trim()) { continue }; $sel.Add("CASE WHEN COL_LENGTH(@o$i, @c$i) IS NULL THEN 0 ELSE 1 END AS [k$i]"); $p["o$i"] = "$t"; $p["c$i"] = "$c"; $names["k$i"] = "$t.$c"; $i++ }
    }
    if (-not $sel.Count) { return @() }
    $rows = @(& $Query $ConnectionString ("SELECT " + ($sel -join ', ')) $p)
    if (-not $rows.Count) { throw 'the schema check returned no row' }
    $r = $rows[0]; $miss = New-Object System.Collections.Generic.List[string]
    foreach ($k in @($names.Keys | Sort-Object { [int]("$_".Substring(1)) })) {
        $v = if ($r -is [System.Collections.IDictionary]) { $r[$k] } else { $r.$k }
        if ("$v" -ne '1') { $miss.Add("$($names[$k])") }
    }
    return @($miss.ToArray())
}

function Confirm-PimSqlSchemaObject {
    <#
      The runtime half of §12.23 run 2: is everything this path uses in the store? NEVER throws:
      @{ ok; created; missing[]; message }. ok = ready (or created by the -Fallback). Cached per process and store once
      ready (not when -Query is a test seam). -Fallback: { } -- the old create, tried ONCE only when something is missing.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [string[]]$Objects = @(), [hashtable]$Columns = @{},
          [scriptblock]$Fallback, [scriptblock]$Query)
    $key = "$ConnectionString|$(@($Objects) -join ',')|$(@($Columns.Keys | Sort-Object | ForEach-Object { "$_=$(@($Columns[$_]) -join '+')" }) -join ';')"
    if (-not $Query -and $script:PimSchemaReadyCache.ContainsKey($key)) { return [pscustomobject]@{ ok = $true; created = $false; missing = @(); message = '' } }
    $miss = @()
    try { $miss = @(Get-PimSqlSchemaMissing -ConnectionString $ConnectionString -Objects $Objects -Columns $Columns -Query $Query) }
    catch { return [pscustomobject]@{ ok = $false; created = $false; missing = @(); message = "the store could not be checked: $($_.Exception.Message)" } }
    if (-not $miss.Count) { if (-not $Query) { $script:PimSchemaReadyCache[$key] = $true }; return [pscustomobject]@{ ok = $true; created = $false; missing = @(); message = '' } }
    $why = ''
    if ($Fallback) {
        try {
            [void](& $Fallback)
            $miss = @(Get-PimSqlSchemaMissing -ConnectionString $ConnectionString -Objects $Objects -Columns $Columns -Query $Query)
            if (-not $miss.Count) { if (-not $Query) { $script:PimSchemaReadyCache[$key] = $true }; return [pscustomobject]@{ ok = $true; created = $true; missing = @(); message = '' } }
        } catch { $why = " ($((("$($_.Exception.Message)") -split "`n")[0]))" }
    }
    return [pscustomobject]@{ ok = $false; created = $false; missing = @($miss)
        message = ("{0} {1} not in this store -- the next update creates it (the updater's schema step); this component does not create tables{2}" -f (@($miss) -join ', '), $(if (@($miss).Count -eq 1) { 'is' } else { 'are' }), $why) }
}

function Test-PimSqlCanCreateTable {
    <#
      READ-ONLY. May THIS identity create a table in this database (HAS_PERMS_BY_NAME CREATE TABLE -- db_ddladmin / db_owner
      / an explicit grant)? $false when it may not OR the store cannot be read: never throws. -Query: param($cs, $sql) -> rows.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [scriptblock]$Query)
    if (-not $Query) { $Query = { param($cs, $sql) Invoke-PimSqlQuery -ConnectionString $cs -Sql $sql } }
    try {
        $r = @(& $Query $ConnectionString "SELECT HAS_PERMS_BY_NAME(NULL, NULL, 'CREATE TABLE') AS canCreate;")[0]
        return ($null -ne $r -and "$($r.canCreate)" -eq '1')
    } catch { return $false }
}

function Wait-PimHostedStoreSchema {
    <#
      Framework §12.23 run 2 (PIM 100.156, live 2026-10-16 on a fresh community install): a HOSTED component whose store has
      no core tables yet (the Manager's FIRST start, before the deploy's schema step ran) must not attempt DDL -- it holds no
      DDL right, and the attempt logged "CREATE TABLE permission denied" with a stack trace. Instead: ONE calm line, then the
      READ-ONLY check is repeated every -IntervalSeconds until the tables are there or -MaxWaitSeconds passed; one more line
      when they appear. NEVER throws, never runs DDL. Returns { ready; checks; waitedSeconds; missing[] }.
      -Check: param($cs, $objects) -> { ok; missing } (default Confirm-PimSqlSchemaObject, no -Fallback). -Sleep: param($s).
      -Log: param($text) (default Write-Host). All three are test seams.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [string[]]$Objects = @(), [int]$IntervalSeconds = 30, [int]$MaxWaitSeconds = 900,
          [scriptblock]$Check, [scriptblock]$Sleep, [scriptblock]$Log)
    if (-not $Check) { $Check = { param($cs, $o) Confirm-PimSqlSchemaObject -ConnectionString $cs -Objects $o } }
    if (-not $Sleep) { $Sleep = { param($s) Start-Sleep -Seconds $s } }
    if (-not $Log) { $Log = { param($t) Write-Host $t -ForegroundColor DarkGray } }
    if ($IntervalSeconds -lt 1) { $IntervalSeconds = 1 }
    if ($MaxWaitSeconds -lt 0) { $MaxWaitSeconds = 0 }
    $waited = 0; $checks = 0; $said = $false; $miss = @()
    while ($true) {
        $checks++
        $r = $null; try { $r = & $Check $ConnectionString $Objects } catch { $r = $null }
        if ($r -and $r.ok) {
            if ($said) { & $Log ("  [store] the store's schema is there now (after {0} s) -- starting" -f $waited) }
            return [pscustomobject]@{ ready = $true; checks = $checks; waitedSeconds = $waited; missing = @() }
        }
        if ($r -and $r.PSObject.Properties['missing']) { $miss = @($r.missing) }
        if (-not $said) {
            & $Log ("  [store] waiting for the store's schema -- the install / update creates it (checking again every {0} s)" -f $IntervalSeconds)
            $said = $true
        }
        if ($waited -ge $MaxWaitSeconds) { return [pscustomobject]@{ ready = $false; checks = $checks; waitedSeconds = $waited; missing = @($miss) } }
        $step = [Math]::Min($IntervalSeconds, [Math]::Max(1, $MaxWaitSeconds - $waited))
        & $Sleep $step
        $waited += $step
    }
}

function Invoke-PimDepartmentRowKeyMigration {
    <#
      2.4.462 -- re-key PIM-Definitions-Departments to the new store key (Get-PimStoreRowKey: a department GROUP row by its
      GroupTag, an owner row by its department name). Before 2.4.462 group rows were keyed on the Department column, so a
      new group of an existing department collided with that department's owner row and its save was refused.
      A full-set save re-keys by itself, but ROW-BY-ROW writers (the MSP downlink) would add a second copy next to the old
      key -- so existing rows are moved here, once, idempotently:
        * key already right                         -> untouched
        * new key free                              -> UPDATE [Key] (the row keeps its data and timestamp)
        * new key taken by a row with the SAME data -> the old-key copy is a duplicate -> deleted
        * new key taken by DIFFERENT data           -> left alone and reported (never merged or overwritten)
      Returns @{ moved; deduplicated; conflicts[] }. Never throws: a failed migration must not stop the store from opening.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [object[]]$Rows = $null, [scriptblock]$Exec = $null)
    $out = @{ moved = 0; deduplicated = 0; conflicts = @() }
    try {
        $e = 'PIM-Definitions-Departments'
        if ($null -eq $Rows) { $Rows = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT [Key], DataJson FROM pim.Rows WHERE Entity=@e" -Parameters @{ e = $e }) }
        if (-not $Exec) { $Exec = { param($sql, $p) [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql $sql -Parameters $p) } }
        $byKey = @{}; foreach ($r in @($Rows)) { if ($r) { $byKey["$($r.Key)".ToLowerInvariant()] = $r } }
        foreach ($r in @($Rows)) {
            if (-not $r) { continue }
            $data = $null; try { $data = "$($r.DataJson)" | ConvertFrom-Json } catch { continue }
            $nk = "$(Get-PimStoreRowKey -Base $e -Row $data)".Trim()
            if (-not $nk -or $nk -ieq "$($r.Key)") { continue }
            $other = $byKey[$nk.ToLowerInvariant()]
            if (-not $other) {
                & $Exec 'UPDATE pim.Rows SET [Key]=@nk WHERE Entity=@e AND [Key]=@ok' @{ e = $e; nk = $nk; ok = "$($r.Key)" }
                $byKey.Remove("$($r.Key)".ToLowerInvariant()); $byKey[$nk.ToLowerInvariant()] = $r
                $out.moved++
            } elseif ("$($other.DataJson)" -eq "$($r.DataJson)") {
                & $Exec 'DELETE FROM pim.Rows WHERE Entity=@e AND [Key]=@ok' @{ e = $e; ok = "$($r.Key)" }
                $byKey.Remove("$($r.Key)".ToLowerInvariant())
                $out.deduplicated++
            } else {
                $out.conflicts += "$($r.Key) -> $nk"
            }
        }
        if ($out.moved -or $out.deduplicated) { Write-Host ("[store] Departments re-keyed to the 2.4.462 store key: moved {0}, duplicates removed {1}" -f $out.moved, $out.deduplicated) -ForegroundColor DarkCyan }
        if ($out.conflicts.Count) { Write-Warning ("[store] Departments: {0} row(s) could not be re-keyed (a different row already holds the new key): {1}" -f $out.conflicts.Count, ($out.conflicts -join '; ')) }
    } catch { Write-Warning "[store] Departments re-key migration skipped: $($_.Exception.Message)" }
    return $out
}

function Get-PimRingOrderMigrationSql {
    # §77.20 -- the ONE-TIME conversion of every stored ring to the dev-first order (new = 2 - old), in ONE transaction,
    # guarded by the pim.Settings['RingOrder'] marker read under UPDLOCK so two starts cannot both convert. Rings outside
    # 0..2 are left as they are (they reached no tenant before and reach none now). UpdatedUtc is NOT touched: the
    # conversion changes no reach, so it must not look like an edit to the change detector.
    return @"
SET XACT_ABORT ON;
BEGIN TRAN;
IF NOT EXISTS (SELECT 1 FROM pim.Settings WITH (UPDLOCK, HOLDLOCK) WHERE Name = 'RingOrder')
BEGIN
    DECLARE @rows INT = 0, @central INT = 0, @tenants INT = 0;
    UPDATE pim.Rows
       SET DataJson = JSON_MODIFY(DataJson, '$.Ring', CAST(2 - CAST(JSON_VALUE(DataJson, '$.Ring') AS INT) AS NVARCHAR(10)))
     WHERE ISJSON(DataJson) = 1 AND JSON_VALUE(DataJson, '$.Ring') IN ('0', '1', '2');
    SET @rows = @@ROWCOUNT;
    IF OBJECT_ID('pim.CentralAdmins') IS NOT NULL
    BEGIN
        EXEC sp_executesql N'UPDATE pim.CentralAdmins SET Ring = 2 - Ring WHERE Ring BETWEEN 0 AND 2; SET @n = @@ROWCOUNT;', N'@n INT OUTPUT', @n = @central OUTPUT;
    END
    IF OBJECT_ID('platform.Tenants') IS NOT NULL AND COL_LENGTH('platform.Tenants', 'Ring') IS NOT NULL
    BEGIN
        EXEC sp_executesql N'UPDATE platform.Tenants SET Ring = 2 - Ring WHERE Ring BETWEEN 0 AND 2; SET @n = @@ROWCOUNT;', N'@n INT OUTPUT', @n = @tenants OUTPUT;
    END
    INSERT pim.Settings (Name, ValueJson)
    VALUES ('RingOrder', CONCAT('{"order":"dev-first","convertedUtc":"', CONVERT(NVARCHAR(30), SYSUTCDATETIME(), 127),
                                '","rows":', @rows, ',"centralAdmins":', @central, ',"tenants":', @tenants, '}'));
    SELECT 'converted' AS Outcome, @rows AS RowsConverted, @central AS CentralAdmins, @tenants AS Tenants;
END
ELSE
    SELECT 'already' AS Outcome, 0 AS RowsConverted, 0 AS CentralAdmins, 0 AS Tenants;
COMMIT;
"@
}

function Invoke-PimRingOrderMigration {
    <#
      §77.20 (operator 2026-09-21: "ring 0 = dev, ring 1 = test, ring 2 = broad (all)" / "make it consistent"). Until
      2.4.388 ring 0 was the BROADEST reach; every stored ring is converted ONCE per store so each row keeps exactly the
      tenants it reached: pim.Rows (every entity's Ring), pim.CentralAdmins.Ring, platform.Tenants.Ring, and the
      conformance overlay's per-entry rings. Idempotent (marker pim.Settings['RingOrder']); a fresh store just gets
      the marker. Returns @{ outcome = converted|already|failed; rows; centralAdmins; tenants; overlay; error }.
      A failure is REPORTED, never thrown: the store keeps working, and the next start tries again.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString)
    $res = [ordered]@{ outcome = 'failed'; rows = 0; centralAdmins = 0; tenants = 0; overlay = 0; error = '' }
    try {
        # The conformance overlay first: it carries its own done-flag, so a retry after a failed SQL step never
        # converts it twice.
        $ov = $null
        try { $ov = Get-PimSqlSetting -ConnectionString $ConnectionString -Name 'ConformanceTemplateOverlay' } catch { $ov = $null }
        $marker = $null
        try { $marker = Get-PimSqlSetting -ConnectionString $ConnectionString -Name 'RingOrder' } catch { $marker = $null }
        if ($null -eq $marker -and $null -ne $ov) {
            if ($ov -is [string]) { try { $ov = $ov | ConvertFrom-Json } catch { $ov = $null } }
            if ($null -ne $ov -and -not $ov.PSObject.Properties['__ringOrder']) {
                $n = 0
                foreach ($tp in @($ov.PSObject.Properties)) {
                    $entry = $tp.Value
                    if ($null -eq $entry -or -not $entry.PSObject -or -not $entry.PSObject.Properties['rings'] -or $null -eq $entry.rings) { continue }
                    foreach ($rp in @($entry.rings.PSObject.Properties)) {
                        if ("$($rp.Value)".Trim() -match '^[0-2]$') { $rp.Value = 2 - [int]"$($rp.Value)".Trim(); $n++ }
                    }
                }
                $ov | Add-Member -NotePropertyName '__ringOrder' -NotePropertyValue 'dev-first' -Force
                Set-PimSqlSetting -ConnectionString $ConnectionString -Name 'ConformanceTemplateOverlay' -ValueJson ($ov | ConvertTo-Json -Depth 10 -Compress) | Out-Null
                $res.overlay = $n
            }
        }
        $out = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql (Get-PimRingOrderMigrationSql))
        $row = $out | Select-Object -Last 1
        $res.outcome = "$($row.Outcome)"
        $res.rows = [int]$row.RowsConverted; $res.centralAdmins = [int]$row.CentralAdmins; $res.tenants = [int]$row.Tenants
        if ($res.outcome -eq 'converted') {
            Write-Host ("  [store] ring order converted to dev-first (0 dev, 1 test, 2 broad): {0} row(s), {1} central admin(s), {2} tenant(s), {3} conformance ring(s) -- every row keeps the tenants it reached" -f $res.rows, $res.centralAdmins, $res.tenants, $res.overlay) -ForegroundColor Yellow
        }
    } catch {
        $res.error = "$($_.Exception.Message)"
        Write-Warning ("  [store] the ring-order conversion (0 dev, 1 test, 2 broad) did NOT run: {0} -- rings are still in the OLD order in this store; it is retried on the next start." -f $res.error)
    }
    return $res
}

function Initialize-PimNamingConventionSeed {
    <#
      🔴 DEPLOY THE DEFAULT NAMING TEMPLATE INTO THE STORE (operator, 2026-09-20: *"naming convention are
      always per customer. if this are samples or default or initial, then we should incude that in the
      deployment instead"* / *"remember to add it to setup script also so we can deploy default naming
      template"*).

      Naming used to have THREE homes: the shipped defaults in code (PIM-Naming.ps1), a hand-synced copy in
      config\PIM4EntraPS.NamingConventions.locked.ps1, and pim.Settings. The file is gone; this is what
      replaces it -- every path that creates or opens a store (Initialize-PimTenantStore, the Manager's
      boot, the updater's schema step, Invoke-PimUpdate) now SEEDS the shipped defaults into
      pim.Settings['NamingConventions'], so a fresh environment has a complete, editable naming template on
      day one and nothing has to read a file.

      🔒 SEED, NEVER OVERWRITE. Naming is per customer: if the setting already exists -- even empty-ish --
      it is left exactly as it is. Writing defaults over a customer's conventions would silently rename
      every group and admin account the next run computes. Best-effort: a store that cannot take the seed
      is not a reason to fail store initialisation, so this never throws.
    #>
    [CmdletBinding()] param([Parameter(Mandatory)][string]$ConnectionString)
    try {
        if (-not (Get-Command Get-PimShippedNamingConventions -ErrorAction SilentlyContinue)) { return $false }
        $existing = $null
        try { $existing = Get-PimSqlSetting -ConnectionString $ConnectionString -Name 'NamingConventions' } catch { return $false }
        if ($null -ne $existing) { return $false }          # already the customer's -- untouched
        # 🔴 SEED A *NEW* STORE ONLY -- NEVER AN ESTABLISHED ONE.
        # Absent is not the same as new. An environment that already holds admins and groups was named by
        # SOME convention; if its setting is missing, writing the SHIPPED default here would declare the
        # wrong convention and the engine would then happily run on it. MSP-SETUP-GUIDE §5 / IMP-13:
        # a test tenant's admins are 'admin-contoso-{Initial}', so the shipped 'Admin-{Initial}' would make every one
        # of them invisible to the Admins provider's prefix match -- re-created every tick, accumulating
        # unmanaged privileged accounts. Seeding the wrong convention is WORSE than not seeding: on a
        # populated store we leave it absent so the engine's preflight REFUSES and a human decides.
        $populated = $true
        try {
            $rows = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql 'SELECT TOP 1 1 AS x FROM pim.Rows')
            $populated = [bool](@($rows).Count)
        } catch { $populated = $true }                      # cannot tell => treat as established, do not seed
        if ($populated) {
            Write-Warning ("  [store] pim.Settings['NamingConventions'] is NOT set and this store already holds rows -- " +
                           "NOT seeding the shipped default (it would declare the wrong convention for an estate that is already named). " +
                           "Set this tenant's convention in the Manager (Settings > Naming); the engine refuses to run until it is there.")
            return $false
        }
        $shipped = Get-PimShippedNamingConventions
        if ($shipped -isnot [System.Collections.IDictionary] -or -not $shipped.Keys.Count) { return $false }
        Set-PimSqlSetting -ConnectionString $ConnectionString -Name 'NamingConventions' `
            -ValueJson (ConvertTo-Json -InputObject $shipped -Depth 12 -Compress)
        $back = Get-PimSqlSetting -ConnectionString $ConnectionString -Name 'NamingConventions'
        if ($null -eq $back) { Write-Warning '  [store] the default naming template was written but did not read back.'; return $false }
        Write-Host ("  [store] seeded the default naming template into pim.Settings['NamingConventions'] ({0} keys) -- edit it per customer in the Manager." -f $shipped.Keys.Count) -ForegroundColor DarkGray
        return $true
    } catch {
        Write-Warning "  [store] could not seed the default naming template (the environment keeps the in-code defaults): $($_.Exception.Message)"
        return $false
    }
}

# --- tenant-list cache (pim.TenantCache) -------------------------------------------
function Set-PimSqlTenantCache {
    # Upsert one cache kind. -Value is the whole document (e.g. @{ refreshedUtc; items }).
    # -ValueJson (100.31 SNAPSHOT-OOM): the document ALREADY serialised by the caller (the active-assignments snapshot
    # writes its rows one at a time into one compact string); stored as given, never parsed or re-serialised here.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Kind, [object]$Value, [datetime]$RefreshedUtc = [datetime]::UtcNow,
          [AllowNull()][string]$ValueJson = $null)
    $json = if ($PSBoundParameters.ContainsKey('ValueJson')) { $(if ("$ValueJson" -ne '') { $ValueJson } else { $null }) }
            elseif ($null -ne $Value) { $Value | ConvertTo-Json -Depth 12 -Compress } else { $null }
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
MERGE pim.TenantCache AS t USING (SELECT @k AS Kind) AS s ON t.Kind = s.Kind
WHEN MATCHED THEN UPDATE SET ValueJson=@v, RefreshedUtc=@r, UpdatedUtc=SYSUTCDATETIME()
WHEN NOT MATCHED THEN INSERT (Kind, ValueJson, RefreshedUtc, UpdatedUtc) VALUES (@k, @v, @r, SYSUTCDATETIME());
"@ -Parameters @{ k = $Kind; v = $json; r = $RefreshedUtc.ToUniversalTime() } -CommandTimeoutSec 180)   # a large tenant's snapshot is one multi-MB row: 30 s timed out on a busy S0 (2026-10-08)
}

function Get-PimSqlTenantCache {
    # One cache kind, parsed; $null when the kind has never been written.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Kind)
    $j = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql "SELECT ValueJson FROM pim.TenantCache WHERE Kind=@k" -Parameters @{ k = $Kind }
    if ($null -eq $j -or $j -is [System.DBNull] -or "$j".Trim() -eq '') { return $null }
    return ($j | ConvertFrom-Json)
}

function Get-PimSqlTenantCacheStamps {
    # REQ 100.112: WHEN each kind was last written -- Kind + RefreshedUtc only, NEVER the document (one kind's document can
    # be tens of MB, and reading it is what made a "is there a snapshot?" question cost 25 s). Returns a hashtable
    # kind -> round-trip UTC text ('' when the column is NULL); a kind with no row is ABSENT from it. Throws on a failed read.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string[]]$Kinds)
    $out = @{}
    $ks = @($Kinds | Where-Object { "$_".Trim() })
    if ($ks.Count -eq 0) { return $out }
    $p = @{}; $names = New-Object System.Collections.Generic.List[string]
    for ($i = 0; $i -lt $ks.Count; $i++) { $p["k$i"] = "$($ks[$i])"; $names.Add("@k$i") }
    $rows = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql ("SELECT Kind, RefreshedUtc FROM pim.TenantCache WHERE Kind IN (" + ($names -join ', ') + ")") -Parameters $p)
    foreach ($r in $rows) {
        if ($null -eq $r) { continue }
        $v = $r.RefreshedUtc; $txt = ''
        if ($v -is [datetime]) { $txt = [datetime]::SpecifyKind($v, [DateTimeKind]::Utc).ToString('yyyy-MM-ddTHH:mm:ss.fffffffZ', [System.Globalization.CultureInfo]::InvariantCulture) }
        elseif ($null -ne $v) { $txt = "$v" }
        $out["$($r.Kind)"] = $txt
    }
    return $out
}

# --- active-assignment rows (pim.ActiveAssignmentRows) -- REQ 100.114 (2) / 100.110 ---------------------------------
# The active-assignments snapshot used to be ONE document in pim.TenantCache (22 MB at 38,000 assignments): written as
# one row (the write timed out, 100.110) and read + parsed whole for every request (25-63 s, 100.114). The ROWS now live
# in pim.ActiveAssignmentRows, one row per assignment, indexed for what the page filters and sorts on; the
# pim.TenantCache row 'active-assignments' keeps only the small header and names the generation (snapshotId) its rows
# are in. Writing = a new generation, batch by batch; the header is switched to it in ONE transaction after the row
# count was verified, so a reader sees the previous complete generation or the new complete one, never a part.
# A store where the table cannot be created keeps the one-document form (the caller falls back to it).
# Every default / limit is a FUNCTION returning a literal: a $script: variable is $null in a child scope behind a
# Get-Command load guard, and `-gt $null` is TRUE.
function Get-PimActiveAssignmentRowsBatchSize         { return 500 }    # rows per write batch (one transaction each)
function Get-PimActiveAssignmentRowsCommandTimeoutSec { return 120 }    # per batch / per statement of the snapshot write
function Get-PimActiveAssignmentRowsWriteAttempts     { return 4 }      # tries per batch on a transient error
function Get-PimActiveAssignmentRowsRetryDelayMs      { return 1500 }   # first wait; doubled per further try
function Get-PimActiveAssignmentsPageSizeDefault      { return 200 }
function Get-PimActiveAssignmentsPageSizeMax          { return 2000 }
function Get-PimActiveAssignmentsQueryTimeoutSec      { return 60 }
function Get-PimActiveAssignmentsAliasMax             { return 60 }     # exact-name alternatives per text search
function Get-PimActiveAssignmentsTableFormName        { return 'table' }

function Get-PimActiveAssignmentRowsDdl {
    <# PURE. The two tables + the indexes. Idempotent (every object guarded); additive only. #>
@'
IF OBJECT_ID('pim.ActiveAssignmentSnapshots') IS NULL
CREATE TABLE pim.ActiveAssignmentSnapshots (
    SnapshotId    BIGINT        NOT NULL CONSTRAINT PK_pim_ActiveAssignmentSnapshots PRIMARY KEY,
    State         NVARCHAR(20)  NOT NULL,
    StartedUtc    DATETIME2     NOT NULL CONSTRAINT DF_pim_AaSnapshots_Started DEFAULT SYSUTCDATETIME(),
    CompletedUtc  DATETIME2     NULL,
    RowsExpected  INT           NOT NULL CONSTRAINT DF_pim_AaSnapshots_Rows DEFAULT 0,
    MarksKey      NVARCHAR(100) NULL,
    MarksUtc      DATETIME2     NULL
);
IF OBJECT_ID('pim.ActiveAssignmentRows') IS NULL
CREATE TABLE pim.ActiveAssignmentRows (
    SnapshotId    BIGINT         NOT NULL,
    Seq           INT            NOT NULL,
    RowId         NVARCHAR(900)  NULL,
    Kind          NVARCHAR(40)   NOT NULL,
    Principal     NVARCHAR(400)  NULL,
    PrincipalId   NVARCHAR(100)  NULL,
    PrincipalKind NVARCHAR(40)   NULL,
    PrincipalUpn  NVARCHAR(400)  NULL,
    Role          NVARCHAR(400)  NULL,
    Scope         NVARCHAR(400)  NULL,
    GroupId       NVARCHAR(100)  NULL,
    StartUtc      DATETIME2      NULL,
    EndUtc        DATETIME2      NULL,
    Justification NVARCHAR(400)  NULL,
    IdentityKey   NVARCHAR(450)  NULL,
    Managed       BIT            NOT NULL CONSTRAINT DF_pim_AaRows_Managed DEFAULT 0,
    OwnKind       NVARCHAR(20)   NOT NULL CONSTRAINT DF_pim_AaRows_OwnKind DEFAULT N'',
    SearchText    NVARCHAR(4000) NULL,
    RowJson       NVARCHAR(MAX)  NOT NULL,
    CONSTRAINT PK_pim_ActiveAssignmentRows PRIMARY KEY CLUSTERED (SnapshotId, Seq)
);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AaRows_Kind' AND object_id = OBJECT_ID('pim.ActiveAssignmentRows'))
CREATE INDEX IX_pim_AaRows_Kind ON pim.ActiveAssignmentRows (SnapshotId, Kind, PrincipalKind, Managed, OwnKind) INCLUDE (PrincipalId);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AaRows_Principal' AND object_id = OBJECT_ID('pim.ActiveAssignmentRows'))
CREATE INDEX IX_pim_AaRows_Principal ON pim.ActiveAssignmentRows (SnapshotId, Principal, Seq) INCLUDE (Kind, PrincipalKind, Managed, OwnKind);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AaRows_Role' AND object_id = OBJECT_ID('pim.ActiveAssignmentRows'))
CREATE INDEX IX_pim_AaRows_Role ON pim.ActiveAssignmentRows (SnapshotId, Role, Seq) INCLUDE (Kind, PrincipalKind, Managed, OwnKind);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AaRows_Scope' AND object_id = OBJECT_ID('pim.ActiveAssignmentRows'))
CREATE INDEX IX_pim_AaRows_Scope ON pim.ActiveAssignmentRows (SnapshotId, Scope, Seq) INCLUDE (Kind, PrincipalKind, Managed, OwnKind);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AaRows_EndUtc' AND object_id = OBJECT_ID('pim.ActiveAssignmentRows'))
CREATE INDEX IX_pim_AaRows_EndUtc ON pim.ActiveAssignmentRows (SnapshotId, EndUtc, Seq) INCLUDE (Kind, PrincipalKind, Managed, OwnKind);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AaRows_PrincipalId' AND object_id = OBJECT_ID('pim.ActiveAssignmentRows'))
CREATE INDEX IX_pim_AaRows_PrincipalId ON pim.ActiveAssignmentRows (SnapshotId, PrincipalId);
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_pim_AaRows_GroupId' AND object_id = OBJECT_ID('pim.ActiveAssignmentRows'))
CREATE INDEX IX_pim_AaRows_GroupId ON pim.ActiveAssignmentRows (SnapshotId, GroupId);
'@
}

function Initialize-PimSqlActiveAssignmentRows {
    # Create the tables + indexes when they are not there. NEVER throws: returns @{ ok; error }. ok=$false = this store
    # keeps the one-document snapshot (the identity may lack CREATE TABLE); the writer and the readers both handle that.
    param([Parameter(Mandatory)][string]$ConnectionString)
    try {
        [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql (Get-PimActiveAssignmentRowsDdl) -CommandTimeoutSec (Get-PimActiveAssignmentRowsCommandTimeoutSec))
        return [pscustomobject]@{ ok = $true; error = '' }
    } catch {
        return [pscustomobject]@{ ok = $false; error = "$($_.Exception.Message)" }
    }
}

function Confirm-PimSqlActiveAssignmentRowsReady {
    # Framework §12.23 run 2 prerequisite (PIM 100.156): the RUNTIME half (the snapshot job). Read-only check that the two
    # tables are there; the create (Initialize-PimSqlActiveAssignmentRows) is only a one-time fallback -- the schema step
    # creates them. Same answer shape as Initialize-PimSqlActiveAssignmentRows: @{ ok; error }. NEVER throws.
    param([Parameter(Mandatory)][string]$ConnectionString)
    $r = Confirm-PimSqlSchemaObject -ConnectionString $ConnectionString -Objects @('pim.ActiveAssignmentSnapshots', 'pim.ActiveAssignmentRows') `
            -Fallback { $i = Initialize-PimSqlActiveAssignmentRows -ConnectionString $ConnectionString; if (-not $i.ok) { throw "$($i.error)" } }
    return [pscustomobject]@{ ok = [bool]$r.ok; error = "$($r.message)" }
}

function Test-PimSqlTransientError {
    <#
      PURE. Is this failure worth one more try of the SAME statement? A command / connection timeout, a deadlock victim,
      a dropped connection, Azure SQL "busy / reconfiguring / resource limit". Walks the inner exceptions. Anything else
      (a constraint, a missing object, a permission) is not transient: it fails at once.
    #>
    param([AllowNull()][object]$Exception)
    $numbers = @(-2, 53, 64, 121, 233, 1205, 4060, 10053, 10054, 10060, 10928, 10929, 40143, 40197, 40501, 40540, 40613, 49918, 49919, 49920)
    $e = $Exception
    if ($e -is [System.Management.Automation.ErrorRecord]) { $e = $e.Exception }
    $depth = 0
    while ($null -ne $e -and $depth -lt 8) {
        if ($e -is [System.TimeoutException]) { return $true }
        $n = $null
        try { if ($e.PSObject.Properties['Number']) { $n = $e.Number } } catch { $n = $null }
        if ($null -ne $n -and ($numbers -contains [int]$n)) { return $true }
        if ("$($e.Message)" -match '(?i)timeout expired|timed out|transport-level error|deadlocked|connection was (forcibly )?closed|not currently available|service is busy') { return $true }
        $e = $e.InnerException; $depth++
    }
    return $false
}

function New-PimSqlActiveAssignmentRowTable {
    <#
      The batch buffer: a DataTable with the table's WRITTEN columns. Managed is written too (2.4.645: the MANAGED mark as
      the write already knows it, Get-PimSqlManagedLiveIdentitySet -- $false when not set); OwnKind keeps its default.
    #>
    $t = New-Object System.Data.DataTable 'ActiveAssignmentRows'
    [void]$t.Columns.Add('SnapshotId', [long])
    [void]$t.Columns.Add('Seq', [int])
    foreach ($c in 'RowId', 'Kind', 'Principal', 'PrincipalId', 'PrincipalKind', 'PrincipalUpn', 'Role', 'Scope', 'GroupId') { [void]$t.Columns.Add($c, [string]) }
    [void]$t.Columns.Add('StartUtc', [datetime])
    [void]$t.Columns.Add('EndUtc', [datetime])
    foreach ($c in 'Justification', 'IdentityKey', 'SearchText', 'RowJson') { [void]$t.Columns.Add($c, [string]) }
    $m = $t.Columns.Add('Managed', [bool]); $m.AllowDBNull = $false; $m.DefaultValue = $false
    return ,$t
}

function Get-PimSqlManagedLiveIdentitySet {
    <#
      2.4.645 (E3 regression, measured on the test VM): the engine's 'managed-live' identities as a case-sensitive set of
      the SAME normalised values Sync-PimSqlActiveAssignmentMarks compares with (LOWER(LEFT(value, 450)), the scalar
      fallback included -- normalised IN SQL, so both sides agree). The snapshot write marks MANAGED with it as it inserts
      the rows, so the set-based marks pass after it (job or Manager page) rewrites only the rows it disagrees with --
      normally none -- instead of ~9,500 rows x 6 index structures (19.5 MB of log at 40,000 rows, 1 s to 75 s on the
      test VM depending on its disk). Correctness stays with that SQL pass; this is an optimisation only.
      Returns the set, or $null when there is no list (or it is not JSON). Throws on a failed read (the caller ignores it).
    #>
    param([Parameter(Mandatory)][string]$ConnectionString)
    $sql = @'
SET NOCOUNT ON;
IF NOT EXISTS (SELECT 1 FROM pim.TenantCache WHERE Kind = N'managed-live' AND ISJSON(ValueJson) = 1) BEGIN SELECT CAST(0 AS INT) AS Has; RETURN; END
SELECT CAST(1 AS INT) AS Has;
DECLARE @m TABLE (v NVARCHAR(450) NOT NULL PRIMARY KEY);
INSERT @m (v)
SELECT DISTINCT LOWER(LEFT(CAST(j.[value] AS NVARCHAR(MAX)), 450))
FROM pim.TenantCache t CROSS APPLY OPENJSON(t.ValueJson, '$.identities') j
WHERE t.Kind = N'managed-live' AND ISJSON(t.ValueJson) = 1 AND j.[value] IS NOT NULL AND j.[value] <> N'';
IF NOT EXISTS (SELECT 1 FROM @m)
    INSERT @m (v)
    SELECT LOWER(LEFT(JSON_VALUE(t.ValueJson, '$.identities'), 450)) FROM pim.TenantCache t
    WHERE t.Kind = N'managed-live' AND ISJSON(t.ValueJson) = 1 AND JSON_VALUE(t.ValueJson, '$.identities') IS NOT NULL AND JSON_VALUE(t.ValueJson, '$.identities') <> N'';
SELECT v FROM @m;
'@
    $set = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::Ordinal)
    $has = $false
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandText = $sql; $cmd.CommandTimeout = Get-PimActiveAssignmentRowsCommandTimeoutSec
        $rd = $cmd.ExecuteReader()
        try {
            if ($rd.Read()) { $has = ([int]$rd.GetValue(0) -eq 1) }
            if ($has -and $rd.NextResult()) { while ($rd.Read()) { if (-not $rd.IsDBNull(0)) { [void]$set.Add([string]$rd.GetValue(0)) } } }
        } finally { $rd.Close() }
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
    if (-not $has) { return $null }
    return ,$set
}

function Write-PimSqlActiveAssignmentRowBatch {
    <#
      ONE batch of rows into pim.ActiveAssignmentRows: one bulk insert in ONE transaction of its own, with the snapshot
      write's command timeout. -Attempt > 1 = a retry: whatever an earlier try may have left of exactly this batch
      (SnapshotId + its Seq range) is removed first, so a retry can never double a row. Throws on failure.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId, [Parameter(Mandatory)][System.Data.DataTable]$Table, [int]$Attempt = 1)
    if ($Table.Rows.Count -eq 0) { return 0 }
    $timeout = Get-PimActiveAssignmentRowsCommandTimeoutSec
    $first = [int]$Table.Rows[0]['Seq']; $last = [int]$Table.Rows[$Table.Rows.Count - 1]['Seq']
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open()
        if ($Attempt -gt 1) {
            $cmd = $c.CreateCommand(); $cmd.CommandTimeout = $timeout
            $cmd.CommandText = 'DELETE FROM pim.ActiveAssignmentRows WHERE SnapshotId = @s AND Seq BETWEEN @a AND @b'
            [void]$cmd.Parameters.AddWithValue('@s', $SnapshotId); [void]$cmd.Parameters.AddWithValue('@a', $first); [void]$cmd.Parameters.AddWithValue('@b', $last)
            [void]$cmd.ExecuteNonQuery()
        }
        $ct = $c.GetType(); $asm = $ct.Assembly; $ns = $ct.Namespace
        $bcType  = $asm.GetType("$ns.SqlBulkCopy", $true)
        $optType = $asm.GetType("$ns.SqlBulkCopyOptions", $true)
        $txType  = $asm.GetType("$ns.SqlTransaction", $true)
        $opt = [Enum]::Parse($optType, 'UseInternalTransaction')
        $bc = $bcType.GetConstructor([type[]]@($ct, $optType, $txType)).Invoke(@($c, $opt, $null))
        try {
            $bc.DestinationTableName = 'pim.ActiveAssignmentRows'
            $bc.BulkCopyTimeout = $timeout
            $bc.BatchSize = $Table.Rows.Count          # the whole batch = one internal transaction
            foreach ($col in $Table.Columns) { [void]$bc.ColumnMappings.Add($col.ColumnName, $col.ColumnName) }
            $bc.WriteToServer($Table)
        } finally { try { $bc.Close() } catch { } }
        return $Table.Rows.Count
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
}

function Invoke-PimSqlActiveAssignmentBatchWrite {
    <#
      One batch with the retry: up to Get-PimActiveAssignmentRowsWriteAttempts tries, a growing wait between them, and only
      for a TRANSIENT failure (Test-PimSqlTransientError). Returns @{ rows; attempts }. Throws the last error.
      -Writer / -Sleep are the test seams (default: Write-PimSqlActiveAssignmentRowBatch / Start-Sleep).
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId, [Parameter(Mandatory)][System.Data.DataTable]$Table,
          [scriptblock]$Writer = $null, [scriptblock]$Sleep = $null)
    if (-not $Writer) { $Writer = { param($cs, $sid, $tbl, $attempt) Write-PimSqlActiveAssignmentRowBatch -ConnectionString $cs -SnapshotId $sid -Table $tbl -Attempt $attempt } }
    if (-not $Sleep) { $Sleep = { param($ms) Start-Sleep -Milliseconds $ms } }
    $max = Get-PimActiveAssignmentRowsWriteAttempts
    $delay = Get-PimActiveAssignmentRowsRetryDelayMs
    for ($attempt = 1; $attempt -le $max; $attempt++) {
        try {
            $n = & $Writer $ConnectionString $SnapshotId $Table $attempt
            return [pscustomobject]@{ rows = [int]$Table.Rows.Count; attempts = $attempt; written = $n }
        } catch {
            $transient = Test-PimSqlTransientError -Exception $_.Exception
            if (-not $transient -or $attempt -ge $max) { throw }
            Write-Warning ("  [active-assignments] a batch write did not complete (try {0} of {1}): {2} -- trying again" -f $attempt, $max, $_.Exception.Message)
            & $Sleep $delay
            $delay = $delay * 2
        }
    }
}

function Get-PimSqlActiveAssignmentsForm {
    <#
      Which form the stored snapshot has, read CHEAPLY (the first characters of the row, never the document):
      'none' (no row) | 'table' (the header of a table-form snapshot) | 'document' (the one-document form of 2.4.611 and
      before). Throws on a failed read.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString)
    $rows = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT LEFT(ValueJson, 40) AS Head FROM pim.TenantCache WHERE Kind = @k" -Parameters @{ k = 'active-assignments' })
    if ($rows.Count -eq 0) { return 'none' }
    $head = "$($rows[0].Head)"
    if (-not $head.Trim()) { return 'none' }
    if ($head -match '^\s*\{\s*"rowStore"\s*:\s*"table"') { return 'table' }
    return 'document'
}

function Test-PimActiveAssignmentsTableEntry {
    <# PURE. Is this parsed pim.TenantCache 'active-assignments' entry the header of a table-form snapshot? #>
    param([AllowNull()][object]$Entry)
    if ($null -eq $Entry) { return $false }
    $v = $null
    if ($Entry -is [System.Collections.IDictionary]) { if ($Entry.Contains('rowStore')) { $v = $Entry['rowStore'] } }
    elseif ($Entry.PSObject.Properties['rowStore']) { $v = $Entry.rowStore }
    return ("$v" -eq (Get-PimActiveAssignmentsTableFormName))
}

function Get-PimSqlActiveAssignmentsCurrentSnapshotId {
    # The generation the stored header points at; 0 when there is none / it is the one-document form. Throws on a failed read.
    param([Parameter(Mandatory)][string]$ConnectionString)
    # The writer puts rowStore and snapshotId FIRST in the header, so the first characters answer this (no JSON function,
    # no document).
    $v = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql 'SELECT LEFT(ValueJson, 120) FROM pim.TenantCache WHERE Kind = @k' -Parameters @{ k = 'active-assignments' }
    if ($null -eq $v -or $v -is [System.DBNull] -or -not "$v".Trim()) { return [long]0 }
    $m = [regex]::Match("$v", '^\s*\{\s*"rowStore"\s*:\s*"table"\s*,\s*"snapshotId"\s*:\s*(\d{1,18})')
    if (-not $m.Success) { return [long]0 }
    return [long]$m.Groups[1].Value
}

function Start-PimSqlActiveAssignmentSnapshot {
    <#
      Open a NEW generation for the snapshot write and return its id (greater than every id in the store). Removes what
      no reader can need any more: every generation that is neither the one the header points at nor this new one -- the
      leftovers of a failed write and generations before the current one -- in bounded deletes. The CURRENT generation is
      never touched here: it stays complete and readable until the header is switched (Complete-...), and after the switch
      it stays as the previous generation until the NEXT write starts, so a reader that read the header just before the
      switch still finds its rows.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [int]$ExpectedRows = 0, [datetime]$NowUtc = [datetime]::UtcNow)
    $timeout = Get-PimActiveAssignmentRowsCommandTimeoutSec
    $current = Get-PimSqlActiveAssignmentsCurrentSnapshotId -ConnectionString $ConnectionString
    $max = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql 'SELECT ISNULL(MAX(SnapshotId), 0) FROM pim.ActiveAssignmentSnapshots'
    $maxId = [long]0; if ($null -ne $max -and $max -isnot [System.DBNull]) { $maxId = [long]$max }
    $epoch = [datetime]::SpecifyKind([datetime]'1970-01-01T00:00:00', [DateTimeKind]::Utc)
    $id = [long][math]::Floor(($NowUtc.ToUniversalTime() - $epoch).TotalMilliseconds)
    if ($id -le $maxId) { $id = $maxId + 1 }
    if ($id -le $current) { $id = $current + 1 }
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql "INSERT INTO pim.ActiveAssignmentSnapshots (SnapshotId, State, RowsExpected) VALUES (@s, N'writing', @n)" -Parameters @{ s = $id; n = $ExpectedRows } -CommandTimeoutSec $timeout)
    $removed = 0
    for ($i = 0; $i -lt 100000; $i++) {
        $n = Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql 'DELETE TOP (5000) FROM pim.ActiveAssignmentRows WHERE SnapshotId <> @keep AND SnapshotId <> @new' -Parameters @{ keep = $current; new = $id } -CommandTimeoutSec $timeout
        if ([int]$n -le 0) { break }
        $removed += [int]$n
    }
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql 'DELETE FROM pim.ActiveAssignmentSnapshots WHERE SnapshotId <> @keep AND SnapshotId <> @new' -Parameters @{ keep = $current; new = $id } -CommandTimeoutSec $timeout)
    return [pscustomobject]@{ snapshotId = $id; previousSnapshotId = $current; removedRows = $removed }
}

function Complete-PimSqlActiveAssignmentSnapshot {
    <#
      THE SWITCH. One transaction: the generation's row count is checked against what was written, the generation is
      marked complete and the pim.TenantCache header is replaced by -HeaderJson (which names this generation). A count
      that does not match rolls everything back and throws -- the header keeps pointing at the previous generation.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId, [Parameter(Mandatory)][int]$ExpectedRows,
          [Parameter(Mandatory)][string]$HeaderJson, [datetime]$RefreshedUtc = [datetime]::UtcNow)
    $sql = @'
SET XACT_ABORT ON;
BEGIN TRAN;
DECLARE @have BIGINT = (SELECT COUNT_BIG(*) FROM pim.ActiveAssignmentRows WHERE SnapshotId = @s);
IF @have <> @n
BEGIN
    ROLLBACK;
    DECLARE @msg NVARCHAR(300) = CONCAT(N'active-assignment rows incomplete: ', @have, N' of ', @n, N' stored for generation ', @s, N' -- the previous snapshot stays in place');
    THROW 51114, @msg, 1;
END
UPDATE pim.ActiveAssignmentSnapshots SET State = N'complete', CompletedUtc = SYSUTCDATETIME(), RowsExpected = @n WHERE SnapshotId = @s;
MERGE pim.TenantCache AS t USING (SELECT @k AS Kind) AS src ON t.Kind = src.Kind
WHEN MATCHED THEN UPDATE SET ValueJson = @v, RefreshedUtc = @r, UpdatedUtc = SYSUTCDATETIME()
WHEN NOT MATCHED THEN INSERT (Kind, ValueJson, RefreshedUtc, UpdatedUtc) VALUES (@k, @v, @r, SYSUTCDATETIME());
COMMIT;
'@
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql $sql -Parameters @{ s = $SnapshotId; n = $ExpectedRows; k = 'active-assignments'; v = $HeaderJson; r = $RefreshedUtc.ToUniversalTime() } -CommandTimeoutSec (Get-PimActiveAssignmentRowsCommandTimeoutSec))
}

function Get-PimSqlActiveAssignmentRowsJson {
    <#
      Every stored row of one generation as ONE JSON array string ('[{...},{...}]'), in snapshot order -- for the readers
      that still need the whole set (the coverage report, the Home tile, a delegated caller's filtered answer). The stored
      row JSON is passed through, never parsed here. -Kind = only that assignment type. -ExpectedRows (when no -Kind): a
      generation that holds another number of rows throws -- a part of a snapshot is never returned as the snapshot.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId, [string]$Kind = '', [int]$ExpectedRows = -1)
    $sb = New-Object System.Text.StringBuilder 65536
    [void]$sb.Append('[')
    $n = 0
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandTimeout = Get-PimActiveAssignmentsQueryTimeoutSec
        if ("$Kind".Trim()) {
            $cmd.CommandText = 'SELECT RowJson FROM pim.ActiveAssignmentRows WHERE SnapshotId = @s AND Kind = @k ORDER BY Seq'
            [void]$cmd.Parameters.AddWithValue('@k', "$Kind".Trim())
        } else { $cmd.CommandText = 'SELECT RowJson FROM pim.ActiveAssignmentRows WHERE SnapshotId = @s ORDER BY Seq' }
        [void]$cmd.Parameters.AddWithValue('@s', $SnapshotId)
        $rd = $cmd.ExecuteReader()
        try {
            while ($rd.Read()) {
                if ($n -gt 0) { [void]$sb.Append(',') }
                [void]$sb.Append($rd.GetString(0))
                $n++
            }
        } finally { $rd.Close() }
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
    if ($ExpectedRows -ge 0 -and -not "$Kind".Trim() -and $n -ne $ExpectedRows) {
        throw "the stored active-assignment rows are incomplete ($n of $ExpectedRows for generation $SnapshotId)"
    }
    [void]$sb.Append(']')
    return $sb.ToString()
}

function Expand-PimSqlActiveAssignmentsEntry {
    <#
      A table-form header (parsed) -> the SAME shape the one-document form had: the header's fields plus 'rows' (every
      row, parsed). For the readers that work on the whole set. Throws when the rows cannot be read or are incomplete.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][object]$Entry)
    $sid = [long]0; [void][long]::TryParse("$($Entry.snapshotId)", [ref]$sid)
    $exp = -1; if ("$($Entry.rowCount)".Trim() -match '^\d+$') { $exp = [int]"$($Entry.rowCount)" }
    $json = Get-PimSqlActiveAssignmentRowsJson -ConnectionString $ConnectionString -SnapshotId $sid -ExpectedRows $exp
    $rows = @()
    if ($json.Length -gt 2) {
        # Windows PowerShell 5.1 hands a JSON array back as ONE object, pwsh 7 enumerates it: foreach covers both.
        $parsed = $json | ConvertFrom-Json
        $rows = @(foreach ($x in $parsed) { $x })
        $parsed = $null
    }
    $json = $null
    $out = [ordered]@{}
    foreach ($p in @($Entry.PSObject.Properties)) { $out[$p.Name] = $p.Value }
    $out['rows'] = $rows
    return [pscustomobject]$out
}

function Get-PimSqlActiveAssignmentServicePrincipalIds {
    # The distinct principal ids of kind servicePrincipal in one generation (index-only). For the "own identities" marks.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId)
    $rows = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT DISTINCT PrincipalId FROM pim.ActiveAssignmentRows WHERE SnapshotId = @s AND PrincipalKind = N'servicePrincipal' AND PrincipalId IS NOT NULL AND PrincipalId <> N''" -Parameters @{ s = $SnapshotId })
    return @($rows | ForEach-Object { "$($_.PrincipalId)" } | Where-Object { $_ })
}

# SNAP-INC (owner 2026-10-20): the snapshot's PIM-for-Groups read is INCREMENTAL -- groups whose membership did not change
# carry their rows forward from the previous complete generation. These two read that generation back (the decision is in
# engine/_shared/PIM-ActiveAssignments.ps1, Get-PimSnapshotGroupReadPlan). Both throw on a failed read: the caller then reads
# every group in full, never a partial snapshot presented as complete.
function Get-PimActiveAssignmentsCarryReadTimeoutSec { return 600 }   # per statement; a 500k-row generation is read back in one pass

function Get-PimSqlActiveAssignmentGroupSummary {
    <#
      SNAP-INC. One line per group of one generation's PIM-for-Groups rows: { groupId; rows; alwaysRead }. alwaysRead = the group
      holds a row that a MEMBERSHIP change cannot announce -- a row with an end date, a start still in the future, or an
      owner (or unidentifiable) row: IdentityKey is 'g|<principal>|<group>|member' only for a plain member row. Index columns
      only (no RowJson). Returns { groups; total; noGroup } (noGroup = rows without a group id: they cannot be carried).
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId, [datetime]$NowUtc = [datetime]::UtcNow)
    $sql = @'
SELECT GroupId, COUNT_BIG(*) AS N,
       MAX(CASE WHEN EndUtc IS NOT NULL OR (StartUtc IS NOT NULL AND StartUtc > @now) OR IdentityKey IS NULL OR IdentityKey NOT LIKE N'%|member' THEN 1 ELSE 0 END) AS AlwaysRead
FROM pim.ActiveAssignmentRows WHERE SnapshotId = @s AND Kind = N'pim-for-groups'
GROUP BY GroupId
'@
    $groups = New-Object System.Collections.Generic.List[object]
    $total = [long]0; $noGroup = [long]0
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandText = $sql; $cmd.CommandTimeout = Get-PimActiveAssignmentsCarryReadTimeoutSec
        [void]$cmd.Parameters.AddWithValue('@s', $SnapshotId); [void]$cmd.Parameters.AddWithValue('@now', $NowUtc.ToUniversalTime())
        $rd = $cmd.ExecuteReader()
        try {
            while ($rd.Read()) {
                $n = [long]$rd.GetValue(1); $total += $n
                if ($rd.IsDBNull(0) -or -not "$($rd.GetValue(0))".Trim()) { $noGroup += $n; continue }
                $groups.Add([pscustomobject]@{ groupId = "$($rd.GetValue(0))".Trim().ToLowerInvariant(); rows = $n; alwaysRead = ([int]$rd.GetValue(2) -eq 1) })
            }
        } finally { $rd.Close() }
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
    return [pscustomobject]@{ groups = $groups.ToArray(); total = $total; noGroup = $noGroup }
}

function Read-PimSqlActiveAssignmentGroupRows {
    <#
      SNAP-INC. The stored RowJson of one generation's PIM-for-Groups rows whose GroupId is in -GroupIds (lower-case ids),
      handed to -OnChunk in chunks of up to 500 strings (the caller parses each chunk and drops the text: a 500k-row
      generation is never held as text). Returns the number of rows handed over. Throws on a failed read.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId,
          [Parameter(Mandatory)][System.Collections.Generic.HashSet[string]]$GroupIds, [Parameter(Mandatory)][scriptblock]$OnChunk)
    $n = 0
    $chunk = New-Object System.Collections.Generic.List[string]
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandTimeout = Get-PimActiveAssignmentsCarryReadTimeoutSec
        $cmd.CommandText = "SELECT GroupId, RowJson FROM pim.ActiveAssignmentRows WHERE SnapshotId = @s AND Kind = N'pim-for-groups' ORDER BY Seq"
        [void]$cmd.Parameters.AddWithValue('@s', $SnapshotId)
        $rd = $cmd.ExecuteReader()
        try {
            while ($rd.Read()) {
                if ($rd.IsDBNull(0)) { continue }
                if (-not $GroupIds.Contains("$($rd.GetValue(0))".Trim().ToLowerInvariant())) { continue }
                $chunk.Add($rd.GetString(1)); $n++
                if ($chunk.Count -ge 500) { & $OnChunk $chunk.ToArray(); $chunk.Clear() }
            }
        } finally { $rd.Close() }
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
    if ($chunk.Count -gt 0) { & $OnChunk $chunk.ToArray(); $chunk.Clear() }
    return $n
}

function ConvertTo-PimSqlJsonStringArray {
    <# PURE. A string list -> a compact JSON array of strings ('[]' for none); trimmed, empty values dropped, lower-cased. #>
    param([AllowNull()][string[]]$Values)
    $sb = New-Object System.Text.StringBuilder
    [void]$sb.Append('[')
    $first = $true
    foreach ($v in @($Values)) {
        $s = "$v".Trim().ToLowerInvariant()
        if (-not $s) { continue }
        if (-not $first) { [void]$sb.Append(',') }
        $first = $false
        [void]$sb.Append('"')
        foreach ($ch in $s.ToCharArray()) {
            if ($ch -eq '"') { [void]$sb.Append('\"') }
            elseif ($ch -eq '\') { [void]$sb.Append('\\') }
            elseif ([int]$ch -lt 0x20) { [void]$sb.Append(('\u{0:x4}' -f [int]$ch)) }
            else { [void]$sb.Append($ch) }
        }
        [void]$sb.Append('"')
    }
    [void]$sb.Append(']')
    return $sb.ToString()
}

function Get-PimActiveAssignmentMarksKey {
    <# PURE. One key for everything the MANAGED / own-identity marks of a generation are computed from. #>
    param([string]$ManagedStamp = '', [bool]$ManagedKnown = $false, [string[]]$Product = @(), [string[]]$Support = @(), [string[]]$BreakGlass = @())
    $norm = { param($a) (@(@($a) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ } | Sort-Object -Unique) -join ',') }
    $text = @("m=$ManagedKnown", "ml=$ManagedStamp", "p=$(& $norm $Product)", "s=$(& $norm $Support)", "b=$(& $norm $BreakGlass)") -join '|'
    $sha = [System.Security.Cryptography.SHA256]::Create()
    try { $h = $sha.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($text)) } finally { $sha.Dispose() }
    return (-join ($h | ForEach-Object { $_.ToString('x2') }))
}

function Sync-PimSqlActiveAssignmentMarks {
    <#
      Bring the stored marks of one generation up to date, in SQL, set-based, ONLY when what they are computed from changed
      (-MarksKey differs from the one recorded for the generation):
        Managed  = the row's identity is in the engine's 'managed-live' list (pim.TenantCache, read inside SQL -- the list
                   never travels to this process)
        OwnKind  = breakglass | support | product | '' (that order of precedence) from the three small lists
      Returns @{ updated; changed }. Throws on failure (the caller reports it; rows are then served with the marks they have).
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId, [Parameter(Mandatory)][string]$MarksKey,
          [bool]$ManagedKnown = $false, [string[]]$Product = @(), [string[]]$Support = @(), [string[]]$BreakGlass = @())
    $sql = @'
SET NOCOUNT ON; SET XACT_ABORT ON;
IF EXISTS (SELECT 1 FROM pim.ActiveAssignmentSnapshots WHERE SnapshotId = @s AND MarksKey = @mk)
BEGIN
    SELECT 0 AS Updated, 0 AS Changed;
    RETURN;
END
DECLARE @bg TABLE (v NVARCHAR(400) NOT NULL PRIMARY KEY);
DECLARE @sup TABLE (v NVARCHAR(400) NOT NULL PRIMARY KEY);
DECLARE @prod TABLE (v NVARCHAR(400) NOT NULL PRIMARY KEY);
DECLARE @m TABLE (v NVARCHAR(450) NOT NULL PRIMARY KEY);
INSERT @bg (v) SELECT DISTINCT LOWER(LEFT(CAST(j.[value] AS NVARCHAR(MAX)), 400)) FROM OPENJSON(@bgJson) j WHERE j.[value] IS NOT NULL AND j.[value] <> N'';
INSERT @sup (v) SELECT DISTINCT LOWER(LEFT(CAST(j.[value] AS NVARCHAR(MAX)), 400)) FROM OPENJSON(@supJson) j WHERE j.[value] IS NOT NULL AND j.[value] <> N'';
INSERT @prod (v) SELECT DISTINCT LOWER(LEFT(CAST(j.[value] AS NVARCHAR(MAX)), 400)) FROM OPENJSON(@prodJson) j WHERE j.[value] IS NOT NULL AND j.[value] <> N'';
IF @useManaged = 1
BEGIN
    INSERT @m (v)
    SELECT DISTINCT LOWER(LEFT(CAST(j.[value] AS NVARCHAR(MAX)), 450))
    FROM pim.TenantCache t CROSS APPLY OPENJSON(t.ValueJson, '$.identities') j
    WHERE t.Kind = N'managed-live' AND ISJSON(t.ValueJson) = 1 AND j.[value] IS NOT NULL AND j.[value] <> N'';
    IF NOT EXISTS (SELECT 1 FROM @m)
        INSERT @m (v)
        SELECT LOWER(LEFT(JSON_VALUE(t.ValueJson, '$.identities'), 450)) FROM pim.TenantCache t
        WHERE t.Kind = N'managed-live' AND ISJSON(t.ValueJson) = 1 AND JSON_VALUE(t.ValueJson, '$.identities') IS NOT NULL AND JSON_VALUE(t.ValueJson, '$.identities') <> N'';
END
BEGIN TRAN;
UPDATE a SET Managed = n.Managed, OwnKind = n.OwnKind
FROM pim.ActiveAssignmentRows a
CROSS APPLY (SELECT
    CAST(CASE WHEN a.IdentityKey IS NOT NULL AND a.IdentityKey <> N'' AND EXISTS (SELECT 1 FROM @m m WHERE m.v = LOWER(a.IdentityKey)) THEN 1 ELSE 0 END AS BIT) AS Managed,
    CASE WHEN EXISTS (SELECT 1 FROM @bg b WHERE b.v IN (LOWER(a.PrincipalId), LOWER(LTRIM(RTRIM(a.Principal))), LOWER(LTRIM(RTRIM(a.PrincipalUpn))))) THEN N'breakglass'
         WHEN EXISTS (SELECT 1 FROM @sup s WHERE s.v = LOWER(a.PrincipalId)) THEN N'support'
         WHEN EXISTS (SELECT 1 FROM @prod p WHERE p.v = LOWER(a.PrincipalId)) THEN N'product'
         ELSE N'' END AS OwnKind) n
WHERE a.SnapshotId = @s AND (a.Managed <> n.Managed OR a.OwnKind <> n.OwnKind);
DECLARE @chg INT = @@ROWCOUNT;
UPDATE pim.ActiveAssignmentSnapshots SET MarksKey = @mk, MarksUtc = SYSUTCDATETIME() WHERE SnapshotId = @s;
COMMIT;
SELECT 1 AS Updated, @chg AS Changed;
'@
    $p = @{ s = $SnapshotId; mk = $MarksKey; useManaged = [bool]$ManagedKnown
            bgJson   = (ConvertTo-PimSqlJsonStringArray -Values @($BreakGlass | Where-Object { "$_" -notmatch '^\s*<' }))
            supJson  = (ConvertTo-PimSqlJsonStringArray -Values $Support)
            prodJson = (ConvertTo-PimSqlJsonStringArray -Values $Product) }
    $sets = Invoke-PimSqlQuerySets -ConnectionString $ConnectionString -Sql $sql -Parameters $p -CommandTimeoutSec (Get-PimActiveAssignmentRowsCommandTimeoutSec)
    $row = $null
    for ($i = 0; $i -lt $sets.Count; $i++) { foreach ($r in $sets[$i]) { if ($null -ne $r -and $r.PSObject.Properties['Updated']) { $row = $r } } }
    if ($null -eq $row) { return [pscustomobject]@{ updated = $false; changed = 0 } }
    return [pscustomobject]@{ updated = ([int]$row.Updated -eq 1); changed = [int]$row.Changed }
}

function Invoke-PimSqlQuerySets {
    <# Like Invoke-PimSqlQuery, for a batch that answers SEVERAL result sets: returns a list, one object[] per set. #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Sql, [hashtable]$Parameters = @{}, [int]$CommandTimeoutSec = 0)
    Assert-PimSqlDemoScope -Sql $Sql
    $sets = New-Object System.Collections.Generic.List[object]
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    try {
        $c.Open(); $cmd = $c.CreateCommand(); $cmd.CommandText = $Sql
        if ($CommandTimeoutSec -gt 0) { $cmd.CommandTimeout = $CommandTimeoutSec }
        foreach ($k in $Parameters.Keys) { [void]$cmd.Parameters.AddWithValue("@$k", $(if ($null -eq $Parameters[$k]) { [DBNull]::Value } else { $Parameters[$k] })) }
        $rd = $cmd.ExecuteReader()
        try {
            do {
                $rows = New-Object System.Collections.Generic.List[object]
                while ($rd.Read()) { $o = [ordered]@{}; for ($i = 0; $i -lt $rd.FieldCount; $i++) { $o[$rd.GetName($i)] = $(if ($rd.IsDBNull($i)) { $null } else { $rd.GetValue($i) }) }; $rows.Add([pscustomobject]$o) }
                $sets.Add($rows.ToArray())
            } while ($rd.NextResult())
        } finally { $rd.Close() }
    } finally { if ($c) { $c.Close(); $c.Dispose() } }
    # an ARRAY of the sets (index it; Windows PowerShell 5.1 cannot wrap a generic list in @() -- "Argument types do not match")
    return ,($sets.ToArray())
}

function Get-PimActiveAssignmentsSortColumn {
    <#
      PURE. The page's sort key -> the column it sorts on. A CLOSED list: the ORDER BY text is built from these literals
      only, never from what the request sent. An unknown key = the default (principal).
    #>
    param([string]$Key = '')
    switch ("$Key".Trim().ToLowerInvariant()) {
        'principal'     { return 'a.Principal' }
        'role'          { return 'a.Role' }
        'scope'         { return 'a.Scope' }
        'type'          { return 'a.Kind' }
        'start'         { return 'a.StartUtc' }
        'end'           { return 'a.EndUtc' }
        'justification' { return 'a.Justification' }
    }
    return 'a.Principal'
}

function ConvertTo-PimSqlLikeContains {
    <# PURE. A search text -> the LIKE pattern for "contains" with ESCAPE '\' (the text's own % _ [ \ are literals). #>
    param([AllowNull()][string]$Text)
    $t = "$Text"
    $t = $t.Replace('\', '\\').Replace('%', '\%').Replace('_', '\_').Replace('[', '\[')
    return '%' + $t + '%'
}

function Get-PimActiveAssignmentsConditionColumn {
    <#
      PURE. PIM 100.120. A list-menu condition's column name -> the SQL expression it compares. A CLOSED list: the text
      of a condition is built from these literals only, never from what the request sent. Unknown = '' (the caller
      refuses). -Exact: "is" / "starts with" / "any of" compare the name itself; "contains" on principal also reads the
      sign-in name, as the page shows both.
    #>
    param([string]$Key = '', [switch]$Exact)
    switch -CaseSensitive ("$Key") {
        'principal'     { if ($Exact) { return "ISNULL(a.Principal, N'')" } else { return "CONCAT(ISNULL(a.Principal, N''), N' ', ISNULL(a.PrincipalUpn, N''))" } }
        'role'          { return "ISNULL(a.Role, N'')" }
        'scope'         { return "ISNULL(a.Scope, N'')" }
        'type'          { return "ISNULL(a.Kind, N'')" }
        'justification' { return "ISNULL(a.Justification, N'')" }
        '*'             { return "ISNULL(a.SearchText, N'')" }
    }
    return ''
}

function Get-PimActiveAssignmentsConditionSql {
    <#
      PURE. PIM 100.120. The list menu's conditions (already checked: ConvertTo-PimListQuery) -> the text added to the
      WHERE of the paged query, and its parameters: @{ sql; parameters; count }. Every VALUE is a parameter (@lmc0,
      @lmc1, ... -- the names come from a counter here, @lmq for the search); the only text that varies is a column
      expression from the closed list above and one of five fixed comparisons. No condition and no search = '' and no
      parameter, so the statement is what it was. A column or an operator outside the lists THROWS (fail closed).
    #>
    param([AllowNull()][object[]]$Conditions, [AllowNull()][string]$Search = '')
    $sb = New-Object System.Text.StringBuilder
    $p = @{}
    $n = 0
    foreach ($c in @($Conditions)) {
        if ($null -eq $c) { continue }
        if ($n -ge 10) { throw 'more than 10 list conditions' }
        $op = "$($c.op)"
        $exact = (@('equals', 'startsWith', 'anyOf') -ccontains $op)
        $col = Get-PimActiveAssignmentsConditionColumn -Key "$($c.col)" -Exact:$exact
        if (-not $col) { throw 'a list condition names a column that is not in the list of known columns' }
        $name = 'lmc' + $n
        $text = "$($c.value)".Trim().ToLowerInvariant()
        if ($text.Length -gt 200) { $text = $text.Substring(0, 200) }
        if ($op -ceq 'contains') {
            [void]$sb.Append("`n  AND LOWER($col) LIKE @$name ESCAPE N'\'")
            $p[$name] = (ConvertTo-PimSqlLikeContains -Text $text)
        } elseif ($op -ceq 'notContains') {
            [void]$sb.Append("`n  AND LOWER($col) NOT LIKE @$name ESCAPE N'\'")
            $p[$name] = (ConvertTo-PimSqlLikeContains -Text $text)
        } elseif ($op -ceq 'startsWith') {
            [void]$sb.Append("`n  AND LOWER(LTRIM($col)) LIKE @$name ESCAPE N'\'")
            $p[$name] = (ConvertTo-PimSqlLikeContains -Text $text).Substring(1)
        } elseif ($op -ceq 'equals') {
            [void]$sb.Append("`n  AND LOWER(LTRIM(RTRIM($col))) = @$name")
            $p[$name] = $text
        } elseif ($op -ceq 'anyOf') {
            $vals = @(@($c.values) | ForEach-Object { "$_" })
            $hasEmpty = (@($vals | Where-Object { -not "$_".Trim() }).Count -gt 0)
            [void]$sb.Append("`n  AND (LOWER(LTRIM(RTRIM($col))) IN (SELECT CAST(j.[value] AS NVARCHAR(400)) FROM OPENJSON(@$name) j)")
            if ($hasEmpty) { [void]$sb.Append(" OR LTRIM(RTRIM($col)) = N''") }
            [void]$sb.Append(')')
            $p[$name] = (ConvertTo-PimSqlJsonStringArray -Values @($vals | Select-Object -First 50))
        } else { throw 'a list condition has an operator that is not one of the five known ones' }
        $n++
    }
    $s = "$Search".Trim().ToLowerInvariant()
    if ($s.Length -gt 200) { $s = $s.Substring(0, 200) }
    if ($s) {
        [void]$sb.Append("`n  AND a.SearchText LIKE @lmq ESCAPE N'\'")
        $p['lmq'] = (ConvertTo-PimSqlLikeContains -Text $s)
    }
    return @{ sql = $sb.ToString(); parameters = $p; count = $n }
}

function Get-PimActiveAssignmentsViewCounts {
    <#
      PURE. The page's counters from the grouped counts of a whole generation (-Groups: Kind, IsDeleted, Managed, OwnKind,
      N) and the five "show" ticks -- the SAME rule the page applies to a row (deleted first, then its own kind, then
      managed): total, deleted, managed, own{product,support,breakglass}, hidden, hiddenBy{...}, and the per-type counts of
      what is not hidden.
    #>
    param([AllowNull()][object[]]$Groups, [bool]$ShowDeleted = $false, [bool]$ShowManaged = $false, [bool]$ShowProduct = $false, [bool]$ShowSupport = $false, [bool]$ShowBreakGlass = $false)
    $own = [ordered]@{ product = 0; support = 0; breakglass = 0 }
    $hiddenBy = [ordered]@{ product = 0; support = 0; breakglass = 0; managed = 0; deleted = 0 }
    $visible = [ordered]@{ all = 0; 'entra-role' = 0; 'azure-rbac' = 0; 'pim-for-groups' = 0 }
    $byType = [ordered]@{ total = 0; 'entra-role' = 0; 'azure-rbac' = 0; 'pim-for-groups' = 0 }
    $total = [long]0; $deleted = [long]0; $managed = [long]0; $hidden = [long]0
    $showOwn = @{ product = $ShowProduct; support = $ShowSupport; breakglass = $ShowBreakGlass }
    foreach ($g in @($Groups)) {
        if ($null -eq $g) { continue }
        $n = [long]$g.N; $kind = "$($g.Kind)"; $ok = "$($g.OwnKind)"
        $isDel = ([int]$g.IsDeleted -eq 1); $isMan = [bool]$g.Managed
        $total += $n; $byType['total'] += $n
        if ($byType.Contains($kind)) { $byType[$kind] += $n }
        if ($isDel) { $deleted += $n }
        if ($isMan) { $managed += $n }
        if ($own.Contains($ok)) { $own[$ok] += $n }
        $why = ''
        if (-not $ShowDeleted -and $isDel) { $why = 'deleted' }
        elseif ($own.Contains($ok) -and -not $showOwn[$ok]) { $why = $ok }
        elseif (-not $ShowManaged -and $isMan) { $why = 'managed' }
        if ($why) { $hidden += $n; $hiddenBy[$why] += $n; continue }
        $visible['all'] += $n
        if ($visible.Contains($kind)) { $visible[$kind] += $n }
    }
    return [ordered]@{ total = $total; deleted = $deleted; managed = $managed; own = $own; hidden = $hidden; hiddenBy = $hiddenBy; visible = $visible; byType = $byType }
}

function Invoke-PimSqlActiveAssignmentsQuery {
    <#
      COUNTS + ONE PAGE of one generation, filter, sort and paging IN SQL. Every value of the request is a PARAMETER; the
      only text that varies is the ORDER BY column and direction, taken from a closed list in this file
      (Get-PimActiveAssignmentsSortColumn). Returns:
        @{ groups   = the grouped counts of the whole generation (for Get-PimActiveAssignmentsViewCounts)
           filtered = how many rows match the filter (all pages)
           rows     = this page: @{ seq; json (the stored row, as written); managed; ownKind }
           page; pageSize }
      -Type all | entra-role | azure-rbac | pim-for-groups | deleted. -Search = "contains", over principal id, principal,
      role, scope and justification (lower-cased both sides). -Aliases = exact names (principal / role / scope) that also
      match the search (the page's tag <-> display-name pairs). -ScopeIs = exact scope names (the group-delete check).
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][long]$SnapshotId,
        [string]$Type = 'all', [string]$Search = '', [string[]]$Aliases = @(), [string[]]$ScopeIs = @(),
        [string]$Sort = 'principal', [switch]$Descending, [int]$Page = 1, [int]$PageSize = 0,
        [bool]$ShowDeleted = $false, [bool]$ShowManaged = $false, [bool]$ShowProduct = $false, [bool]$ShowSupport = $false, [bool]$ShowBreakGlass = $false,
        # PIM 100.120: the list menu's conditions and search (checked by the caller), added to the filter of the COUNT and
        # of the page -- so "filtered" is the number of matching rows of the whole list. None = the statement as it was.
        [AllowNull()][object[]]$Conditions = @(), [AllowNull()][string]$ListSearch = ''
    )
    $max = Get-PimActiveAssignmentsPageSizeMax
    if ($PageSize -le 0) { $PageSize = Get-PimActiveAssignmentsPageSizeDefault }
    if ($PageSize -gt $max) { $PageSize = $max }
    if ($Page -lt 1) { $Page = 1 }
    $typeV = "$Type".Trim().ToLowerInvariant()
    if (@('all', 'entra-role', 'azure-rbac', 'pim-for-groups', 'deleted') -notcontains $typeV) { $typeV = 'all' }
    $q = "$Search".Trim().ToLowerInvariant()
    if ($q.Length -gt 200) { $q = $q.Substring(0, 200) }
    $aliasMax = Get-PimActiveAssignmentsAliasMax
    $al = @(@($Aliases) | Where-Object { "$_".Trim() } | Select-Object -First $aliasMax)
    $sc = @(@($ScopeIs) | Where-Object { "$_".Trim() } | Select-Object -First $aliasMax)
    $col = Get-PimActiveAssignmentsSortColumn -Key $Sort
    $dir = if ($Descending) { 'DESC' } else { 'ASC' }
    $where = @'
a.SnapshotId = @sid
  AND (@showDeleted = 1 OR a.PrincipalKind IS NULL OR a.PrincipalKind <> N'deleted')
  AND (a.OwnKind = N'' OR (a.OwnKind = N'product' AND @showProduct = 1) OR (a.OwnKind = N'support' AND @showSupport = 1) OR (a.OwnKind = N'breakglass' AND @showBreakGlass = 1))
  AND (@showManaged = 1 OR a.Managed = 0)
  AND (@type = N'all' OR (@type = N'deleted' AND a.PrincipalKind = N'deleted') OR (@type <> N'deleted' AND a.Kind = @type))
  AND (@q = N'' OR a.SearchText LIKE @qLike ESCAPE N'\' OR (@hasAl = 1 AND EXISTS (SELECT 1 FROM @al x WHERE x.v IN (LOWER(LTRIM(RTRIM(a.Scope))), LOWER(LTRIM(RTRIM(a.Role))), LOWER(LTRIM(RTRIM(a.Principal)))))))
  AND (@hasSc = 0 OR EXISTS (SELECT 1 FROM @sc y WHERE y.v = LOWER(LTRIM(RTRIM(a.Scope)))))
'@
    $lmSql = Get-PimActiveAssignmentsConditionSql -Conditions $Conditions -Search $ListSearch
    if ("$($lmSql.sql)") { $where = $where + "$($lmSql.sql)" }
    $sql = @"
SET NOCOUNT ON;
DECLARE @al TABLE (v NVARCHAR(400) NOT NULL PRIMARY KEY);
DECLARE @sc TABLE (v NVARCHAR(400) NOT NULL PRIMARY KEY);
INSERT @al (v) SELECT DISTINCT LOWER(LEFT(CAST(j.[value] AS NVARCHAR(MAX)), 400)) FROM OPENJSON(@aliasJson) j WHERE j.[value] IS NOT NULL AND j.[value] <> N'';
INSERT @sc (v) SELECT DISTINCT LOWER(LEFT(CAST(j.[value] AS NVARCHAR(MAX)), 400)) FROM OPENJSON(@scopeJson) j WHERE j.[value] IS NOT NULL AND j.[value] <> N'';
DECLARE @hasAl BIT = CASE WHEN EXISTS (SELECT 1 FROM @al) THEN 1 ELSE 0 END;
DECLARE @hasSc BIT = CASE WHEN EXISTS (SELECT 1 FROM @sc) THEN 1 ELSE 0 END;
SELECT a.Kind, CASE WHEN a.PrincipalKind = N'deleted' THEN 1 ELSE 0 END AS IsDeleted, a.Managed, a.OwnKind, COUNT_BIG(*) AS N
FROM pim.ActiveAssignmentRows a WHERE a.SnapshotId = @sid
GROUP BY a.Kind, CASE WHEN a.PrincipalKind = N'deleted' THEN 1 ELSE 0 END, a.Managed, a.OwnKind;
SELECT COUNT_BIG(*) AS N FROM pim.ActiveAssignmentRows a WHERE $where OPTION (RECOMPILE);
SELECT a.Seq, a.RowJson, a.Managed, a.OwnKind FROM pim.ActiveAssignmentRows a WHERE $where
ORDER BY $col $dir, a.Seq ASC OFFSET @off ROWS FETCH NEXT @take ROWS ONLY OPTION (RECOMPILE);
"@
    $p = @{ sid = $SnapshotId; type = $typeV; q = $q; qLike = (ConvertTo-PimSqlLikeContains -Text $q)
            aliasJson = (ConvertTo-PimSqlJsonStringArray -Values $al); scopeJson = (ConvertTo-PimSqlJsonStringArray -Values $sc)
            showDeleted = [bool]$ShowDeleted; showManaged = [bool]$ShowManaged; showProduct = [bool]$ShowProduct; showSupport = [bool]$ShowSupport; showBreakGlass = [bool]$ShowBreakGlass
            off = [int](($Page - 1) * $PageSize); take = [int]$PageSize }
    foreach ($lmKey in @($lmSql.parameters.Keys)) { $p["$lmKey"] = $lmSql.parameters[$lmKey] }
    $sets = Invoke-PimSqlQuerySets -ConnectionString $ConnectionString -Sql $sql -Parameters $p -CommandTimeoutSec (Get-PimActiveAssignmentsQueryTimeoutSec)
    if ($sets.Count -lt 3) { throw "the active-assignments query answered $($sets.Count) of 3 result sets" }
    $filtered = [long]0
    foreach ($r in $sets[1]) { if ($null -ne $r) { $filtered = [long]$r.N } }
    $rows = New-Object System.Collections.Generic.List[object]
    foreach ($r in $sets[2]) {
        if ($null -eq $r) { continue }
        $rows.Add([pscustomobject]@{ seq = [int]$r.Seq; json = "$($r.RowJson)"; managed = [bool]$r.Managed; ownKind = "$($r.OwnKind)" })
    }
    return [pscustomobject]@{ groups = @($sets[0]); filtered = $filtered; rows = $rows.ToArray(); page = $Page; pageSize = $PageSize; sort = $col; descending = [bool]$Descending }
}

# --- row CRUD -------------------------------------------------------------------
function Get-PimSqlRows {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Entity)
    $raw = Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT [Key], DataJson FROM pim.Rows WHERE Entity = @e ORDER BY [Key]" -Parameters @{ e = $Entity }
    # §97.1: parsed 200 rows per ConvertFrom-Json call, not one call per row (a 400-row entity was ~1 s of parser start-up,
    # read twice per commit). Same objects, same order; a row whose JSON does not parse alone still fails the read.
    $js = @($raw | Where-Object { "$($_.DataJson)".Trim() } | ForEach-Object { "$($_.DataJson)" })
    $out = New-Object System.Collections.Generic.List[object]
    for ($at = 0; $at -lt $js.Count; $at += 200) {
        $chunk = $js[$at..([Math]::Min($js.Count, $at + 200) - 1)]
        $parsed = ConvertFrom-Json -InputObject ('[' + ($chunk -join ',') + ']')   # assigned first: PS 5.1 emits the array as ONE object
        foreach ($o in @($parsed)) { $out.Add($o) }
    }
    return @($out.ToArray())
}

function Get-PimSqlRow {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Entity, [Parameter(Mandatory)][string]$Key)
    $j = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql "SELECT DataJson FROM pim.Rows WHERE Entity=@e AND [Key]=@k" -Parameters @{ e = $Entity; k = $Key }
    if ($null -eq $j -or "$j".Trim() -eq '') { return $null }
    return ($j | ConvertFrom-Json)
}

function Invoke-PimSqlJournaledRowWrite {
    <#
      CONFIG-1.1: ONE row written (upsert, or delete with -Remove) together with its journal row, in ONE transaction:
      read the stored JSON (UPDLOCK), write, and journal Add / Modify / Remove when the content changed. A byte-identical
      upsert still stamps UpdatedUtc (unchanged behaviour) and leaves no journal row. Throws (rolled back) on any failure.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Entity, [Parameter(Mandatory)][string]$Key,
          [AllowNull()][string]$Json, [switch]$Remove)
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    $tx = $null
    try {
        $c.Open(); $tx = $c.BeginTransaction()
        $before = Get-PimRowJsonTx -Connection $c -Transaction $tx -Entity $Entity -Key $Key
        $cmd = $c.CreateCommand(); $cmd.Transaction = $tx
        [void]$cmd.Parameters.AddWithValue('@e', $Entity); [void]$cmd.Parameters.AddWithValue('@k', $Key)
        if ($Remove) {
            $cmd.CommandText = 'DELETE FROM pim.Rows WHERE Entity=@e AND [Key]=@k'
            [void]$cmd.ExecuteNonQuery()
            if ($null -ne $before) { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity $Entity -Key $Key -Op Remove -BeforeJson $before -AfterJson $null }
        } else {
            $cmd.CommandText = @"
MERGE pim.Rows AS t USING (SELECT @e AS Entity, @k AS [Key]) AS s
  ON t.Entity = s.Entity AND t.[Key] = s.[Key]
WHEN MATCHED THEN UPDATE SET DataJson = @d, UpdatedUtc = SYSUTCDATETIME()
WHEN NOT MATCHED THEN INSERT (Entity, [Key], DataJson, UpdatedUtc) VALUES (@e, @k, @d, SYSUTCDATETIME());
"@
            [void]$cmd.Parameters.AddWithValue('@d', $Json)
            [void]$cmd.ExecuteNonQuery()
            if ($null -eq $before) { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity $Entity -Key $Key -Op Add -BeforeJson $null -AfterJson $Json }
            elseif (-not [string]::Equals($before, $Json, [StringComparison]::Ordinal)) { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity $Entity -Key $Key -Op Modify -BeforeJson $before -AfterJson $Json }
        }
        $tx.Commit(); $tx = $null
    } catch {
        if ($tx) { try { $tx.Rollback() } catch { Write-Warning "  [sql] transaction rollback failed: $($_.Exception.Message)" } }
        throw
    } finally {
        if ($c) { $c.Close(); $c.Dispose() }
    }
}

function Set-PimSqlRow {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Entity, [Parameter(Mandatory)][string]$Key, [object]$Data)
    $json = if ($null -ne $Data) { $Data | ConvertTo-Json -Depth 12 -Compress } else { '{}' }
    Invoke-PimSqlJournaledRowWrite -ConnectionString $ConnectionString -Entity $Entity -Key $Key -Json $json
}

function Remove-PimSqlRow {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Entity, [Parameter(Mandatory)][string]$Key)
    Invoke-PimSqlJournaledRowWrite -ConnectionString $ConnectionString -Entity $Entity -Key $Key -Remove
}

# --- SQL-backed change queue (mirrors the JSON adapter) -------------------------
function ConvertTo-PimSqlUtcDateTime {
    <#
      BUG-251 (§78 live GUI sweep, 2026-09-24): `[datetime]'2026-09-24T04:06:10Z'` converts to the MACHINE'S LOCAL time,
      and that local value was written into pim.ChangeQueue.EnqueuedUtc. In the hosted container local IS UTC, so it hid;
      a Manager or tool on a UTC+2 host stored every enqueue two hours ahead, and Pending changes then showed an entry
      "applied" two hours before it was requested. Always hand SQL a real UTC value:
        * a [datetime]: Local -> converted; Utc -> as is; Unspecified -> taken AS UTC (it came from a ...Utc column)
        * a string: parsed invariant, assumed UTC when it carries no offset, adjusted to UTC when it does
      Empty -> now (UTC), matching the old behaviour of an enqueue without a timestamp.
    #>
    param($Value)
    if ($null -eq $Value -or "$Value".Trim() -eq '') { return [datetime]::UtcNow }
    if ($Value -is [datetime]) {
        if ($Value.Kind -eq [DateTimeKind]::Local) { return $Value.ToUniversalTime() }
        return [datetime]::SpecifyKind($Value, [DateTimeKind]::Utc)
    }
    $styles = [Globalization.DateTimeStyles]::AssumeUniversal -bor [Globalization.DateTimeStyles]::AdjustToUniversal
    return [datetime]::Parse("$Value", [Globalization.CultureInfo]::InvariantCulture, $styles)
}

function Add-PimSqlQueueChange {
    # §65 -- carries Kind/Origin/Justification. Both dimensions default at the DDL level to
    # DesiredState/Proposal, so a caller built before §65 (or one that passes a bare change record)
    # enqueues exactly what it always did.
    # 🔒 Status is hard-coded 'pending'. There is deliberately NO way to enqueue something already
    # committed -- committing is an operator act on a stored row (§65.7), never a property of the
    # insert. A caller that could mint a committed entry would bypass the whole review surface.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][object]$Change)
    $payload = if ($null -ne $Change.payload) { $Change.payload | ConvertTo-Json -Depth 12 -Compress } else { $null }
    $kind    = if ("$($Change.kind)".Trim())   { "$($Change.kind)" }   else { 'DesiredState' }
    $origin  = if ("$($Change.origin)".Trim()) { "$($Change.origin)" } else { 'Proposal' }
    $just    = if ("$($Change.justification)".Trim()) { "$($Change.justification)" } else { $null }
    $enq     = ConvertTo-PimSqlUtcDateTime $Change.enqueuedUtc
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
INSERT INTO pim.ChangeQueue (Id, Entity, [Key], Op, Payload, EnqueuedUtc, [By], Status, Kind, Origin, Justification)
VALUES (@id, @e, @k, @op, @p, @enq, @by, 'pending', @kind, @origin, @just);
"@ -Parameters @{ id = [guid]$Change.id; e = "$($Change.entity)"; k = "$($Change.key)"; op = "$($Change.op)"; p = $payload; enq = $enq; by = "$($Change.by)"; kind = $kind; origin = $origin; just = $just })
    # Framework §12.11f item 2 / PIM 100.144a: the requester's signature, when a signed-in Manager request enqueued this (never throws).
    if ($global:PIM_SignedRequestCapture -and (Get-Command Save-PimSignedRequestForQueue -ErrorAction SilentlyContinue)) { [void](Save-PimSignedRequestForQueue -ConnectionString $ConnectionString -QueueId "$($Change.id)" -Role requester) }
}

function Add-PimSqlQueueChangeIfAbsent {
    <#
      🔴 BUG-212 (§33.28) -- DE-DUPLICATED ENQUEUE. Discovery proposes the same items every day (discovery-entra
      runs daily with -GetLiveRoles and proposed ~130 Creates each run); only COMMITTED rows are drained, so every
      un-reviewed proposal was added again the next day and pending rows piled up. This inserts ONLY when no
      OPEN entry (pending / committed / applying / failed -- anything not applied or discarded) exists for the same
      Entity + Key + Op, in ONE statement (INSERT ... WHERE NOT EXISTS), so two runners cannot both insert it.
      Returns $true when a row was added, $false when an open duplicate already exists. THROWS on a store error.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][object]$Change)
    $payload = if ($null -ne $Change.payload) { $Change.payload | ConvertTo-Json -Depth 12 -Compress } else { $null }
    $kind    = if ("$($Change.kind)".Trim())   { "$($Change.kind)" }   else { 'DesiredState' }
    $origin  = if ("$($Change.origin)".Trim()) { "$($Change.origin)" } else { 'Proposal' }
    $just    = if ("$($Change.justification)".Trim()) { "$($Change.justification)" } else { $null }
    $n = Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
INSERT INTO pim.ChangeQueue (Id, Entity, [Key], Op, Payload, EnqueuedUtc, [By], Status, Kind, Origin, Justification)
SELECT @id, @e, @k, @op, @p, @enq, @by, 'pending', @kind, @origin, @just
WHERE NOT EXISTS (SELECT 1 FROM pim.ChangeQueue WITH (UPDLOCK, HOLDLOCK)
                  WHERE Entity=@e AND [Key]=@k AND Op=@op AND Status IN ('pending','committed','applying','failed'));
"@ -Parameters @{ id = [guid]$Change.id; e = "$($Change.entity)"; k = "$($Change.key)"; op = "$($Change.op)"; p = $payload; enq = (ConvertTo-PimSqlUtcDateTime $Change.enqueuedUtc); by = "$($Change.by)"; kind = $kind; origin = $origin; just = $just }
    if ([int]$n -gt 0 -and $global:PIM_SignedRequestCapture -and (Get-Command Save-PimSignedRequestForQueue -ErrorAction SilentlyContinue)) { [void](Save-PimSignedRequestForQueue -ConnectionString $ConnectionString -QueueId "$($Change.id)" -Role requester) }
    return ([int]$n -gt 0)
}

function Add-PimSqlQueueChangeUnlessPending {
    <#
      §33.0a -- REVOKE DE-DUPE (operator 2026-10-07: three identical revokes were queued by three Delete clicks).
      Inserts the change ONLY when no PENDING entry exists for the same Entity + Key + Op, in ONE statement
      (INSERT ... WHERE NOT EXISTS under UPDLOCK/HOLDLOCK), so two admins clicking at once cannot both insert it.
      🔒 PENDING ONLY, deliberately narrower than Add-PimSqlQueueChangeIfAbsent: an entry that is already
      committed / applying / applied / failed is a decision (or an outcome) of its own, so a new revoke of the same
      target is a new request and is queued -- the de-dupe never hides a request behind an older one.
      Returns @{ added = $true|$false; existingId = '<id of the pending entry>' | '' }. THROWS on a store error.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][object]$Change)
    $payload = if ($null -ne $Change.payload) { $Change.payload | ConvertTo-Json -Depth 12 -Compress } else { $null }
    $kind    = if ("$($Change.kind)".Trim())   { "$($Change.kind)" }   else { 'DesiredState' }
    $origin  = if ("$($Change.origin)".Trim()) { "$($Change.origin)" } else { 'Proposal' }
    $just    = if ("$($Change.justification)".Trim()) { "$($Change.justification)" } else { $null }
    $n = Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
INSERT INTO pim.ChangeQueue (Id, Entity, [Key], Op, Payload, EnqueuedUtc, [By], Status, Kind, Origin, Justification)
SELECT @id, @e, @k, @op, @p, @enq, @by, 'pending', @kind, @origin, @just
WHERE NOT EXISTS (SELECT 1 FROM pim.ChangeQueue WITH (UPDLOCK, HOLDLOCK)
                  WHERE Entity=@e AND [Key]=@k AND Op=@op AND Status='pending');
"@ -Parameters @{ id = [guid]$Change.id; e = "$($Change.entity)"; k = "$($Change.key)"; op = "$($Change.op)"; p = $payload; enq = (ConvertTo-PimSqlUtcDateTime $Change.enqueuedUtc); by = "$($Change.by)"; kind = $kind; origin = $origin; just = $just }
    if ([int]$n -gt 0) {
        if ($global:PIM_SignedRequestCapture -and (Get-Command Save-PimSignedRequestForQueue -ErrorAction SilentlyContinue)) { [void](Save-PimSignedRequestForQueue -ConnectionString $ConnectionString -QueueId "$($Change.id)" -Role requester) }
        return [pscustomobject]@{ added = $true; existingId = '' }
    }
    $ex = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT TOP 1 Id FROM pim.ChangeQueue WHERE Entity=@e AND [Key]=@k AND Op=@op AND Status='pending' ORDER BY EnqueuedUtc" -Parameters @{ e = "$($Change.entity)"; k = "$($Change.key)"; op = "$($Change.op)" })
    return [pscustomobject]@{ added = $false; existingId = $(if ($ex.Count) { "$($ex[0].Id)" } else { '' }) }
}

function Set-PimSqlQueueCommitted {
    <#
      §65.7 -- COMMIT THE ENTRIES THE OPERATOR SELECTED. Per-id, never "everything pending".

      🔒 THE TRANSITION IS CONDITIONAL (`WHERE Id=@id AND Status='pending'`), which is what makes
      this safe with several admins working at once. Two people committing the same entry: the
      first moves it, the second's UPDATE affects 0 rows and is reported back as 'skipped' with the
      state it is actually in. The loser is TOLD, never silently ignored -- a commit that appears to
      succeed twice is how a revoke gets applied twice.

      Returns one record per requested id: @{ id; committed; state; reason }.
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [Parameter(Mandatory)][string[]]$Ids,
        [Parameter(Mandatory)][string]$By
    )
    $out = New-Object System.Collections.Generic.List[object]
    foreach ($raw in @($Ids)) {
        $id = "$raw".Trim()
        if (-not $id) { continue }
        $g = [guid]::Empty
        if (-not [guid]::TryParse($id, [ref]$g)) {
            $out.Add([pscustomobject]@{ id = $id; committed = $false; state = 'invalid'; reason = 'not a GUID' }); continue
        }
        $n = Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
UPDATE pim.ChangeQueue
   SET Status='committed', CommittedBy=@by, CommittedUtc=SYSUTCDATETIME()
 WHERE Id=@id AND Status='pending';
"@ -Parameters @{ id = $g; by = "$By" }
        if ([int]$n -eq 1) {
            # Framework §12.11f item 2 / PIM 100.144a: the approver's signature (the person who committed the entry; never throws).
            if ($global:PIM_SignedRequestCapture -and (Get-Command Save-PimSignedRequestForQueue -ErrorAction SilentlyContinue)) { [void](Save-PimSignedRequestForQueue -ConnectionString $ConnectionString -QueueId $id -Role approver) }
            $out.Add([pscustomobject]@{ id = $id; committed = $true; state = 'committed'; reason = '' })
        } else {
            # Say WHAT it is now. "0 rows" alone cannot distinguish "already committed by a
            # colleague" from "this id does not exist", and those need different responses.
            $cur = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT Status FROM pim.ChangeQueue WHERE Id=@id" -Parameters @{ id = $g })
            $state = if ($cur.Count) { "$($cur[0].Status)" } else { 'missing' }
            $reason = if ($state -eq 'missing') { 'no such queue entry' } else { "already '$state' -- only a pending entry can be committed" }
            $out.Add([pscustomobject]@{ id = $id; committed = $false; state = $state; reason = $reason })
        }
    }
    return @($out.ToArray())
}

function Get-PimDesiredStateSignature {
    <#
      A CHEAP change-detector for one entity's desired state, used to invalidate the
      convergence-verification cache (Get-PimConvergenceScopePlan) without re-reading rows.

      COUNT(*) + MAX(UpdatedUtc) over pim.Rows for the entity: an insert or delete moves the
      count, any edit moves the timestamp (Set-PimSqlRow stamps UpdatedUtc=SYSUTCDATETIME() on
      both the MATCHED and NOT MATCHED branch). So any Manager commit touching this entity
      changes the signature and forces a fresh verification -- which is the property that makes
      caching safe: a newly-authored delegation is re-verified at once, not on a slow cycle.

      Returns '' when the signature cannot be read. 🪤 The CALLER MUST treat '' as "unknown, so
      verify" and never as "unchanged" -- reading an error as a negative result is the exact
      mistake that let BUG-134 hide.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Entity)
    try {
        $r = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString `
                -Sql "SELECT COUNT(*) AS N, MAX(UpdatedUtc) AS M FROM pim.Rows WHERE Entity=@e" `
                -Parameters @{ e = $Entity })
        if (-not $r.Count) { return '' }
        $n = "$($r[0].N)"
        $m = if ($null -ne $r[0].M -and "$($r[0].M)".Trim()) { ([datetime]$r[0].M).ToString('o') } else { 'none' }
        return "$Entity|$n|$m"
    } catch { return '' }
}

function Get-PimSqlQueue {
    <#
      §65.7 -- THIS IS THE SHARED REVIEW SURFACE, so it returns everything a reviewer needs to judge
      an entry: who enqueued it, why, who committed it, and what happened on the last attempt.
      -Status '' returns ALL states (the GUI's default view: a queue that hides its failures is not
      a review surface).
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [string]$Status = 'pending',
        [ValidateSet('','DesiredState','Action')][string]$Kind = '',
        # 🔴 READ WHAT WILL BE LOOKED AT (operator, 2026-09-22: "loading queue is taking too long").
        # Every row carries its PAYLOAD -- for a configuration commit that is the whole row set it
        # wrote (one live queue held 151 discarded entries and a Services commit of 67 rows) -- and
        # the page was reading, parsing, describing and shipping all of it to render 36 rows.
        # -ExcludeStatus drops states nobody is looking at; -Limit keeps the NEWEST n.
        # Neither may be used to hide a failure: the caller still counts every state separately
        # (Get-PimSqlQueueCounts), so what is not read is still REPORTED.
        [string[]]$ExcludeStatus = @(),
        [int]$Limit = 0
    )
    $where = New-Object System.Collections.Generic.List[string]
    $p = @{}
    if ("$Status".Trim()) { $where.Add('Status=@s'); $p['s'] = $Status }
    if ("$Kind".Trim())   { $where.Add('Kind=@kd');  $p['kd'] = $Kind }
    $ex = @($ExcludeStatus | Where-Object { "$_".Trim() })
    if ($ex.Count) {
        $names = @()
        for ($i = 0; $i -lt $ex.Count; $i++) { $names += "@x$i"; $p["x$i"] = "$($ex[$i])" }
        $where.Add('Status NOT IN (' + ($names -join ',') + ')')
    }
    # The discard columns are ADDITIVE (2026-09-12). Select them only when the store has them, so an
    # engine/drain running against a store the Manager has not migrated yet keeps working unchanged.
    $hasDiscard = $false
    try {
        $colLen = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql "SELECT COL_LENGTH('pim.ChangeQueue','DiscardedBy')"
        $hasDiscard = ($null -ne $colLen -and -not ($colLen -is [System.DBNull]) -and "$colLen".Trim() -ne '')
    } catch { $hasDiscard = $false }
    $discardCols = if ($hasDiscard) { ', DiscardedBy, DiscardedUtc, DiscardReason' } else { '' }
    $top = if ($Limit -gt 0) { "TOP ($([int]$Limit)) " } else { '' }
    $sql = "SELECT ${top}Id, Entity, [Key], Op, Payload, EnqueuedUtc, [By], Status, Kind, Origin, Justification, CommittedBy, CommittedUtc, Attempts, LastAttemptUtc, LastError, AppliedUtc, AppliedBy$discardCols FROM pim.ChangeQueue"
    if ($where.Count) { $sql += ' WHERE ' + ($where -join ' AND ') }
    # With a limit the NEWEST rows are the ones worth reading, so the cut is taken from the top and
    # the result is turned back into the ascending order every caller expects.
    $sql += $(if ($Limit -gt 0) { ' ORDER BY EnqueuedUtc DESC' } else { ' ORDER BY EnqueuedUtc' })
    $raw = Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql $sql -Parameters $p
    if ($Limit -gt 0) { $raw = @($raw) ; [array]::Reverse($raw) }
    $iso = { param($v) if ($null -ne $v -and "$v".Trim()) { ([datetime]$v).ToString('o') } else { '' } }
    return @($raw | ForEach-Object {
        [pscustomobject]@{ id = "$($_.Id)"; entity = "$($_.Entity)"; key = "$($_.Key)"; op = "$($_.Op)"
            payload = $(if ("$($_.Payload)".Trim()) { $_.Payload | ConvertFrom-Json } else { $null })
            enqueuedUtc = (& $iso $_.EnqueuedUtc); by = "$($_.By)"; status = "$($_.Status)"
            kind = "$($_.Kind)"; origin = "$($_.Origin)"; justification = "$($_.Justification)"
            committedBy = "$($_.CommittedBy)"; committedUtc = (& $iso $_.CommittedUtc)
            attempts = [int]"$(if ($null -ne $_.Attempts) { $_.Attempts } else { 0 })"
            lastAttemptUtc = (& $iso $_.LastAttemptUtc); lastError = "$($_.LastError)"
            appliedUtc = (& $iso $_.AppliedUtc); appliedBy = "$($_.AppliedBy)"
            discardedBy = $(if ($hasDiscard) { "$($_.DiscardedBy)" } else { '' })
            discardedUtc = $(if ($hasDiscard) { (& $iso $_.DiscardedUtc) } else { '' })
            discardReason = $(if ($hasDiscard) { "$($_.DiscardReason)" } else { '' }) }
    })
}

function Get-PimSqlQueueCounts {
    <#
      How many entries are in each state, as ONE aggregate -- no payloads, no rows.
      The queue list may legitimately read a subset (see -ExcludeStatus / -Limit on Get-PimSqlQueue),
      and this is what keeps the page HONEST about what it is not showing: "151 discarded hidden" is
      a fact read from the store, not a count of rows that happened to be fetched.
      Returns @{ pending = n; applied = n; ... } -- states with no rows are simply absent.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString)
    $out = @{}
    $raw = Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql 'SELECT Status, COUNT(*) AS N FROM pim.ChangeQueue GROUP BY Status'
    foreach ($r in @($raw)) {
        $s = "$($r.Status)".Trim()
        if ($s) { $out[$s] = [int]"$($r.N)" }
    }
    return $out
}

function Set-PimSqlQueueDiscarded {
    <#
      DISCARD selected queue entries (2026-09-12). Operator: a failed test row "cannot be removed".

      🔒 ONLY 'pending' OR 'failed' may be discarded -- never 'committed', 'applying' or 'applied'.
      A committed entry is authorised work the drain may claim at any moment, and an applying or
      applied one has (or is having) a real directory effect; hiding those would falsify the record.
      The transition is CONDITIONAL in SQL (`WHERE Status IN ('pending','failed')`) so a drain that
      claims the row first wins, and the loser is TOLD the state it is really in.

      🔒 THE ROW IS KEPT (section 65.8 retains history): Status='discarded' + DiscardedBy/Utc/Reason.
      The drain only ever claims Status='committed', so a discarded entry can never be applied.

      Returns one record per id: @{ id; discarded; state; reason }.
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [Parameter(Mandatory)][string[]]$Ids,
        [Parameter(Mandatory)][string]$By,
        [Parameter(Mandatory)][string]$Reason
    )
    if (-not "$Reason".Trim()) { throw 'a discard needs a reason' }
    $out = New-Object System.Collections.Generic.List[object]
    foreach ($raw in @($Ids)) {
        $id = "$raw".Trim()
        if (-not $id) { continue }
        $g = [guid]::Empty
        if (-not [guid]::TryParse($id, [ref]$g)) {
            $out.Add([pscustomobject]@{ id = $id; discarded = $false; state = 'invalid'; reason = 'not a GUID' }); continue
        }
        $n = Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
UPDATE pim.ChangeQueue
   SET Status='discarded', DiscardedBy=@by, DiscardedUtc=SYSUTCDATETIME(), DiscardReason=@r
 WHERE Id=@id AND Status IN ('pending','failed');
"@ -Parameters @{ id = $g; by = "$By"; r = "$Reason" }
        if ([int]$n -eq 1) {
            $out.Add([pscustomobject]@{ id = $id; discarded = $true; state = 'discarded'; reason = '' })
        } else {
            $cur = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT Status FROM pim.ChangeQueue WHERE Id=@id" -Parameters @{ id = $g })
            $state = if ($cur.Count) { "$($cur[0].Status)" } else { 'missing' }
            $why = if ($state -eq 'missing') { 'no such queue entry' } else { "'$state' -- only a pending or failed entry can be discarded" }
            $out.Add([pscustomobject]@{ id = $id; discarded = $false; state = $state; reason = $why })
        }
    }
    return @($out.ToArray())
}

# --- the drain: apply COMMITTED desired-state entries to pim.Rows ----------------
function Invoke-PimSqlCommit {
    <#
      🔴 BUG-152 -- REWRITTEN. The previous version ended with:

          UPDATE pim.ChangeQueue SET Status='applied' WHERE Status='pending'

      Unbounded by id, so it marked every row that was pending AT THE END OF THE DRAIN -- not the
      rows it planned. Three defects, all of which §65.8 forbids:
        1. THE READ->UPDATE RACE. Anything enqueued while the loop ran was marked applied without
           ever being applied. Silent loss, and the slower the drain the wider the window.
        2. NO TRANSACTION. The pim.Rows write and the status change were separate statements.
        3. NO PER-ENTRY OUTCOME, so a failure could not be attributed -- and therefore not retried.
      It never damaged a customer only because nothing called it (BUG-135).

      🔑 ONLY 'committed' ENTRIES ARE DRAINED. 'pending' means nobody has selected it yet, which is
      what preserves BUG-135's "propose-don't-auto-map": a discovery proposal sits here forever
      until an operator commits it.

      🪤 PER-ENTRY, NOT NET-FOLDED -- a DELIBERATE trade. Get-PimQueueApplyPlan folds several
      changes on one (entity,key) into a single net op, which is faster but destroys attribution:
      if three entries fold into one write and it fails, no entry can be marked failed and none can
      be retried. §65.8 requires per-entry outcome, so entries are applied in order instead. The
      final state is identical (Create-then-Update applied in sequence == the folded result).

      -MaxAttempts: after this many failed attempts an entry becomes 'failed' -- RETAINED and
      surfaced, never deleted. Without a cap a permanently-broken entry retries every tick forever
      and stays invisible.
      -FailAfter: TEST SEAM ONLY (mirrors Set-PimSqlEntityRowsTransactional) -- throw after N
      applies to prove the per-entry transaction rolls back and the entry stays retryable.
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [int]$MaxAttempts = 3,
        [string]$AppliedBy = '',
        [int]$FailAfter = -1
    )
    $committed = @(Get-PimSqlQueue -ConnectionString $ConnectionString -Status 'committed' -Kind 'DesiredState')
    if ($committed.Count -eq 0) {
        return [pscustomobject]@{ applied = 0; failed = 0; retrying = 0; rowsAffected = 0; results = @() }
    }
    # Definitions before assignments, then enqueue order -- the same ordering the fold used, so a
    # binding is never applied before the thing it references.
    $ordered = @($committed | Sort-Object { Get-PimEntityOrderRank $_.entity }, { "$($_.enqueuedUtc)" })

    $who = if ("$AppliedBy".Trim()) { "$AppliedBy" } else { "$env:COMPUTERNAME" }
    $results = New-Object System.Collections.Generic.List[object]
    $applied = 0; $failedN = 0; $retrying = 0; $affected = 0; $done = 0; $unrecorded = 0

    foreach ($ch in $ordered) {
        $id = [guid]"$($ch.id)"
        $err = ''
        $c = New-PimSqlConnection -ConnectionString $ConnectionString
        $tx = $null
        try {
            $c.Open()
            $tx = $c.BeginTransaction()
            $exec = {
                param($sql, $params)
                $cmd = $c.CreateCommand(); $cmd.Transaction = $tx; $cmd.CommandText = $sql
                foreach ($k in $params.Keys) { [void]$cmd.Parameters.AddWithValue("@$k", $(if ($null -eq $params[$k]) { [DBNull]::Value } else { $params[$k] })) }
                return $cmd.ExecuteNonQuery()
            }
            # 🔒 THE EFFECT AND THE STATUS CHANGE ARE ONE TRANSACTION (§65.8). A crash between them
            # leaves the entry 'committed' and therefore replayed -- never applied-but-not-done.
            # CONFIG-1.1: the journal row joins that transaction; the entry's id is its commit id, its submitter and committer
            # are the initiator and approver.
            $qCtx = New-PimCommitJournalContext -CommitId "$($ch.id)".Replace('-', '') -Source 'queue' `
                        -InitiatedBy $(if ("$($ch.by)".Trim()) { "$($ch.by)" } else { $who }) `
                        -ApprovedBy $(if ("$($ch.committedBy)".Trim() -and "$($ch.committedBy)" -ne "$($ch.by)") { "$($ch.committedBy)" } else { '' })
            $qBefore = Get-PimRowJsonTx -Connection $c -Transaction $tx -Entity "$($ch.entity)" -Key "$($ch.key)"
            if ("$($ch.op)" -eq 'Remove') {
                [void](& $exec "DELETE FROM pim.Rows WHERE Entity=@e AND [Key]=@k" @{ e = "$($ch.entity)"; k = "$($ch.key)" })
                if ($null -ne $qBefore) { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity "$($ch.entity)" -Key "$($ch.key)" -Op Remove -BeforeJson $qBefore -AfterJson $null -Context $qCtx }
            } else {
                $json = if ($null -ne $ch.payload) { $ch.payload | ConvertTo-Json -Depth 12 -Compress } else { '{}' }
                [void](& $exec @"
MERGE pim.Rows AS t USING (SELECT @e AS Entity, @k AS [Key]) AS s
  ON t.Entity = s.Entity AND t.[Key] = s.[Key]
WHEN MATCHED THEN UPDATE SET DataJson = @d, UpdatedUtc = SYSUTCDATETIME()
WHEN NOT MATCHED THEN INSERT (Entity, [Key], DataJson, UpdatedUtc) VALUES (@e, @k, @d, SYSUTCDATETIME());
"@ @{ e = "$($ch.entity)"; k = "$($ch.key)"; d = $json })
                if ($null -eq $qBefore) { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity "$($ch.entity)" -Key "$($ch.key)" -Op Add -BeforeJson $null -AfterJson $json -Context $qCtx }
                elseif (-not [string]::Equals($qBefore, $json, [StringComparison]::Ordinal)) { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity "$($ch.entity)" -Key "$($ch.key)" -Op Modify -BeforeJson $qBefore -AfterJson $json -Context $qCtx }
            }
            $done++
            if ($FailAfter -ge 0 -and $done -gt $FailAfter) { throw "FailAfter=$FailAfter test seam" }

            # Conditional on Status='committed' so a concurrent drain cannot apply the same entry
            # twice -- the second one's UPDATE affects 0 rows and it rolls back.
            $n = & $exec @"
UPDATE pim.ChangeQueue
   SET Status='applied', AppliedUtc=SYSUTCDATETIME(), AppliedBy=@who,
       Attempts=Attempts+1, LastAttemptUtc=SYSUTCDATETIME(), LastError=NULL
 WHERE Id=@id AND Status='committed';
"@ @{ id = $id; who = $who }
            if ([int]$n -ne 1) { throw "entry was claimed by another drain (status changed under us)" }
            $tx.Commit(); $tx = $null
            $applied++; $affected++
            $results.Add([pscustomobject]@{ id = "$($ch.id)"; entity = "$($ch.entity)"; key = "$($ch.key)"; outcome = 'applied'; error = '' })
        } catch {
            $err = "$($_.Exception.Message)"
            if ($tx) { try { $tx.Rollback() } catch { } }
        } finally {
            if ($c) { $c.Close(); $c.Dispose() }
        }

        if ($err) {
            # The row write rolled back, so record the ATTEMPT separately. An entry that has burnt
            # its attempts becomes 'failed' and is kept; anything else returns to 'committed' and is
            # retried on the next tick (§65.8 -- "goes into the queue again").
            $attempts = [int]$ch.attempts + 1
            $next = if ($attempts -ge $MaxAttempts) { 'failed' } else { 'committed' }
            # 🔴 THIS BOOKKEEPING WRITE IS NOT OPTIONAL, AND ITS FAILURE IS NOT COSMETIC.
            # It was first written as `try { ... } catch { }` -- and Test-PimCodeAudit's
            # SWALLOWED-MUTATION class caught it, correctly: if this UPDATE fails, the entry keeps
            # its OLD attempt count and NO error text, so it retries forever with nothing on it
            # explaining why. A drain that reports 'retrying' while failing to record the attempt is
            # the same "a failed write reports success" shape this whole chapter exists to remove.
            $bookkept = $false
            $bookErr = ''
            try {
                [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
UPDATE pim.ChangeQueue
   SET Status=@st, Attempts=@n, LastAttemptUtc=SYSUTCDATETIME(), LastError=@e
 WHERE Id=@id;
"@ -Parameters @{ st = $next; n = $attempts; e = $err; id = $id })
                $bookkept = $true
            } catch {
                $bookErr = "$($_.Exception.Message)"
            }
            if (-not $bookkept) {
                # Counted separately: the action did not apply AND its state could not be recorded,
                # so the caller must not read this as a clean retry.
                $unrecorded++
                $results.Add([pscustomobject]@{ id = "$($ch.id)"; entity = "$($ch.entity)"; key = "$($ch.key)"
                    outcome = 'unrecorded'
                    error = "$err -- AND the queue state could not be updated: $bookErr" })
                continue
            }
            if ($next -eq 'failed') { $failedN++ } else { $retrying++ }
            $results.Add([pscustomobject]@{ id = "$($ch.id)"; entity = "$($ch.entity)"; key = "$($ch.key)"; outcome = $next; error = $err })
        }
    }

    return [pscustomobject]@{ applied = $applied; failed = $failedN; retrying = $retrying
        unrecorded = $unrecorded; rowsAffected = $affected; results = @($results.ToArray()) }
}

function Get-PimStoreRowKey {
    # Natural key per entity/base (matches the manager's row-key convention) so a
    # row maps to a stable pim.Rows [Key]. Returns '' when no key can be derived.
    param([Parameter(Mandatory)][string]$Base, [Parameter(Mandatory)][object]$Row)
    $g = {
        param($n)
        if ($Row -is [System.Collections.IDictionary]) { if ($Row.Contains($n)) { "$($Row[$n])" } else { '' } }
        else { $p = $Row.PSObject.Properties[$n]; if ($p -and $null -ne $p.Value) { "$($p.Value)" } else { '' } }
    }
    # NB: 'switch -Wildcard' evaluates EVERY matching clause unless 'break' stops it.
    # The exact 'PIM-Definitions-AU'/'-Departments' patterns ALSO match the generic
    # 'PIM-Definitions-*' below, so without 'break' both clauses ran and their outputs
    # concatenated (e.g. 'AU1 GT1'). 'break' makes the specific clause win.
    $k = switch -Wildcard ($Base) {
        'PIM-Definitions-AU'              { (& $g 'AdministrativeUnitTag'); break }
        # Departments are a people/owner-routing entity: rows are identified by the
        # department NAME, not a GroupTag (the §11 Departments grid + the scenario
        # seed write { Department; Owners; ... } with NO GroupTag). The generic
        # 'PIM-Definitions-*' branch below keys on GroupTag -> blank key -> the row
        # is silently dropped on save. Key on Department/DepartmentName first, then
        # fall back to GroupTag/GroupName for the shipped-sample shape that carries one.
        # 🔴 2.4.462 (demo on internal 2026-09-29): a department GROUP row carries BOTH its business department (Department =
        # FINANCE) and its own GroupTag (DEPT-deptsimon). Keyed on Department, a NEW group of an existing department took the
        # key of that department's owner row -> "duplicate store key" -> the definition save was refused (400) AFTER the
        # assignments naming it had been written. One department can own several DEPT- groups: a row with a GroupTag is
        # keyed on the tag; an owner row (no tag) on the department name.
        'PIM-Definitions-Departments'    {
            $d = (& $g 'GroupTag')
            if (-not "$d".Trim()) { $d = (& $g 'Department') }
            if (-not "$d".Trim()) { $d = (& $g 'DepartmentName') }
            if (-not "$d".Trim()) { $d = (& $g 'GroupName') }
            $d; break
        }
        'PIM-Definitions-*'              { (& $g 'GroupTag') }
        'Account-Definitions-Admins'     { (& $g 'UserName') }
        # 68.6 row 35: central admins imported from a managing tenant (PIM-Downlink.ps1 Invoke-PimDownlinkAdminApply).
        'Account-Definitions-Admins-Central' { (& $g 'UserName') }
        # §82 consultant lifecycle: an external company, keyed on its name. Deliberately NOT a PIM-Definitions-* entity --
        # every PIM-Definitions-* base is treated as an Entra GROUP definition (template packs, cutover, policy catalog).
        'Account-Definitions-Companies'  { (& $g 'Company'); break }
        # TEST-13: neither of these carries a GroupTag/GroupName, so both fell through to
        # the generic 'default' branch, derived a BLANK key, and every row was dropped on
        # save with a warning that scrolls past. An offboarding row is identified by the
        # ACCOUNT it offboards; a discovery row by its tag. Found because the scenario
        # seeder reported "seeded PIM-Offboarding 0 rows" while TESTS.md said it plants one
        # -- so every assertion that depended on either entity was passing vacuously.
        'PIM-Offboarding'                {
            $o = (& $g 'Username'); if (-not "$o".Trim()) { $o = (& $g 'UserName') }
            if (-not "$o".Trim()) { $o = (& $g 'UserPrincipalName') }
            if (-not "$o".Trim()) { $o = (& $g 'Upn') }
            $o; break
        }
        'PIM-Discovery'                  {
            $d = (& $g 'DiscoveryTag'); if (-not "$d".Trim()) { $d = (& $g 'Tag') }
            if (-not "$d".Trim()) { $d = (& $g 'GroupTag') }
            $d; break
        }
        'PIM-Assignments-Admins'         { ((& $g 'Username') + '|' + (& $g 'GroupTag')) }
        'PIM-Assignments-Groups'         { ((& $g 'TargetGroupTag') + '|' + (& $g 'SourceGroupTag')) }
        # 2026-09-21 (operator: "assign permanent ga to ..."): a DIRECT Entra role row names a user, not a group, so it
        # fell through to 'default' (GroupTag / GroupName), got a BLANK key and was dropped on every save. Keyed like the
        # engine's Get-PimDirectRoleKey: the user, the role and the assignment type.
        'PIM-Assignments-Roles-Direct'   {
            $u = (& $g 'UserPrincipalName'); if (-not "$u".Trim()) { $u = (& $g 'Username') }; if (-not "$u".Trim()) { $u = (& $g 'UserName') }
            $r = (& $g 'RoleDefinitionName'); if (-not "$r".Trim()) { $r = (& $g 'RoleName') }
            if (-not "$u".Trim() -or -not "$r".Trim()) { ''; break }
            ("$u".Trim() + '|' + "$r".Trim() + '|' + (& $g 'AssignmentType')); break
        }
        'PIM-Assignments-Roles-Groups'   { ((& $g 'GroupTag') + '|' + (& $g 'RoleDefinitionName')) }
        'PIM-Assignments-Roles-AUs'      { ((& $g 'GroupTag') + '|' + (& $g 'AdministrativeUnitTag') + '|' + (& $g 'RoleDefinitionName')) }
        'PIM-Assignments-Azure-Resources'{ ((& $g 'GroupTag') + '|' + (& $g 'AzScope') + '|' + (& $g 'AzScopePermission')) }
        default                          { $x = (& $g 'GroupTag'); if (-not "$x".Trim()) { $x = (& $g 'GroupName') }; $x }
    }
    $k = "$k".Trim()
    if ($k -eq '' -or $k -eq '|' -or $k -match '^\|+$') { return '' }
    return $k
}

function Get-PimDuplicateStoreKeys {
    # PURE (BUG-204, 2.4.371). The store keys that two or more of $Rows share for $Base. The full-set replace below
    # upserts row by row into a case-insensitive map, so rows that share a key COLLAPSE: the last one wins and the
    # others are silently dropped (a 2-role workload delegation kept only its last role -- the Workloads key is
    # GroupTag alone). Returns @( @{ key; count; rows = @(1-based positions) } ), empty when every key is unique.
    # Rows with no derivable key are not reported here (they are skipped by the store, a separate concern).
    param([Parameter(Mandatory)][string]$Base, [AllowEmptyCollection()][object[]]$Rows = @())
    $seen = @{}; $order = New-Object System.Collections.Generic.List[string]
    $i = 0
    foreach ($r in @($Rows)) {
        $i++
        if ($null -eq $r) { continue }
        $k = Get-PimStoreRowKey -Base $Base -Row $r
        if (-not $k) { continue }
        if (-not $seen.ContainsKey($k)) { $seen[$k] = New-Object System.Collections.Generic.List[int]; $order.Add($k) }
        $seen[$k].Add($i)
    }
    $out = New-Object System.Collections.Generic.List[object]
    foreach ($k in $order) { if ($seen[$k].Count -gt 1) { $out.Add([pscustomobject]@{ key = $k; count = $seen[$k].Count; rows = @($seen[$k].ToArray()) }) } }
    return @($out.ToArray())
}

function Set-PimSqlEntityRows {
    # Full-set replace of an entity's rows (matches CSV file-write semantics):
    # upsert every submitted row by its natural key, delete current keys that are
    # no longer present. Returns @{ rowCount; removed }.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Entity, [object[]]$Rows = @(), [string]$Base,
          [switch]$AllowEmpty)
    $base = if ("$Base".Trim()) { $Base } else { $Entity }
    $submitted = @{}
    foreach ($r in @($Rows)) {
        $k = Get-PimStoreRowKey -Base $base -Row $r
        if (-not $k) { continue }
        $submitted[$k] = $true
        Set-PimSqlRow -ConnectionString $ConnectionString -Entity $Entity -Key $k -Data $r
    }
    $removed = 0
    $currentKeys = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT [Key] FROM pim.Rows WHERE Entity=@e" -Parameters @{ e = $Entity } | ForEach-Object { "$($_.Key)" })
    # 🔴 Same empty-set wipe as the transactional twin, and MORE dangerous here: there is no
    # transaction, so a refusal after the deletes had started could not be rolled back. Guard
    # BEFORE the delete loop. See the long note in Set-PimSqlEntityRowsTransactional.
    if (-not $submitted.Count -and $currentKeys.Count -and -not $AllowEmpty) {
        throw ("Set-PimSqlEntityRows: refusing to delete all $($currentKeys.Count) row(s) of '$Entity' " +
               'because NO rows were submitted -- that is almost always a failed upstream read. ' +
               'Pass -AllowEmpty if you genuinely mean to empty it.')
    }
    foreach ($ck in $currentKeys) { if (-not $submitted.ContainsKey($ck)) { Remove-PimSqlRow -ConnectionString $ConnectionString -Entity $Entity -Key $ck; $removed++ } }
    return @{ rowCount = $submitted.Count; removed = $removed }
}

# §97.1: rows per set-based statement batch. One batch is one round trip; the JSON it carries stays far below any limit.
$script:PimSqlRowBatchSize = 500

function Invoke-PimSqlEntityRowBatchTx {
    <#
      §97.1 -- SET-BASED row writes on the caller's connection + transaction. -Items, in order: @{ k; op = Add|Modify|Remove;
      d = the row JSON (Add/Modify); b = the stored JSON it replaces (Modify/Remove) }. Each batch of <= $script:PimSqlRowBatchSize
      items is ONE statement batch (one round trip): the upserts (MERGE), the deletes, and one journal row per item in
      the given order (CONFIG-1.1: the same rows Add-PimCommitJournalRowTx wrote one by one, with the per-key initiator /
      approver of the ambient journal context). Returns the number of batches sent. Throws on failure (the caller's
      transaction then rolls back). -FailAfter: test seam -- throw once that many items have been written.
    #>
    param([Parameter(Mandatory)][object]$Connection, [AllowNull()][object]$Transaction, [Parameter(Mandatory)][string]$Entity,
          [AllowEmptyCollection()][object[]]$Items = @(), [int]$FailAfter = -1)
    $sql = @'
SET NOCOUNT ON;
DECLARE @in TABLE (o INT NOT NULL, k NVARCHAR(400) COLLATE DATABASE_DEFAULT NOT NULL, op NVARCHAR(10) NOT NULL, d NVARCHAR(MAX) NULL,
                   b NVARCHAR(MAX) NULL, i NVARCHAR(200) NOT NULL, a NVARCHAR(200) NULL);
INSERT INTO @in (o, k, op, d, b, i, a)
SELECT o, k, op, d, b, i, a FROM OPENJSON(@j) WITH (o INT '$.o', k NVARCHAR(400) '$.k', op NVARCHAR(10) '$.op', d NVARCHAR(MAX) '$.d',
                                                   b NVARCHAR(MAX) '$.b', i NVARCHAR(200) '$.i', a NVARCHAR(200) '$.a');
MERGE pim.Rows WITH (HOLDLOCK) AS t
USING (SELECT k, d FROM @in WHERE op <> 'Remove') AS s ON t.Entity = @e AND t.[Key] = s.k
WHEN MATCHED THEN UPDATE SET DataJson = s.d, UpdatedUtc = SYSUTCDATETIME()
WHEN NOT MATCHED THEN INSERT (Entity, [Key], DataJson, UpdatedUtc) VALUES (@e, s.k, s.d, SYSUTCDATETIME());
DELETE t FROM pim.Rows AS t JOIN @in AS x ON t.Entity = @e AND t.[Key] = x.k WHERE x.op = 'Remove';
INSERT INTO pim.CommitJournal (CommitId, Entity, [Key], Op, BeforeJson, AfterJson, InitiatedBy, ApprovedBy, Source, UndoOf)
SELECT @jc, @e, k, op, b, CASE WHEN op = 'Remove' THEN NULL ELSE d END, i, a, @js, @ju FROM @in ORDER BY o;
'@
    $all = @($Items | Where-Object { $null -ne $_ })
    if (-not $all.Count) { return 0 }
    $ctx = Get-PimCommitJournalContext
    $size = [Math]::Max(1, [int]$script:PimSqlRowBatchSize)
    $batches = 0; $done = 0
    for ($at = 0; $at -lt $all.Count; $at += $size) {
        $chunk = @($all[$at..([Math]::Min($all.Count, $at + $size) - 1)])
        $payload = New-Object System.Collections.Generic.List[object]
        $o = 0
        foreach ($x in $chunk) {
            $who = Resolve-PimCommitJournalActor -Context $ctx -Key "$($x.k)"
            $payload.Add([ordered]@{
                o = $o; k = "$($x.k)"; op = "$($x.op)"
                d = $(if ("$($x.d)" -ne '') { "$($x.d)" } else { $null })
                b = $(if ("$($x.b)" -ne '') { "$($x.b)" } else { $null })
                i = $(if ("$($who.initiatedBy)".Trim()) { "$($who.initiatedBy)" } else { 'system' })
                a = $(if ("$($who.approvedBy)".Trim()) { "$($who.approvedBy)" } else { $null })
            })
            $o++
        }
        $cmd = $Connection.CreateCommand(); if ($Transaction) { $cmd.Transaction = $Transaction }
        $cmd.CommandText = $sql
        try { $cmd.CommandTimeout = 180 } catch { }
        $p = [ordered]@{ e = $Entity; j = (ConvertTo-Json -InputObject @($payload.ToArray()) -Depth 3 -Compress)
                         jc = "$($ctx.commitId)"; js = "$($ctx.source)"; ju = $(if ("$($ctx.undoOf)".Trim()) { "$($ctx.undoOf)" } else { $null }) }
        foreach ($k in $p.Keys) { [void]$cmd.Parameters.AddWithValue("@$k", $(if ($null -eq $p[$k]) { [DBNull]::Value } else { $p[$k] })) }
        [void]$cmd.ExecuteNonQuery()
        # Framework §12.11f item 2 / PIM 100.144a: the commit's captured signatures join the same transaction (once per
        # transaction; guarded -- a signature never fails the change). None on the context (mode off) = nothing.
        if ($ctx.PSObject.Properties['signatures'] -and @($ctx.signatures).Count -and (Get-Command Add-PimSignedRequestRowsForJournalTx -ErrorAction SilentlyContinue)) {
            Add-PimSignedRequestRowsForJournalTx -Connection $Connection -Transaction $Transaction -Context $ctx
        }
        $batches++; $done += $chunk.Count
        if ($FailAfter -ge 0 -and $done -ge $FailAfter) { throw "injected mid-commit failure after $done statement(s) (test seam)" }
    }
    return $batches
}

function Set-PimSqlEntityRowsTransactional {
    # TRANSACTIONAL full-set replace of an entity's rows (REQUIREMENTS.md s28 [M1]).
    # Identical SEMANTICS to Set-PimSqlEntityRows -- upsert every submitted row by
    # its natural key, delete current keys no longer present -- but every upsert AND
    # delete runs inside ONE SqlTransaction on ONE connection. A failure mid-loop
    # rolls the WHOLE batch back, so the store is left exactly as before (never a
    # half-applied row-set, the [M1] defect). Returns @{ rowCount; removed }.
    #
    # -FailAfter is a TEST seam only: throw deliberately after applying N statements
    # to prove the rollback leaves pim.Rows unchanged (the offline tests use it; it
    # is never set in production).
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [Parameter(Mandatory)][string]$Entity,
        [object[]]$Rows = @(),
        [string]$Base,
        [int]$FailAfter = -1,
        # 🔴 See the empty-set guard below. Deliberately clearing an entity is legitimate; doing it
        # BY ACCIDENT is a production data wipe, and the two look identical from in here.
        [switch]$AllowEmpty
    )
    $base = if ("$Base".Trim()) { $Base } else { $Entity }
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    $tx = $null
    try {
        $c.Open()
        $tx = $c.BeginTransaction()
        $stmts = 0

        # §97.1: the round trips this replace made (SqlConnection statistics; a fake connection has none -> -1).
        $statsErr = ''; try { $c.StatisticsEnabled = $true } catch { $statsErr = "$($_.Exception.Message)" }

        # 1) read current keys AND their stored JSON (inside the tx for a consistent snapshot).
        $curCmd = $c.CreateCommand(); $curCmd.Transaction = $tx
        $curCmd.CommandText = "SELECT [Key], DataJson FROM pim.Rows WHERE Entity=@e"
        [void]$curCmd.Parameters.AddWithValue('@e', $Entity)
        $rd = $curCmd.ExecuteReader(); $currentKeys = New-Object System.Collections.Generic.List[string]
        # The key match is case-insensitive, like pim.Rows' own key (and the $submitted map below): a submitted 'A' IS the
        # stored 'a' -- an update, journaled as a Modify of that row (never an Add plus a kept duplicate).
        $currentJson = New-Object 'System.Collections.Generic.Dictionary[string,string]' ([StringComparer]::OrdinalIgnoreCase)
        while ($rd.Read()) { $ck0 = "$($rd.GetValue(0))"; $currentKeys.Add($ck0); $dj = $rd.GetValue(1); $currentJson[$ck0] = $(if ($null -eq $dj -or $dj -is [DBNull]) { '' } else { "$dj" }) }
        $rd.Close()

        # 2) the submitted rows that CHANGED -- planned here, written SET-BASED below.
        # §88 (operator 2026-10-02: "why is the commit so slow into the sql"): this used to MERGE EVERY submitted row --
        # the Manager submits the whole entity, so one changed admin on internal (659 rows) was 659 round trips to Azure
        # SQL inside the commit. A row whose JSON is byte-identical to what is stored is skipped: same data, and its
        # UpdatedUtc stays honest (the change detector still sees the rows that did change).
        # 🔴 §97.1 (a test tenant 2026-10-08, 168 template rows, 132 s): every CHANGED row was still TWO round trips (its MERGE +
        # its journal INSERT) inside the transaction. The plan is now built in memory and written in ONE statement batch
        # per <= $script:PimSqlRowBatchSize rows (Invoke-PimSqlEntityRowBatchTx): same rows, same journal rows, same
        # single transaction, a constant number of round trips. Two rows with one key: the LAST wins (as before).
        $submitted = @{}; $written = 0
        $plan = New-Object 'System.Collections.Specialized.OrderedDictionary' ([StringComparer]::OrdinalIgnoreCase)
        foreach ($r in @($Rows)) {
            $k = Get-PimStoreRowKey -Base $base -Row $r
            if (-not $k) { continue }
            $submitted[$k] = $true
            $json = if ($null -ne $r) { $r | ConvertTo-Json -Depth 12 -Compress } else { '{}' }
            if ($currentJson.ContainsKey($k) -and [string]::Equals($currentJson[$k], $json, [StringComparison]::Ordinal)) { if ($plan.Contains($k)) { $plan.Remove($k) }; continue }
            # CONFIG-1.1: every written row gets its journal row in the same transaction (a failure rolls the whole set back).
            $item = [ordered]@{ k = $k; op = $(if ($currentJson.ContainsKey($k)) { 'Modify' } else { 'Add' }); d = $json; b = $(if ($currentJson.ContainsKey($k)) { $currentJson[$k] } else { $null }) }
            if ($plan.Contains($k)) { $plan[$k] = $item } else { $plan.Add($k, $item) }
        }
        $written = $plan.Count

        # 🔴 AN EMPTY SUBMISSION AGAINST A NON-EMPTY ENTITY IS A WIPE, AND IT ARRIVES BY ACCIDENT.
        # -Rows defaults to @(). This is a FULL-SET REPLACE, so "no rows submitted" means "delete
        # every row of this entity" -- and it would do so transactionally, then return
        # @{ rowCount = 0; removed = <all of them> } as a SUCCESS.
        # 🪤 The way that happens is never someone typing "delete everything": it is an upstream
        # read that failed and returned nothing (a Graph throttle, an empty CSV, a caught exception
        # yielding @()). Set-PimManagerAccess.ps1 already carries this exact lesson for the access
        # model -- "A read failure is FATAL, never 'nothing was stored'" -- but the general row
        # store, which holds every assignment and definition in the product, had no such guard.
        # 🔒 So: submitting NOTHING while the store holds SOMETHING is refused unless the caller
        # says it means it. Rolls back, changes nothing, and names the entity. (R8: "dont delete
        # sql ... this is production".)
        if (-not $submitted.Count -and $currentKeys.Count -and -not $AllowEmpty) {
            throw ("Set-PimSqlEntityRowsTransactional: refusing to delete all $($currentKeys.Count) row(s) of " +
                   "'$Entity' because NO rows were submitted. A full-set replace with an empty set is " +
                   "almost always a failed upstream read, not an intent to clear the entity. " +
                   'Pass -AllowEmpty if you genuinely mean to empty it.')
        }
        # 3) delete dropped keys (after the upserts, journaled in that order -- as before).
        $removed = 0
        $items = New-Object System.Collections.Generic.List[object]
        foreach ($v in $plan.Values) { $items.Add($v) }
        foreach ($ck in $currentKeys) {
            if (-not $submitted.ContainsKey($ck)) { $items.Add([ordered]@{ k = $ck; op = 'Remove'; d = $null; b = $currentJson[$ck] }); $removed++ }
        }
        $batches = Invoke-PimSqlEntityRowBatchTx -Connection $c -Transaction $tx -Entity $Entity -Items @($items.ToArray()) -FailAfter $FailAfter

        $tx.Commit()
        $rt = -1; $rtWhy = ''
        try {
            $st = $c.RetrieveStatistics()
            $rtv = $null; foreach ($sk in @($st.Keys)) { if ("$sk" -eq 'ServerRoundtrips') { $rtv = $st[$sk] } }
            if ($null -ne $rtv) { $rt = [int]$rtv } else { $rtWhy = "no ServerRoundtrips in the statistics ($(@($st.Keys) -join ','))" }
        } catch { $rt = -1; $rtWhy = "$($_.Exception.Message)" }
        if ($statsErr) { $rtWhy = "statistics could not be enabled: $statsErr; $rtWhy" }
        # commands = statements sent on this connection after the open: the read + one per batch (+ begin/commit by the driver)
        return @{ rowCount = $submitted.Count; removed = $removed; written = $written; batches = [int]$batches; commands = 1 + [int]$batches; roundTrips = $rt; roundTripsNote = $rtWhy }
    } catch {
        if ($tx) { try { $tx.Rollback() } catch { Write-Warning "  [sql] transaction rollback failed: $($_.Exception.Message)" } }
        throw
    } finally {
        # 🔴 §52.18 -- DISPOSE, NOT JUST CLOSE. `Close()` returns the connection to the pool;
        # `Dispose()` is what releases it deterministically instead of waiting for a finalizer.
        # Across this file there were 8 opens, 6 closes and ZERO disposes, so a run that threw --
        # or simply ran long -- accumulated sessions. Measured at a live customer 2026-09-09: a
        # CSV import died halfway with "The session limit for the database is 300 and has been
        # reached" on a Basic-tier database, after that morning's deploys, the Manager and the
        # tick job had each left sessions behind.
        if ($c) { $c.Close(); $c.Dispose() }
    }
}

# --- UPSERT-ONLY: add or update by key, NEVER delete (REQ-G) --------------------
# The full-set replace above is right for a grid save (the grid IS the whole set). An IMPORT is not the whole
# set: a row the Manager added after go-live is not in the file, and must survive. These three are the store's
# upsert-only path, so an importer does not have to carry a private MERGE of its own (Migrate-PimToSql did).

function Compare-PimSqlRowContent {
    # PURE. Does row A say exactly what row B says? Every column of either side is compared as text (a column one
    # side lacks reads as blank), so a value the store holds that the new row does not carry is a DIFFERENCE --
    # overwriting would drop it. pwsh 7's ConvertFrom-Json turns an ISO date into a [datetime]; the two are equal
    # when they are the same instant. A dictionary is compared by its keys, like an object's properties.
    # Returns @() when equal, else @( @{ column; file; store } ) ('file' = -FileRow, 'store' = -StoreRow).
    # (The algorithm Migrate-PimToSql's REQ-G import compared rows with; it moved here with the upsert.)
    param([Parameter(Mandatory)][object]$FileRow, [Parameter(Mandatory)][object]$StoreRow)
    if ($FileRow -is [System.Collections.IDictionary]) { $FileRow = [pscustomobject]$FileRow }
    if ($StoreRow -is [System.Collections.IDictionary]) { $StoreRow = [pscustomobject]$StoreRow }
    $names = [ordered]@{}
    foreach ($p in @($FileRow.PSObject.Properties) + @($StoreRow.PSObject.Properties)) { if (-not $names.Contains($p.Name.ToLowerInvariant())) { $names[$p.Name.ToLowerInvariant()] = $p.Name } }
    $diff = New-Object System.Collections.Generic.List[object]
    foreach ($n in @($names.Values)) {
        $a = $FileRow.PSObject.Properties[$n]; $b = $StoreRow.PSObject.Properties[$n]
        $av = if ($a -and $null -ne $a.Value) { $a.Value } else { '' }
        $bv = if ($b -and $null -ne $b.Value) { $b.Value } else { '' }
        if ($bv -is [datetime] -or $av -is [datetime]) {
            $ad = $av; $bd = $bv
            try { if ($ad -isnot [datetime]) { $ad = [datetime]::Parse("$ad", [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::RoundtripKind) } } catch { $ad = $null }
            try { if ($bd -isnot [datetime]) { $bd = [datetime]::Parse("$bd", [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::RoundtripKind) } } catch { $bd = $null }
            if ($null -ne $ad -and $null -ne $bd -and $ad.ToUniversalTime() -eq $bd.ToUniversalTime()) { continue }
        }
        if ("$av" -cne "$bv") { $diff.Add([ordered]@{ column = $n; file = "$av"; store = "$bv" }) | Out-Null }
    }
    return @($diff.ToArray())
}

function Get-PimSqlMergePlan {
    <#
      PURE. What an upsert-only write of -Rows / -Items would do to an entity that already holds -Existing.
        -Rows      rows, keyed by Get-PimStoreRowKey -Base (a row with no derivable key is skipped + counted)
        -Items     @( @{ key; row } ), already keyed by the caller (used instead of -Rows when given)
        -Existing  @( @{ key; row } ), the entity's stored rows (row = parsed DataJson)
      Keys match case-insensitively; two submitted rows with one key COLLAPSE to the last (counted), as the store
      itself would keep them. Per key:
        not stored                        -> add
        stored, same content              -> unchanged (not written)
        stored, DIFFERENT content         -> a key CONFLICT, decided by -OnKeyConflict:
                                             Overwrite -> update (written under the STORED key's spelling)
                                             KeepExisting -> kept (the store's row stays)
                                             Refuse -> listed in conflicts; Merge-PimSqlEntityRows then writes NOTHING
      Nothing is ever planned for a stored key that was not submitted: there is no delete in this plan.
      Returns @{ add; update; unchanged; kept; conflicts; skippedNoKey; collapsed } (lists of @{ key; row [; columns] }).
    #>
    param(
        [string]$Base,
        [AllowEmptyCollection()][object[]]$Rows = @(),
        [AllowEmptyCollection()][object[]]$Items,
        [AllowEmptyCollection()][object[]]$Existing = @(),
        [ValidateSet('Refuse','KeepExisting','Overwrite')][string]$OnKeyConflict = 'Overwrite'
    )
    $skippedNoKey = 0
    $sub = [ordered]@{}; $nSub = 0
    if ($PSBoundParameters.ContainsKey('Items')) {
        foreach ($it in @($Items)) {
            if ($null -eq $it) { continue }
            $k = "$($it.key)".Trim()
            if (-not $k) { $skippedNoKey++; continue }
            $sub[$k.ToLowerInvariant()] = @{ key = "$($it.key)"; row = $it.row }; $nSub++
        }
    } else {
        if (-not "$Base".Trim()) { throw 'Get-PimSqlMergePlan: -Base is required to key -Rows (or pass -Items already keyed).' }
        foreach ($r in @($Rows)) {
            if ($null -eq $r) { continue }
            $k = Get-PimStoreRowKey -Base $Base -Row $r
            if (-not $k) { $skippedNoKey++; continue }
            $sub[$k.ToLowerInvariant()] = @{ key = $k; row = $r }; $nSub++
        }
    }
    $have = @{}
    foreach ($e in @($Existing)) { if ($null -ne $e -and "$($e.key)") { $have["$($e.key)".ToLowerInvariant()] = $e } }
    $add = New-Object System.Collections.Generic.List[object]; $upd = New-Object System.Collections.Generic.List[object]
    $same = New-Object System.Collections.Generic.List[object]; $kept = New-Object System.Collections.Generic.List[object]
    $conf = New-Object System.Collections.Generic.List[object]
    foreach ($lk in @($sub.Keys)) {
        $s = $sub[$lk]
        if (-not $have.ContainsKey($lk)) { $add.Add(@{ key = $s.key; row = $s.row }) | Out-Null; continue }
        $cur = $have[$lk]
        $rowObj = if ($null -ne $s.row) { $s.row } else { [pscustomobject]@{} }
        $curObj = if ($null -ne $cur.row) { $cur.row } else { [pscustomobject]@{} }
        $d = @(Compare-PimSqlRowContent -FileRow $rowObj -StoreRow $curObj)
        if (-not $d.Count) { $same.Add(@{ key = "$($cur.key)"; row = $s.row }) | Out-Null; continue }
        $one = @{ key = "$($cur.key)"; row = $s.row; columns = $d }
        switch ($OnKeyConflict) {
            'Overwrite'    { $upd.Add($one) | Out-Null }
            'KeepExisting' { $kept.Add($one) | Out-Null }
            default        { $conf.Add($one) | Out-Null }
        }
    }
    return @{
        add = @($add.ToArray()); update = @($upd.ToArray()); unchanged = @($same.ToArray()); kept = @($kept.ToArray())
        conflicts = @($conf.ToArray()); skippedNoKey = $skippedNoKey; collapsed = ($nSub - $sub.Count)
    }
}

function Merge-PimSqlEntityRows {
    <#
      UPSERT-ONLY, TRANSACTIONAL write of an entity's rows (REQ-G) -- Set-PimSqlEntityRowsTransactional WITHOUT
      its delete half. A stored key that is not submitted is NEVER touched, so an import cannot remove a row the
      Manager added after go-live, and there is no empty-set guard to need: submitting nothing changes nothing.
      ONE connection, ONE transaction per entity (§52.18b: one session per entity, not per row): the stored rows
      are read inside the transaction (UPDLOCK, HOLDLOCK -- nobody changes them between the compare and the
      write), classified by Get-PimSqlMergePlan, and the adds + updates are MERGEd -- the same statement the
      replace uses. A failure rolls the entity back whole.
        -OnKeyConflict  a submitted key the store already holds with DIFFERENT content:
                          Overwrite (default -- a plain upsert) = the submitted row wins;
                          KeepExisting = the store's row stays, counted as kept;
                          Refuse = THROW and roll back: nothing of this entity is written, and the keys are named.
      Returns @{ submitted; added; updated; unchanged; kept; skippedNoKey; collapsed; conflicts }.
      -FailAfter: TEST SEAM ONLY (as in the replace) -- throw after N writes to prove the rollback.
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [Parameter(Mandatory)][string]$Entity,
        [AllowEmptyCollection()][object[]]$Rows = @(),
        [AllowEmptyCollection()][object[]]$Items,
        [string]$Base,
        [ValidateSet('Refuse','KeepExisting','Overwrite')][string]$OnKeyConflict = 'Overwrite',
        [int]$FailAfter = -1
    )
    $base = if ("$Base".Trim()) { $Base } else { $Entity }
    $hasItems = $PSBoundParameters.ContainsKey('Items')
    $nIn = if ($hasItems) { @($Items | Where-Object { $null -ne $_ }).Count } else { @($Rows | Where-Object { $null -ne $_ }).Count }
    if (-not $nIn) { return @{ submitted = 0; added = 0; updated = 0; unchanged = 0; kept = 0; skippedNoKey = 0; collapsed = 0; conflicts = @() } }
    $c = New-PimSqlConnection -ConnectionString $ConnectionString
    $tx = $null
    try {
        $c.Open()
        $tx = $c.BeginTransaction()
        $curCmd = $c.CreateCommand(); $curCmd.Transaction = $tx
        $curCmd.CommandText = "SELECT [Key], DataJson FROM pim.Rows WITH (UPDLOCK, HOLDLOCK) WHERE Entity=@e"
        [void]$curCmd.Parameters.AddWithValue('@e', $Entity)
        $rd = $curCmd.ExecuteReader(); $raw = New-Object System.Collections.Generic.List[object]
        try { while ($rd.Read()) { $raw.Add(@{ key = "$($rd.GetValue(0))"; json = $(if ($rd.IsDBNull(1)) { '' } else { "$($rd.GetValue(1))" }) }) } } finally { $rd.Close() }
        # parsed AFTER the reader is closed (one connection = one open reader); a row that will not parse THROWS --
        # an unreadable stored row is not "different", and must not be overwritten on a guess
        $existing = @($raw.ToArray() | ForEach-Object { @{ key = $_.key; row = $(if ("$($_.json)".Trim()) { $_.json | ConvertFrom-Json } else { [pscustomobject]@{} }) } })
        $planArgs = @{ Base = $base; Existing = $existing; OnKeyConflict = $OnKeyConflict }
        if ($hasItems) { $planArgs['Items'] = @($Items) } else { $planArgs['Rows'] = @($Rows) }
        $plan = Get-PimSqlMergePlan @planArgs
        if (@($plan.conflicts).Count) {
            $names = @($plan.conflicts | Select-Object -First 5 | ForEach-Object { "'$($_.key)' ($(@($_.columns | ForEach-Object { $_.column }) -join ', '))" }) -join '; '
            throw ("Merge-PimSqlEntityRows: {0} key conflict(s) in '{1}' -- the store holds these keys with DIFFERENT content: {2}{3}. -OnKeyConflict Refuse: NOTHING of this entity was written." -f `
                   @($plan.conflicts).Count, $Entity, $names, $(if (@($plan.conflicts).Count -gt 5) { ' ...' } else { '' }))
        }
        $mergeSql = @"
MERGE pim.Rows AS t USING (SELECT @e AS Entity, @k AS [Key]) AS s
  ON t.Entity = s.Entity AND t.[Key] = s.[Key]
WHEN MATCHED THEN UPDATE SET DataJson = @d, UpdatedUtc = SYSUTCDATETIME()
WHEN NOT MATCHED THEN INSERT (Entity, [Key], DataJson, UpdatedUtc) VALUES (@e, @k, @d, SYSUTCDATETIME());
"@
        $n = 0
        $beforeByKey = @{}; foreach ($x in $raw) { $beforeByKey["$($x.key)"] = "$($x.json)" }
        foreach ($it in @($plan.add) + @($plan.update)) {
            $cmd = $c.CreateCommand(); $cmd.Transaction = $tx; $cmd.CommandText = $mergeSql
            $d = if ($null -ne $it.row) { $it.row | ConvertTo-Json -Depth 12 -Compress } else { '{}' }
            [void]$cmd.Parameters.AddWithValue('@e', $Entity)
            [void]$cmd.Parameters.AddWithValue('@k', "$($it.key)")
            [void]$cmd.Parameters.AddWithValue('@d', $d)
            [void]$cmd.ExecuteNonQuery()
            # CONFIG-1.1: journaled in the same transaction.
            if ($beforeByKey.ContainsKey("$($it.key)")) { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity $Entity -Key "$($it.key)" -Op Modify -BeforeJson $beforeByKey["$($it.key)"] -AfterJson $d }
            else { Add-PimCommitJournalRowTx -Connection $c -Transaction $tx -Entity $Entity -Key "$($it.key)" -Op Add -BeforeJson $null -AfterJson $d }
            $n++
            if ($FailAfter -ge 0 -and $n -ge $FailAfter) { throw "injected mid-commit failure after $n statement(s) (test seam)" }
        }
        $tx.Commit()
        return @{
            submitted = (@($plan.add).Count + @($plan.update).Count + @($plan.unchanged).Count + @($plan.kept).Count)
            added = @($plan.add).Count; updated = @($plan.update).Count; unchanged = @($plan.unchanged).Count; kept = @($plan.kept).Count
            skippedNoKey = [int]$plan.skippedNoKey; collapsed = [int]$plan.collapsed; conflicts = @()
        }
    } catch {
        if ($tx) { try { $tx.Rollback() } catch { Write-Warning "  [sql] transaction rollback failed: $($_.Exception.Message)" } }
        throw
    } finally {
        if ($c) { $c.Close(); $c.Dispose() }
    }
}

# --- settings live in SQL (protected), not a readable JSON file -----------------
# A hacker reading the JSON must not learn/modify the naming convention or policy.
# The file is only an INITIAL SEED; ongoing management is in pim.Settings.
function Get-PimSqlSetting {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Name)
    $j = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql "SELECT ValueJson FROM pim.Settings WHERE Name=@n" -Parameters @{ n = $Name }
    if ($null -eq $j -or "$j".Trim() -eq '') { return $null }
    try { return ($j | ConvertFrom-Json) } catch { return "$j" }
}

function Set-PimSqlSetting {
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Name, [object]$Value,
          # IMP-39: the value ALREADY serialised. `$Value | ConvertTo-Json` UNROLLS an array through the
          # pipeline, so a one-element list was stored as a bare string and an empty list as NULL -- a
          # value that must be a JSON ARRAY (pim.Settings['BreakGlassAccounts']) needs the exact text.
          [string]$ValueJson)
    $json = if ($PSBoundParameters.ContainsKey('ValueJson')) { $ValueJson }
            elseif ($null -ne $Value) { $Value | ConvertTo-Json -Depth 12 -Compress } else { $null }
    # 🔴 §70.8 (2026-09-13) -- WRITE ONLY WHAT CHANGED. Every save rewrote the whole value, changed or not.
    # On internal's Basic database the transaction log write rate is capped, and this MERGE averaged 5.9 s
    # (max 8 s, 396 runs in ~12 h; LOG_RATE_GOVERNOR the top wait at 2,152 s) -- mostly JobRunHistory
    # (1.98 MB) plus values such as the 145 KB AzResPolicyMassHold re-saved unchanged every tick.
    # The compare is BYTE-exact (varbinary): the database collation is case-insensitive and ignores trailing
    # spaces, so a plain `<>` would silently skip a real change. An unchanged save now writes no log and does
    # not bump UpdatedUtc (so it also stops looking like a change to anything polling pim.Settings).
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
MERGE pim.Settings AS t USING (SELECT @n AS Name, @v AS V) AS s ON t.Name = s.Name
WHEN MATCHED AND (   (t.ValueJson IS NULL AND s.V IS NOT NULL)
                  OR (t.ValueJson IS NOT NULL AND s.V IS NULL)
                  OR CAST(t.ValueJson AS VARBINARY(MAX)) <> CAST(s.V AS VARBINARY(MAX)))
    THEN UPDATE SET ValueJson=s.V, UpdatedUtc=SYSUTCDATETIME()
WHEN NOT MATCHED THEN INSERT (Name, ValueJson, UpdatedUtc) VALUES (@n, @v, SYSUTCDATETIME());
"@ -Parameters @{ n = $Name; v = $json })
}

# --- audit trail in SQL (SEC-16 / §36.2) ----------------------------------------
# APPEND-ONLY by intent. There is deliberately no update or delete helper here: the value of an
# audit trail is that it cannot be tidied, and the easiest way to keep a capability from being
# used by accident is not to write it. Retention is a policy decision for §36.3, not an ad-hoc
# DELETE somebody reaches for at 2am.
function Write-PimSqlAuditEvent {
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [Parameter(Mandatory)][string]$Actor,
        [Parameter(Mandatory)][string]$Action,
        [Parameter(Mandatory)][string]$Target,
        [string]$ActorSource = '',
        [string]$RunId = '',
        [string]$CorrelationId = '',
        [object]$Before = $null,
        [object]$After = $null,
        [string]$Result = 'ok',
        [bool]$WhatIf = $false,
        # §36.3 phase 1b -- an IMPORT of the retired file trail must keep each event's ORIGINAL
        # time. Left unbound, Ts stays on its DF_PimAudit_Ts default (SYSUTCDATETIME()), which is
        # what every live write wants; binding it to "now" for an import would stamp the whole
        # imported history with the minute somebody ran the importer and destroy the ordering
        # that makes the trail evidence. Only the importer passes this.
        [datetime]$Ts
    )
    $b = if ($null -ne $Before) { $Before | ConvertTo-Json -Depth 8 -Compress } else { $null }
    $a = if ($null -ne $After)  { $After  | ConvertTo-Json -Depth 8 -Compress } else { $null }
    $cols = 'RunId, CorrelationId, Actor, ActorSource, Action, Target, BeforeJson, AfterJson, Result, WhatIf'
    $vals = '@run, @corr, @actor, @asrc, @action, @target, @before, @after, @result, @whatif'
    $p = @{
        run = $RunId; corr = $CorrelationId; actor = $Actor; asrc = $ActorSource
        action = $Action; target = $Target; before = $b; after = $a
        result = $Result; whatif = [int][bool]$WhatIf
    }
    if ($PSBoundParameters.ContainsKey('Ts')) {
        $cols = 'Ts, ' + $cols; $vals = '@ts, ' + $vals; $p['ts'] = $Ts.ToUniversalTime()
    }
    [void](Invoke-PimSqlNonQuery -ConnectionString $ConnectionString -Sql @"
INSERT INTO pim.AuditEvents ($cols)
VALUES ($vals);
"@ -Parameters $p)
}

function Get-PimSqlAuditEvents {
    <#
      Read the trail newest-first, shaped EXACTLY like the jsonl reader's records so
      Select-PimAuditEvents / Get-PimAuditChangeSummary keep working unchanged -- the point of
      moving the store is not to rewrite the query layer.
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [datetime]$FromUtc, [datetime]$ToUtc,
        [int]$Top = 5000,
        # BUG-264: -Actions narrows to exact action names IN SQL (the commit page asks for config saves only); -NoPayload
        # leaves BeforeJson/AfterJson unread and unparsed (the Audit tab fills them for the page it shows, by `id`).
        [string[]]$Actions,
        [switch]$NoPayload
    )
    $where = @(); $p = @{}
    if ($PSBoundParameters.ContainsKey('FromUtc')) { $where += 'Ts >= @f'; $p['f'] = $FromUtc }
    if ($PSBoundParameters.ContainsKey('ToUtc'))   { $where += 'Ts <= @t'; $p['t'] = $ToUtc }
    $acts = @(@($Actions) | Where-Object { "$_".Trim() } | ForEach-Object { "$_".Trim() } | Select-Object -Unique)
    if ($acts.Count) {
        $names = for ($i = 0; $i -lt $acts.Count; $i++) { $p["a$i"] = $acts[$i]; "@a$i" }
        $where += ('Action IN (' + (@($names) -join ',') + ')')
    }
    $w = if ($where.Count) { 'WHERE ' + ($where -join ' AND ') } else { '' }
    if ($Top -lt 1) { $Top = 1 }
    $payloadCols = if ($NoPayload) { '' } else { ', BeforeJson, AfterJson' }
    $rows = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql @"
SELECT TOP ($Top) Id, Ts, RunId, CorrelationId, Actor, ActorSource, Action, Target$payloadCols, Result, WhatIf
FROM pim.AuditEvents $w ORDER BY Ts DESC, Id DESC;
"@ -Parameters $p)
    $out = New-Object System.Collections.Generic.List[object]
    foreach ($r in $rows) {
        $before = $null; $after = $null
        if (-not $NoPayload) {
            if ("$($r.BeforeJson)".Trim()) { try { $before = $r.BeforeJson | ConvertFrom-Json } catch { $before = "$($r.BeforeJson)" } }
            if ("$($r.AfterJson)".Trim())  { try { $after  = $r.AfterJson  | ConvertFrom-Json } catch { $after  = "$($r.AfterJson)" } }
        }
        $out.Add([pscustomobject]@{
            id = "$($r.Id)"
            # Ts is stored UTC (SYSUTCDATETIME) but comes back Kind=Unspecified, which
            # ToUniversalTime() treats as LOCAL -- shifting every event by the host's offset.
            ts = [datetime]::SpecifyKind([datetime]$r.Ts, [System.DateTimeKind]::Utc).ToString('o')
            runId = "$($r.RunId)"; correlationId = "$($r.CorrelationId)"
            actor = "$($r.Actor)"; actorSource = "$($r.ActorSource)"
            action = "$($r.Action)"; target = "$($r.Target)"
            before = $before; after = $after
            result = "$($r.Result)"; whatIf = [bool]$r.WhatIf
        })
        # -NoPayload: no before/after AT ALL (not $null) -- "not read" must not look like "recorded as empty"
        if ($NoPayload) { $o = $out[$out.Count - 1]; [void]$o.PSObject.Properties.Remove('before'); [void]$o.PSObject.Properties.Remove('after') }
    }
    # 🪤 `.ToArray()`, NOT `@($out)`. Wrapping a System.Collections.Generic.List[object] in @()
    # throws "Argument types do not match" on BOTH Windows PowerShell 5.1 and pwsh 7, empty or
    # not (an ArrayList is unaffected). Measured 2026-08-31.
    # 🔑 CORRECTED 2026-09-12 -- this note used to say "and even for a list of plain strings",
    # which is FALSE and would send a reader to rewrite correct code. Re-measured on both hosts:
    # List[object] throws; List[string], List[int], List[psobject] and List[hashtable] do not.
    # It is the declared ELEMENT TYPE that decides, never the contents -- a List[object] holding
    # only strings still throws, and a List[string] never does.
    # 🪤 The same note also claimed "nothing else in this solution hits it". It has since been hit
    # TWICE more (/api/approvals and /api/admin-accounts, the latter a live 500 that took out the
    # whole Admin accounts screen), which is why the guard is now mechanical:
    # tests/Test-PimListWrapTrap.ps1 scans every shipped script.
    return $out.ToArray()
}

function Read-PimSqlAuditEventPayloads {
    <#
      BUG-264 -- the other half of Get-PimSqlAuditEvents -NoPayload: read BeforeJson/AfterJson for just these events (by
      their `id`) and set .before / .after on them, parsed exactly as the full read parses them. One query per call.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString, [object[]]$Events = @())
    $byId = @{}
    foreach ($e in @($Events)) { if ($null -ne $e -and "$($e.id)" -match '^\d+$') { $byId["$($e.id)"] = $e } }
    if ($byId.Count -eq 0) { return }
    $p = @{}; $i = 0
    $names = foreach ($k in @($byId.Keys)) { $p["i$i"] = [long]$k; "@i$i"; $i++ }
    $rows = @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql ("SELECT Id, BeforeJson, AfterJson FROM pim.AuditEvents WHERE Id IN (" + (@($names) -join ',') + ");") -Parameters $p)
    foreach ($r in $rows) {
        $e = $byId["$($r.Id)"]; if ($null -eq $e) { continue }
        $before = $null; $after = $null
        if ("$($r.BeforeJson)".Trim()) { try { $before = $r.BeforeJson | ConvertFrom-Json } catch { $before = "$($r.BeforeJson)" } }
        if ("$($r.AfterJson)".Trim())  { try { $after  = $r.AfterJson  | ConvertFrom-Json } catch { $after  = "$($r.AfterJson)" } }
        $e | Add-Member -NotePropertyName before -NotePropertyValue $before -Force
        $e | Add-Member -NotePropertyName after -NotePropertyValue $after -Force
    }
}

function Get-PimSqlAuditMonthCount {
    <#
      How many distinct calendar months the trail spans. The file-based reader answered this by
      counting monthly FILES; with SQL there are no files, and "0 months of history" would make
      the Audit tab's window selector claim the trail is empty when it is not.
    #>
    param([Parameter(Mandatory)][string]$ConnectionString)
    $n = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql @"
SELECT COUNT(*) FROM (SELECT DISTINCT YEAR(Ts) AS y, MONTH(Ts) AS m FROM pim.AuditEvents) AS x;
"@
    $i = 0; [void][int]::TryParse("$n", [ref]$i)
    return $i
}

# --- atomic compare-and-set, for the scheduler's single-runner lease (BUG-36) ----
# Set-PimSqlSetting above is an unconditional MERGE: read-then-write with it is NOT atomic, so
# two runners can both read "lease free" and both write, which is the exact double-apply the
# lease exists to prevent. These two give a real CAS.
function Get-PimSqlSettingRaw {
    # The value EXACTLY as stored, unparsed. CAS compares bytes, so it must not round-trip
    # through ConvertFrom-Json/ConvertTo-Json -- that can change formatting and break the compare.
    param([Parameter(Mandatory)][string]$ConnectionString, [Parameter(Mandatory)][string]$Name)
    $j = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql "SELECT ValueJson FROM pim.Settings WHERE Name=@n" -Parameters @{ n = $Name }
    if ($null -eq $j -or $j -is [DBNull]) { return $null }
    return "$j"
}

function Set-PimSqlSettingIfUnchanged {
    <#
      Write $NewValueJson to $Name ONLY IF the stored value is still $ExpectedValueJson
      (pass $null to mean "expected absent-or-null"). Returns the number of rows written:
      1 = we won, 0 = someone else got there first.

      The row is PRIMARY KEY on Name, so two racers taking the insert path collide on the key --
      that duplicate-key failure IS the correct answer (we lost) and is caught, not thrown.

      🪤 BUG-41 -- READ THIS BEFORE CHANGING THE NULL HANDLING BELOW.
      These parameters are typed [string], and PowerShell coerces a $null argument to
      [string]::Empty at the parameter boundary. So `-ExpectedValueJson $null` -- which every
      caller uses to mean "expected absent" -- arrived here as '', the function's own
      `$null -ne $ExpectedValueJson` test read TRUE, and it bound @e='' instead of DBNull.
      `IF @e IS NULL` was then FALSE, so the batch took the ELSE branch and ran
      `UPDATE ... WHERE ValueJson=@e`, which matches nothing when the row is absent. The INSERT
      branch -- the ONLY one that can create the row -- was unreachable, so the function returned
      0 forever and the scheduler lease could never be acquired on a fresh store. Measured live
      2026-08-09: two ticks 'Succeeded', both logged "another runner holds the lease", and
      pim.Settings held 0 rows. Nullness is therefore decided with IsNullOrEmpty, NOT with
      `-ne $null`, and that is not a style choice -- `-ne $null` cannot work through a [string]
      parameter. (An empty string is not a meaningful stored value here either: a real value is
      JSON, and Get-PimSqlSettingRaw already returns $null for a NULL column.)
    #>
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [Parameter(Mandatory)][string]$Name,
        [string]$NewValueJson,
        [string]$ExpectedValueJson
    )
    $sql = @"
SET NOCOUNT ON;
DECLARE @affected INT = 0;
IF @e IS NULL
BEGIN
    UPDATE pim.Settings SET ValueJson=@v, UpdatedUtc=SYSUTCDATETIME()
      WHERE Name=@n AND ValueJson IS NULL;
    SET @affected = @@ROWCOUNT;
    IF @affected = 0
    BEGIN
        INSERT INTO pim.Settings (Name, ValueJson, UpdatedUtc)
        SELECT @n, @v, SYSUTCDATETIME()
          WHERE NOT EXISTS (SELECT 1 FROM pim.Settings WHERE Name=@n);
        SET @affected = @@ROWCOUNT;
    END
END
ELSE
BEGIN
    UPDATE pim.Settings SET ValueJson=@v, UpdatedUtc=SYSUTCDATETIME()
      WHERE Name=@n AND ValueJson=@e;
    SET @affected = @@ROWCOUNT;
END
SELECT @affected;
"@
    try {
        $r = Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql $sql -Parameters @{
            n = $Name
            # IsNullOrEmpty, not `-ne $null` -- see BUG-41 in the comment block above. `v` gets the
            # same treatment because Remove-PimSchedulerLease releases by passing -NewValueJson
            # $null, which by the identical coercion was storing '' instead of NULL.
            v = $(if ([string]::IsNullOrEmpty($NewValueJson))      { [DBNull]::Value } else { $NewValueJson })
            e = $(if ([string]::IsNullOrEmpty($ExpectedValueJson)) { [DBNull]::Value } else { $ExpectedValueJson })
        }
        if ($null -eq $r -or $r -is [DBNull]) { return 0 }
        return [int]$r
    } catch {
        # Duplicate key = another runner inserted first. That is a LOST RACE, not an error.
        if ("$($_.Exception.Message)" -match '(?i)duplicate key|PRIMARY KEY') { return 0 }
        throw
    }
}

function Get-PimAllSqlSettings {
    # All settings as a hashtable Name -> value (JSON-parsed). For loading over the
    # file seed into $global:PIM_NamingConventions at boot.
    param([Parameter(Mandatory)][string]$ConnectionString)
    $out = @{}
    foreach ($r in @(Invoke-PimSqlQuery -ConnectionString $ConnectionString -Sql "SELECT Name, ValueJson FROM pim.Settings")) {
        $v = if ("$($r.ValueJson)".Trim()) { try { $r.ValueJson | ConvertFrom-Json } catch { "$($r.ValueJson)" } } else { $null }
        $out["$($r.Name)"] = $v
    }
    return $out
}

function Import-PimSettingsSeed {
    # Seed pim.Settings from a setup-file default hashtable -- ONLY keys not already
    # present (so the SQL store, once managed, is never overwritten by the seed).
    param([Parameter(Mandatory)][string]$ConnectionString, [hashtable]$Seed = @{})
    $existing = Get-PimAllSqlSettings -ConnectionString $ConnectionString
    $added = 0
    foreach ($k in @($Seed.Keys)) { if (-not $existing.ContainsKey("$k")) { Set-PimSqlSetting -ConnectionString $ConnectionString -Name "$k" -Value $Seed[$k]; $added++ } }
    return $added
}

function Test-PimSqlConnectivity {
    param([Parameter(Mandatory)][string]$ConnectionString)
    # 🔴 BUG-77 -- THIS USED TO BE `catch { return $false }`, WHICH DISCARDED THE ONLY SENTENCE THAT
    # SAYS WHAT WENT WRONG. Its caller then reports `Preflight FAILED: cannot reach the desired
    # store: no SELECT 1` -- a message that is true of a firewall block, an expired token, a missing
    # contained user, a wrong tenant and an unreachable server alike. Three rebuild/redeploy/run
    # cycles were spent guessing between those on the greenfield slave, because the process was
    # telling us "no" and refusing to say why. A probe that hides the reason is not a probe.
    try { return ((Invoke-PimSqlScalar -ConnectionString $ConnectionString -Sql 'SELECT 1') -eq 1) }
    catch {
        $script:PimSqlLastError = "$($_.Exception.Message)"
        Write-Warning "  [sql] connectivity probe FAILED: $($_.Exception.Message)"
        return $false
    }
}

# --- cold-process settings hydration (the GUI-state == actual-behavior fix) -----
# The Manager hydrates pim.Settings into $global:PIM_NamingConventions at boot, so its
# OWN process honours GUI-saved EmailControls / JobSchedule. But a COLD-booted scheduler
# or a one-shot engine/job run never ran that boot path -- so a kill switch set in the
# GUI would NOT stop a cold scheduled send, and a freshly-booted scheduler would NOT see
# a changed cadence. Get-PimSqlSettingsConnectionString resolves the store CS the same
# way the scheduler tick already does (ambient globals only -- never builds a credential
# out of thin air), and Import-PimSettingsFromStore loads ALL pim.Settings into
# $global:PIM_NamingConventions so Get-PimPolicySetting (engine/scheduler reader) resolves
# the persisted values in ANY process. FAIL-SAFE: a read failure leaves whatever was
# already configured untouched (it never CLEARS an existing kill switch and never
# fails-open to sending more than configured). REQUIREMENTS s29.
function Get-PimSqlSettingsConnectionString {
    # Best-effort store CS for a cold process. Mirrors Invoke-PimSchedulerTick's resolver:
    # an explicit in-memory CS wins; else build from ambient SQL globals ONLY when one is
    # actually configured (so a bare default never fabricates a connection). Returns $null
    # when no store is configured -- the caller then leaves settings as-is (fail-safe).
    if ("$($global:PIM_SqlConnectionString)".Trim()) { return "$($global:PIM_SqlConnectionString)" }
    $hasSig = ("$($global:PIM_SqlServer)".Trim() -or "$($global:PIM_SqlConnStringVault)".Trim() -or "$($global:PIM_SqlDatabase)".Trim())
    if ($hasSig -and (Get-Command Get-PimSqlConnectionString -ErrorAction SilentlyContinue)) {
        try { return (Get-PimSqlConnectionString) } catch { return $null }
    }
    return $null
}

function Import-PimSettingsFromStore {
    # Load pim.Settings into $global:PIM_NamingConventions (the engine/scheduler reader
    # source -- Get-PimPolicySetting reads it first). Additive: existing keys are
    # overwritten with the persisted value, other globals untouched. Returns the number
    # of settings loaded, or -1 when no store was reachable (so the caller can tell
    # "nothing to load" from "couldn't read" -- both are non-fatal / fail-safe).
    # -ConnectionString overrides the resolver (tests / an already-open CS).
    param([string]$ConnectionString)
    $cs = if ("$ConnectionString".Trim()) { $ConnectionString } else { Get-PimSqlSettingsConnectionString }
    if (-not "$cs".Trim()) { return -1 }
    $loaded = $null
    try { $loaded = Get-PimAllSqlSettings -ConnectionString $cs } catch { Write-Warning "  [settings] hydrate from store failed (leaving current settings unchanged): $($_.Exception.Message)"; return -1 }
    if ($null -eq $loaded) { return -1 }
    if (-not ($global:PIM_NamingConventions -is [hashtable])) { $global:PIM_NamingConventions = @{} }
    $n = 0
    foreach ($k in @($loaded.Keys)) { $global:PIM_NamingConventions[$k] = $loaded[$k]; $n++ }
    # 🔴 REQ-T (2.4.377): THE TENANT'S OWN NAMING NEVER REACHED THE ENGINE. The Settings page stores every naming key
    # (PimGroupPattern, AdminAccountPattern, AdminAccountUpnSuffix, …) as ONE record, pim.Settings['NamingConventions'],
    # and the loop above put that record under the key 'NamingConventions' -- where Get-PimNamingConvention, which reads
    # flat keys, never looks. So every engine-side name (discovery auto-create, hybrid AD, the admin UPN domain) used the
    # SHIPPED defaults whatever the customer had configured. The Manager flattens the same record
    # (Get-PimManagerNamingSettings); the engine now does too. A key stored as its own setting row still wins.
    $nc = $loaded['NamingConventions']
    if ($nc) {
        $pairs = if ($nc -is [System.Collections.IDictionary]) { @($nc.Keys | ForEach-Object { @{ k = "$_"; v = $nc[$_] } }) }
                 else { @($nc.PSObject.Properties | ForEach-Object { @{ k = $_.Name; v = $_.Value } }) }
        foreach ($p in $pairs) { if ($p.k -and -not $loaded.ContainsKey($p.k)) { $global:PIM_NamingConventions[$p.k] = $p.v } }
    }
    # Apply the EmailControls record to the email globals the notify path reads (the
    # Manager does this in its PUT handler; do it here too so a cold process is covered).
    if ((Get-Command Set-PimEmailControlsGlobals -ErrorAction SilentlyContinue) -and $global:PIM_NamingConventions.ContainsKey('EmailControls')) {
        [void](Set-PimEmailControlsGlobals -EmailControls $global:PIM_NamingConventions['EmailControls'])
    }
    # IMP-06a: the SENDER is not part of the EmailControls record, so the projection above could
    # never carry it -- which is why $global:PIM_MailSender had no persisted path at all and every
    # hosted environment was mail-mute no matter what onboarding did. Project it here so the
    # Manager can change the sender without a container redeploy and a cold-booted tick Job still
    # honours it, overriding the deploy-time env var Invoke-PimEngineCore reads.
    # 🔒 FAIL-SAFE DIRECTION, and it is the opposite of the kill switch's. A missing or BLANK
    # stored value must LEAVE an existing sender alone: clearing it would silently mute a working
    # environment, and muting is the exact failure IMP-06 exists to stop. Only a non-blank value
    # ever writes here. (The kill switch is fail-safe by staying ON; the sender is fail-safe by
    # staying SET.)
    if ($global:PIM_NamingConventions.ContainsKey('MailSender')) {
        $__sender = "$($global:PIM_NamingConventions['MailSender'])".Trim()
        if ($__sender) { $global:PIM_MailSender = $__sender }
    }
    # MAIL-1 (framework 12.3): the TRANSPORT -- MailMode (none | sharedMailbox | smtp) and the SmtpRelay record (no
    # password: that lives in Key Vault). Same fail-safe direction as the sender: only a valid, non-blank value writes.
    if ($global:PIM_NamingConventions.ContainsKey('MailMode') -and (Get-Command ConvertTo-PimMailMode -ErrorAction SilentlyContinue)) {
        $__mode = ConvertTo-PimMailMode -Value $global:PIM_NamingConventions['MailMode']
        if ($__mode) { $global:PIM_MailMode = $__mode }
    }
    if ($global:PIM_NamingConventions.ContainsKey('SmtpRelay') -and $null -ne $global:PIM_NamingConventions['SmtpRelay']) {
        $global:PIM_SmtpRelay = $global:PIM_NamingConventions['SmtpRelay']
    }
    return $n
}

# AUDIT-1.3: the append-only guard + the retention job ride with the store, so every loader of the store has them.
$__auditRet = Join-Path $PSScriptRoot 'PIM-AuditRetention.ps1'
if (Test-Path -LiteralPath $__auditRet) { <# optional load of $__auditRet left out: this file is self-contained #> }
# AUDIT-1 actor: the change attribution rides with the store too.
$__chgAttr = Join-Path $PSScriptRoot 'PIM-ChangeAttribution.ps1'
if (Test-Path -LiteralPath $__chgAttr) { <# optional load of $__chgAttr left out: this file is self-contained #> }
# SEC-80: the managed-key ledger rides with the store too.
$__mgdKeys = Join-Path $PSScriptRoot 'PIM-ManagedKeys.ps1'
if (Test-Path -LiteralPath $__mgdKeys) { <# optional load of $__mgdKeys left out: this file is self-contained #> }
# CONFIG-1.1: the change journal is written BY the store's write functions, so it must ride with the store.
$__cmtJrn = Join-Path $PSScriptRoot 'PIM-CommitJournal.ps1'
if (Test-Path -LiteralPath $__cmtJrn) { <# optional load of $__cmtJrn left out: this file is self-contained #> }
# Framework §12.11f item 2 / PIM 100.144a: the signed-request store is written next to the journal (same transaction) and by
# the change queue's writers, so it rides with the store too. Inert while the mode is off.
if (-not (Get-Command Add-PimSignedRequestRowsForJournalTx -ErrorAction SilentlyContinue)) { $__sgnReq = Join-Path $PSScriptRoot 'PIM-SignedRequests.ps1'; if (Test-Path -LiteralPath $__sgnReq) { <# optional load of $__sgnReq left out: this file is self-contained #> } }
# PIM 96.5: the daily reconcile's removal report + pause / resume ride with the store (the scheduler, the engine and the
# Manager all read them).
$__rcnRem = Join-Path $PSScriptRoot 'PIM-ReconcileRemoval.ps1'
if (Test-Path -LiteralPath $__rcnRem) { <# optional load of $__rcnRem left out: this file is self-contained #> }
# CONFIG-1.3 / PIM §96.3: the configuration backup (pim.ConfigBackups) rides with the store too.
$__cfgBak = Join-Path $PSScriptRoot 'PIM-ConfigBackup.ps1'
if (Test-Path -LiteralPath $__cfgBak) { <# optional load of $__cfgBak left out: this file is self-contained #> }
# CR8 item 1 (PIM 100.152): the commit snapshot table's DDL rides with the store, so the updater's schema step creates it.
if (-not (Get-Command Initialize-PimBackupStore -ErrorAction SilentlyContinue)) { $__cmtBak = Join-Path $PSScriptRoot 'PIM-CommitBackup.ps1'; if (Test-Path -LiteralPath $__cmtBak) { <# optional load of $__cmtBak left out: this file is self-contained #> } }
# Framework §12.23 run 2 (PIM 100.156): the publish job's control-view refresh rides with the store, so the updater's schema
# step runs it (it was run by the Manager at every start -- a CREATE OR ALTER VIEW the web app may not run after run 2).
if (-not (Get-Command Get-PimPublishJobControlViewRefreshSql -ErrorAction SilentlyContinue)) { $__jobCad = Join-Path $PSScriptRoot 'PIM-JobCadence.ps1'; if (Test-Path -LiteralPath $__jobCad) { <# optional load of $__jobCad left out: this file is self-contained #> } }
# Framework §12.23 / PIM 100.156: the activation ledger's DDL rides with the store, so the updater's schema step creates it.
if (-not (Get-Command Get-PimImpactActivationLedgerDdl -ErrorAction SilentlyContinue)) { $__impCnt = Join-Path $PSScriptRoot 'PIM-ImpactCounters.ps1'; if (Test-Path -LiteralPath $__impCnt) { <# optional load of $__impCnt left out: this file is self-contained #> } }
# PIM 100.121: the feature-setting reader rides with the store -- it reads what Import-PimSettingsFromStore hydrates, so
# every process that can hold a stored setting (the engine, the scheduler, the Manager) has the reader for it.
$__featSet = Join-Path $PSScriptRoot 'PIM-FeatureSettings.ps1'
if (Test-Path -LiteralPath $__featSet) { <# optional load of $__featSet left out: this file is self-contained #> }

# ===== END inlined helper: ..\..\engine\_shared\PIM-SqlStore.ps1 =====
# ===== BEGIN inlined helper: ..\..\engine\_shared\PIM-License.ps1 =====
<#
.SYNOPSIS
    PIM4EntraPS offline license verification (Core + Pro split).

.DESCRIPTION
    PIM4EntraPS Community is free for a single tenant. Pro (the licensed single-tenant features, and the
    multi-tenant half: managing tenant / managed tenants) requires a customer licence: the issued signed document,
    stored in SQL pim.Settings[License] (IMP-42 -- no file). REQ-Y: a managing tenant / slave is refused without one.

    The license is FULLY OFFLINE -- no online activation, no call-home, no
    public endpoint. It is a JSON payload signed with the maintainer's private
    RSA key (machine cert store on the management host, never distributed);
    this file embeds only the PUBLIC certificate and verifies the signature
    locally (RSA-SHA256). Customers on locked-down automation servers need
    nothing but the stored document.

    File format (issued by the internal-only New-PimLicense.ps1 -- NOT shipped):
      { "product": "PIM4EntraPS", "payloadB64": "<b64 of payload JSON>", "signature": "<b64 RSA sig>" }
    Payload:
      { licenseId, customer, sku, features[], tenantIds[], validFrom, validTo, graceDays }

    Semantics:
      * Signature is verified over the EXACT payloadB64 bytes (no JSON
        canonicalization pitfalls).
      * tenantIds [] / missing = any tenant; non-empty = the connected tenant
        must be listed (binding is the Entra tenant GUID).
      * features may contain '*' (all Pro features) or explicit names.
      * After validTo, a grace window (graceDays, default 30) keeps Pro
        features working with a warning; after grace they disable. Core is
        NEVER affected by license state.

    PS 5.1 note: certificate is loaded from raw bytes (X509Certificate2), and
    RSA comes via RSACertificateExtensions -- no ImportFromPem (PS 7-only).
#>

# Public certificate of the licensing key (CN=PIM4EntraPS-Licensing).
# The PRIVATE key never leaves the maintainer's machine store.
# LIC-1 (2026-08-11) -- the platform framework licensing signer, CN=the platform-Licensing-Service.
# PIM now accepts BOTH this and its own legacy key below, so licences issued by the framework
# tool (TOOLS/New-AitLicense.ps1) verify here with no cutover and no reissue.
#
# 🔴 WHY THE MIGRATION IS URGENT, not cosmetic: the legacy CN=PIM4EntraPS-Licensing key is marked
# NON-EXPORTABLE, so backup-job-certificates-automation SKIPS it on every run -- verified absent
# from all recent backups. If the build host were lost, no further PIM licence could EVER be issued (already
# issued ones keep verifying, since only the public half ships). The cert is valid to 2041, which
# makes it look safe; exportability is the thing that actually matters and is invisible unless
# checked. This key IS backed up.
$script:AitLicensePublicCertB64 = 'MIIFFzCCAv+gAwIBAgIQNY8l3/KZOoxF7K1nXIXwazANBgkqhkiG9w0BAQsFADAnMSUwIwYDVQQDDBxBdXRvbWF0ZUlULUxpY2Vuc2luZy1TZXJ2aWNlMB4XDTI2MDgxMTEzMDY0NloXDTQ2MDgxMTEzMTE0NlowJzElMCMGA1UEAwwcQXV0b21hdGVJVC1MaWNlbnNpbmctU2VydmljZTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBALuth8WywLfudbaoZ6eR570apvs5LXzOeGfl5Z14z6Nl6DQgvwMLXG/8lZEHOCKsHWVtEnjZOZigsh4c16owJVhuW67OgY0Iy6OjmfeXzu+kcTICSdZ+Qj3ecsGp1Cz6Xo1AjYbgIORdqUBncy4BAuA1bxH0E+V+1zT+ltEk840xpLdWde+m7W8q7BrG9klh+xQl8xJTjeliyV0JN2mvBjI0JwB9t9vL2/luMWWtHp752/ZG4Icd9u6HyqSR/xEmlZIjkZwI7LEPLTICXV1iA3c3nFUEHkLhLlpDW6EQn3cip0Sijr7SVWEBH1fCA8vCo+PxIEgJc3RXaeRhqD4UOwPJIziHtrpy8+9L15zrhXnhIGZv2mUAHKiamUIOmKl9vj31vFp/vJx1chE0XA358T09HGu0jKgSbbC4afKQPKf3v+BHPU42T/xIOPMxDJWuFqKvr4anL7P5PEkTjycBRCkXnIPC5PlrXR/ZZz4oit4WKhbdzONYwb8CKnsF2Z9IVL9yviVJxAIr7kiGqRme9+H0t5A+hzAydxdFMQnop+R8Q02a0sei9WrdtCbwLempVVrXIS6N4hh5kvLqMouDi62b0h645UNk2cWahDIZWTKd/MYdlcdrtRt5muy2LOasHByVxUrZKwH7IetCmv+Kkm1BfMF6Fvi1Jh2Qgz4bo5XJAgMBAAGjPzA9MA4GA1UdDwEB/wQEAwIHgDAMBgNVHRMBAf8EAjAAMB0GA1UdDgQWBBT+IiWP1iqSIwaRLiV1somJAQ+ELjANBgkqhkiG9w0BAQsFAAOCAgEAFiDfl7nhDNIywkCZgu9iw0RtJUyJqiq8y+fXomucqowAQZKPhkpuHftZZjtDe09WM35TqjRgL7hqmJiEgqPlRrAv78FjE41RwMcANN2PVCrdcMcuDVdRbS40rObpp0B6+uVUiWY4+8MW6G8Wv+7CIBUEP8ypo3BhxQJZLpyJDKLNiPqnTVKOmYXe7BivfVz63F2Pg2dNXic1poQ7S6JTi/8FM4AV2Ge/zVQF+LaiIuBDJX3JjHnKXxNf1Zhk8PF6DeWaVSNyXtjESlaUfsz0U2Ue87UUZ8ELIuqjHTpG66HPInblBZme6VvR13n5QxmnvjPXdtmXAJzDzCf+76labSGQu9fMFxUoKwjAwT9vHrdFw8JEStappW7urXj+Oafp1wVafJOXzjd9utr8WT3AhaPeqMx3FYH20e2b7QNCI3owtm0ogHRg36neahe78PikiMe15AUpD3+BD6pKeLV7tsExeXZjxDxhFUSpScD0TrCOUEJdKL2Cfx8rM3ceISSiTTYmuJmU7fznQ122A6GNW58mpSk8miPYb3MzbLW0JFPRrEDiyT8dW1M9s98DL+7VR0z2QxgxhNMKyrVgBM7YgQtbtPLz26NBqAQsqG50rOdn7XmprzvnTmnb+r2PUQuqb6rCTAQFTJ3MjH7BviP3GkwJyvzMZ+S6OnUAGB2Fn3Y='

$script:PimLicensePublicCertB64 = 'MIID+zCCAmOgAwIBAgIQZi8bo4EYqJ9PSvrXsI3orTANBgkqhkiG9w0BAQsFADAgMR4wHAYDVQQDDBVQSU00RW50cmFQUy1MaWNlbnNpbmcwHhcNMjYwNjEyMTY1MzM4WhcNNDEwNjEyMTcwMzM0WjAgMR4wHAYDVQQDDBVQSU00RW50cmFQUy1MaWNlbnNpbmcwggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQD+YFgQSxRJNuwpv/lc9z6ClbFgEc+9/hpM/TXPg7f3Q40TQfyWf54EgaKzC8Y04JkdS2lNv69NWZ5MJgwyHkwTuyngDx/giBF0aVBbnbW9dLixSY0YaN435uylMgrL9irYB79c+rN+NAWyRZTzFdw3LFLR7zhl4Wor3OexsI7tYHgH/WXegzmbl4R8amVHR2QsAr3ZHBg5WEW3C3DeomDeAuVIny4xMZp/nq6i1VXTqrBx76Cxdms6RJS0cwtystrFQFdCB4e06jqdttuj5m8CCvQbUILEzAhNnzHnFtMXJC/wWWu2vfOqqY/Wy7ORjZCWaI/a/c7bfXWpdiI5H3E4pcZCezSH7lg1VdvSGrq/bbQxOUO4a5FQ5JI5fXZuzQksjm7t0u5AAmdLpvtac86vMQmM8LCTsUoNs9GAhVvNmV+pJtReWyubfqLgzaRmMP4qMp7a6DoR3RKeuYjmSzhjFn5S4lcDmAz35Qc/LO0sEPDr3LL30fQxhX8uSqlFAEkCAwEAAaMxMC8wDgYDVR0PAQH/BAQDAgeAMB0GA1UdDgQWBBS2n3cmD8taKDsdy2debDNeQkv7qzANBgkqhkiG9w0BAQsFAAOCAYEArrFYyp4BQzH803d4htpcqtWbkTgg10tFrdQndJ35tv+ZDGcq7AIHohI7egzH4pDPgbXOGf7GuisIzj8MEJkH63+xqB4wHHBPn+pl9YGYk02XiWY9H0blP+TIlYjderzr/XH/mLn67z2VAm9dGAw1X2xw1zMtc36aPVU7i7bRIZwfxIA5Y1sVJ9bpMRkXDawMhegA39a0inLVriBWcvfku3zz84MtHtB4WLfwUI97QLvDObHPdkQ68w+0+0tmIz33z5Fgu9dtIUf6RROkFhjoc2rC+GcI023SLeDPjHrUHg1RjUeoPJkPQiX8N8lSnX335dJddiHIDAn43OhQn13lITovtz5EHiaJJSXr/DwsaZzyv6UC067KpFeKLc4heYiM0A0Orj7UH/B5f/qEu8MPsl+XdBGl7v0lecn2DbG2bXlOxEucP8JNzIeOnLg609XaneGRdu93dFLUGSsNtUMnrhrSWGjqAwXteWhhGy+aJ/WfUdfUGJ+rf/D9hVOBIpsk'

# LIC-4 (operator 2026-10-03): the Invardia licence signer, CN=Invardia-Licensing (BA65E6AA62128EBE89A743722E404980F6D2878D).
# Trusted ALONGSIDE the two signers above, never instead: Invardia switches to it only after this release is rolled out.
# Byte-identical to sync/_AitLicense.ps1 $script:AitLicenseInvardiaCertB64 (tests/Test-PimLicensing.ps1 pins it).
$script:InvardiaLicensePublicCertB64 = 'MIIFQDCCAyigAwIBAgIQXXs1IY0ZQE2MwtugYutXwDANBgkqhkiG9w0BAQsFADAdMRswGQYDVQQDExJJbnZhcmRpYS1MaWNlbnNpbmcwHhcNMjYxMDAzMTY1NDMxWhcNMzYxMDAzMTcwNDMxWjAdMRswGQYDVQQDExJJbnZhcmRpYS1MaWNlbnNpbmcwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCn9X21WYLer9r3ojq9lCP3eGV5YK8UMHoyyGT/q8carwQK+ztBRweKAgHyg8rr67utZ1zZBDRei64T/63nXGZpC666efzNZjIU+Og7vtO0bTNjQm/yVD/Q4KFZachYbE5orU+99HQcgRrcwnmmltyazyun2MV2CTk2nUDeMX5IIFD/1yIT8SLNFa6b6Gy4Ms/TIlc4u3lEH3zjbTSF+phSrbv7J6ytz5Eq1ahRkKHWcdBoF9GJo2ynWP0vTGHWvvjNdeVpXP1rkGnLt9MAQj2Us/2XiTgZzf26QLNiXX9YeJeUA9IVdPWczJav+YYkcICyG4ynwhPCudI6S2iDeu8jyL54gfVT871/+RFebzKHq9teY2vB0aGsbaW9VOmV5dDQ2mVfQLFTkNd1ByeZKv9tR0vPfaiZCza+DedApF2LfoAa7Y34pb9WHGRJFAPVmG2WMSsTY90Y0VBYrktF4g4q712W2ZdQc+QIxtvP5nsz6bk1QBvJ1Hcsr/euiysxmkFxcl3NH7WM1EKzdzUaYDJpysoE9e0jkjdJpb9bNNmSE7V9IMTk7r/XOiYJ+8qOALTgwUIEyOLi/hfOihJDRn31aJ6aPvzCEYikueJV5oALrDxquiXbPi8z10aMuXLL4hfi6B7U0qo2kOTPQ9Qh/cJFVkV9pEXjtY+NwwI9EtxgaQIDAQABo3wwejAOBgNVHQ8BAf8EBAMCB4AwCQYDVR0TBAIwADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwHwYDVR0jBBgwFoAUuZzWkYh3hkE0oJH42LneYVKXIzowHQYDVR0OBBYEFLmc1pGId4ZBNKCR+Ni53mFSlyM6MA0GCSqGSIb3DQEBCwUAA4ICAQCluVZnotzEyS5ux+4hMuz9mOfpSJCNg5nkS8XxIHySiE2AEjVT4ZFEyykZUFoROv5clLBkO5icvDDRBitkeKHvioZruRPtVGy0fs0VxJ4VMcOU/i5cVdJXBQeyUFE8o//4+7FXZp10ToVNv/drjdO7adcNHRVjsddm2mXPNyHmE07ErV6eInPj+r0/1dogPBW1knF+T53RTwT2O0Ppe5qK0QEdBfo5sf4nvjg7ONNXYlW38SzXGLsXy6TZphRWqxLq7u31HAwujQGy9syO+TPIzusH1WHkCsvjDDRXNI8iYhKcS2wq/P/O6O4Ebt/PFN0hxyzyuYx4kreXKKhqrfsEMDxzMUQNnUEjFgU4/4atLVJpBvoDmb/MuQDIzlhxz8obAJi5BuxyjyemR9jg6XMIE2IAhe1v+MN0ZY58tbZR3t5rF30tp541NRaJfn4DBpqNmAIFyDQMdM2FogkFoOV+Mo0IBmGzV/jyv/2z+sre1P5MncLP2qZhfFmu595gWnNoOsMdUZmEWMkbISMGvGzfpPRF3IBan+fymCZSsKNB00E3W50Sh/t2sopEYc3eSwpu6bhvPUgB2ZKU6KN49Al4Pf41uldHVY0aVVp+kpLmRntDFzkTNXUG4OWOwF5gHuGY8jIrwDR7pCPSNzDWrUf857O6DyWEsHXERWg5OPLNUg=='

# Editions: COMMUNITY (free) and PRO (licensed). One engine/manager/activator; Pro
# unlocks the advanced capabilities below. (The free tier was historically called
# 'Core'; it is surfaced as 'Community' now. A licence SKU of 'Core' is NOT Pro --
# REQ-Y 2026-09-20; see the sku match in Test-PimProLicence for why that changed.)
$script:PimCommunityEditionName = 'Community'
$script:PimProEditionName       = 'Pro'

# Catalog of gateable Pro features. SQL data store is deliberately NOT here --
# operator decision 2026-06-12: SQL is part of the free (Community) edition.
# 🔒 REQ-Y (operator 2026-09-19: "single tenant must be sep in free and pro"): the feature catalog
# (engine/_shared/PIM-FeatureCatalog.ps1, license x scope per entry) is the ONE authoritative list. This list is the
# gate's copy (this file is also loaded standalone, without the catalog) and must EQUAL Get-PimCatalogProFeatureNames:
# tests/Test-PimMspLicense.ps1 fails on any drift. The single-tenant Pro set was decided 2026-09-19 ("i agree to your
# proposals"): coverage + discovery, the connectors other than Intune / Defender XDR, revoke, access review campaigns,
# the second approver, delegated administration ceilings, the tier-impact report and the evidence export. Dropped then
# (free, and never gated by production code): Intake, SelfService, ContactsRouting, Conformance, Rings, ApproverMatrix,
# PawPolicy, Lifecycle, AzureDiscovery (now 'Discovery'), DefinitionImport, PermissionWizard.
# MGMT-REPORT (owner 2026-10-29): 'ManagementReport' -- the management report (PowerPoint), single tenant.
# EDITION-API (owner 2026-11-01): 'ApiApplications' (script / service access to the Manager API) and 'ApiReference'
# (Settings > API and MCP reference), single tenant.
# CORE SECURITY (framework §0 "CORE SECURITY IS THE SAME IN PRO AND COMMUNITY", owner 2026-11-04): FOUR-EYES (the second
# approver, 'MakerChecker') and AUDIT (the evidence / audit export, 'EvidenceExport') are core in BOTH editions -- no longer
# Pro names. A licence that still lists them is harmless (a free feature needs no licence).
$script:PimProFeatureCatalog = @('AccessReviews', 'ApiApplications', 'ApiReference', 'BrokerApi', 'ConsultantLifecycle', 'Coverage', 'Discovery', 'HybridAd', 'ManagementReport', 'McpServer', 'MspFanout',
    'PortalAdmins', 'Revoke', 'Rfa', 'TierReport', 'WorkloadConnectors')
# PRO-FEATURES-MISSING (PIM REQUIREMENTS §100.32, owner 2026-10-09: "i cannot use any of the features" on a Pro licence issued
# before ConsultantLifecycle / Rfa / BrokerApi / McpServer existed). The SINGLE-TENANT Pro features: the catalog's scope='single'
# Pro names (Get-PimCatalogProFeatureNames -Scope single). Framework §12.6a LICENCE-FEATURES (owner 2026-10-09): the licence
# names the EDITION, the product maps edition -> features, no re-signing for a new feature ever. Every Pro licence -- Pro
# Enterprise AND Pro Business (Business differs only by its signed `limits`, §12.6) -- grants every one of these, current and
# future, whatever its features[] list says. MSP (scope='multi', MspFanout) is never in this list: it is the Pro MSP edition
# (sku Pro-MSP, or a licence naming MspFanout / '*' as every MSP licence issued so far does). Must equal the catalog's
# single-tenant list (tests/Test-PimProEnterpriseFeatures.ps1).
$script:PimProSingleTenantFeatures = @('AccessReviews', 'ApiApplications', 'ApiReference', 'BrokerApi', 'ConsultantLifecycle', 'Coverage', 'Discovery', 'HybridAd', 'ManagementReport', 'McpServer',
    'PortalAdmins', 'Revoke', 'Rfa', 'TierReport', 'WorkloadConnectors')

$script:PimLicenseCache = $null
$script:PimLicenseWarned = @{}

Function Get-PimProFeatureCatalog {
    # The gateable Pro feature names. The SQL data store is deliberately ABSENT
    # (SQL is part of the free edition -- operator decision 2026-06-12).
    @($script:PimProFeatureCatalog)
}

Function Get-PimProSingleTenantFeatures {
    # The single-tenant Pro feature names every Pro licence grants without listing them (§100.32, framework §12.6a).
    @($script:PimProSingleTenantFeatures)
}

Function Get-PimLicenceFeatureGrant {
    <#
      PURE. §100.32 / framework §12.6a -- does the licence's EDITION cover -FeatureNames, and why? Status, sku-is-Pro and
      tenant are NOT judged here (Test-PimProLicence does that around it); -License is a Get-PimLicense result, so everything
      read is from the SIGNED payload (Sku, Features, Limits) -- nothing unsigned can widen it.
        enterprise -- every name is a single-tenant Pro feature, no signed `limits`  -> covers ("included in Pro Enterprise")
        business   -- every name is a single-tenant Pro feature, signed `limits`     -> covers ("included in Pro Business (limits apply)")
        msp        -- an MSP name, and the licence is the MSP edition: sku Pro-MSP, or features[] names MspFanout / msp.downlink /
                      Msp / '*' (every MSP licence issued so far)                    -> covers ("included in Pro MSP")
        needs-msp  -- an MSP name on a licence that is not the MSP edition           -> not covered ("needs the MSP licence")
        listed     -- any other name (an explicit add-on) that features[] names or '*' -> covers ("listed in the licence")
        not-listed -- any other name the list lacks                                  -> not covered
      The features[] list is NEVER the gate for an edition feature (single-tenant Pro, MSP): it only identifies an MSP licence
      issued before the Pro-MSP sku, and names explicit add-ons. Returns @{ covers; basis; text }.
    #>
    param($License, [string[]]$FeatureNames)
    $features = @(@($(if ($License) { $License.Features } else { @() })) | ForEach-Object { "$_".Trim() } | Where-Object { $_ })
    $names = @(@($FeatureNames) | ForEach-Object { "$_".Trim() } | Where-Object { $_ })
    $isBusiness = [bool]($License -and $License.PSObject.Properties['Limits'] -and $null -ne $License.Limits)
    $sku = if ($License) { "$($License.Sku)".Trim() } else { '' }
    $isMsp = ($sku -match '^(?i)pro-msp$') -or ($features -contains '*') -or (@($features | Where-Object { $script:PimMspLicenseFeatures -contains $_ }).Count -gt 0)
    if ($names.Count -gt 0 -and @($names | Where-Object { $script:PimProSingleTenantFeatures -notcontains $_ }).Count -eq 0) {
        if ($isBusiness) { return [pscustomobject]@{ covers = $true; basis = 'business'; text = 'included in Pro Business (limits apply)' } }
        return [pscustomobject]@{ covers = $true; basis = 'enterprise'; text = 'included in Pro Enterprise' }
    }
    if (@($names | Where-Object { $script:PimMspLicenseFeatures -contains $_ }).Count -gt 0) {
        if ($isMsp) { return [pscustomobject]@{ covers = $true; basis = 'msp'; text = 'included in Pro MSP' } }
        return [pscustomobject]@{ covers = $false; basis = 'needs-msp'; text = 'needs the MSP licence' }
    }
    if ($features -contains '*') { return [pscustomobject]@{ covers = $true; basis = 'listed'; text = 'listed in the licence (all Pro features)' } }
    foreach ($n in $names) { if ($features -contains $n) { return [pscustomobject]@{ covers = $true; basis = 'listed'; text = 'listed in the licence' } } }
    return [pscustomobject]@{ covers = $false; basis = 'not-listed'; text = 'not listed in the licence' }
}

# --- Distribution policy (internal) ----------------------------------------
# Pro is distributed to customers free of charge. The license MECHANISM
# (offline signed-license verification + per-feature gate) is retained for
# internal/audit use, but the default POLICY is "Pro granted to everyone, for
# free, with no nag". So by default Test-PimProFeature passes silently for any
# feature regardless of license state -- and emits NO operator-facing message
# and NO customer-facing nag. Set $global:PIM_EnforceProLicense = $true ONLY in
# internal verification harnesses to exercise the gate.
#
# Invariants that hold REGARDLESS of this switch:
#   * Core behaviour is NEVER gated.
#   * Super-admins are NEVER locked out (the -SuperAdmin bypass always wins).
#   * Verification NEVER blocks startup -- a bad/missing license can never break
#     a tenant; the worst case is "edition reads Community".
Function Test-PimProLicenseEnforced {
    # Internal: is the Pro gate actively enforced this session? Defaults to OFF
    # (customers get Pro free). Honour the global if an internal harness set it.
    if ($null -ne $global:PIM_EnforceProLicense) { return [bool]$global:PIM_EnforceProLicense }
    $false
}

Function Test-PimLicenseSignature {
    <#
    .SYNOPSIS
        Pure RSA-SHA256 PKCS#1 signature verify over raw bytes, against a
        base64-DER public certificate. Returns $true/$false; never throws.
    .DESCRIPTION
        Isolated so the verification path can be unit-tested with valid /
        invalid / tampered fixtures using an ephemeral test keypair, without
        the maintainer's private key (which only ever exists on the build host).
        PS 5.1-safe: X509Certificate2 from raw bytes + RSACertificateExtensions
        -- NO RSA.ImportFromPem (PS 7 / .NET Core 3.0+ only).
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][byte[]]$PayloadBytes,
        [Parameter(Mandatory)][byte[]]$SignatureBytes,
        [Parameter(Mandatory)][string]$PublicCertB64
    )
    try {
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new([Convert]::FromBase64String($PublicCertB64))
        $rsa  = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPublicKey($cert)
        if (-not $rsa) { return $false }
        return [bool]$rsa.VerifyData($PayloadBytes, $SignatureBytes, [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
    } catch {
        return $false
    }
}

Function Get-PimLicenseFromStore {
    # IMP-42: the stored licence document. Returns @{ ok; text; error }. ok=$false = a store that exists but
    # could not be read (never read as "no licence"). No store wired = ok with no text (Core, as before).
    $v = $null
    try {
        if (Get-Command Get-PimSetting -ErrorAction SilentlyContinue) { $v = Get-PimSetting -Name 'License' }
        elseif ((Get-Command Get-PimSqlSetting -ErrorAction SilentlyContinue) -and "$($global:PIM_SqlConnectionString)".Trim()) { $v = Get-PimSqlSetting -ConnectionString "$($global:PIM_SqlConnectionString)" -Name 'License' }
        # REQ-Y: the engine / jobs hold their store as $global:PIM_EngineSqlCs (the same store the feature gates read).
        elseif ((Get-Command Get-PimSqlSetting -ErrorAction SilentlyContinue) -and "$($global:PIM_EngineSqlCs)".Trim()) { $v = Get-PimSqlSetting -ConnectionString "$($global:PIM_EngineSqlCs)" -Name 'License' }
        else { return [pscustomobject]@{ ok = $true; text = ''; error = '' } }
    } catch { return [pscustomobject]@{ ok = $false; text = ''; error = "$($_.Exception.Message)" } }
    if ($null -eq $v) { return [pscustomobject]@{ ok = $true; text = ''; error = '' } }
    $t = if ($v -is [string]) { $v } else { ConvertTo-Json -InputObject $v -Depth 6 -Compress }
    return [pscustomobject]@{ ok = $true; text = $t; error = '' }
}

Function Set-PimLicense {
    <#
      IMP-42: store an issued licence in pim.Settings['License'] -- ONLY after it verifies (a tampered or
      foreign document is refused, never stored). -LicenseText is the issued file's content. Returns the
      verified licence object. THROWS on a failed verify or a failed write.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)][string]$LicenseText, [string]$PublicCertB64, [string]$TenantId = $(if ("$($global:PIM_TenantId)".Trim()) { "$($global:PIM_TenantId)" } else { "$env:PIM_TenantId" }))
    $chk = if ($PublicCertB64) { Get-PimLicense -LicenseText $LicenseText -PublicCertB64 $PublicCertB64 } else { Get-PimLicense -LicenseText $LicenseText }
    if ($chk.Status -in @('Invalid','Missing')) { throw "licence NOT stored: $($chk.Reason)" }
    # BUG-278: a licence that can never make THIS environment Pro is refused at the door, not discovered later per feature.
    if ("$($chk.Sku)".Trim() -notmatch '^(?i)pro(-.+)?$') { throw "licence NOT stored: it is a '$("$($chk.Sku)".Trim())' licence, not Pro" }
    $bind = Test-PimLicenseTenantBinding -License $chk -TenantId $TenantId
    if (-not $bind.ok) { throw "licence NOT stored: $($bind.reason)" }
    if (-not (Get-Command Set-PimSetting -ErrorAction SilentlyContinue)) { throw 'licence NOT stored: no SQL settings store (Set-PimSetting) is wired -- PIM v2 keeps the licence in SQL only' }
    # BUG-277: was this environment Community until now? Then record the conversion. A Community install has no in-cloud
    # updater by design; the ring gate reads this marker so the install keeps updating as before until the upgrade step
    # (tools\setup\Upgrade-PimToPro.ps1) gives it the Pro updater and its ring.
    $wasPro = $false
    try { $prev = Get-PimLicense -Refresh; $wasPro = [bool](Test-PimLicenseIsProForTenant -License $prev -TenantId $TenantId).pro } catch { $wasPro = $false }
    Set-PimSetting -Name 'License' -Value $LicenseText
    $script:PimLicenseCache = $null
    if (-not $wasPro) {
        try {
            Set-PimSetting -Name 'EditionUpgrade' -Value ([pscustomobject][ordered]@{ fromEdition = 'community'; toEdition = 'pro'; licensedUtc = [datetime]::UtcNow.ToString('o'); customer = "$($chk.Customer)"; licenseId = "$($chk.LicenseId)" }) | Out-Null
        } catch { Write-Warning "[licence] the Community -> Pro conversion could not be recorded ($($_.Exception.Message)) -- run tools\setup\Upgrade-PimToPro.ps1 before the next update." }
    }
    return $chk
}

Function Get-PimEditionUpgradeState {
    <#
      PURE. BUG-277: is this environment a Community install that registered a Pro licence and has NOT been given the Pro
      updater yet? -Marker = pim.Settings['EditionUpgrade'], -UpdateState = pim.Settings['UpdateState'] (written by the
      in-cloud updater on every run). Pending while the marker exists and no updater run is recorded after it.
      Returns @{ pending; since; reason; command }.
    #>
    param($Marker, $UpdateState)
    $m = $Marker; if ($m -is [string]) { try { $m = $m | ConvertFrom-Json } catch { $m = $null } }
    $cmd = '.\tools\setup\Upgrade-PimToPro.ps1 -SourceUrlTemplate ''<the Pro update feed you received with your licence>'' -Apply'
    if (-not $m -or "$($m.toEdition)" -ne 'pro') { return [pscustomobject]@{ pending = $false; since = ''; reason = ''; command = $cmd } }
    $since = "$($m.licensedUtc)"
    $u = $UpdateState; if ($u -is [string]) { try { $u = $u | ConvertFrom-Json } catch { $u = $null } }
    # PIM 100.87 (owner 2026-10-11, a paid install showed "still updates like the Community edition"): the updater's record names its
    # run time tsUtc / lastSuccessUtc (PIM-UpdateState.ps1) -- neither was in this list, so the box never went away.
    $last = ''; foreach ($n in 'tsUtc', 'lastSuccessUtc', 'lastRunUtc', 'finishedUtc', 'startedUtc', 'updatedUtc', 'utc') { if ($u -and $u.PSObject.Properties[$n] -and "$($u.$n)") { $last = "$($u.$n)"; break } }
    $pending = $true
    # An install whose updater pulls from Invardia IS on the paid update feed -- never pending, whatever the dates say.
    if ($u -and $u.PSObject.Properties['source'] -and "$($u.source)".Trim() -ieq 'invardia' -and $last) { $pending = $false }
    elseif ($last -and $since) {
        try {
            $ls = [datetime]::Parse($last, [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]'AdjustToUniversal,AssumeUniversal')
            $ss = [datetime]::Parse($since, [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]'AdjustToUniversal,AssumeUniversal')
            if ($ls -gt $ss) { $pending = $false }
        } catch { }
    }
    return [pscustomobject]@{ pending = $pending; since = $since
        reason = $(if ($pending) { 'the Pro licence is registered; this install does not receive Pro releases automatically until the Pro updater is installed' } else { 'the Pro updater runs (it has reported since the licence was registered)' })
        command = $cmd }
}

Function Get-PimLicense {
    <#
    .SYNOPSIS
        Load + verify the customer's licence from pim.Settings[License] (offline). Cached per session.
    .PARAMETER PublicCertB64
        Internal/testing override of the trusted public certificate. When
        omitted, the embedded production licensing cert is used. Tests pass an
        ephemeral test cert here to exercise valid/invalid/tampered fixtures.
    .PARAMETER Path
        Internal/testing override of the license file to load (bypasses the
        config-dir scan).
    #>
    [CmdletBinding()]
    param(
        [switch]$Refresh,
        [string]$PublicCertB64,
        [string]$Path,
        # IMP-42: the licence DOCUMENT itself (JSON with payloadB64 + signature) -- what pim.Settings['License'] holds.
        [string]$LicenseText
    )

    # An override (test) load is never cached -- it must not poison the real
    # session cache, and must always re-evaluate against the supplied inputs.
    $useOverride = $PublicCertB64 -or $Path -or $LicenseText
    # REQ-Y: the hard Pro gates read this cache on hot paths, so it lives 5 minutes -- a licence registered while a
    # long-running process (the Manager, the tick) is up takes effect without a restart. A cache set with no stamp (a
    # test seeding it directly) is honoured as fresh.
    if ($script:PimLicenseCache -and -not $Refresh -and -not $useOverride) {
        if (-not $script:PimLicenseCacheUtc -or (([datetime]::UtcNow - $script:PimLicenseCacheUtc).TotalMinutes -lt 5)) { return $script:PimLicenseCache }
    }
    if (-not $useOverride) { $script:PimLicenseCacheUtc = [datetime]::UtcNow }

    # LIC-1 / LIC-4 -- accept ANY trusted signer (the platform, the legacy PIM key, Invardia). the platform first (the going-forward framework key), then the
    # legacy PIM key so anything already issued keeps verifying. An explicit -PublicCertB64 still
    # wins, which is what the negative tests rely on.
    $trustedCerts = if ($PublicCertB64) { @($PublicCertB64) }
                    else { @($script:AitLicensePublicCertB64, $script:PimLicensePublicCertB64, $script:InvardiaLicensePublicCertB64) }

    $result = [pscustomobject]@{
        Status     = 'Missing'      # Missing | Invalid | NotYetValid | Expired | Grace | Valid
        Reason     = 'no licence is stored (pim.Settings[''License'']) -- register the issued licence in Settings > Licence (it shows the two lines that download and run Set-PimLicense.ps1)'
        Customer   = ''
        Sku        = 'Core'
        Features   = @()
        TenantIds  = @()
        ValidFrom  = $null
        ValidTo    = $null
        GraceUntil = $null
        LicenseId  = ''
        Path       = $null
        # Framework §12.6 LICENCE-DIMENSION: the SIGNED payload's optional `limits` object ($null = none = Pro Enterprise).
        Limits     = $null
    }

    # 🔴 IMP-42 (§33.28) -- THE LICENCE LIVES IN SQL, NOT IN A FILE. It used to be found by scanning config/ for
    # *.pimlicense / *.aitlicense -- a directory the container image EXCLUDES, so every hosted environment read
    # "Missing" whatever had been issued. The signed document (payloadB64 + signature, byte-identical to the issued
    # file) is now pim.Settings['License'] (Set-PimLicense stores it after verifying it). -Path / -LicenseText stay
    # as EXPLICIT inputs (verify a file before importing it; the tests) -- they are never scanned for.
    $docText = $null
    if ($LicenseText) { $docText = "$LicenseText"; $result.Path = '(supplied text)' }
    elseif ($Path) {
        if (-not (Test-Path -LiteralPath $Path)) { $result.Reason = "no licence file at '$Path'"; return $result }
        $docText = Get-Content -LiteralPath $Path -Raw -Encoding UTF8; $result.Path = $Path
    } else {
        $st = Get-PimLicenseFromStore
        if (-not $st.ok) { $result.Status = 'Invalid'; $result.Reason = "the licence could not be read from the store: $($st.error)"; $script:PimLicenseCache = $result; return $result }
        if (-not "$($st.text)".Trim()) { $script:PimLicenseCache = $result; return $result }
        $docText = "$($st.text)"; $result.Path = "pim.Settings['License']"
    }

    try {
        $doc = $docText | ConvertFrom-Json
        if (-not $doc.payloadB64 -or -not $doc.signature) { throw "file is not a PIM4EntraPS license (payloadB64/signature missing)" }

        $payloadBytes = [Convert]::FromBase64String($doc.payloadB64)
        $sigBytes     = [Convert]::FromBase64String($doc.signature)

        $ok = $false
        foreach ($__tc in @($trustedCerts | Where-Object { $_ })) {
            if (Test-PimLicenseSignature -PayloadBytes $payloadBytes -SignatureBytes $sigBytes -PublicCertB64 $__tc) { $ok = $true; break }
        }
        if (-not $ok) { $result.Status = 'Invalid'; $result.Reason = 'signature verification FAILED (file tampered or not issued by the PIM4EntraPS licensing key)'; if (-not $useOverride) { $script:PimLicenseCache = $result }; return $result }

        $p = [System.Text.Encoding]::UTF8.GetString($payloadBytes) | ConvertFrom-Json
        $result.Customer  = "$($p.customer)"
        $result.Sku       = "$($p.sku)"
        $result.LicenseId = "$($p.licenseId)"
        $result.Features  = @($p.features | Where-Object { $_ })
        $result.TenantIds = @($p.tenantIds | Where-Object { $_ })
        $result.ValidFrom = [datetime]::Parse("$($p.validFrom)", [System.Globalization.CultureInfo]::InvariantCulture).Date
        $result.ValidTo   = [datetime]::Parse("$($p.validTo)",   [System.Globalization.CultureInfo]::InvariantCulture).Date
        $graceDays = 30; if ($p.PSObject.Properties.Name -contains 'graceDays' -and "$($p.graceDays)" -match '^\d+$') { $graceDays = [int]$p.graceDays }
        $result.GraceUntil = $result.ValidTo.AddDays($graceDays)
        # §12.6: read ONLY from the verified payload bytes ($p) -- a `limits` on the outer document ($doc) is unsigned and
        # never read. Absent = Pro Enterprise (every licence issued before §12.6 is byte-identical and stays uncapped).
        if ($p.PSObject.Properties.Name -contains 'limits') { $result.Limits = ConvertTo-PimLicenceLimits -Value $p.limits }

        $today = (Get-Date).Date
        if     ($today -lt $result.ValidFrom)  { $result.Status = 'NotYetValid'; $result.Reason = "license starts $($result.ValidFrom.ToString('yyyy-MM-dd'))" }
        elseif ($today -le $result.ValidTo)    { $result.Status = 'Valid';       $result.Reason = "valid until $($result.ValidTo.ToString('yyyy-MM-dd'))" }
        elseif ($today -le $result.GraceUntil) { $result.Status = 'Grace';       $result.Reason = "EXPIRED $($result.ValidTo.ToString('yyyy-MM-dd')) -- grace until $($result.GraceUntil.ToString('yyyy-MM-dd')), renew now" }
        else                                   { $result.Status = 'Expired';     $result.Reason = "expired $($result.ValidTo.ToString('yyyy-MM-dd')) (grace ended $($result.GraceUntil.ToString('yyyy-MM-dd')))" }
    } catch {
        $result.Status = 'Invalid'
        $result.Reason = "license could not be read: $($_.Exception.Message)"
    }

    if (-not $useOverride) { $script:PimLicenseCache = $result }
    return $result
}

Function Test-PimProFeature {
    <#
    .SYNOPSIS
        Gate for a Pro feature. $true = allowed. Core behavior is NEVER gated.
    .PARAMETER Feature
        Name from the Pro feature catalog (e.g. 'MspFanout').
    .PARAMETER TenantId
        Tenant to check the license binding against. When omitted, the
        connected Graph context's tenant is used if resolvable; if no tenant
        can be resolved, the tenant binding is not evaluated here (per-tenant
        call sites pass it explicitly).
    .PARAMETER SuperAdmin
        The caller is acting as a super-admin. Super-admins are NEVER locked
        out -- the gate always returns $true for them, no matter the license
        state or enforcement policy.
    .PARAMETER Quiet
        Suppress the operator-facing block message.
    .NOTES
        By default Pro is granted free (Test-PimProLicenseEnforced = $false), so
        this returns $true silently with NO nag. The gate only actually blocks
        when an internal harness sets $global:PIM_EnforceProLicense = $true.
        Core behaviour is never routed through this gate.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$Feature,
        [string]$TenantId,
        [switch]$SuperAdmin,
        [switch]$Quiet
    )

    # Super-admins are never locked out.
    if ($SuperAdmin) { return $true }

    # Default policy: customers get Pro free, with no nag. The verification
    # mechanism still ran (so Get-PimEdition / audit can report it), but the
    # gate does not block and emits nothing customer-facing.
    if (-not (Test-PimProLicenseEnforced)) { return $true }

    # REQ-Y: a feature that is not in the Pro list is free -- never gated, even when a harness enforces the switch.
    # The list follows the feature catalog (see $script:PimProFeatureCatalog), so the list and the gate cannot disagree.
    if (@(Get-PimProFeatureCatalog) -notcontains $Feature) { return $true }

    $lic = Get-PimLicense
    $blockReason = $null

    if ($lic.Status -notin @('Valid', 'Grace')) {
        $blockReason = $lic.Reason
    } elseif (-not ($grant = Get-PimLicenceFeatureGrant -License $lic -FeatureNames @($Feature)).covers) {   # §100.32 / §12.6a: every Pro licence = every single-tenant Pro feature
        $blockReason = "license for '$($lic.Customer)' does not include feature '$Feature' -- $($grant.text) (features: $($lic.Features -join ', '))"
    } else {
        # §100.42: no Graph-SDK context fallback -- Resolve-PimLicenseTenantId takes the PIM-Rest tenant (MI home tenant /
        # $global:PIM_TenantId) when -TenantId is empty.
        $bind = Test-PimLicenseTenantBinding -License $lic -TenantId $TenantId
        if (-not $bind.ok) { $blockReason = "license for '$($lic.Customer)': $($bind.reason)" }
    }

    if ($blockReason) {
        if (-not $Quiet -and -not $script:PimLicenseWarned["$Feature|$TenantId"]) {
            $script:PimLicenseWarned["$Feature|$TenantId"] = $true
            Write-Host "[Pro] '$Feature' requires a PIM Manager Pro license -- $blockReason. Core features continue to work normally." -ForegroundColor Yellow
        }
        if (Get-Command Write-PimAuditEvent -ErrorAction SilentlyContinue) {
            Write-PimAuditEvent -Action 'license.blocked' -Target $Feature -After @{ reason = $blockReason; tenantId = "$TenantId" }
        }
        return $false
    }

    if ($lic.Status -eq 'Grace' -and -not $Quiet -and -not $script:PimLicenseWarned['__grace__']) {
        $script:PimLicenseWarned['__grace__'] = $true
        Write-Host "[Pro] license $($lic.Reason)" -ForegroundColor Yellow
    }
    return $true
}

Function Resolve-PimLicenseTenantId {
    <#
      LIC anti-copy (2026-10-03). The tenant a licence is checked against: the MANAGED IDENTITY's home tenant when this
      process has minted a managed-identity token (PIM-Rest.ps1 records its tid in $global:PIM_ManagedIdentityTenantId --
      a managed identity's token always comes from its home tenant, so editing PIM_TenantId cannot change it); otherwise
      the configured -TenantId (operator tools that run as a certificate SPN or the signed-in user).
    #>
    param([string]$TenantId)
    $mi = "$($global:PIM_ManagedIdentityTenantId)".Trim().ToLowerInvariant()
    if ($mi) { return $mi }
    # SPN / signed-in: a token is requested FOR the configured tenant and issued BY it, so pointing the configuration at a
    # licensed tenant makes the process really operate there -- the configured tenant is honest without a managed identity.
    foreach ($c in @($TenantId, $global:PIM_TenantId, $env:PIM_TenantId)) { if ("$c".Trim()) { return "$c".Trim().ToLowerInvariant() } }
    return ''
}

Function Test-PimLicenseTenantBinding {
    <#
      PURE (given $global:PIM_ManagedIdentityTenantId). LIC anti-copy (operator 2026-10-03: "validate license against the
      tenant so license can not be copied to other tenants"). Returns @{ ok; reason; tenantId }.
        * a licence that names NO tenant is refused -- every licence is issued for the tenant(s) it was bought for;
        * the tenant is Resolve-PimLicenseTenantId (the managed identity's home tenant when known);
        * an unknown tenant is refused (fail closed); a tenant not in the licence is refused.
    #>
    param($License, [string]$TenantId)
    $bound = @(@($License.TenantIds) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
    $tid = Resolve-PimLicenseTenantId -TenantId $TenantId
    if (-not $bound.Count) { return [pscustomobject]@{ ok = $false; tenantId = $tid; reason = 'the licence names no tenant -- a licence is only valid for the tenant it was issued for; ask for a licence bound to this tenant' } }
    if (-not $tid) { return [pscustomobject]@{ ok = $false; tenantId = $tid; reason = "the licence is bound to tenant $($bound -join ', '), and this environment's tenant id is not known" } }
    if ($bound -notcontains $tid) {
        $cfg = "$TenantId".Trim().ToLowerInvariant()
        $why = if ($cfg -and $cfg -ne $tid) { "; this environment runs in tenant $tid (its managed identity), although it is configured as $cfg" } else { "; this tenant is $tid" }
        return [pscustomobject]@{ ok = $false; tenantId = $tid; reason = "the licence is for another tenant (bound to $($bound -join ', ')$why)" }
    }
    return [pscustomobject]@{ ok = $true; tenantId = $tid; reason = '' }
}

Function Test-PimLicenseIsProForTenant {
    <#
      PURE. BUG-278 (2026-10-01): THE edition verdict -- the same rule the hard gate (Test-PimProLicence) applies, minus the
      per-feature check: Status Valid or Grace, sku Pro / Pro-<variant> (never Community, never 'Core'), and a tenant
      binding that includes -TenantId (or no binding). The badge, GET /api/license, the updater's edition read and the
      import all use it, so the header can no longer say Pro while every Pro feature is locked.
      Returns @{ pro; reason }. A bound licence with an UNKNOWN tenant is not Pro (fail closed, as the gate).
    #>
    param($License, [string]$TenantId)
    if (-not $License) { return [pscustomobject]@{ pro = $false; reason = 'no Pro licence is installed' } }
    $st = "$($License.Status)"
    if ($st -notin @('Valid', 'Grace')) { return [pscustomobject]@{ pro = $false; reason = $(if ($st -eq 'Missing') { 'no Pro licence is installed' } else { "the licence is $st ($($License.Reason))" }) } }
    $sku = "$($License.Sku)".Trim()
    if ($sku -notmatch '^(?i)pro(-.+)?$') { return [pscustomobject]@{ pro = $false; reason = "the licence is a '$sku' licence, not Pro" } }
    $bind = Test-PimLicenseTenantBinding -License $License -TenantId $TenantId
    if (-not $bind.ok) { return [pscustomobject]@{ pro = $false; reason = $bind.reason } }
    return [pscustomobject]@{ pro = $true; reason = $(if ($st -eq 'Grace') { "Pro licence in its grace period ($($License.Reason))" } else { "Pro licence for '$($License.Customer)'" }) }
}

Function Get-PimEdition {
    # The active EDITION: 'Pro' when a valid (or in-grace) PRO licence for THIS tenant is present, else 'Community' (free).
    # Drives the manager edition badge. BUG-278: was "any Valid licence" -- a Community-sku or another tenant's licence
    # showed Pro while the hard gate (which checks both) kept every Pro feature locked.
    param([string]$TenantId = $(if ("$($global:PIM_TenantId)".Trim()) { "$($global:PIM_TenantId)" } else { "$env:PIM_TenantId" }))
    $lic = Get-PimLicense
    if ((Test-PimLicenseIsProForTenant -License $lic -TenantId $TenantId).pro) { return $script:PimProEditionName }
    return $script:PimCommunityEditionName
}

# =====================================================================================================================
# Framework DOCS/REQUIREMENTS.md §12.6 LICENCE-DIMENSION (owner 2026-10-08) -- PIM's half; PIM docs/REQUIREMENTS.md §95.2d.
# Pro has two dimensions, decided by the SIGNED licence: Pro Business = the payload carries a `limits` object (PIM reads
# `admins`: the number of managed admin accounts it covers); Pro Enterprise = no `limits`. Community and MSP unchanged.
# Enforcement is a WARNING, never a stop: from 90% a banner; at/over the cap only a NEW managed admin account is refused
# (Manager commit + staging + MCP -- the page only mirrors it). Nothing existing is disabled or touched, and the ENGINE
# never reads the limit at all.
# =====================================================================================================================
$script:PimLicenceDimensionBusiness   = 'Pro Business'
$script:PimLicenceDimensionEnterprise = 'Pro Enterprise'
$script:PimLicenceUpgradeUrl          = 'invardia.com'
# An admin row in one of these states is not counted: it is off, removed from PIM or deleted (the row only keeps it so).
$script:PimAdminNotCountedStatuses    = @('disabled', 'removed', 'deleted', 'revoked')

Function ConvertTo-PimLicenceLimits {
    <#
      PURE. The payload's `limits` value -> an ordered map name (lower-case) -> non-negative int, or $null when the value is
      not an object (absent / null / a string / a number = no limits = Pro Enterprise). A key whose value is not a whole
      number is dropped (never guessed); an empty object stays an (empty) map -- the licence IS Business, with no PIM cap.
    #>
    param([AllowNull()]$Value)
    if ($null -eq $Value) { return $null }
    $pairs = @()
    if ($Value -is [System.Collections.IDictionary]) { foreach ($k in @($Value.Keys)) { $pairs += ,@("$k", $Value[$k]) } }
    # 🪤 not `-is [pscustomobject]`: that is [psobject], true for a PSObject-WRAPPED string too, whose properties (Length)
    # would read as a limit. The JSON object type itself is the only object accepted.
    elseif ($Value.GetType().FullName -eq 'System.Management.Automation.PSCustomObject') { foreach ($pp in @($Value.PSObject.Properties)) { $pairs += ,@("$($pp.Name)", $pp.Value) } }
    else { return $null }
    $out = [ordered]@{}
    foreach ($pr in $pairs) {
        $n = "$($pr[0])".Trim().ToLowerInvariant(); $v = "$($pr[1])".Trim()
        if ($n -and $v -match '^\d{1,9}$') { $out[$n] = [int]$v }
    }
    return $out
}

Function Get-PimLicenceDimension {
    <#
      PURE. 'Community' | 'Pro Business' | 'Pro Enterprise' for -License as THIS tenant sees it: not Pro here (the same verdict
      as the badge, Test-PimLicenseIsProForTenant) = Community; Pro with a signed `limits` object = Pro Business; Pro without
      = Pro Enterprise (every licence issued before §12.6, MSP included).
    #>
    param($License, [string]$TenantId)
    if (-not $License -or -not (Test-PimLicenseIsProForTenant -License $License -TenantId $TenantId).pro) { return $script:PimCommunityEditionName }
    $lim = $null; if ($License.PSObject.Properties['Limits']) { $lim = $License.Limits }
    if ($null -ne $lim) { return $script:PimLicenceDimensionBusiness }
    return $script:PimLicenceDimensionEnterprise
}

Function Get-PimLicenceAdminCap {
    # PURE. The licence's managed-admin cap (int), or $null = no cap (Enterprise, Community, or a Business licence without `admins`).
    param($License)
    if (-not $License -or -not $License.PSObject.Properties['Limits'] -or $null -eq $License.Limits) { return $null }
    $l = $License.Limits
    if ($l -is [System.Collections.IDictionary] -and $l.Contains('admins')) { return [int]$l['admins'] }
    return $null
}

Function Get-PimLicenceDimensionText {
    # PURE. The one label every surface shows: "Pro Enterprise", "Pro Business (5 admins)", "Pro Business", "Community".
    param($License, [string]$TenantId)
    $d = Get-PimLicenceDimension -License $License -TenantId $TenantId
    if ($d -ne $script:PimLicenceDimensionBusiness) { return $d }
    $cap = Get-PimLicenceAdminCap -License $License
    if ($null -ne $cap) { return ('{0} ({1} admin{2})' -f $d, $cap, $(if ($cap -eq 1) { '' } else { 's' })) }
    return $d
}

Function Get-PimManagedAdminIdentities {
    <#
      PURE. The managed admin ACCOUNTS -- Account-Definitions-Admins rows -- that count against the cap, each counted once:
      the identity is the UPN (lower-case), else the UserName. A row whose AccountStatus is Disabled / Removed / Deleted /
      Revoked is not counted (it is off, or the row only keeps it gone). -All counts every row whatever its state (the "is
      this account NEW" test). Returns a sorted, distinct string array.
    #>
    param([AllowNull()][object[]]$Rows, [switch]$All)
    $seen = @{}
    foreach ($r in @($Rows)) {
        if ($null -eq $r) { continue }
        $get = { param($n) if ($r -is [System.Collections.IDictionary]) { if ($r.Contains($n)) { "$($r[$n])" } else { '' } } elseif ($r.PSObject.Properties[$n]) { "$($r.$n)" } else { '' } }
        $id = (& $get 'UserPrincipalName').Trim().ToLowerInvariant()
        if (-not $id) { $id = (& $get 'UserName').Trim().ToLowerInvariant() }
        if (-not $id) { continue }
        if (-not $All -and ($script:PimAdminNotCountedStatuses -contains (& $get 'AccountStatus').Trim().ToLowerInvariant())) { continue }
        $seen[$id] = $true
    }
    return @($seen.Keys | Sort-Object)
}

Function Get-PimAdminLicenceUsage {
    <#
      PURE. The admin usage against the licence, for /api/license, the banners and the refusal:
        @{ dimension; dimensionText; cap ($null = none); count ($null when -Rows was not given); percent; state; message }
        state: none (no cap, or the count is unknown) | ok (< 90%) | warn (>= 90%, below the cap) | at (= cap) | over (> cap)
      message is the plain sentence the banner shows ('' for none/ok).
    #>
    param($License, [string]$TenantId, [AllowNull()][object[]]$Rows, [switch]$RowsKnown)
    $dim = Get-PimLicenceDimension -License $License -TenantId $TenantId
    $cap = if ($dim -eq $script:PimLicenceDimensionBusiness) { Get-PimLicenceAdminCap -License $License } else { $null }
    $known = $RowsKnown -or $PSBoundParameters.ContainsKey('Rows')
    $count = if ($known) { @(Get-PimManagedAdminIdentities -Rows $Rows).Count } else { $null }
    $out = [ordered]@{ dimension = $dim; dimensionText = (Get-PimLicenceDimensionText -License $License -TenantId $TenantId); cap = $cap; count = $count; percent = $null; state = 'none'; message = '' }
    if ($null -eq $cap -or $null -eq $count) { return $out }
    $pct = if ($cap -gt 0) { [int][math]::Floor(100.0 * $count / $cap) } else { 100 }
    $out.percent = $pct
    $covers = "Your Pro Business licence covers $cap admin account$(if ($cap -eq 1) { '' } else { 's' })"
    if ($count -gt $cap) {
        $out.state = 'over'
        $out.message = "$covers and $count are managed. Nothing is switched off, but a new admin account is refused -- upgrade to Pro Enterprise at $script:PimLicenceUpgradeUrl, or remove one."
    } elseif ($count -eq $cap) {
        $out.state = 'at'
        $out.message = "$covers and all $count are in use. A new admin account is refused -- upgrade to Pro Enterprise at $script:PimLicenceUpgradeUrl, or remove one."
    } elseif ($cap -gt 0 -and ($count * 10) -ge ($cap * 9)) {
        $out.state = 'warn'
        $out.message = "$covers and $count are in use ($pct%). Upgrade to Pro Enterprise at $script:PimLicenceUpgradeUrl before you add more."
    } else {
        $out.state = 'ok'
    }
    return $out
}

Function Test-PimAdminLicenceLimit {
    <#
      PURE. The server-side cap check for a change to Account-Definitions-Admins (the commit, staging, MCP).
        -Before = the rows as they are; -After = the rows the change would leave.
      Refused ONLY when the change brings in a NEW admin account (an identity in no -Before row, in any state) that is
      counted, and the counted total afterwards exceeds the cap. Editing, disabling, removing or re-enabling an existing
      account is never refused, and nothing already there is touched. No cap (Enterprise / Community / no `admins`) = ok.
      Returns @{ ok; refused; cap; count; before; added[]; dimension; message }.
    #>
    param($License, [string]$TenantId, [AllowNull()][object[]]$Before, [AllowNull()][object[]]$After)
    $u = Get-PimAdminLicenceUsage -License $License -TenantId $TenantId -Rows @($After) -RowsKnown
    $res = [ordered]@{ ok = $true; refused = $false; cap = $u.cap; count = $u.count; before = @(Get-PimManagedAdminIdentities -Rows @($Before)).Count; added = @(); dimension = $u.dimension; message = '' }
    if ($null -eq $u.cap) { return [pscustomobject]$res }
    $known = @{}; foreach ($i in @(Get-PimManagedAdminIdentities -Rows @($Before) -All)) { $known[$i] = $true }
    $added = @(@(Get-PimManagedAdminIdentities -Rows @($After)) | Where-Object { -not $known.ContainsKey($_) })
    $res.added = @($added)
    if ($added.Count -gt 0 -and $u.count -gt $u.cap) {
        $res.ok = $false; $res.refused = $true
        # 🪤 the list is built first: inside a -f argument list the comma binds tighter than +, so "(a) + b" there splits
        # the array and the format string loses its arguments.
        $names = (@($added | Select-Object -First 5) -join ', ')
        if ($added.Count -gt 5) { $names += ', ...' }
        $res.message = ("Your Pro Business licence covers {0} admin account{1} -- upgrade to Pro Enterprise at {2}, or remove one. Not saved: {3} new admin account{4} ({5}) would make {6}. Existing admin accounts are not changed." -f
            $u.cap, $(if ($u.cap -eq 1) { '' } else { 's' }), $script:PimLicenceUpgradeUrl, $added.Count, $(if ($added.Count -eq 1) { '' } else { 's' }), $names, $u.count)
    }
    return [pscustomobject]$res
}

Function Get-PimLicenseStatusText {
    # One-line status for banners / the Manager Governance panel.
    $lic = Get-PimLicense
    switch ($lic.Status) {
        'Missing' { 'Community (free) -- no Pro license installed' }
        'Valid'   { "Pro -- $($lic.Customer) -- $($lic.Reason)" }
        'Grace'   { "Pro (GRACE) -- $($lic.Customer) -- $($lic.Reason)" }
        default   { "Community (free) -- license $($lic.Status): $($lic.Reason)" }
    }
}

# =====================================================================================================================
# REQ-Y (operator 2026-09-19: "managing tenant slave require license pro" / "enforce in code" / "write text to contact
# mok@mortenknudsen.net for license" / "msp license is req now"). A TARGETED enforcement: an environment that runs as an
# MANAGING TENANT (publishes the signed baseline) or an MSP SLAVE (pulls it) needs a Pro licence bound to its tenant.
#   * It does NOT read Test-PimProLicenseEnforced. The global switch stays OFF, so every OTHER Pro feature stays free.
#   * Valid = run. Grace (the licence's own graceDays after validTo) = run, with a warning. Anything else = refuse.
#   * No introduction grace: the requirement is immediate (operator 2026-09-19, "msp license is req now").
# The MSP jobs (tools/pim-engine/publish-job-entry.ps1, downlink-job-entry.ps1) refuse through Invoke-PimMspLicenseGate;
# the Manager serves the same verdict on GET /api/license (Get-PimLicenseApiBody) for the Settings > Licence section and
# the MSP-page banners.
# =====================================================================================================================
$script:PimLicenseContact = 'info@invardia.com'
# Operator 2026-10-01: "https://invardia.com ... is the website for buying pro version. it is also the support page
# (portal.invardia.com) for support to paid licenses".
$script:PimProBuyUrlDefault  = 'https://invardia.com'
$script:PimProSupportUrl     = 'https://portal.invardia.com'
# The licence feature names that cover MSP: the Pro catalog's MspFanout, the feature catalog key msp.downlink, and 'Msp'.
# '*' (all Pro features) covers it too.
$script:PimMspLicenseFeatures = @('MspFanout', 'msp.downlink', 'Msp')

Function Get-PimLicenseContact { "$script:PimLicenseContact" }

Function Get-PimLicenseRegisterCommand {
    <#
      PURE. The supported way to register an issued licence file (Set-PimLicense.ps1, downloaded from Invardia), with this environment's
      store server and tenant filled in when known; placeholders otherwise. Never carries a secret -- and never a certificate (97.1, owner 2026-10-08: "we dont support certificates"): -UseSignedInAccount signs the person in through the browser (a member of the store's SQL admin group), or uses the Invardia Support app session open in that window -- no command-line tool, no module (REQUIREMENTS 100.77: no customer-facing text names one).
    #>
    param([string]$SqlServer, [string]$TenantId)
    $srv = "$SqlServer".Trim(); if (-not $srv) { $srv = '<server>.database.windows.net' }
    $tid = "$TenantId".Trim();  if (-not $tid) { $tid = '<tenant>' }
    # REQUIREMENTS 100.81 (owner 2026-10-11, "Yes, publish"): Set-PimLicense.ps1 is a published standalone script, so the
    # command is the TWO lines every published script shows -- line 1 downloads it from Invardia, line 2 runs it -- and
    # nothing else. The central builder (tools\setup\_PimScriptDoc.ps1) when it is loaded; the same two lines when not.
    $run = ".\Set-PimLicense.ps1 -LicensePath <file> -SqlServer {0} -TenantId {1} -UseSignedInAccount" -f $srv, $tid
    if (Get-Command Get-PimSupportScriptCommand -ErrorAction SilentlyContinue) { return ((Get-PimSupportScriptCommand -Script 'Set-PimLicense' -Run @($run)) -join "`n") }
    return ("Invoke-WebRequest https://invardia.com/support/pim/Set-PimLicense.ps1 -OutFile Set-PimLicense.ps1`n$run")
}

Function Get-PimLicenseRegisterText {
    <#
      PURE. REQUIREMENTS 100.81 + 100.77: the register command for PLAIN TEXT (a job's log line, an API refusal, a mail) --
      the two command lines on their own lines, then ONE plain line under them, outside the block:
      "What does this script do: <the script's documentation page>". The block itself is Get-PimLicenseRegisterCommand's.
    #>
    param([string]$SqlServer, [string]$TenantId, [string]$Command)
    $cmd = if ("$Command".Trim()) { "$Command" } else { Get-PimLicenseRegisterCommand -SqlServer $SqlServer -TenantId $TenantId }
    if (Get-Command Add-PimSupportScriptDocLines -ErrorAction SilentlyContinue) { return (Add-PimSupportScriptDocLines -Text $cmd) }
    if ($cmd -match '(?m)^What does this script do: ') { return $cmd }
    return ($cmd + "`nWhat does this script do: https://invardia.com/docs/pim/scripts/Set-PimLicense/")
}

Function ConvertFrom-PimLicenseSettingRaw {
    <#
      PURE. pim.Settings['License'] as the raw ValueJson column -> the licence DOCUMENT text Get-PimLicense verifies.
      Set-PimLicense stores the issued text through Set-PimSetting, i.e. as a JSON string literal; a document stored as a
      JSON object is accepted too (same rule as Get-PimLicenseFromStore). '' = nothing stored.
    #>
    param([AllowNull()][object]$Raw)
    if ($null -eq $Raw -or $Raw -is [System.DBNull]) { return '' }
    $t = "$Raw".Trim()
    if (-not $t) { return '' }
    try { $v = $t | ConvertFrom-Json } catch { return $t }
    if ($null -eq $v) { return '' }
    if ($v -is [string]) { return "$v" }
    return (ConvertTo-Json -InputObject $v -Depth 6 -Compress)
}

Function Test-PimProLicence {
    <#
    .SYNOPSIS
        REQ-Y. The ONE hard licence check: does this environment hold a Pro licence that covers -FeatureNames for its
        tenant? Used by the MSP jobs (Test-PimMspLicense) and by every Pro feature of the catalog
        (Test-PimFeatureProLicence in PIM-FeatureCatalog.ps1). Independent of the global switch.
    .DESCRIPTION
        Returns @{ ok; status; grace; customer; sku; validTo; graceUntil; tenantIds; tenantId; label; reason; message;
        contact; command }.
          ok     = licence Status Valid or Grace, sku Pro or Pro-<variant> (nothing else -- 'Core' is refused), features '*' or one of
                   -FeatureNames, and a tenant binding that includes -TenantId (or no binding at all).
          grace  = ok, but in the licence's grace window: run, and say so.
          reason = plain words ("no Pro licence is installed", "the licence expired 2027-09-19 ...", "the licence is for
                   another tenant ...").
          message= the one line a job logs, an API refusal carries and the GUI shows:
                   "<Label> requires a PIM Manager Pro licence -- <reason>. Contact <contact> for a licence; register it with: <command>"
        It NEVER consults Test-PimProLicenseEnforced.
    .PARAMETER LicenseText
        The stored document (pim.Settings['License'] as text). When BOUND it is used as-is (empty = nothing stored). When
        not bound, Get-PimLicense reads the store itself (-UseCache: its short-lived session cache, for hot paths).
    .PARAMETER StoreError
        The caller could not read the store: the licence cannot be verified, so the check is not ok (never "no licence").
    .PARAMETER PublicCertB64
        Test seam only (the same one Get-PimLicense has): the trusted licensing certificate.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string[]]$FeatureNames,
        [Parameter(Mandatory)][string]$Label,
        [string]$FeatureWord,
        [string]$TenantId,
        [AllowEmptyString()][AllowNull()][string]$LicenseText,
        [string]$StoreError,
        [string]$SqlServer,
        [string]$PublicCertB64,
        [switch]$UseCache
    )
    $tid = "$TenantId".Trim().ToLowerInvariant()
    $word = if ("$FeatureWord".Trim()) { "$FeatureWord".Trim() } else { $Label }
    $out = [ordered]@{
        ok = $false; status = 'Missing'; grace = $false; customer = ''; sku = ''; validTo = ''; graceUntil = ''
        tenantIds = @(); tenantId = $tid; label = "$Label"; reason = ''; message = ''
        # §100.32: WHY the feature is (or is not) licensed -- enterprise | business | msp | needs-msp | listed | not-listed, or
        # 'licence' when the licence itself (missing, expired, another tenant, not Pro) decides; basisText says it in words.
        basis = ''; basisText = ''
        contact = "$script:PimLicenseContact"; command = (Get-PimLicenseRegisterCommand -SqlServer $SqlServer -TenantId $TenantId)
    }
    $lic = $null
    if ("$StoreError".Trim()) {
        $out.status = 'Invalid'
        $out.reason = "the licence could not be read from the store ($("$StoreError".Trim()))"
    } else {
        $a = @{}
        if (-not $UseCache) { $a['Refresh'] = $true }
        if ($PublicCertB64) { $a['PublicCertB64'] = $PublicCertB64 }
        if ($PSBoundParameters.ContainsKey('LicenseText')) {
            if ("$LicenseText".Trim()) { $a['LicenseText'] = "$LicenseText" } else { $a = $null }
        }
        if ($null -ne $a) { $lic = Get-PimLicense @a }
    }
    if ($lic) {
        $out.status   = "$($lic.Status)"
        $out.customer = "$($lic.Customer)"
        $out.sku      = "$($lic.Sku)"
        $out.validTo    = $(if ($lic.ValidTo) { $lic.ValidTo.ToString('yyyy-MM-dd') } else { '' })
        $out.graceUntil = $(if ($lic.GraceUntil) { $lic.GraceUntil.ToString('yyyy-MM-dd') } else { '' })
        $out.tenantIds  = @($lic.TenantIds | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ })
        $features = @($lic.Features | ForEach-Object { "$_".Trim() })
        # §100.32 / framework §12.6a (owner 2026-10-09): the licence names the EDITION. Every Pro licence (Enterprise and
        # Business alike) covers every single-tenant Pro feature, current and future; MSP needs the Pro MSP edition; the
        # features[] list only names add-ons. The verdict reads only the verified payload (Sku, Features, Limits).
        $grant = Get-PimLicenceFeatureGrant -License $lic -FeatureNames $FeatureNames
        $covers = [bool]$grant.covers
        switch ("$($lic.Status)") {
            'Missing'     { $out.reason = 'no Pro licence is installed' }
            'Invalid'     { $out.reason = "the stored licence is not valid ($($lic.Reason))" }
            'NotYetValid' { $out.reason = "the licence only starts $($lic.ValidFrom.ToString('yyyy-MM-dd'))" }
            'Expired'     { $out.reason = "the licence expired $($out.validTo) (its grace period ended $($out.graceUntil))" }
            default {
                # Pro, Pro-<variant> (Pro-DesignPartner). Anything else -- Community, or the old 'Core' -- is NOT Pro.
                # 🔴 REQ-Y (operator 2026-09-20: "fix req-y 3 items") -- 'Core' NO LONGER UNLOCKS PRO.
                # It was accepted as "documented back-compat", and that back-compat protected nothing: the ONLY issuer
                # is TOOLS\New-AitLicense.ps1, whose -Sku is [ValidateSet('Pro','Community')], so no signing run can
                # ever have produced a 'Core' licence -- and none exists (every issued licence, checked 2026-09-20,
                # decodes to sku 'Pro'). What the clause DID do was make the word most likely to be typed by hand for
                # the FREE tier -- 'Core' is this product's own historical name for it, still the internal edition name
                # in PIM-FeatureCatalog.ps1 -- unlock every Pro feature instead of none of them. A licence that grants
                # MORE the more it looks free is the wrong direction for a gate with no grace.
                # 🪤 The EDITION 'Core' (Get-PimActiveEdition / $script:PimEditionNames) is a different thing and is
                # unchanged: that is the free edition's internal name, not a licence sku.
                if ("$($lic.Sku)".Trim() -notmatch '^(?i)pro(-.+)?$') {
                    $out.reason = "the licence is a '$("$($lic.Sku)".Trim())' licence, not Pro"
                } elseif (-not $covers) {
                    $out.reason = switch ("$($grant.basis)") {
                        'needs-msp' { "the licence does not include $word -- it needs the MSP licence (features: $(($features -join ', ')))" }
                        default     { "the licence does not include $word (features: $(($features -join ', ')))" }
                    }
                    $out.basis = "$($grant.basis)"; $out.basisText = "$($grant.text)"
                } elseif (-not ($bind = Test-PimLicenseTenantBinding -License $lic -TenantId $TenantId).ok) {
                    $out.reason = $bind.reason
                } else {
                    $out.ok = $true
                    $out.basis = "$($grant.basis)"; $out.basisText = "$($grant.text)"
                    if ("$($lic.Status)" -eq 'Grace') {
                        $out.grace = $true
                        $out.reason = "the licence expired $($out.validTo), grace until $($out.graceUntil)"
                    } else {
                        $out.reason = "Pro licence for '$($out.customer)', valid until $($out.validTo)"
                    }
                }
            }
        }
    } elseif (-not $out.reason) {
        $out.reason = 'no Pro licence is installed'
    }
    if (-not $out.basis) { $out.basis = 'licence'; $out.basisText = "$($out.reason)" }
    if (-not $out.ok) {
        # 100.81: the command is two lines (download, run) on their OWN lines, the doc line under them (100.77) -- never joined into the sentence
        $out.message = ("{0} requires a PIM Manager Pro licence -- {1}. Contact {2} for a licence; register it with:`n{3}" -f $Label, $out.reason, $out.contact, (Get-PimLicenseRegisterText -Command $out.command))
    } elseif ($out.grace) {
        $out.message = ("{0}: licence expired {1}, grace until {2} -- contact {3} to renew" -f $Label, $out.validTo, $out.graceUntil, $out.contact)
    } else {
        $out.message = ("{0}: {1}" -f $Label, $out.reason)
    }
    return [pscustomobject]$out
}

Function Test-PimMspLicense {
    <#
    .SYNOPSIS
        REQ-Y. Does this managing tenant / slave hold a Pro licence that covers MSP for its tenant? (Test-PimProLicence with
        the MSP feature names, labelled "managing tenant" / "MSP slave".) The result also carries role = master | slave.
    #>
    [CmdletBinding()]
    param(
        [string]$TenantId,
        [ValidateSet('Master', 'Slave')][string]$Role = 'Master',
        [AllowEmptyString()][AllowNull()][string]$LicenseText,
        [string]$StoreError,
        [string]$SqlServer,
        [string]$PublicCertB64
    )
    $roleWord = if ($Role -eq 'Slave') { 'slave' } else { 'master' }
    # §85 (operator 2026-10-01: "slave is not nice"): the WORDS are "managing tenant" / "managed tenant"; the role field the
    # API and the jobs read stays master | slave.
    $roleLabel = if ($Role -eq 'Slave') { 'Managed tenant (MSP)' } else { 'Managing tenant (MSP)' }
    $a = @{ FeatureNames = $script:PimMspLicenseFeatures; Label = $roleLabel; FeatureWord = 'MSP'; TenantId = $TenantId; StoreError = $StoreError; SqlServer = $SqlServer }
    if ($PublicCertB64) { $a['PublicCertB64'] = $PublicCertB64 }
    if ($PSBoundParameters.ContainsKey('LicenseText')) { $a['LicenseText'] = "$LicenseText" }
    $r = Test-PimProLicence @a
    $r | Add-Member -NotePropertyName role -NotePropertyValue $roleWord -Force
    return $r
}
Function Invoke-PimMspLicenseGate {
    <#
      REQ-Y. The MSP jobs' gate: runs Test-PimMspLicense and logs ONE line through -Log (param($message, $level)):
        not ok -> ERROR  "MSP <role> requires a PIM Manager Pro licence -- <reason>. Contact ... ; register it with: ..."
        grace  -> WARN   "MSP <role>: licence expired <date>, grace until <date> -- contact ... to renew"
        ok     -> INFO   "MSP <role>: Pro licence for '<customer>', valid until <date>"
      Returns the Test-PimMspLicense result; the caller refuses (exit non-zero, nothing published / pulled) when not ok.
      A check that THROWS is not ok (a gate that cannot decide never runs the MSP pipeline).
    #>
    param(
        [Parameter(Mandatory)][ValidateSet('Master', 'Slave')][string]$Role,
        [string]$TenantId,
        [AllowEmptyString()][AllowNull()][string]$LicenseText,
        [string]$StoreError,
        [string]$SqlServer,
        [scriptblock]$Log
    )
    $a = @{ Role = $Role; TenantId = $TenantId; StoreError = $StoreError; SqlServer = $SqlServer }
    if ($PSBoundParameters.ContainsKey('LicenseText')) { $a['LicenseText'] = "$LicenseText" }
    try { $r = Test-PimMspLicense @a }
    catch {
        $roleWord = if ($Role -eq 'Slave') { 'slave' } else { 'master' }
        $cmd = Get-PimLicenseRegisterCommand -SqlServer $SqlServer -TenantId $TenantId
        $r = [pscustomobject]@{ ok = $false; status = 'Invalid'; grace = $false; customer = ''; sku = ''; validTo = ''; graceUntil = ''; tenantIds = @(); tenantId = "$TenantId"; role = $roleWord
            reason = "the licence check failed ($($_.Exception.Message))"; contact = "$script:PimLicenseContact"; command = $cmd
            message = ("{0} requires a PIM Manager Pro licence -- the licence check failed ({1}). Contact {2} for a licence; register it with:`n{3}" -f $(if ($Role -eq 'Slave') { 'Managed tenant (MSP)' } else { 'Managing tenant (MSP)' }), $_.Exception.Message, $script:PimLicenseContact, (Get-PimLicenseRegisterText -Command $cmd)) }
    }
    $lvl = if (-not $r.ok) { 'ERROR' } elseif ($r.grace) { 'WARN' } else { 'INFO' }
    if ($Log) { & $Log $r.message $lvl }
    return $r
}

Function Get-PimLicenseApiBody {
    <#
      REQ-Y. The body of the Manager's GET /api/license: the licence status in plain words, plus the MSP verdict for THIS
      environment. -MspRole '' = single (non-MSP): mspRequired false and the GUI shows no MSP banner. Read-only.
      mspState: none (single) | ok | grace | refused.
    #>
    param([ValidateSet('', 'Master', 'Slave')][string]$MspRole = '', [string]$TenantId, [string]$SqlServer, [string]$PublicCertB64,
          # §12.6: the stored Account-Definitions-Admins rows, for the admin usage (count / cap / state). Not given = count unknown.
          [AllowNull()][object[]]$AdminRows, [string]$LicenseText)
    $la = @{ Refresh = $true }; if ($PublicCertB64) { $la['PublicCertB64'] = $PublicCertB64 }
    if ($PSBoundParameters.ContainsKey('LicenseText') -and "$LicenseText".Trim()) { $la['LicenseText'] = "$LicenseText" }
    $lic = Get-PimLicense @la
    $ua = @{ License = $lic; TenantId = $TenantId }; if ($PSBoundParameters.ContainsKey('AdminRows')) { $ua['Rows'] = @($AdminRows); $ua['RowsKnown'] = $true }
    $usage = Get-PimAdminLicenceUsage @ua
    $ma = @{ Role = $(if ($MspRole) { $MspRole } else { 'Master' }); TenantId = $TenantId; SqlServer = $SqlServer }
    if ($la.ContainsKey('LicenseText')) { $ma['LicenseText'] = $la['LicenseText'] }
    if ($PublicCertB64) { $ma['PublicCertB64'] = $PublicCertB64 }
    $m = Test-PimMspLicense @ma
    $pro = [bool](Test-PimLicenseIsProForTenant -License $lic -TenantId $TenantId).pro   # BUG-278: sku + tenant, as the gate
    # ONE-LINE-INSTALL (owner 2026-11-02): a trial / Pro install is deployed WITHOUT a licence, with the Pro updater. Until the
    # licence is added the card says so in one line (the update source the deploy / the updater recorded is Invardia's Pro feed).
    $awaitingLicence = $false
    if ("$($lic.Status)" -eq 'Missing' -and (Get-Command Get-PimSetting -ErrorAction SilentlyContinue)) {
        try {
            $usA = Get-PimSetting -Name 'UpdateState'; if ($usA -is [string]) { $usA = $usA | ConvertFrom-Json }
            $awaitingLicence = [bool]($usA -and (@("$($usA.source)", "$($usA.configuredSource)") | Where-Object { "$_".Trim() -ieq 'invardia' }))
        } catch { $awaitingLicence = $false }
    }
    $statusText = switch ("$($lic.Status)") {
        'Missing' { if ($awaitingLicence) { 'Pro installation -- no licence yet: add your licence here to switch on the Pro features' } else { 'Community (free) -- no Pro licence installed' } }
        'Valid'   { "Pro -- $($lic.Customer) -- valid until $($m.validTo)" }
        'Grace'   { "Pro (grace) -- $($lic.Customer) -- expired $($m.validTo), grace until $($m.graceUntil)" }
        default   { "Community (free) -- licence $($lic.Status): $($lic.Reason)" }
    }
    $state = 'none'
    if ($MspRole) { $state = if (-not $m.ok) { 'refused' } elseif ($m.grace) { 'grace' } else { 'ok' } }
    return [ordered]@{
        status       = "$($lic.Status)"
        statusText   = $statusText
        awaitingLicence = $awaitingLicence
        edition      = $(if ($pro) { $script:PimProEditionName } else { $script:PimCommunityEditionName })
        # Framework §12.6: Pro Business (signed `limits`) | Pro Enterprise | Community; the limits as signed; the admin usage.
        dimension     = "$($usage.dimension)"
        dimensionText = "$($usage.dimensionText)"
        limits        = $(if ($pro -and $null -ne $lic.Limits) { $lic.Limits } else { $null })
        usage         = [ordered]@{ admins = [ordered]@{ cap = $usage.cap; count = $usage.count; percent = $usage.percent; state = $usage.state; message = $usage.message } }
        customer     = "$($lic.Customer)"
        sku          = "$($lic.Sku)"
        features     = @($lic.Features)
        tenantIds    = @($lic.TenantIds)
        boundTenant  = $(if (@($lic.TenantIds).Count) { (@($lic.TenantIds) -join ', ') } else { '' })
        tenantId     = "$TenantId".Trim()
        validTo      = $(if ($lic.ValidTo) { $lic.ValidTo.ToString('yyyy-MM-dd') } else { '' })
        graceUntil   = $(if ($lic.GraceUntil) { $lic.GraceUntil.ToString('yyyy-MM-dd') } else { '' })
        reason       = "$($lic.Reason)"
        mspRequired  = [bool]$MspRole
        mspRole      = $(if ($MspRole -eq 'Slave') { 'slave' } elseif ($MspRole) { 'master' } else { '' })
        mspOk        = $(if ($MspRole) { [bool]$m.ok } else { $true })
        mspState     = $state
        mspReason    = $(if ($MspRole) { "$($m.reason)" } else { '' })
        mspMessage   = $(if ($MspRole) { "$($m.message)" } else { '' })
        contact      = "$script:PimLicenseContact"
        # Free edition (operator 2026-09-26): where "Buy Pro" goes. An https URL from PIM_PRO_BUY_URL (env or global) --
        # anything else is ignored and the page mails the contact instead.
        buyUrl       = $(foreach ($u in @("$($global:PIM_ProBuyUrl)", "$env:PIM_PRO_BUY_URL", "$script:PimProBuyUrlDefault")) { if ("$u".Trim() -match '^https://[^\s"''<>]+$') { "$u".Trim(); break } })
        supportUrl   = "$script:PimProSupportUrl"   # support for paid licences (shown once the environment is Pro)
        command      = "$($m.command)"
        # BUG-277: a Community install that registered a Pro licence and has not got the Pro updater yet -> the page says how.
        upgrade      = $(try { $mk = $null; $us = $null; if (Get-Command Get-PimSetting -ErrorAction SilentlyContinue) { $mk = Get-PimSetting -Name 'EditionUpgrade'; $us = Get-PimSetting -Name 'UpdateState' }; $ug = Get-PimEditionUpgradeState -Marker $mk -UpdateState $us; [ordered]@{ pending = [bool]($pro -and $ug.pending); since = $ug.since; reason = $ug.reason; command = $ug.command } } catch { [ordered]@{ pending = $false; since = ''; reason = ''; command = '' } })
        editionLine  = "Free: the community edition for a single tenant. Pro: the licensed features for a single tenant, and the multi-tenant half (managing tenant / managed tenants). Contact $script:PimLicenseContact."
        # key -> { label; scope; ok; grace; state ok|grace|locked; reason; message } for every Pro feature of the catalog
        # (the GUI's "Pro -- contact" notices). Empty when the catalog is not loaded in this process.
        pro          = $(if (Get-Command Get-PimProFeatureStates -ErrorAction SilentlyContinue) { $pa = @{ TenantId = $TenantId; SqlServer = $SqlServer }; if ($PublicCertB64) { $pa['PublicCertB64'] = $PublicCertB64 }; Get-PimProFeatureStates @pa } else { [ordered]@{} })
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Set-PimLicense / Get-PimLicenseFromStore speak to the store through Get-PimSetting / Set-PimSetting (the
# Manager and the scheduler bind those to their own store). Bind them here to the store this script targets.
$script:PimLicenseImportCs = ''
function Get-PimSetting { param([Parameter(Mandatory)][string]$Name) Get-PimSqlSetting -ConnectionString $script:PimLicenseImportCs -Name $Name }
function Set-PimSetting { param([Parameter(Mandatory)][string]$Name, [object]$Value) Set-PimSqlSetting -ConnectionString $script:PimLicenseImportCs -Name $Name -Value $Value }

function ConvertTo-PimStoredLicenseText {
    # The stored value comes back through ConvertFrom-Json: a string for what this script writes. Anything else
    # (a hand-written object) is re-serialised so it can still be verified.
    param([AllowNull()][object]$Value)
    if ($null -eq $Value) { return '' }
    if ($Value -is [string]) { return "$Value" }
    return (ConvertTo-Json -InputObject $Value -Depth 6 -Compress)
}

function Import-PimLicenseToStore {
    <#
      Verify, store, read back, re-verify. Returns the outcome; THROWS on any failure (a refused document,
      an unreachable store, a read-back mismatch). -PublicCertB64 is the test seam Set-PimLicense already has
      (an ephemeral test key); the script itself never passes it.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$ConnectionString,
        [Parameter(Mandatory)][string]$LicenseText,
        [string]$PublicCertB64,
        [switch]$WhatIfOnly
    )
    $text = "$LicenseText".Trim()
    if (-not $text) { throw 'the licence document is empty' }
    $verifyArgs = @{ LicenseText = $text }
    if ($PublicCertB64) { $verifyArgs['PublicCertB64'] = $PublicCertB64 }

    # 1. Verify BEFORE touching the store: a document that does not verify is never written.
    $pre = Get-PimLicense @verifyArgs
    if ($pre.Status -in @('Invalid','Missing')) { throw "licence NOT stored: $($pre.Reason)" }

    $script:PimLicenseImportCs = $ConnectionString
    # 2. What is there now (reported, so a replacement is visible). A store that cannot be read is not written.
    $prevId = ''
    try {
        $prevText = ConvertTo-PimStoredLicenseText -Value (Get-PimSqlSetting -ConnectionString $ConnectionString -Name 'License')
        if ($prevText) {
            $pv = Get-PimLicense -LicenseText $prevText -PublicCertB64 $(if ($PublicCertB64) { $PublicCertB64 } else { '' })
            $prevId = if ("$($pv.LicenseId)".Trim()) { "$($pv.LicenseId)" } else { '(a stored document that does not verify)' }
        }
    } catch { throw "could not read the store before writing ($($_.Exception.Message)) -- nothing was stored" }

    $out = [ordered]@{ ok = $false; stored = $false; whatIf = [bool]$WhatIfOnly; status = "$($pre.Status)"; reason = "$($pre.Reason)"
                       licenseId = "$($pre.LicenseId)"; customer = "$($pre.Customer)"; sku = "$($pre.Sku)"
                       features = @($pre.Features); tenantIds = @($pre.TenantIds)
                       validTo = $(if ($pre.ValidTo) { $pre.ValidTo.ToString('yyyy-MM-dd') } else { '' }); previousLicenseId = $prevId }
    if ($WhatIfOnly) { $out.ok = $true; return [pscustomobject]$out }

    # 3. Store (Set-PimLicense verifies AGAIN and refuses before writing).
    $setArgs = @{ LicenseText = $text }
    if ($PublicCertB64) { $setArgs['PublicCertB64'] = $PublicCertB64 }
    [void](Set-PimLicense @setArgs)

    # 4. Read back what the containers will read, and verify THAT.
    $back = ''
    try { $back = ConvertTo-PimStoredLicenseText -Value (Get-PimSqlSetting -ConnectionString $ConnectionString -Name 'License') }
    catch { throw "wrote the licence, but could not read it back: $($_.Exception.Message)" }
    if ("$back".Trim() -ne $text) { throw "read-back mismatch: pim.Settings['License'] does not hold the document that was written" }
    $verifyArgs['LicenseText'] = "$back"
    $post = Get-PimLicense @verifyArgs
    if ($post.Status -in @('Invalid','Missing')) { throw "the stored licence does not verify on read-back: $($post.Reason)" }
    $out.ok = $true; $out.stored = $true; $out.status = "$($post.Status)"; $out.reason = "$($post.Reason)"
    return [pscustomobject]$out
}

# Dot-sourced (the offline test): define the functions, run nothing.
if ($MyInvocation.InvocationName -eq '.') { return }

$null = Start-PimScriptRun -Script 'Set-PimLicense'
try {
$result = [ordered]@{ ok = $false; reason = ''; whatIf = [bool]$WhatIfPreference }
function Write-ResultFile { if ("$OutFile".Trim()) { try { $result | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $OutFile -Encoding UTF8 } catch {} } }
function Fail($m) { $result.reason = $m; Write-ResultFile; Write-Host "RESULT: FAILED -- $m" -ForegroundColor Red; exit 1 }
function Note($m, $c = 'Gray') { Write-Host "  $m" -ForegroundColor $c }

Write-Host "=== PIM licence -> pim.Settings['License'] ===" -ForegroundColor Cyan

# --- the document (validated before any connection) ------------------------------------------
if ("$LicensePath".Trim() -and "$LicenseJson".Trim()) { Fail 'supply -LicensePath OR -LicenseJson, not both' }
$doc = ''
if ("$LicensePath".Trim()) {
    if (-not (Test-Path -LiteralPath $LicensePath)) { Fail "no licence file at '$LicensePath'" }
    $doc = Get-Content -LiteralPath $LicensePath -Raw -Encoding UTF8
} elseif ("$LicenseJson".Trim()) {
    $doc = "$LicenseJson"
} else { Fail 'supply -LicensePath (the issued licence file) or -LicenseJson (its content)' }

# --- the store ------------------------------------------------------------------------------
$cs = ''
if ("$ConnectionString".Trim()) {
    if ("$SqlServer".Trim()) { Fail 'supply -ConnectionString OR -SqlServer, not both' }
    $cs = "$ConnectionString"
} elseif ("$SqlServer".Trim()) {
    $global:PIM_SqlServer   = $SqlServer
    $global:PIM_SqlDatabase = $Database
    if ($SqlServer -match '(?i)database\.windows\.net') {
        if (-not "$TenantId".Trim()) { Fail 'an Azure SQL store needs -TenantId (token auth)' }
        if ("$SqlAccessToken".Trim()) {
            if ($UseSignedInAccount -or "$AdminAppId".Trim() -or "$AdminCertThumbprint".Trim() -or "$AdminSecret".Trim()) { Fail '-SqlAccessToken cannot be combined with -UseSignedInAccount or -AdminAppId/-AdminCertThumbprint/-AdminSecret' }
            $global:PIM_TenantId = $TenantId
            $global:PIM_ClientId = $null; $global:PIM_SqlClientId = $null; $global:PIM_CertThumbprint = $null; $global:PIM_SqlCertThumbprint = $null
            $global:PIM_ClientSecret = $null; $global:PIM_SqlClientSecret = $null
            $global:PIM_UseManagedIdentity = $false; $global:PIM_NoManagedIdentity = $true   # never the machine's MI
            $global:PIM_SqlAccessToken = "$SqlAccessToken".Trim()
            Note 'store identity: the supplied SQL access token' 'DarkGray'
        } elseif ($UseSignedInAccount) {
            if ("$AdminAppId".Trim() -or "$AdminCertThumbprint".Trim() -or "$AdminSecret".Trim()) { Fail '-UseSignedInAccount cannot be combined with -AdminAppId/-AdminCertThumbprint/-AdminSecret' }
            try { $who = Connect-PimSignedInSql -TenantId $TenantId; Note "store identity: signed-in user $($who.userName)" 'DarkGray' } catch { Fail "$($_.Exception.Message)" }
        } else {
            if (-not "$AdminAppId".Trim()) { Fail 'supply -AdminAppId with -AdminCertThumbprint or -AdminSecret, or -UseSignedInAccount' }
            if ("$AdminCertThumbprint".Trim() -and "$AdminSecret".Trim()) { Fail 'supply -AdminCertThumbprint OR -AdminSecret, not both' }
            if (-not "$AdminCertThumbprint".Trim() -and -not "$AdminSecret".Trim()) { Fail 'supply -AdminAppId with -AdminCertThumbprint (certificate) or -AdminSecret (client secret)' }
            $global:PIM_TenantId       = $TenantId
            $global:PIM_ClientId       = $AdminAppId
            # Set only the credential supplied and CLEAR the other: a stale global of the opposite kind would win
            # inside Get-PimRestToken's chain (same two lines as Initialize-PimMailSender / Grant-PimMiSql).
            $global:PIM_CertThumbprint = $AdminCertThumbprint
            $global:PIM_ClientSecret   = $AdminSecret
        }
    }
    try { $cs = Get-PimSqlConnectionString -Server $SqlServer -Database $Database }
    catch { Fail "could not build a connection string: $($_.Exception.Message)" }
} else { Fail 'supply -SqlServer (with -Database) or -ConnectionString' }

if ($RequireMspRole) {
    $msp = Test-PimMspLicense -TenantId "$TenantId".Trim() -Role $RequireMspRole -LicenseText $doc
    if (-not $msp.ok) {
        $who = if ($RequireMspRole -eq 'Slave') { 'A managed tenant runs the managing company''s MSP licence (it lists both tenants).' } else { 'The managing tenant needs an MSP licence that lists it.' }
        Fail "this licence cannot run MSP here: $($msp.reason). $who Nothing was stored."
    }
    Note "MSP: $($msp.reason)" 'DarkGray'
}

# --- verify, store, read back ----------------------------------------------------------------
$storeName = $(if ("$SqlServer".Trim()) { "$SqlServer/$Database" } else { 'the store' })
$whatIfOnly = -not $PSCmdlet.ShouldProcess("pim.Settings['License'] in $storeName", 'store the verified licence')
try { $r = Import-PimLicenseToStore -ConnectionString $cs -LicenseText $doc -WhatIfOnly:$whatIfOnly }
catch { Fail "$($_.Exception.Message)" }

foreach ($k in $r.PSObject.Properties.Name) { $result[$k] = $r.$k }
Note ("licence : $($r.licenseId) -- $($r.customer), sku $($r.sku), valid to $($r.validTo)") 'Gray'
Note ("features: " + $(if (@($r.features).Count) { @($r.features) -join ', ' } else { '(none)' })) 'DarkGray'
if (@($r.tenantIds).Count) {
    Note ("bound to: " + (@($r.tenantIds) -join ', ')) 'DarkGray'
    if ("$TenantId".Trim() -and (@($r.tenantIds) -notcontains "$TenantId".Trim())) {
        Note "WARNING: this licence is NOT bound to tenant $TenantId -- Pro features will not unlock on it." 'Yellow'
    }
}
if ("$($r.previousLicenseId)".Trim()) { Note "replaces: $($r.previousLicenseId)" 'Yellow' }
if ($r.status -ne 'Valid') { Note "STATUS: $($r.status) -- $($r.reason)" 'Yellow' }

if ($r.whatIf) {
    Note "What if: would store licence $($r.licenseId) in pim.Settings['License'] ($storeName) and read it back" 'Yellow'
    $keyGiven = [bool]("$InstallKey".Trim() -or "$InstallKeyPath".Trim())
    $claimText = $(if ("$InstallKeyPath".Trim()) { " and the claim state in pim.Settings['InstallKeyClaimState']" } else { '' })
    if ($keyGiven) { Note "What if: would store the install key in pim.Settings['InvardiaInstallKey']$claimText" 'Yellow' }
    elseif ($QueueInstallKeyClaim) { Note "What if: would queue the engine's install-key claim in pim.Settings['SchedulerTriggers']" 'Yellow' }
    $result.ok = $true; $result.reason = "what-if -- the licence verifies ($($r.status)); nothing written"
    Write-ResultFile; Write-Host "RESULT: WHAT-IF -- $($result.reason)" -ForegroundColor Yellow; exit 0
}
$keyFromFile = $false
if ("$InstallKeyPath".Trim()) {
    if ("$InstallKey".Trim()) { Fail 'supply -InstallKey OR -InstallKeyPath, not both' }
    if (-not (Test-Path -LiteralPath $InstallKeyPath)) { Fail 'the install key file does not exist -- not stored' }
    $InstallKey = "$(Get-Content -LiteralPath $InstallKeyPath -Raw)".Trim()
    $keyFromFile = $true
}
if ("$InstallKey".Trim()) {
    if ("$InstallKey".Trim() -notmatch '^inv-[A-Za-z0-9_-]{20,100}$') { Fail 'the install key is not an Invardia install key (inv-...) -- not stored' }
    try {
        Set-PimSqlSetting -ConnectionString $cs -Name 'InvardiaInstallKey' -Value "$InstallKey".Trim()
        if ("$(Get-PimSqlSetting -ConnectionString $cs -Name 'InvardiaInstallKey')".Trim() -ne "$InstallKey".Trim()) { Fail 'read-back mismatch: the install key was not stored' }
        if ($keyFromFile) {
            # The same record Invoke-PimInstallKeyClaimCycle writes after a claim (Settings > Licence shows it).
            Set-PimSqlSetting -ConnectionString $cs -Name 'InstallKeyClaimState' -Value ([pscustomobject][ordered]@{ action = 'claimed'; message = 'install key issued with the enrollment'; atUtc = [datetime]::UtcNow.ToString('o'); licenceHash = '' })
        }
    } catch { Fail "the install key could not be stored: $($_.Exception.Message)" }
    $result['installKey'] = 'stored'
    Note 'install key: stored (the engine uses it; it does not claim another)' 'Gray'
} elseif ($QueueInstallKeyClaim) {
    try {
        $cur = Get-PimSqlSetting -ConnectionString $cs -Name 'SchedulerTriggers'
        $list = @(@($cur) | Where-Object { $null -ne $_ })
        if (-not @($list | Where-Object { "$($_.type)" -eq 'install-key' }).Count) {
            $list += [pscustomobject][ordered]@{ type = 'install-key'; scope = 'All'; reason = 'run-now:install-key (setup: licence registered)'; requestedUtc = [datetime]::UtcNow.ToString('o'); job = 'install-key' }
            # IMP-39: -ValueJson -- a one-element list through -Value is stored as a bare object, not an array.
            Set-PimSqlSetting -ConnectionString $cs -Name 'SchedulerTriggers' -ValueJson (ConvertTo-Json -InputObject @($list) -Depth 6 -Compress)
        }
        $result['installKey'] = 'claim queued'
        Note 'install key: claim queued -- the engine claims it at its next run (within 5 minutes)' 'Gray'
    } catch { Note "install key: the claim could not be queued ($($_.Exception.Message)) -- the engine's install-key job claims it within 6 hours" 'Yellow' }
}
$result.ok = $true
$result.reason = "stored and read back: $($r.licenseId) ($($r.status): $($r.reason))"
Write-ResultFile
Write-Host "RESULT: OK -- $($result.reason)" -ForegroundColor Green
Write-Host "  NOTE: the containers cache the licence per process; it is picked up on the next start/roll." -ForegroundColor DarkGray
exit 0
} finally { Stop-PimScriptRun -Script 'Set-PimLicense' }