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


<#
.SYNOPSIS
  Set up the shared mailbox PIM Manager sends its notification mail from: create the mailbox, give each sending identity a send right scoped to that one mailbox (Exchange RBAC for applications), remove any tenant-wide Microsoft Graph Mail.Send from those identities, and store the sender in the PIM store.

.DESCRIPTION
  IMP-06 / MAIL-1 -- make an environment able to send its own notification mail, UNATTENDED.
  Run it with -WhatIf first: it signs in, reads, and prints every change it would make (mailbox, Exchange
  registration, scope, scoped send right, revoked tenant-wide Mail.Send, the stored setting) without making any.

  Operator directive 2026-08-12: *"the onboarding scripts must handle this prep unattended"*. Doing
  these steps by hand in a portal is the DEFECT, not the workaround: every future tenant would
  otherwise land in the state a test tenant was in -- engine provisions fine, mail never sends, and nothing
  reports an error.

  Why "nothing reports an error" is the whole point. With no sender configured the notify path
  RENDERS the mail and returns without sending (PIM-Notify.ps1 L201, a warning only), while account
  creation and TAP minting still report success. A mail-mute environment therefore looks completely
  healthy, and the first symptom is a TAP that never arrives -- days later, blamed on the TAP
  provider. That is why the precondition below FAILS LOUDLY rather than warning.

  Four steps, each idempotent and each VERIFIED BY READING BACK rather than by trusting its own
  create call:

    0. PRECONDITION -- the tenant must have a real Exchange Online plan.
       🪤 `assignedPlans` reporting `exchange = Enabled` is NOT the signal. EXCHANGE_S_FOUNDATION
       rides along with Entra P2 and reports exactly that while mailbox creation is impossible --
       it provisions directory objects only. The signal is an Exchange service plan in
       `subscribedSkus` BEYOND Foundation (e.g. EXCHANGE_S_STANDARD). Measured on a test tenant: the org
       looked mail-capable and `New-Mailbox -Shared` would still have failed, for a reason the
       status does not hint at.
    1. CREATE THE SHARED SENDER MAILBOX (default `PIM-Engine@<initial domain>`). A shared mailbox
       is the designed sender and is FREE once an EXO plan exists -- admin accounts themselves need
       no mailbox and no licence, because the engine mails *about* them, not *as* them.
    2. GRANT SEND ACCESS *SCOPED TO THAT ONE MAILBOX*, via Exchange RBAC for Applications.
    3. ENSURE NO TENANT-WIDE Graph `Mail.Send` CONSENT EXISTS -- revoking it if it does.

  ⚠️ STEPS 2 AND 3 ARE INVERTED FROM IMP-06 AS WRITTEN, and the inversion is load-bearing.
  The finding said "grant Mail.Send, then scope it with an Application Access Policy". Measured in
  a test tenant, doing exactly that leaves the app UNSCOPED: Exchange RBAC does not RESTRICT a tenant-wide
  Graph consent, it GRANTS scoped access in its own right, and a tenant-wide consent alongside it
  keeps winning. Proven both directions, ~60 minutes apart so propagation is not the explanation:
    * WITH the Graph consent    -- in-scope send ACCEPTED, out-of-scope send ACCEPTED  (unscoped)
    * WITHOUT the Graph consent -- in-scope send ACCEPTED, out-of-scope send DENIED    (scoped)
  So the right configuration grants NO tenant-wide permission at all. That is strictly better than
  the finding asked for: there is never a tenant-wide send right to claw back.

  🔒 WHICH IDENTITY DOES THE WORK, and why it is not the obvious one.
  Exchange administration is done by the ONBOARDING SPN (-AdminAppId plus -AdminSecret OR
  -AdminCertThumbprint; a certificate is the preferred form), never by the
  engine SPN. The obvious-looking alternative -- grant the engine SPN `Exchange.ManageAsApp` + the
  Exchange Administrator directory role -- hands the LONG-LIVED RUNTIME identity tenant-wide
  Exchange administration in order to create a single mailbox. That is a strictly BIGGER grant than
  the Application Access Policy in step 3 exists to claw back, so it would defeat the finding it is
  meant to implement. The onboarding SPN is a provisioning-time credential that already elevates
  itself to Global Administrator + Owner, so it is the correct holder of a transient Exchange grant.
  Net result: the engine SPN ends up with `Mail.Send` SCOPED TO ONE MAILBOX and nothing else.

  Measured on a test tenant before this script existed: the engine SPN held ~100 Graph app-roles but NOT
  Mail.Send, NOT Exchange.ManageAsApp, and no directory role at all -- its EXO token came back with
  an empty `roles` claim and the admin endpoint answered 401.

  REST-only: no ExchangeOnlineManagement module, no Graph SDK, no command-line tools. Exchange is driven through
  the `/adminapi/beta/<tenant>/InvokeCommand` endpoint that the EXO V3 module itself uses.

  🔒 HOW IT SIGNS IN (MAIL-1, framework 12.3, owner 2026-10-08: "we dont use certificates here, either interactive
  login or secret. not certificates"). Four ways, decided before anything is touched (Resolve-PimMailSetupAuthMode):
    * nothing passed           -> BROWSER sign-in (the default for a person): an Exchange or Global Administrator signs
                                  in in Edge (auth code + PKCE on localhost, no device code, no module). The person acts
                                  with their OWN Exchange role -- no app is granted Exchange.ManageAsApp or a directory
                                  role, so that whole step is skipped. -AdminAppId is not needed.
    * -AdminAppId -AdminSecret -> the Invardia Support app (the setup / support identity; its secret is the one
                                  allowed exception, framework 4.1a). It activates its own time-boxed Exchange
                                  Administrator through PIM.
    * -UseSignedInAccount      -> the signed-in session of this window: the Invardia Support session when one is
                                  open for this tenant, otherwise the person's own browser sign-in.
    * -AdminCertThumbprint     -> still accepted for old callers; never what a page or a document prints.
  Published standalone at https://invardia.com/support/pim/Initialize-PimMailSender.ps1 (Build-PimSupportScripts.ps1).

.PARAMETER OutFile
  Where to write the result JSON ({ ok, sender, ... }). This is how a calling deploy gets the sender
  UPN back: each setup step runs in its OWN process with stdout redirected to a log, so a
  return value cannot travel any other way.

.PARAMETER MailboxName
  The mailbox name (the part before the @) -- your company's naming. Default PIM-Engine.

.PARAMETER MailDomain
  The mailbox domain, one of the tenant's verified domains. Default: the tenant's initial (onmicrosoft.com) domain.

.PARAMETER DisplayName
  The mailbox display name (what recipients see as the sender). Default 'PIM Manager'.

.PARAMETER ScopeName
  The Exchange management scope name. Default '<MailboxName>-SendScope'; an existing scope for this mailbox is kept.

.PARAMETER AssignmentNamePrefix
  The prefix of the Exchange role-assignment names ('<prefix>-<short id>-MailSend'). Default: the mailbox name.

.PARAMETER AllowThisIpTemporarily
  Opt-in: if the PIM database refuses this computer (SQL firewall), add a temporary rule for this IP, save the sender,
  and always remove the rule again. Without it, no firewall rule is changed and PIM Manager finishes the step.

.EXAMPLE
  # A person (Exchange or Global Administrator), browser sign-in -- what PIM Manager's Get Started prints:
  .\Initialize-PimMailSender.ps1 -TenantId <tid> -MailboxName pim-notify -MailDomain contoso.com -DisplayName 'PIM notifications' `
       -ManagedIdentityObjectId <managerMiObjectId>,<tickMiObjectId> -SqlServerFqdn <server>.database.windows.net

.EXAMPLE
  # From another process (a deploy step, a scheduled task): `pwsh -File` passes every argument as a
  # STRING, so a PowerShell array literal ('a','b') arrives as ONE value. Pass several managed
  # identities comma-separated with no quotes or spaces -- the script splits and validates them.
  pwsh -NoProfile -File tools\setup\Initialize-PimMailSender.ps1 -TenantId <tid> -AdminAppId <supportAppId> `
       -AdminSecret <secret> -ManagedIdentityObjectId <tickMiObjectId>,<managerMiObjectId> `
       -SqlServerFqdn <server>.database.windows.net

.NOTES
  Requirements:
    PowerShell: 7.0 or later (pwsh). Windows PowerShell 5.1 is not supported.
    Role: Exchange Administrator or Global Administrator (Microsoft Entra, active), and Privileged Role Administrator
          or Cloud Application Administrator for the grants on the sending identities. To store the sender
          (-SqlServerFqdn): member of the environment's SQL admin group. With -TickJobName / -ManagerAppName: Reader on
          those container apps (Azure).
    Hosts: login.microsoftonline.com, graph.microsoft.com, outlook.office365.com, management.azure.com (only with
           -TickJobName / -ManagerAppName / -AllowThisIpTemporarily), *.database.windows.net (only with -SqlServerFqdn),
           *.vault.azure.net (only with -KeyVaultName)

    PERMISSIONS AND CHANGES (from Initialize-PimMailSender.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Initialize-PimMailSender/)
    The person running it needs:
      - Exchange Administrator (or Global Administrator) [entraRole, the tenant (an ACTIVE assignment -- activate it first if it is eligible)] -- Browser sign-in (the default): the person's own Exchange role creates the mailbox, the Exchange registrations, the management scope and the scoped Application Mail.Send assignments. No app is granted any Exchange right in this mode.
      - Delegated Microsoft Graph consent: Organization.Read.All, Application.Read.All, User.Read.All, AppRoleAssignment.ReadWrite.All (public client Microsoft Graph Command Line Tools) [other, the signed-in person, this tenant] -- Reads the Exchange plan (subscribedSkus), the initial domain (organization), the sending identities' service principals and the mailbox's directory user; AppRoleAssignment.ReadWrite.All is used only to remove a tenant-wide Mail.Send. The consent prompt appears at the first sign-in when the tenant has not consented yet.
      - Privileged Role Administrator, Cloud Application Administrator or Global Administrator [entraRole, the tenant] -- Only when a sending identity or the engine identity still holds a tenant-wide Microsoft Graph Mail.Send: removing an application permission needs one of these roles besides the delegated AppRoleAssignment.ReadWrite.All. An Exchange Administrator alone can do every other step.
      - Reader [azureRbac, the Container Apps job and/or Manager container app named by -TickJobName / -ManagerAppName (or their resource group)] -- Only with -SubscriptionId -ResourceGroup -TickJobName / -ManagerAppName: reads the app's managed identity so its object id does not have to be typed.
      - Member of the environment's SQL admin group (grp-pim-sql-admins) [other, the environment's SQL database (pim.Settings)] -- Only with -SqlServerFqdn: stores MailSender and MailMode. From a computer that cannot reach the store this step is reported as 'Saved: no ... Finish in PIM Manager' (Get Started > Mail sender > Check and send a test mail) and is not a failure in the browser sign-in -- or, with -AllowThisIpTemporarily, a temporary firewall rule is added (see below).
      - SQL Server Contributor (or Contributor) [azureRbac, the environment's SQL server] -- Only with -AllowThisIpTemporarily: adds a temporary firewall rule for the refused IP and removes it again in the same run.
      - Invardia Support app (-AdminAppId + -AdminSecret) holding Microsoft Graph application permissions AppRoleAssignment.ReadWrite.All and RoleManagement.ReadWrite.Directory [other, the tenant] -- Only for the unattended support / deploy path instead of a person: the app gives ITSELF Exchange.ManageAsApp and activates a time-bound Exchange Administrator through PIM (see changes). When the app cannot grant itself, a Global Administrator signs in in the browser for those two grants only.
    What it creates, changes or grants:
      - create shared mailbox <MailboxName>@<initial domain> (New-Mailbox -Shared; default PIM-Engine@<tenant>.onmicrosoft.com, display name 'PIM Manager') (Exchange Online) @ the tenant -- The address PIM Manager sends its notifications from. A shared mailbox needs no licence and no password; nobody signs in to it. Undo: Remove the mailbox (Exchange admin center > Mailboxes, or Remove-Mailbox) -- PIM Manager then stops sending mail.
      - create Exchange registration of each sending identity (New-ServicePrincipal with the identity's app id and object id): the engine job's and the Manager's managed identity, or the engine application when no managed identity sends (Exchange Online) @ the tenant's Exchange organization -- Exchange RBAC for applications can only assign a role to a service principal Exchange knows. Undo: Remove-ServicePrincipal -Identity <app id> (after removing its role assignment).
      - create management scope -ScopeName (default <MailboxName>-SendScope; a scope that already restricts to this mailbox -- e.g. PIM4EntraPS-Sender from an earlier release -- is kept under its own name, never duplicated) with RecipientRestrictionFilter PrimarySmtpAddress -eq '<sender>' (New-ManagementScope) (Exchange Online) @ exactly one recipient: the sender mailbox -- Limits the send right below to this one mailbox. A scope that already exists for ANOTHER mailbox is never reused or changed (the run stops instead). Undo: Remove-ManagementScope -Identity <scope name> (after removing the assignments that use it).
      - grant each sending identity (New-ManagementRoleAssignment, name <AssignmentNamePrefix>-<short id>-MailSend or <AssignmentNamePrefix>-App-MailSend; an assignment the identity already holds -- e.g. PIM4EntraPS-MI-<id>-MailSend -- is kept, never duplicated) (Exchange Online): Exchange role 'Application Mail.Send' (Exchange RBAC for applications) @ the management scope above = the sender mailbox only -- Lets PIM Manager's engine and Manager send as that one mailbox and no other. This is the ONLY send right the script grants -- there is no tenant-wide Mail.Send. Undo: Remove-ManagementRoleAssignment -Identity <assignment name>.
      - remove a sending identity's Application Mail.Send assignment on ANOTHER sender scope of PIM Manager (<mailbox>-SendScope or PIM4EntraPS-Sender*; Remove-ManagementRoleAssignment) -- and, only with -RemoveEngineSpnAssignment, the engine application's older assignment on this scope (Exchange Online) @ the one assignment named -- An identity scoped to another environment's mailbox would send as the wrong mailbox (assignment names are tenant-unique, so the right one cannot be created beside it). The engine application's own older assignment is left in place unless explicitly asked. Undo: Re-create it with New-ManagementRoleAssignment (same name, role, app and scope).
      - update the organization: Enable-OrganizationCustomization -- only when the organization is still 'dehydrated' (Exchange Online) @ the tenant's Exchange organization -- A new Exchange organization refuses every custom RBAC object until customization is enabled. Undo: None -- Microsoft offers no way back, and it changes nothing visible.
      - remove application permission (app role assignment) Microsoft Graph Mail.Send held TENANT-WIDE by a sending identity or the engine identity (Microsoft Graph) @ the tenant (the assignment being removed was tenant-wide) -- A tenant-wide Mail.Send lets the identity send as ANY mailbox and silently defeats the per-mailbox scope above (measured: with it, an out-of-scope send is accepted). Removing it makes the scope govern. Undo: Not recommended. Re-grant Mail.Send (application) to that identity in Entra admin center > Enterprise applications > the identity > Permissions.
      - update pim.Settings rows MailSender (the mailbox's directory UPN -- the key Microsoft Graph sends as) and MailMode = sharedMailbox, MailSenderAddress (the mailbox's primary SMTP address -- the address you chose -- that PIM Manager shows, with the UPN as detail), plus MailSenderSetupCheck (the read-back that confirmed the scoped Mail.Send for every sending identity in one scope, so PIM Manager shows the engine job's send right as granted once its own test mail works) (PIM store (Azure SQL)) @ this environment -- Only with -SqlServerFqdn. The engine and the Manager read the sender from here; without it the mail is rendered and never sent. Undo: PIM Manager > Settings > Mail & alerting: choose another sender or mode.
      - create a TEMPORARY firewall rule PimSetupTemp-<ip>-<utc time> for exactly the refused IP -- only with -AllowThisIpTemporarily and only when the store refused this computer (Azure SQL server) @ the environment's SQL server, one IP -- Lets this computer store the sender when the SQL firewall refuses it. Removed again in the same run (finally), whether the write worked or not; a rule that could not be removed is reported with its name. Undo: It is removed by the run. If the run reports it could not: SQL server > Networking > remove the PimSetupTemp-* rule.
      - grant the setup app itself (-AdminAppId) (Microsoft Graph (Invardia Support app sign-in only)): Exchange.ManageAsApp (application permission of Office 365 Exchange Online) @ the tenant -- App-only Exchange administration needs it. Not used and not granted in the browser sign-in. It has no expiry but is inert without the directory role below. Undo: Entra admin center > Enterprise applications > the setup app > Permissions: remove Exchange.ManageAsApp.
      - grant the setup app itself (-AdminAppId), through PIM (roleAssignmentScheduleRequests, time-bound) (Microsoft Entra ID (Invardia Support app sign-in only)): Exchange Administrator directory role (active, -ExchangeAdminDuration, default PT4H) @ the tenant -- Exchange accepts the app's admin calls only while it holds an Exchange role. Granted through PIM so it EXPIRES by itself; an assignment that is already active is reused, and one that lasts longer than asked is reported as standing privilege. Undo: It expires by itself. To end it sooner: Entra admin center > Roles > Exchange Administrator > Active assignments > remove (a different administrator: an identity cannot remove its own role).
      - grant the setup app itself (-AdminAppId) -- self-heal, only when it does not hold it yet (Microsoft Graph (Invardia Support app sign-in only)): RoleManagement.ReadWrite.Directory (application permission of Microsoft Graph) @ the tenant -- Needed to read and request the time-bound Exchange Administrator role above. A setup identity created before 2026-09-26 lacks it; it holds AppRoleAssignment.ReadWrite.All, which is exactly the right to add it. Undo: Entra admin center > Enterprise applications > the setup app > Permissions: remove RoleManagement.ReadWrite.Directory.
      - create the result file named by -OutFile (JSON: ok, sender, steps, privileged grants); a transcript in <temp>\pim-manager-logs (This computer) @ this computer -- -OutFile: how a deploy step reads the outcome. The transcript is the local record of what the run did (no secret values). Undo: Delete the files.
    -WhatIf: Signs in and reads everything above, then prints every change it would make: the mailbox to create, each Exchange registration, the scope and each scoped Application Mail.Send assignment, each tenant-wide Mail.Send it would remove, organization customization when needed, and the MailSender / MailMode it would store -- and makes none of them (no Exchange create or remove, no Graph write, no SQL connection). With the Support app sign-in, the app's own grants (Exchange.ManageAsApp, the time-bound Exchange Administrator) are previewed too; Exchange may then not be usable for the preview yet, which the run says ('steps [1]-[3] cannot be previewed; run without -WhatIf to apply').
    Undo: In Exchange Online: Remove-ManagementRoleAssignment for each *-MailSend assignment the run reported, Remove-ManagementScope <the scope it reported> (default <MailboxName>-SendScope; PIM4EntraPS-Sender on an install from before 2.4.538), Remove-ServicePrincipal for each registered identity, then remove the shared mailbox. In PIM Manager: Settings > Mail & alerting (another sender or mode). With the Support app sign-in also remove Exchange.ManageAsApp and RoleManagement.ReadWrite.Directory from the setup app if no longer wanted (the Exchange Administrator role expires by itself). A removed tenant-wide Mail.Send is not restored on purpose.

  RE-RUNNING IS SAFE. Every step reads first and treats "already there" as success; a read that
  FAILS (as opposed to finding nothing) stops the run instead of guessing that the object is absent.
  A re-run on a fully configured tenant changes nothing in Exchange -- it only re-activates the
  short-lived Exchange Administrator role (through PIM) it needs in order to read.

  🪤 An Application Access Policy can take up to ~30 minutes to take effect tenant-wide. A send
  attempted immediately after this script may still fail; that is Microsoft-side propagation, not a
  misconfiguration. The policy is verified as EXISTING here, which is what this script can honestly
  assert.

  PERMISSIONS (full list with scope, reason and undo: Initialize-PimMailSender.doc.json / the documentation page)
    The person running it: Exchange Administrator or Global Administrator (browser sign-in); to store the sender,
    membership of the SQL server's admin group. With -AdminAppId + -AdminSecret the Invardia Support app needs
    AppRoleAssignment.ReadWrite.All + RoleManagement.ReadWrite.Directory to give itself the transient grants below.
    It creates / grants: the shared mailbox (New-Mailbox -Shared); per sending identity New-ServicePrincipal (Exchange
    registration) and New-ManagementRoleAssignment 'Application Mail.Send' on a New-ManagementScope that matches ONLY
    the sender mailbox; it REMOVES a tenant-wide Graph Mail.Send (application) from the sending identities and the
    engine identity; it writes MailSender + MailMode to pim.Settings. App sign-in only: Exchange.ManageAsApp (app role)
    and a time-bound Exchange Administrator (through PIM) on the setup app itself, and RoleManagement.ReadWrite.Directory
    (self-heal) when the setup app lacks it.
    Transcript: <temp>\pim-manager-logs\Initialize-PimMailSender-<utc>.log (path printed at the start and the end).

.LINK
    https://invardia.com/docs/pim/scripts/Initialize-PimMailSender/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)][string]$TenantId,
    # The ONBOARDING SPN -- privileged, provisioning-time. See the identity note above. Not needed (and refused alone)
    # for the browser sign-in: the person who signs in acts with their own Exchange role.
    [string]$AdminAppId,
    # ONE of these. 🔴 The secret used to be Mandatory, which made a CLIENT SECRET structurally
    # required to provision the sender mailbox -- against the repo-root rule ("authenticate as its
    # SPN using a CERTIFICATE, never a client secret") and unsatisfiable where the onboarding SPN
    # is cert-only. Grant-PimMiSql was fixed for exactly this on 2026-08-09; this script was not,
    # and neither were Initialize-PimTenantStore.ps1 or Setup-PimMsp.ps1 -- three instances of one
    # defect, which is why the offline gate now audits the whole family instead of naming them.
    [string]$AdminSecret,
    [string]$AdminCertThumbprint,
    # 2026-10-07 (operator, at a customer: "you are welcome to fix this at <customer>"): run as the SIGNED-IN session
    # instead -- the Invardia Support session open in this window (Connect-InvardiaSupport), else the person's browser
    # sign-in (framework 12.17: one sign-in rule, _PimSignedIn.ps1) -- with no secret or certificate passed. -AdminAppId is then the signed-in app (it activates its own short-lived Exchange Administrator role).
    [switch]$UseSignedInAccount,
    # The engine SPN. It receives the scoped Mail.Send ONLY when no managed identity is named below
    # (a non-hosted engine sends as the SPN). With a managed identity it is still checked for a
    # tenant-wide Graph Mail.Send. Read from the environment's own Key Vault ('Modern-AppId') when
    # not supplied and no managed identity is given.
    [string]$EngineAppId,
    # 🔒 THE HOSTED SENDER (REQUIREMENTS 65.11, operator decision 2026-09-13): the container sends as
    # its MANAGED IDENTITY, so the scoped assignment must name that identity -- the tick job's, and
    # the Manager's when it sends alerts. Service-principal OBJECT ids (the resource's
    # identity.principalId). A non-managed-identity object is refused.
    [string[]]$ManagedIdentityObjectId = @(),
    # Or resolve the tick job's managed identity by ARM REST (read only), by the same rule the
    # engine's token call uses (PIM_ManagedIdentityClientId -> that user-assigned identity, else
    # system-assigned).
    [string]$SubscriptionId,
    [string]$ResourceGroup,
    [string]$TickJobName,
    # MAIL-1: and the Manager container app's (it sends the alert notices) -- same ARM read, same rule.
    [string]$ManagerAppName,
    # EXPLICIT, off by default: also remove the older scoped assignment that names the engine SPN.
    # Left in place by default -- it is scoped to the same single mailbox, so it widens nothing,
    # and removing a working send right is the operator's call, not a side effect.
    [switch]$RemoveEngineSpnAssignment,
    [string]$KeyVaultName,
    [string]$BootstrapAppId,
    [string]$BootstrapThumbprint,
    # MAIL-NAMING (100.14, owner 2026-10-09: "companies have their own naming"): the company names the mailbox.
    # Local part of the sender mailbox. The domain is the tenant's initial (onmicrosoft.com) domain
    # unless -MailDomain says otherwise -- a freshly-onboarded tenant has no custom domain, and
    # guessing one produces a mailbox nobody can receive from. A mailbox that already exists under that address is
    # used as it is (not created again). PIM Manager's Get Started > Mail sender prints the command with these filled in.
    [string]$MailboxName  = 'PIM-Engine',
    [string]$MailDomain,
    [string]$DisplayName  = 'PIM Manager',
    # The Exchange names this script creates, also the company's: the management scope (default '<MailboxName>-SendScope')
    # and the role-assignment name prefix (default <MailboxName> -> '<prefix>-<short id>-MailSend'). A scope that already
    # restricts to this mailbox, and assignments already held by the sending identities, are KEPT under their existing
    # names (an install from before 2.4.538: 'PIM4EntraPS-Sender', 'PIM4EntraPS-MI-<id>-MailSend') -- never duplicated.
    [string]$ScopeName,
    [string]$AssignmentNamePrefix,
    # Opt-in, off by default: when the store refuses this computer's IP (the Azure SQL firewall), add a TEMPORARY firewall
    # rule for exactly that IP, write the sender, and ALWAYS remove the rule again (finally). Needs the signed-in person's
    # (or app's) Azure rights on the SQL server; honours -WhatIf / -Confirm. Without it no firewall is changed.
    [switch]$AllowThisIpTemporarily,
    # Where the sender is PERSISTED (IMP-06a runtime half). Writing it to pim.Settings is what lets
    # this script run AFTER the containers are already deployed: the store overrides the deploy-time
    # env var and a cold-booted tick Job hydrates it on its next run, so no redeploy is needed.
    # Optional -- without it the sender still travels via -OutFile / -MailSender at deploy time.
    [string]$SqlServerFqdn,
    [string]$SqlDatabase  = 'PimPlatform',
    [string]$OutFile,
    # Exchange provisioning after a licence lands is not instant, and neither is app-role
    # propagation. Bounded, and it reports what it waited for rather than hanging silently.
    [int]$TimeoutSeconds  = 600,
    # IMP-31 (2026-09-18): how long the onboarding SPN's Exchange Administrator role stays ACTIVE. The
    # role is now granted THROUGH PIM as a time-bound assignment that expires on its own -- it used to be
    # a permanent assignment outside PIM, which the SPN could not remove again (Graph refuses a self-
    # removal) and which the tenant's alerting flagged. ISO 8601, PT15M..PT24H.
    [string]$ExchangeAdminDuration = 'PT4H',
    # INSTALL-HARDEN-1 item 4: how long to wait for a just-hydrated Exchange organization that still refuses RBAC creates
    # ("you must be assigned a delegating role assignment"; measured ~40-60 min), and how often to try again.
    [ValidateRange(0, 240)][int]$ExchangeReadyMinutes = 75,   # 0 = do not wait (the install defers the mail sender instead, 2026-10-10)
    [ValidateRange(10, 900)][int]$ExchangeReadyIntervalSeconds = 150,
    # one plain progress line per wait (the deploy forwards it to the install's reporter as a 'waiting' event)
    [scriptblock]$OnProgress
)

$ErrorActionPreference = 'Stop'

$here = if ($PSScriptRoot) { $PSScriptRoot } else { Split-Path -Parent $MyInvocation.MyCommand.Path }
# Every helper is dot-sourced by a literal path relative to this script's folder, so Build-PimSupportScripts.ps1 can
# inline it: the published file at https://invardia.com/support/pim/Initialize-PimMailSender.ps1 is ONE standalone script.
# 2.4.648 (Invardia's 2.4.647 handover review): the published file loaded PIM-SignedRequests.ps1 from its own folder when
# such a file sat there -- a code-injection path on a customer's machine. The next line tells the build to leave out every
# OPTIONAL load the inlined engine libraries end with, and to fail on any load left (as Set-PimLicense / Grant-PimSupportSqlAccess).
# 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: _PimMailSenderPlan.ps1 =====
<#
.SYNOPSIS
  PURE decision cores for the mail send right (REQUIREMENTS 65.11). No network, no state.

.DESCRIPTION
  Operator decision 2026-09-13: the HOSTED engine sends as its MANAGED IDENTITY. The scoped
  Exchange 'Application Mail.Send' assignment (Exchange RBAC for Applications, pinned to the
  sender mailbox by a management scope) must therefore name the identity that actually sends --
  the tick job's managed identity, plus the Manager's when it sends alerts -- not only the
  engine SPN. Until now the assignment named the SPN while the container sent as its managed
  identity: two different principals.

  Shared by tools/setup/Initialize-PimMailSender.ps1 (which EXECUTES the plan),
  tools/setup/Invoke-PimDeployAll.ps1 (which resolves the tick job's identity) and
  tools/setup/Test-PimTenantReady.ps1 (which checks no sending identity holds a tenant-wide
  Graph Mail.Send). Dot-sourceable: defines functions only.
#>
# 12.7 / 12.10 item 11: the command for the person (New-PimMailSenderCommand) is the save-verify-preview-run form with the
# documentation link -- built by _PimScriptDoc.ps1, loaded here so EVERY loader of this file has it (Confirm-PimInstall,
# Invoke-PimDeployAll, Install-PimEngineAppRegistration, Test-PimTenantReady, the mail scripts).
# (helper _PimScriptDoc.ps1 already inlined above)


function Get-PimJobManagedIdentityPrincipalId {
    <#
      Which managed identity a Container Apps job's engine really authenticates as.
      The engine's token call uses PIM_ManagedIdentityClientId when the job carries it
      (user-assigned) and the system-assigned identity otherwise (PIM-Rest.ps1
      Get-PimManagedIdentityToken). Picking by the same rule is the only way the send right lands
      on the identity that sends.
      Input: the job resource (ARM GET of the Container Apps job). Returns
      { principalId; kind = system|user; reason }; reason non-empty = could not decide.
    #>
    [CmdletBinding()] param([object]$Job, [string]$ManagedIdentityClientId = '')
    if ($null -eq $Job) { return [pscustomobject]@{ principalId = ''; kind = ''; reason = 'no job resource was supplied' } }
    $cid = "$ManagedIdentityClientId".Trim()
    if (-not $cid) {
        foreach ($c in @($Job.properties.template.containers)) {
            foreach ($e in @($c.env)) { if ("$($e.name)" -eq 'PIM_ManagedIdentityClientId' -and "$($e.value)".Trim()) { $cid = "$($e.value)".Trim() } }
        }
    }
    $ids = $Job.identity
    $ua = @()
    if ($ids -and $ids.userAssignedIdentities) {
        foreach ($p in $ids.userAssignedIdentities.PSObject.Properties) {
            $ua += [pscustomobject]@{ resourceId = $p.Name; clientId = "$($p.Value.clientId)"; principalId = "$($p.Value.principalId)" }
        }
    }
    if ($cid) {
        $hit = @($ua | Where-Object { $_.clientId -eq $cid })
        if ($hit.Count -eq 1 -and $hit[0].principalId) { return [pscustomobject]@{ principalId = $hit[0].principalId; kind = 'user'; reason = '' } }
        return [pscustomobject]@{ principalId = ''; kind = ''; reason = "the job sets PIM_ManagedIdentityClientId=$cid but carries no user-assigned identity with that client id" }
    }
    if ($ids -and "$($ids.principalId)".Trim()) { return [pscustomobject]@{ principalId = "$($ids.principalId)".Trim(); kind = 'system'; reason = '' } }
    if ($ua.Count -eq 1 -and $ua[0].principalId) {
        # With a user-assigned identity ONLY and no client id, IDENTITY_ENDPOINT issues no token
        # (BUG-76), so the engine cannot send at all -- named, not papered over.
        return [pscustomobject]@{ principalId = ''; kind = ''; reason = "the job has only a user-assigned identity ($($ua[0].clientId)) and no PIM_ManagedIdentityClientId -- the engine gets no managed-identity token (BUG-76); set PIM_ManagedIdentityClientId on the job first" }
    }
    return [pscustomobject]@{ principalId = ''; kind = ''; reason = 'the job has no managed identity' }
}

function Resolve-PimMailSendPrincipals {
    <#
      The identities that RECEIVE the scoped send right, from already-fetched Graph service
      principals. Managed identities first (the hosted senders); the engine SPN only when no
      managed identity was named (a non-hosted topology sends as the SPN).
      A managed-identity object id that resolves to something that is NOT a managed identity is
      REFUSED: the parameter must never become a way to hand a send right to an arbitrary app.
      Returns { principals = @({ kind; appId; objectId; displayName; assignmentName }); reason }.
    #>
    # MAIL-NAMING (100.14, owner 2026-10-09: "companies have their own naming"): the Exchange names follow the company's
    # mailbox -- -AssignmentNamePrefix (default: the mailbox name) -> '<prefix>-<short id>-MailSend'. The names earlier
    # releases forced on every tenant ('PIM4EntraPS-MI-<short id>-MailSend', 'PIM4EntraPS-Engine-MailSend') travel along
    # as legacyAssignmentNames, so an existing assignment is RECOGNISED (adopted), never duplicated.
    [CmdletBinding()] param([object[]]$ManagedIdentitySps = @(), [object]$EngineSp, [string]$AssignmentNamePrefix = 'PIM-Engine')
    $pfx = ConvertTo-PimExoNamePart -Value $AssignmentNamePrefix
    if (-not $pfx) { $pfx = 'PIM-Engine' }
    $out = New-Object System.Collections.Generic.List[object]
    foreach ($sp in @($ManagedIdentitySps | Where-Object { $null -ne $_ })) {
        $type = "$($sp.servicePrincipalType)".Trim()
        if ($type -and $type -ne 'ManagedIdentity') {
            return [pscustomobject]@{ principals = @(); reason = "object $($sp.id) is a '$type' service principal, not a managed identity -- refusing to grant it the send right" }
        }
        if (-not "$($sp.appId)".Trim() -or -not "$($sp.id)".Trim()) {
            return [pscustomobject]@{ principals = @(); reason = 'a managed identity service principal without appId/id cannot be registered in Exchange' }
        }
        $oid = "$($sp.id)".Trim()
        $short = $oid.Substring(0, [Math]::Min(8, $oid.Length))
        $out.Add([pscustomobject]@{ kind = 'managed-identity'; appId = "$($sp.appId)".Trim(); objectId = $oid
                                    displayName = ("{0} sender {1}" -f $pfx, $short)
                                    assignmentName = ("{0}-{1}-MailSend" -f $pfx, $short)
                                    legacyAssignmentNames = @(("PIM4EntraPS-MI-{0}-MailSend" -f $short)) })
    }
    if ($out.Count -eq 0 -and $null -ne $EngineSp -and "$($EngineSp.appId)".Trim()) {
        $out.Add([pscustomobject]@{ kind = 'engine-spn'; appId = "$($EngineSp.appId)".Trim(); objectId = "$($EngineSp.id)".Trim()
                                    displayName = ("{0} sender (engine app)" -f $pfx); assignmentName = ("{0}-App-MailSend" -f $pfx)
                                    legacyAssignmentNames = @('PIM4EntraPS-Engine-MailSend') })
    }
    if ($out.Count -eq 0) {
        return [pscustomobject]@{ principals = @(); reason = 'no sending identity: pass -ManagedIdentityObjectId (hosted: the tick job''s managed identity), -SubscriptionId/-ResourceGroup/-TickJobName to resolve it, or -EngineAppId for a non-hosted engine' }
    }
    return [pscustomobject]@{ principals = $out.ToArray(); reason = '' }
}

function Get-PimExoAssigneeIds {
    # Every string Exchange may use to name one service principal in a role assignment.
    [CmdletBinding()] param([object[]]$ExoServicePrincipals = @(), [string]$AppId, [string]$ObjectId)
    $ids = New-Object System.Collections.Generic.List[string]
    foreach ($v in @($AppId, $ObjectId)) { if ("$v".Trim()) { $ids.Add("$v".Trim().ToLowerInvariant()) } }
    foreach ($s in @($ExoServicePrincipals | Where-Object { $null -ne $_ })) {
        if ("$($s.AppId)".Trim().ToLowerInvariant() -ne "$AppId".Trim().ToLowerInvariant()) { continue }
        foreach ($v in @($s.Identity, $s.Name, $s.ObjectId, $s.AppId, $s.DisplayName)) { if ("$v".Trim()) { $ids.Add("$v".Trim().ToLowerInvariant()) } }
    }
    return @($ids | Sort-Object -Unique)
}

function Select-PimExoMailSendAssignment {
    <#
      The scoped send assignments that belong to ONE identity.
      The old idempotency check matched role + scope ONLY, so once the engine SPN held the
      assignment, a managed identity's would have been reported "already present" and never
      created -- the send would then be refused with nothing in the setup log to say why.
      Matched by assignee; the assignment Name is used only when the record names no assignee.
    #>
    # -AlternateNames (MAIL-NAMING 100.14): the names earlier releases gave the same assignment -- matched like
    # -AssignmentName, so a legacy-named assignment is adopted rather than created a second time.
    [CmdletBinding()] param([object[]]$Assignments = @(), [string]$ScopeName = 'PIM-Engine-SendScope',
                            [string[]]$AssigneeIds = @(), [string]$AssignmentName = '', [string[]]$AlternateNames = @())
    $want = @($AssigneeIds | Where-Object { "$_".Trim() } | ForEach-Object { "$_".Trim().ToLowerInvariant() })
    $names = @(@($AssignmentName) + @($AlternateNames) | Where-Object { "$_".Trim() } | ForEach-Object { "$_".Trim().ToLowerInvariant() })
    return @(@($Assignments) | Where-Object {
        $null -ne $_ -and "$($_.Role)" -eq 'Application Mail.Send' -and "$($_.CustomResourceScope)" -eq $ScopeName -and (
            ($want -contains "$($_.RoleAssignee)".Trim().ToLowerInvariant()) -or
            ($want -contains "$($_.RoleAssigneeName)".Trim().ToLowerInvariant()) -or
            (-not "$($_.RoleAssignee)$($_.RoleAssigneeName)".Trim() -and $names.Count -and ($names -contains "$($_.Name)".Trim().ToLowerInvariant())))
    })
}

function ConvertTo-PimExoNamePart {
    # PURE. A mailbox name (or a company-given prefix) as a safe part of an Exchange object name: letters, digits, '-'.
    param([AllowEmptyString()][AllowNull()][string]$Value)
    return (("$Value".Trim() -replace '[^A-Za-z0-9-]', '-') -replace '-{2,}', '-').Trim('-')
}

function Test-PimExoObjectName {
    <# PURE. MAIL-NAMING: a company-given Exchange object name (-ScopeName / -AssignmentNamePrefix). Returns '' or the reason. #>
    param([AllowEmptyString()][AllowNull()][string]$Value, [string]$What = 'name')
    $v = "$Value".Trim()
    if (-not $v) { return '' }
    if ($v -notmatch '^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$') { return "$What '$v' is not usable as an Exchange object name (letters, digits, space, '.', '_' and '-'; at most 64 characters, starting with a letter or digit)" }
    return ''
}

function Test-PimMailboxLocalPart {
    <# PURE. MAIL-NAMING: the mailbox name the company chose (the part before the @). Returns '' or the reason. #>
    param([AllowEmptyString()][AllowNull()][string]$Value)
    $v = "$Value".Trim()
    if (-not $v) { return 'no mailbox name was given' }
    if ($v -notmatch '^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$' -or $v -match '\.\.') { return "'$v' is not usable as a mailbox name (letters, digits, '.', '_' and '-'; at most 64 characters, not starting or ending with '.', '_' or '-')" }
    return ''
}

function Get-PimMailSenderScopeName {
    <#
      PURE. MAIL-NAMING (100.14, owner 2026-10-09): the DEFAULT name of the Exchange management scope for a NEW sender --
      neutral and following the company's mailbox name: '<mailbox>-SendScope' (PIM-Engine@ -> 'PIM-Engine-SendScope').
      Per mailbox, because a scope is a tenant singleton (§94: sharing one meant sending as another environment's mailbox).
      An existing tenant's scope is ADOPTED by Resolve-PimMailSenderScope, never renamed or duplicated.
    #>
    param([Parameter(Mandatory)][string]$Sender)
    $local = ConvertTo-PimExoNamePart -Value (("$Sender" -split '@')[0])
    if (-not $local) { $local = 'PIM-Engine' }
    return ($local + '-SendScope')
}

function Test-PimLegacyMailSenderScopeName {
    # PURE. The names earlier releases gave the scope ('PIM4EntraPS-Sender', 'PIM4EntraPS-Sender-<mailbox>').
    param([AllowEmptyString()][AllowNull()][string]$Name)
    return ("$Name" -match '^(?i)PIM4EntraPS-Sender(-.+)?$')
}

function Get-PimExoDuplicateScopeName {
    <#
      PURE. Exchange refuses a New-ManagementScope whose filter equals an existing scope's: "The <name> management scope has
      the same RecipientRoot, RecipientFilter, ... property values that you specified. Use the existing management scope".
      Returns that existing scope's name ('' for any other answer). A customer install, 2026-10-21: the scope read came back
      empty right after the Exchange Administrator role was activated, so the plan did not adopt 'PIM4EntraPS-Sender' and
      the create was refused -- the run now adopts the scope Exchange names instead of failing.
    #>
    [CmdletBinding()] param([AllowEmptyString()][AllowNull()][string]$Text)
    $m = [regex]::Match("$Text", '(?i)The (?<n>[^\s|"]+) management scope has the same')
    if ($m.Success) { return $m.Groups['n'].Value }
    return ''
}

function Resolve-PimMailSenderScope {
    <#
      PURE. MAIL-NAMING (100.14): WHICH scope this sender's send right lives in, given the scopes that already exist.
        1. a scope that already restricts to EXACTLY this sender is ADOPTED, whatever it is called (a legacy
           'PIM4EntraPS-Sender*' first) -- a re-run, or an install from before 2.4.538, keeps its scope and assignments;
        2. else the company's -ScopeName;
        3. else the neutral default '<mailbox>-SendScope'.
      Returns @{ name; adopted; note }.
    #>
    [CmdletBinding()] param([Parameter(Mandatory)][string]$Sender, [string]$ScopeName = '', [object[]]$Scopes = @())
    $mine = @(@($Scopes) | Where-Object { $null -ne $_ -and "$($_.Name)".Trim() -and "$($_.RecipientRestrictionFilter)".IndexOf("'$Sender'", [StringComparison]::OrdinalIgnoreCase) -ge 0 })
    if ($mine.Count) {
        $pick = @($mine | Where-Object { Test-PimLegacyMailSenderScopeName -Name $_.Name }) + @($mine | Where-Object { -not (Test-PimLegacyMailSenderScopeName -Name $_.Name) })
        $n = "$($pick[0].Name)".Trim()
        $note = if ("$ScopeName".Trim() -and "$ScopeName".Trim() -ne $n) { "the existing scope '$n' already restricts to $Sender -- kept (not renamed to '$("$ScopeName".Trim())', never a second scope)" } else { "the existing scope '$n' (restricts to $Sender) is reused" }
        return [pscustomobject]@{ name = $n; adopted = $true; note = $note }
    }
    if ("$ScopeName".Trim()) { return [pscustomobject]@{ name = "$ScopeName".Trim(); adopted = $false; note = '' } }
    return [pscustomobject]@{ name = (Get-PimMailSenderScopeName -Sender $Sender); adopted = $false; note = '' }
}

function New-PimMailSenderExoPlan {
    <#
      WHAT to create in Exchange, given what already exists. Returns an ordered list of
      { cmdlet; parameters; what } -- registrations, then the scope, then assignments, then (only
      when explicitly asked) removal of the engine SPN's older assignment. An empty list means
      everything is in place: running the plan twice writes nothing.
    #>
    [CmdletBinding()]
    param([object[]]$ExoServicePrincipals = @(), [object[]]$Scopes = @(), [object[]]$Assignments = @(),
          [object[]]$Principals = @(), [string]$Sender, [string]$ScopeName = '',
          [string]$EngineAppId = '', [string]$EngineObjectId = '', [switch]$RemoveEngineSpnAssignment)
    # MAIL-NAMING (100.14): no -ScopeName = the scope that already restricts to this sender (adopted), else the neutral
    # '<mailbox>-SendScope' (Resolve-PimMailSenderScope).
    if (-not "$ScopeName".Trim()) { $ScopeName = (Resolve-PimMailSenderScope -Sender $Sender -Scopes $Scopes).name }
    $plan = New-Object System.Collections.Generic.List[object]
    foreach ($p in @($Principals)) {
        $known = @(@($ExoServicePrincipals) | Where-Object { $null -ne $_ -and "$($_.AppId)".Trim().ToLowerInvariant() -eq "$($p.appId)".ToLowerInvariant() })
        if (-not $known.Count) {
            $plan.Add([pscustomobject]@{ cmdlet = 'New-ServicePrincipal'; what = "register $($p.kind) $($p.appId) in Exchange"
                                         parameters = @{ AppId = $p.appId; ObjectId = $p.objectId; DisplayName = $p.displayName } })
        }
    }
    $existingScope = @(@($Scopes) | Where-Object { $null -ne $_ -and "$($_.Name)" -eq $ScopeName })[0]
    if (-not $existingScope) {
        $plan.Add([pscustomobject]@{ cmdlet = 'New-ManagementScope'; what = "scope $ScopeName -> $Sender only"
                                     parameters = @{ Name = $ScopeName; RecipientRestrictionFilter = "PrimarySmtpAddress -eq '$Sender'" } })
    } else {
        # §94 (live, internal 2026-10-03): a second environment in the tenant found the FIRST one's scope by name and
        # attached its identities to it -- so it could send only as the OTHER environment's mailbox. A scope that does not
        # name THIS sender is never reused (and never rewritten: that would cut the other environment off).
        $flt = "$($existingScope.RecipientRestrictionFilter)"
        if ($flt.Trim() -and $flt.IndexOf("'$Sender'", [StringComparison]::OrdinalIgnoreCase) -lt 0) {
            throw ("the Exchange scope '$ScopeName' already exists for ANOTHER mailbox ($flt), not $Sender -- refusing to attach this " +
                   "sender's identities to it. Give this environment its own scope (-ScopeName, or leave it out: the default is '<mailbox>-SendScope').")
        }
    }
    foreach ($p in @($Principals)) {
        $ids = Get-PimExoAssigneeIds -ExoServicePrincipals $ExoServicePrincipals -AppId $p.appId -ObjectId $p.objectId
        # §94: the same identity's send right on ANOTHER of our sender scopes is the wrong-mailbox grant above -- remove it
        # first (assignment names are tenant-unique, so the right one could not be created beside it).
        # 2026-10-31 (EntraPolicySuite, internal): Exchange's REST Get-ManagementScope can answer an EMPTY
        # RecipientRestrictionFilter for every scope. Removed only when that scope's filter is READ and names ANOTHER
        # mailbox -- an unread filter may be this sender's own scope under an older name (Exchange then refuses the
        # create and the run adopts it), and removing a working send right on a guess is never the fix.
        $otherMailbox = { param($n) $sc = @(@($Scopes) | Where-Object { $null -ne $_ -and "$($_.Name)" -eq "$n" })[0]
            $f = "$(if ($sc) { $sc.RecipientRestrictionFilter })"; ($f.Trim() -and $f.IndexOf("'$Sender'", [StringComparison]::OrdinalIgnoreCase) -lt 0) }
        foreach ($wrong in @(@($Assignments) | Where-Object { $null -ne $_ -and "$($_.Role)" -eq 'Application Mail.Send' -and
                    "$($_.CustomResourceScope)" -ne $ScopeName -and ((Test-PimLegacyMailSenderScopeName -Name "$($_.CustomResourceScope)") -or "$($_.CustomResourceScope)" -like '*-SendScope') -and
                    (& $otherMailbox "$($_.CustomResourceScope)") } |
                    Where-Object { @(Select-PimExoMailSendAssignment -Assignments @($_) -ScopeName "$($_.CustomResourceScope)" -AssigneeIds $ids -AssignmentName $p.assignmentName -AlternateNames @($p.legacyAssignmentNames)).Count })) {
            $idn = if ("$($wrong.Identity)".Trim()) { "$($wrong.Identity)".Trim() } else { "$($wrong.Name)".Trim() }
            $plan.Add([pscustomobject]@{ cmdlet = 'Remove-ManagementRoleAssignment'; what = "remove $($p.kind) $($p.appId)'s send right on the OTHER scope $($wrong.CustomResourceScope) ($idn)"
                                         parameters = @{ Identity = $idn; Confirm = $false } })
        }
        if (-not @(Select-PimExoMailSendAssignment -Assignments $Assignments -ScopeName $ScopeName -AssigneeIds $ids -AssignmentName $p.assignmentName -AlternateNames @($p.legacyAssignmentNames)).Count) {
            $plan.Add([pscustomobject]@{ cmdlet = 'New-ManagementRoleAssignment'; what = "scoped send right for $($p.kind) $($p.appId)"
                                         parameters = @{ App = $p.appId; Role = 'Application Mail.Send'; CustomResourceScope = $ScopeName; Name = $p.assignmentName } })
        }
    }
    # Removal of the SPN's assignment is OPT-IN, and never when the SPN is itself a sender.
    if ($RemoveEngineSpnAssignment -and "$EngineAppId".Trim() -and -not @(@($Principals) | Where-Object { "$($_.appId)" -eq "$EngineAppId".Trim() }).Count) {
        $eIds = Get-PimExoAssigneeIds -ExoServicePrincipals $ExoServicePrincipals -AppId $EngineAppId -ObjectId $EngineObjectId
        foreach ($a in @(Select-PimExoMailSendAssignment -Assignments $Assignments -ScopeName $ScopeName -AssigneeIds $eIds)) {
            $idn = if ("$($a.Identity)".Trim()) { "$($a.Identity)".Trim() } else { "$($a.Name)".Trim() }
            $plan.Add([pscustomobject]@{ cmdlet = 'Remove-ManagementRoleAssignment'; what = "remove the engine SPN's send right $idn (explicitly requested)"
                                         parameters = @{ Identity = $idn; Confirm = $false } })
        }
    }
    return $plan.ToArray()
}

# =============================================================================================
# 2026-09-18 (REQUIREMENTS §33.25 BUG-166 / BUG-167, §33.23 IMP-31). The same script failed partway on
# TWO customer tenants, three times, from ONE pattern: a transient failure on a READ silently became a
# wrong PLAN. The decisions below separate "absent" from "could not read" and "already there" from
# "failed", so the script can be idempotent by construction and the rules are provable offline.
# =============================================================================================

function ConvertTo-PimObjectIdList {
    <#
      BUG-167 -- `-ManagedIdentityObjectId` under `pwsh -File`. An array written as 'a','b' arrives as
      ONE literal string ("'a','b'"), and the script then reported "managed identity service principal
      ''a','b'' not found: 400" -- which reads as a directory problem and is a parameter-marshalling
      one. Accept an array, a comma/semicolon-separated string, or any mix; strip whitespace and quotes;
      require every value to be a GUID; de-duplicate (case-insensitive, first spelling kept).
      Returns { ids; reason } -- reason non-empty = refuse, naming the marshalling cause.
    #>
    [CmdletBinding()] param([AllowNull()][AllowEmptyCollection()][string[]]$Value)
    $out = New-Object System.Collections.Generic.List[string]
    foreach ($v in @($Value)) {
        foreach ($part in ("$v" -split '[,;]')) {
            $t = $part.Trim().Trim("'", '"', ' ', '@', '(', ')').Trim()
            if (-not $t) { continue }
            if ($t -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 [pscustomobject]@{ ids = @(); reason = ("'{0}' is not an object id (GUID). Under 'pwsh -File' an array argument arrives as ONE literal string -- pass the ids comma-separated with no quotes or spaces: -ManagedIdentityObjectId <id1>,<id2>" -f $t) }
            }
            if (-not @($out | Where-Object { $_ -ieq $t }).Count) { $out.Add($t) }
        }
    }
    return [pscustomobject]@{ ids = $out.ToArray(); reason = '' }
}

function Test-PimAlreadyExistsError {
    <#
      "It is already there" -- which, for an idempotent step, is SUCCESS. Graph answers a duplicate
      app-role assignment with 400 "Permission being assigned already exists on the object"; Exchange
      answers a duplicate create with ADObjectAlreadyExistsException / "already exists".
      PURE: the caller passes the error text (message + ErrorDetails).
    #>
    [CmdletBinding()] param([AllowEmptyString()][AllowNull()][string]$Text)
    return ("$Text" -match '(?i)ADObjectAlreadyExistsException|already exists|Permission being assigned already exists|is already assigned|already been assigned')
}

function Test-PimExoNotFoundError {
    <# Exchange's "no such object" -- the ONLY error a single-object lookup may read as "absent". #>
    [CmdletBinding()] param([AllowEmptyString()][AllowNull()][string]$Text)
    return ("$Text" -match "(?i)ManagementObjectNotFoundException|couldn't be found|could not be found|was not found|\bnot found\b|\b404\b")
}

function Test-PimTransientReadError {
    <#
      A read that failed for a reason that passes: role propagation (401/403 while the Exchange
      Administrator grant is still arriving -- measured on two customer tenants, this is exactly how
      Get-ManagementScope "failed"), throttling, a server hiccup. Worth a bounded retry; never worth
      treating as "absent".
    #>
    [CmdletBinding()] param([AllowEmptyString()][AllowNull()][string]$Text)
    return ("$Text" -match '(?i)\b(401|403|408|429|500|502|503|504)\b|Unauthorized|Forbidden|Too ?Many ?Requests|timed? ?out|temporarily|ServiceUnavailable|Bad Gateway')
}

function Resolve-PimExoLookupOutcome {
    <#
      A SINGLE-OBJECT lookup (Get-Mailbox -Identity X) failed. Returns 'absent' only for a genuine
      not-found; anything else is 'unreadable' and the caller must REFUSE rather than plan a create.
      The old code read EVERY failure as "not there", so a 401 during propagation planned a create
      that then 400'd ADObjectAlreadyExistsException.
    #>
    [CmdletBinding()] param([AllowEmptyString()][AllowNull()][string]$ErrorText)
    if (Test-PimExoNotFoundError -Text $ErrorText) { return 'absent' }
    return 'unreadable'
}

function Resolve-PimExoCreateOutcome {
    <#
      An Exchange CREATE failed. What does that mean for an idempotent run?
        'exists'     -- it is already there: success
        'dehydrated' -- the org is not customisable yet: wait (Invoke-ExoWhenHydrated's existing loop)
        'retry'      -- New-ManagementRoleAssignment right after New-ServicePrincipal: Exchange has not
                        MATERIALISED the service principal yet and answers 404 / not found (measured on
                        two customer tenants). Bounded retry.
        'fail'       -- a real failure, reported at once
    #>
    [CmdletBinding()] param([string]$Cmdlet, [AllowEmptyString()][AllowNull()][string]$ErrorText)
    if (Test-PimAlreadyExistsError -Text $ErrorText) { return 'exists' }
    if ("$ErrorText" -like '*InvalidOperationInDehydratedContextException*') { return 'dehydrated' }
    # INSTALL-HARDEN-1 item 4 (2026-10-08, two new tenants): right after the organization was hydrated, Exchange answered
    # New-ManagementRoleAssignment with 400 "You don't have access to create, change, or remove the ... management role
    # assignment. You must be assigned a delegating role assignment ..." for ~40-60 minutes -- and then the same call
    # worked. It is Exchange finishing the new organization's RBAC, not a missing right: a bounded wait, never a failure.
    if (Test-PimExoNotReadyError -Text $ErrorText) { return 'notready' }
    if ("$Cmdlet" -eq 'New-ManagementRoleAssignment' -and (Test-PimExoNotFoundError -Text $ErrorText)) { return 'retry' }
    return 'fail'
}

function Test-PimExoNotReadyError {
    <# Exchange's "the new organization's RBAC is not ready yet" answer (INSTALL-HARDEN-1 item 4). #>
    [CmdletBinding()] param([AllowEmptyString()][AllowNull()][string]$Text)
    return ("$Text" -match "(?i)must be assigned a delegating role assignment|don.t have access to create, change, or remove the .{0,200}management role assignment")
}

function Get-PimExoNotReadyWait {
    <#
      PURE. INSTALL-HARDEN-1 item 4 -- one decision of the bounded wait for a not-ready Exchange organization.
      Returns @{ wait; sleepSeconds; message }: wait = $false once -ElapsedSeconds reaches -BoundSeconds (default 75 min);
      the message is the plain progress line (or, past the bound, the one sentence the install fails with).
    #>
    [CmdletBinding()] param([int]$Attempt = 1, [double]$ElapsedSeconds = 0, [int]$BoundSeconds = 4500, [int]$IntervalSeconds = 150, [string]$What = 'the send right')
    if ($ElapsedSeconds -ge $BoundSeconds) {
        return @{ wait = $false; sleepSeconds = 0
                  message = "Exchange has not finished preparing the new organization -- re-run in an hour (waited $([int]($ElapsedSeconds / 60)) minutes for $What)" }
    }
    $left = [Math]::Max(1, [int][Math]::Ceiling(($BoundSeconds - $ElapsedSeconds) / 60))
    return @{ wait = $true; sleepSeconds = [int][Math]::Min($IntervalSeconds, [Math]::Max(1, $BoundSeconds - $ElapsedSeconds))
              message = "Exchange is still preparing the new organization ($What, attempt $Attempt, $([int]($ElapsedSeconds / 60)) min waited, up to $left min more) -- this is normal for a new tenant" }
}

function Test-PimAssignmentDuration {
    <#
      IMP-31 -- the Exchange Administrator grant is TIME-BOUND. Accept an ISO 8601 duration of
      minutes/hours between 15 minutes and 24 hours (PT15M .. PT24H). A day-plus grant is exactly
      the standing privilege this change removes, so it is refused, not clamped.
      Returns { ok; minutes; reason }.
    #>
    [CmdletBinding()] param([AllowEmptyString()][AllowNull()][string]$Duration)
    $d = "$Duration".Trim().ToUpperInvariant()
    $m = [regex]::Match($d, '^PT(?:(\d+)H)?(?:(\d+)M)?$')
    if (-not $m.Success -or -not ($m.Groups[1].Success -or $m.Groups[2].Success)) {
        return [pscustomobject]@{ ok = $false; minutes = 0; reason = "'$Duration' is not an ISO 8601 duration in hours/minutes (e.g. PT4H, PT90M)" }
    }
    $mins = 0
    if ($m.Groups[1].Success) { $mins += 60 * [int]$m.Groups[1].Value }
    if ($m.Groups[2].Success) { $mins += [int]$m.Groups[2].Value }
    if ($mins -lt 15 -or $mins -gt 1440) {
        return [pscustomobject]@{ ok = $false; minutes = $mins; reason = "'$Duration' is outside PT15M..PT24H -- the Exchange Administrator grant is deliberately short-lived" }
    }
    return [pscustomobject]@{ ok = $true; minutes = $mins; reason = '' }
}

function New-PimRoleScheduleRequestBody {
    <#
      IMP-31 -- the body for POST roleManagement/directory/roleAssignmentScheduleRequests: an ACTIVE,
      TIME-BOUND assignment made THROUGH PIM (action adminAssign, expiration afterDuration).
      Why: the script used to POST roleManagement/directory/roleAssignments -- a PERMANENT active
      assignment outside PIM -- and measured live 2026-09-18 the SPN that received it CANNOT remove it
      again (Graph 400 "Removing self from ... built-in role is not allowed"). The tenants' own
      alerting flagged it as "assigned outside of PIM". A schedule that expires needs no removal.
      PURE: -Now is injectable.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$RoleDefinitionId,
          [string]$Duration = 'PT4H', [string]$Justification = 'PIM4EntraPS mail-sender setup (Initialize-PimMailSender.ps1): transient Exchange administration',
          [datetime]$Now = [datetime]::UtcNow)
    return [ordered]@{
        action           = 'adminAssign'
        principalId      = $PrincipalId
        roleDefinitionId = $RoleDefinitionId
        directoryScopeId = '/'
        justification    = $Justification
        scheduleInfo     = [ordered]@{
            startDateTime = $Now.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
            expiration    = [ordered]@{ type = 'afterDuration'; duration = "$Duration".Trim().ToUpperInvariant() }
        }
    }
}

function Select-PimActiveRoleGrant {
    <#
      IMP-31 -- is the principal ALREADY active in the role, and how? Input: roleAssignmentScheduleInstances
      (and/or plain roleAssignments) already fetched. Returns { active; kind = permanent|time-bound|'';
      endDateTime; id }. A permanent one is REUSED (and reported loudly as standing privilege); a
      time-bound one still valid at -Now is reused; an expired one is ignored.
    #>
    [CmdletBinding()]
    param([object[]]$Instances = @(), [string]$PrincipalId, [string]$RoleDefinitionId, [datetime]$Now = [datetime]::UtcNow)
    $best = $null
    foreach ($i in @($Instances | Where-Object { $null -ne $_ })) {
        if ("$($i.principalId)" -ne "$PrincipalId" -or "$($i.roleDefinitionId)" -ne "$RoleDefinitionId") { continue }
        if ($i.PSObject.Properties['directoryScopeId'] -and "$($i.directoryScopeId)".Trim() -and "$($i.directoryScopeId)" -ne '/') { continue }
        $end = $null
        if ($i.PSObject.Properties['endDateTime'] -and "$($i.endDateTime)".Trim()) {
            try { $end = ([datetime]::Parse("$($i.endDateTime)", [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::AdjustToUniversal -bor [Globalization.DateTimeStyles]::AssumeUniversal)) } catch { $end = $null }
            if ($null -eq $end) { continue }
            if ($end -le $Now.ToUniversalTime()) { continue }
        }
        $cand = [pscustomobject]@{ active = $true; kind = $(if ($null -eq $end) { 'permanent' } else { 'time-bound' }); endDateTime = $end; id = "$($i.id)" }
        # prefer a permanent record (it is the one that must be reported), else the latest-ending
        if ($null -eq $best -or $cand.kind -eq 'permanent' -or ($best.kind -ne 'permanent' -and $cand.endDateTime -gt $best.endDateTime)) { $best = $cand }
    }
    if ($best) { return $best }
    return [pscustomobject]@{ active = $false; kind = ''; endDateTime = $null; id = '' }
}

function Test-PimGrantOverlong {
    <#
      BUG-248 (§73.9, a customer build 2026-09-23) -- a reused time-bound grant that ends LATER than -Duration from now is
      standing privilege in all but name. A manual portal assignment defaulted to ONE YEAR and the script
      reused it as "time-bound". Returns { overlong; limitUtc; reason }. A permanent or inactive grant is not
      judged here (permanent is already reported on its own). 5 minutes of slack for clock skew.
    #>
    [CmdletBinding()]
    param([object]$Grant, [Parameter(Mandatory)][string]$Duration, [datetime]$Now = [datetime]::UtcNow)
    $out = [pscustomobject]@{ overlong = $false; limitUtc = $null; reason = '' }
    if (-not $Grant -or -not $Grant.active -or "$($Grant.kind)" -ne 'time-bound' -or $null -eq $Grant.endDateTime) { return $out }
    try { $span = [System.Xml.XmlConvert]::ToTimeSpan($Duration) } catch { $out.reason = "duration '$Duration' unreadable"; return $out }
    $out.limitUtc = $Now.ToUniversalTime().Add($span).AddMinutes(5)
    if (([datetime]$Grant.endDateTime).ToUniversalTime() -gt $out.limitUtc) {
        $out.overlong = $true
        $out.reason = "ends $(([datetime]$Grant.endDateTime).ToUniversalTime().ToString('u')), later than the requested $Duration allows ($($out.limitUtc.ToString('u')))"
    }
    return $out
}

function New-PimMailSenderSetupCheck {
    <#
      PURE (MAIL-STEP-PROOF, owner 2026-10-09: "why dont you trigger somehing or accept that we just did a test mail"). The
      record Initialize-PimMailSender stores in pim.Settings 'MailSenderSetupCheck' when its step [3] read-back CONFIRMED the
      scoped Application Mail.Send assignment for every sending identity, in ONE management scope on THIS mailbox. PIM Manager
      reads it: with its own successful test mail on the same mailbox the engine job's row is "granted -- confirmed by the
      setup check and the test mail". -Confirmed $false (not read back) or no identity -> $null: nothing is stored, never a guess.
    #>
    param([bool]$Confirmed, [string]$Sender, [string]$ScopeName, [object[]]$Principals = @(), [string]$By = '', [datetime]$NowUtc = [datetime]::UtcNow)
    if (-not $Confirmed -or -not "$Sender".Trim() -or -not "$ScopeName".Trim()) { return $null }
    $ids = @(@($Principals) | Where-Object { $_ -and ("$($_.objectId)".Trim() -or "$($_.appId)".Trim()) } | ForEach-Object { [ordered]@{ kind = "$($_.kind)"; appId = "$($_.appId)".Trim(); objectId = "$($_.objectId)".Trim() } })
    if (-not $ids.Count) { return $null }
    return [ordered]@{ ok = $true; scopedMailSend = 'confirmed'; sender = "$Sender".Trim(); scope = "$ScopeName".Trim(); identities = $ids
                       at = $NowUtc.ToUniversalTime().ToString('o'); by = "$By".Trim(); source = 'Initialize-PimMailSender' }
}

function New-PimMailSenderAddressRecord {
    <#
      PURE (INSTALL-FIX, REQUIREMENTS 100.25 item 4). The record Initialize-PimMailSender stores in pim.Settings
      'MailSenderAddress': the mailbox's PRIMARY SMTP address -- what the customer chose (name@their domain) -- next to the
      MailSender it belongs to (the mailbox's UPN, BUG-296: what Microsoft Graph sends by, often on the initial domain).
      PIM Manager and the end-of-install check SHOW the address with the UPN as detail, and only while 'sender' is still
      the stored MailSender (a later change of sender makes the record stale, never wrong). No address -> $null.
    #>
    param([string]$Sender, [string]$Address, [datetime]$NowUtc = [datetime]::UtcNow)
    if (-not "$Sender".Trim() -or -not "$Address".Trim()) { return $null }
    return [ordered]@{ sender = "$Sender".Trim(); address = "$Address".Trim(); at = $NowUtc.ToUniversalTime().ToString('o'); source = 'Initialize-PimMailSender' }
}

function Select-PimTenantWideMailSend {
    # appRoleAssignments on one service principal that are the TENANT-WIDE Graph Mail.Send.
    [CmdletBinding()] param([object[]]$Assignments = @(), [string]$GraphSpId, [string]$MailSendRoleId)
    return @(@($Assignments) | Where-Object { $null -ne $_ -and "$($_.resourceId)" -eq "$GraphSpId" -and "$($_.appRoleId)" -eq "$MailSendRoleId" })
}

function Get-PimTenantWideMailSendVerdict {
    <#
      Readiness verdict over EVERY identity that can send (engine SPN, tick job managed identity,
      the host's own managed identity). Targets: @({ label; spId; assignments }). No target =
      NOT EVALUATED (ok=$false with the reason) -- "did not look" is never "fine".
    #>
    [CmdletBinding()] param([object[]]$Targets = @(), [string]$GraphSpId, [string]$MailSendRoleId)
    $t = @($Targets | Where-Object { $null -ne $_ -and "$($_.spId)".Trim() })
    if (-not $t.Count) { return [pscustomobject]@{ ok = $false; held = @(); detail = 'engine identity unknown -- neither an engine client id nor a managed identity could be resolved, so cannot tell whether a tenant-wide send right is held (this is "did not look", not "it is fine")' } }
    if (-not "$MailSendRoleId".Trim()) { return [pscustomobject]@{ ok = $false; held = @(); detail = 'could not resolve the Graph Mail.Send app role -- unable to evaluate' } }
    $held = @($t | Where-Object { @(Select-PimTenantWideMailSend -Assignments @($_.assignments) -GraphSpId $GraphSpId -MailSendRoleId $MailSendRoleId).Count } | ForEach-Object { "$($_.label)" })
    if ($held.Count) {
        return [pscustomobject]@{ ok = $false; held = $held; detail = ("TENANT-WIDE Graph Mail.Send held by: {0} -- the per-mailbox Exchange RBAC scope is defeated by it (measured: with this consent an out-of-scope send is ACCEPTED). Revoke it; the scoped grant is what should carry sending." -f ($held -join '; ')) }
    }
    return [pscustomobject]@{ ok = $true; held = @(); detail = ("no tenant-wide Graph Mail.Send on {0} (sending is carried by the per-mailbox Exchange RBAC scope)" -f ((@($t | ForEach-Object { "$($_.label)" })) -join '; ')) }
}

function New-PimMailSenderCommand {
    <#
      MAIL-1 (framework 12.3 (b)-(d), owner 2026-10-08): the command that sets up the shared mailbox AFTERWARDS -- the
      published download plus a browser sign-in call (no certificate, no secret), with every value of this environment
      that is known filled in and a <placeholder> for the rest. PURE. Returns the lines of Get-PimSupportScriptCommand
      (12.7 / 12.10 item 11): the download, the checksum check, the signature status, the documentation link (with the
      -WhatIf hint), then the run line (always the LAST line).
    #>
    # MAIL-NAMING (100.14, owner 2026-10-09: "it must be possible to define as parameter on the scripts"): the company's
    # mailbox name, domain and display name travel in the command (-MailboxName / -MailDomain / -DisplayName) whenever
    # they are known -- the script's own defaults otherwise.
    [CmdletBinding()] param([string]$TenantId, [string[]]$ManagedIdentityObjectId = @(), [string]$SubscriptionId, [string]$ResourceGroup,
                            [string]$TickJobName, [string]$ManagerAppName, [string]$SqlServerFqdn,
                            [string]$MailboxName, [string]$MailDomain, [string]$DisplayName)
    $v = { param($x, $ph) if ("$x".Trim()) { "$x".Trim() } else { $ph } }
    $q = { param($x) $t = "$x".Trim(); if ($t -match '^[A-Za-z0-9._@-]+$') { $t } else { "'" + $t.Replace("'", "''") + "'" } }
    $run = '.\Initialize-PimMailSender.ps1 -TenantId ' + (& $v $TenantId '<tenant id>')
    if ("$MailboxName".Trim()) { $run += ' -MailboxName ' + (& $q $MailboxName) }
    if ("$MailDomain".Trim())  { $run += ' -MailDomain ' + (& $q $MailDomain) }
    if ("$DisplayName".Trim()) { $run += ' -DisplayName ' + (& $q $DisplayName) }
    $mi = @(@($ManagedIdentityObjectId) | Where-Object { "$_".Trim() } | ForEach-Object { "$_".Trim() })
    if ($mi.Count) { $run += ' -ManagedIdentityObjectId ' + ($mi -join ',') }
    if ("$SubscriptionId".Trim() -and "$ResourceGroup".Trim() -and ("$TickJobName".Trim() -or "$ManagerAppName".Trim())) {
        $run += " -SubscriptionId $("$SubscriptionId".Trim()) -ResourceGroup $("$ResourceGroup".Trim())"
        if ("$TickJobName".Trim()) { $run += " -TickJobName $("$TickJobName".Trim())" }
        if ("$ManagerAppName".Trim()) { $run += " -ManagerAppName $("$ManagerAppName".Trim())" }
    } elseif (-not $mi.Count) { $run += ' -ManagedIdentityObjectId <manager identity object id>,<engine job identity object id>' }
    $run += ' -SqlServerFqdn ' + (& $v $SqlServerFqdn '<server>.database.windows.net')
    return @(Get-PimSupportScriptCommand -Script 'Initialize-PimMailSender' -Run @($run))
}

function Resolve-PimDeployMailSignedIn {
    <#
      MAIL-1 (framework 12.3 (a)): in a SIGNED-IN deploy, may the mail-sender step run? PURE over the signed-in account (Get-PimSetupAccount: { tenantId; user = { name; type } }).
        * the signed-in principal is an APPLICATION (user.type servicePrincipal -- the Invardia Support app) in the
          deploy's tenant -> run = $true, appId = user.name: Initialize-PimMailSender -UseSignedInAccount -AdminAppId
          <appId> activates its own time-boxed Exchange Administrator through PIM and creates the mailbox now;
        * a PERSON (user.type user) -> run = $false: loud and not fatal, and `lines` say exactly how to finish it
          afterwards (PIM Manager > Get Started > Mail sender, or the published script, browser sign-in);
        * no / another tenant's account -> run = $false with that reason.
      Returns @{ run; appId; why; lines }.
    #>
    # INSTALL-HARDEN-1 (owner 2026-10-08, the trial runs in the customer's Cloud Shell as a PERSON): a signed-in person who
    # holds an ACTIVE Exchange Administrator or Global Administrator role (-PersonRoleTemplateIds: the 'wids' of their token,
    # or their directory roles) AND for whom the signed-in session mints an Exchange Online token (-PersonExoToken) runs it too: run = $true,
    # person = $true, appId = '' -> Initialize-PimMailSender -UseSignedInAccount with no -AdminAppId (their own role; no app
    # is granted anything). Anyone else stays the loud, non-fatal skip with the Get Started follow-up.
    [CmdletBinding()] param([object]$Account, [string]$TenantId, [string[]]$ManagedIdentityObjectId = @(), [string]$SubscriptionId, [string]$ResourceGroup,
                            [string]$TickJobName, [string]$ManagerAppName, [string]$SqlServerFqdn,
                            [string[]]$PersonRoleTemplateIds = @(), [bool]$PersonExoToken = $false)
    $cmd = New-PimMailSenderCommand -TenantId $TenantId -ManagedIdentityObjectId $ManagedIdentityObjectId -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup `
               -TickJobName $TickJobName -ManagerAppName $ManagerAppName -SqlServerFqdn $SqlServerFqdn
    # REQUIREMENTS 100.77: plain text (this window / the install log) -- the doc page is ONE line UNDER the two command lines.
    $after = @(
        '  DO IT AFTERWARDS (no certificate): PIM Manager > Get Started > Mail sender -- choose Shared mailbox (it prints this',
        '  command with the values filled in: an Exchange or Global Administrator runs it and signs in in the browser) or SMTP relay:') +
        @(@($cmd) | ForEach-Object { "    $_" }) + @("    $(Get-PimSupportScriptDocLine -Script 'Initialize-PimMailSender')")
    $type = "$($Account.user.type)".Trim()
    $name = "$($Account.user.name)".Trim()
    $tid  = "$($Account.tenantId)".Trim()
    if (-not $Account -or -not $name) {
        return @{ run = $false; appId = ''; why = 'no signed-in account'; lines = @('mail sender: NOT RUN -- no signed-in account could be read.') + $after }
    }
    if ("$TenantId".Trim() -and $tid -and $tid -ine "$TenantId".Trim()) {
        return @{ run = $false; appId = ''; why = 'signed in to another tenant'; lines = @("mail sender: NOT RUN -- the signed-in account is in tenant $tid, not $TenantId.") + $after }
    }
    if ($type -ieq 'servicePrincipal' -and $name -match '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') {
        return @{ run = $true; appId = $name; why = 'signed-in application'; lines = @(); person = $false }
    }
    $exoRoles = @('29232cdf-9323-42fd-ade2-1d097af3e4de', '62e90394-69f5-4237-9190-012177145e10')   # Exchange Administrator, Global Administrator
    $held = @(@($PersonRoleTemplateIds) | ForEach-Object { "$_".Trim().ToLowerInvariant() } | Where-Object { $_ -in $exoRoles })
    if ($held.Count -and $PersonExoToken) {
        return @{ run = $true; appId = ''; person = $true; why = 'signed-in person with an active Exchange role'; lines = @() }
    }
    $whyPerson = if (-not $held.Count) { 'no ACTIVE Exchange Administrator or Global Administrator role' } else { 'no Exchange Online token from the signed-in session' }
    return @{ run = $false; appId = ''; person = $true; why = "signed-in deploy is a person ($whyPerson)"
              lines = @("mail sender: NOT RUN -- this deploy is signed in as a person ($name). Creating the shared mailbox needs Exchange administration this run does not",
                        '  hold (an app identity with a time-boxed Exchange Administrator, or an administrator''s own browser sign-in). The environment is MAIL-MUTE until then.') + $after }
}

# =============================================================================================
# MAIL-NAMING 100.14 item 5 (owner 2026-10-09): the store write from a customer PC fails at the Azure SQL firewall
# ("Client with IP address ... is not allowed"). Default: no firewall change, a short message, PIM Manager finishes it.
# Opt-in -AllowThisIpTemporarily: a temporary rule for exactly that IP, the write, and the rule ALWAYS removed (finally).
# =============================================================================================
function Get-PimSqlFirewallBlockedIp {
    # PURE. The IP Azure SQL refused (error 40615), or '' when the error is not the firewall.
    param([AllowEmptyString()][AllowNull()][string]$Text)
    $m = [regex]::Match("$Text", "(?i)Client with IP address '(?<ip>[0-9a-fA-F:.]+)' is not allowed")
    if ($m.Success) { return $m.Groups['ip'].Value }
    return ''
}

function New-PimSqlTempFirewallRuleName {
    # PURE. A rule name that says what it is and when it was made (removed again by the same run).
    param([Parameter(Mandatory)][string]$Ip, [datetime]$Now = [datetime]::UtcNow)
    return ('PimSetupTemp-' + ($Ip -replace '[^0-9A-Za-z]', '-') + '-' + $Now.ToUniversalTime().ToString('yyyyMMddHHmmss'))
}

function Invoke-PimSqlWriteWithTemporaryFirewall {
    <#
      The write, and -- only with -AllowThisIpTemporarily, only when the write was refused by the SQL firewall, and only
      when -ShouldProcess agrees (-WhatIf = no) -- one temporary rule for the refused IP, the write retried while the rule
      takes effect, and the rule REMOVED in finally whether the write worked or not. The calls are injected
      (-Write / -AddRule param($ip) -> handle / -RemoveRule param($handle) / -ShouldProcess param($ip) -> bool / -Sleep),
      so the whole decision is tested offline.
      Returns @{ ok; firewall; ip; whatIf; ruleAdded; ruleRemoved; rule; error; removeError }.
    #>
    [CmdletBinding()]
    param([Parameter(Mandatory)][scriptblock]$Write, [switch]$AllowThisIpTemporarily, [scriptblock]$AddRule, [scriptblock]$RemoveRule,
          [scriptblock]$ShouldProcess, [int]$Attempts = 9, [int]$DelaySeconds = 20, [scriptblock]$Sleep)
    $r = [ordered]@{ ok = $false; firewall = $false; ip = ''; whatIf = $false; ruleAdded = $false; ruleRemoved = $false; rule = $null; error = ''; removeError = '' }
    $txt = { param($e) ("$($e.Exception.Message) $($e.ErrorDetails.Message)" -replace '\s+', ' ').Trim() }
    try { & $Write; $r.ok = $true; return $r } catch { $r.error = & $txt $_ }
    $r.ip = Get-PimSqlFirewallBlockedIp -Text $r.error
    if (-not $r.ip) { return $r }
    $r.firewall = $true
    if (-not $AllowThisIpTemporarily -or -not $AddRule -or -not $RemoveRule) { return $r }
    if ($ShouldProcess -and -not (& $ShouldProcess $r.ip)) { $r.whatIf = $true; return $r }
    try {
        try { $r.rule = & $AddRule $r.ip; $r.ruleAdded = $true }
        catch { $r.error = "could not add the temporary firewall rule: $(& $txt $_)"; return $r }
        for ($i = 1; $i -le [Math]::Max(1, $Attempts); $i++) {
            if ($Sleep) { & $Sleep $DelaySeconds } else { Start-Sleep -Seconds $DelaySeconds }   # a new rule takes a moment to apply
            try { & $Write; $r.ok = $true; $r.error = ''; break }
            catch { $r.error = & $txt $_; if (-not (Get-PimSqlFirewallBlockedIp -Text $r.error)) { break } }
        }
    } finally {
        if ($r.ruleAdded) {
            try { & $RemoveRule $r.rule; $r.ruleRemoved = $true } catch { $r.removeError = & $txt $_ }
        }
    }
    return $r
}

# ===== END inlined helper: _PimMailSenderPlan.ps1 =====
# ===== BEGIN inlined helper: _PimMailSetup.ps1 =====
# _PimMailSetup.ps1 -- the pieces behind Initialize-PimMailSender.ps1 and Set-PimSmtpRelayPassword.ps1: which way the
# script signs in, the BROWSER sign-in itself, and a per-API token cache. Dot-source it; it defines functions only (no
# side effects on load).
#
# MAIL-1 (framework DOCS/REQUIREMENTS.md 12.3, owner 2026-10-08): "we dont use certificates here, either interactive login
# or secret. not certificates". So the published scripts sign in in the BROWSER (an Exchange or Global Administrator) or
# with the Invardia Support app's secret; a certificate stays accepted for old callers and is never what a page prints.
#
# NO MODULES (owner 2026-10-07: "neither pim, si or invardia must have dependencies"): plain Invoke-RestMethod + .NET.
# Sign-in is auth code + PKCE on a localhost loopback, Microsoft Edge launched explicitly (the default browser when Edge
# is missing) -- the pattern of _PimEnginePermissions.ps1 (Get-PimEpInteractiveToken), DUPLICATED here on purpose: each
# published script is ONE standalone file (tools/setup/Build-PimSupportScripts.ps1 inlines this), and isolation beats
# DRY between two scripts that ship separately. Never device code.
#
# The public clients (first-party, present in every tenant, no app registration needed):
#   * Exchange Online admin API -- "Microsoft Exchange REST API Based Powershell", the client the ExchangeOnlineManagement
#     V3 module itself signs in with; the token is for https://outlook.office365.com and drives the same
#     /adminapi/beta/<tenant>/InvokeCommand endpoint the module calls.
#   * Microsoft Graph -- "Microsoft Graph Command Line Tools" (as Grant-PimEnginePermissions.ps1).
#   * Azure Resource Manager, Azure SQL, Key Vault -- "Microsoft Azure PowerShell"; one sign-in, the other two from its
#     refresh token (the client is pre-authorised for all three).

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

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

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

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

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

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

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

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

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

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

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

# Interactive sign-in: auth code + PKCE on a loopback TcpListener (works without elevation), Edge launched explicitly,
# the default browser when Edge is missing. Returns the token response (access_token, refresh_token, expires_in).
function Get-PimMsInteractiveToken {
    param(
        [Parameter(Mandatory)][string]$ClientId,
        [Parameter(Mandatory)][string[]]$Scopes,
        [string]$Tenant = 'organizations',
        [bool]$UseEdge = $true,
        [string]$LoginHint,
        [string]$What = 'sign-in'
    )
    $pkce  = New-PimMsPkcePair
    $state = [guid]::NewGuid().ToString('N')
    $scope = Get-PimMsScopeString -Scopes $Scopes
    $tcp = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0)
    $tcp.Start(); $tcps = @($tcp); try { if ([System.Net.Sockets.Socket]::OSSupportsIPv6) { $tcp6 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::IPv6Loopback, ([System.Net.IPEndPoint]$tcp.LocalEndpoint).Port); $tcp6.Start(); $tcps += $tcp6 } } catch { }   # a customer 2026-10-21: "localhost" may be [::1] -- BOTH loopbacks, same port
    $redirect = "http://localhost:$(([System.Net.IPEndPoint]$tcp.LocalEndpoint).Port)/"
    $authUrl  = New-PimMsAuthorizeUrl -Tenant $Tenant -ClientId $ClientId -RedirectUri $redirect -Scope $scope -State $state -CodeChallenge $pkce.Challenge -LoginHint $LoginHint
    $query = $null
    try {
        $edge = if ($UseEdge) { Get-PimMsEdgePath } else { $null }
        Write-Host "Signing in for $What -- the browser answers to $redirect ..." -ForegroundColor Yellow
        if ($edge) { Start-Process -FilePath $edge -ArgumentList @('--new-window', $authUrl) -WhatIf:$false }
        else {
            if ($UseEdge) { Write-Host 'Microsoft Edge not found -- using the default browser.' -ForegroundColor DarkYellow }
            Start-Process $authUrl -WhatIf:$false
        }
        Write-Host "If no browser opened, open this address yourself:`n  $authUrl" -ForegroundColor DarkGray
        # SIGNIN-PAGE (owner 2026-10-31): only the answer (code / error) ends the wait; every request gets a page; the page
        # keeps answering 10 s after it (PIM-LoopbackAnswer.ps1; tools/setup/_PimLoopbackAnswer.ps1 is its identical copy for the tools).
        if (-not (Get-Command Wait-PimLoopbackAnswer -ErrorAction SilentlyContinue)) {
# ===== BEGIN inlined helper: _PimLoopbackAnswer.ps1 =====
# PIM-LoopbackAnswer.ps1 -- the ONE wait for a browser sign-in's answer on the localhost loopback (auth code + PKCE).
# Used by every PIM browser sign-in: the REST library's own (signed-in setup scripts), the mail setup (Initialize-PimMailSender,
# Set-PimSmtpRelayPassword, Set-PimSqlTier), the engine-permissions grant and the Activator deploy scripts. The tools load the
# identical copy in tools\setup (they may not load engine files). Build-PimSupportScripts inlines it into each published script.
#
# Owner 2026-10-30/31 ("people are reporting this error" -- "This site can't be reached"; "yes fix the sign-in page in all
# scripts"), the same fix as Invardia's Wait-AuthCode: the old loops took the FIRST request -- often the browser's preload
# of the address or its icon request -- and a request that never sent a line held the loop, and once the answer came the
# listener stopped at once, so the browser's real load or a reload got "This site can't be reached". Now:
#   1. only a request whose query carries code= or error= is the answer; the loop goes on until one comes;
#   2. EVERY request gets a page (waiting / signed in / failed), never a closed connection;
#   3. after the answer the listener keeps answering for -GraceSeconds (10), so a second load shows "Signed in" too;
#   4. it throws only when no answer came within -Seconds.
# A connection that sends nothing (a speculative preconnect) is dropped after -ReadTimeoutMs and never blocks the loop.

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

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

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

# ===== END inlined helper: _PimLoopbackAnswer.ps1 =====
        }
        $query = Wait-PimLoopbackAnswer -Listeners $tcps -Seconds 300 -TimeoutMessage 'Timed out (5 minutes) waiting for the browser to finish the sign-in.'
    } finally { foreach ($tcpL in $tcps) { try { $tcpL.Stop() } catch { } } }
    $kv = @{}
    foreach ($pair in ($query -split '&')) {
        $k, $v = $pair -split '=', 2
        $kv[$k] = if ($null -ne $v) { [uri]::UnescapeDataString(($v -replace '\+', ' ')) } else { '' }
    }
    if ($kv['error']) {
        $hint = Get-PimMsSignInFailureHint -ErrorText "$($kv['error']) $($kv['error_description'])"
        throw "Sign-in failed: $($kv['error']) -- $($kv['error_description'])$(if ($hint) { " $hint" })"
    }
    if ($kv['state'] -ne $state) { throw 'The browser answer did not come from this sign-in attempt. Close ALL browser windows and run the script again.' }
    if (-not $kv['code'])        { throw 'The browser answer carried no authorization code.' }
    Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$Tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
        client_id     = $ClientId
        grant_type    = 'authorization_code'
        code          = $kv['code']
        redirect_uri  = $redirect
        code_verifier = $pkce.Verifier
        scope         = $scope
    }
}

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

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

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

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

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

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

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

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

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

# ===== END inlined helper: _PimMailSetup.ps1 =====
# ===== BEGIN inlined helper: _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 =====
$null = Start-PimScriptRun -Script 'Initialize-PimMailSender'
try {

# EITHER a secret OR a certificate (or the signed-in session, or the browser), never two at once. Checked before
# anything is provisioned: this script creates a mailbox and grants Exchange rights, and finding out the credential was
# unusable halfway through leaves a half-configured tenant nobody asked for. ("pass EITHER" / "-AdminAppId is required"
# are the refusals; the decision is Resolve-PimMailSetupAuthMode in _PimMailSetup.ps1, tested offline.)
$authPlan = Resolve-PimMailSetupAuthMode -AdminAppId $AdminAppId -AdminSecret $AdminSecret -AdminCertThumbprint $AdminCertThumbprint -UseSignedInAccount:$UseSignedInAccount
if ($authPlan.reason) { throw "Initialize-PimMailSender: $($authPlan.reason)" }
$script:PimMailAuthMode = $authPlan.mode
$browserMode = ($script:PimMailAuthMode -eq 'browser')
# INSTALL-HARDEN-1 (owner 2026-10-08; the trial runs in the customer's Cloud Shell as a PERSON): -UseSignedInAccount with no
# -AdminAppId is the signed-in PERSON's delegated token -- like the browser sign-in, that person's own Exchange
# Administrator / Global Administrator role does the work and no app is granted anything.
$personSignedIn = ($script:PimMailAuthMode -eq 'signedIn' -and -not "$AdminAppId".Trim())
$delegatedMode = ($browserMode -or $personSignedIn)
# Framework 12.17 (ONE sign-in rule): a signed-in run takes every token from the source _PimSignedIn.ps1 registers in
# PIM-Rest ($global:PIM_TokenProvider) -- the Invardia Support session open in this window (Get-InvardiaSupportToken),
# otherwise the person's own browser sign-in (auth code + PKCE, never device code). PIM-Rest checks each token's tenant.
if ($script:PimMailAuthMode -eq 'signedIn') { Set-PimSignedInGlobals -TenantId $TenantId }
function Get-PimMailSignedInUpn {
    if ($browserMode) { return (Get-PimMsSignedInUpn) }
    if ($personSignedIn) {
        try {
            $c = ConvertFrom-PimJwtClaims -Token (Get-PimMailAdminToken -Resource 'graph')
            return "$(if ($c.upn) { $c.upn } elseif ($c.unique_name) { $c.unique_name } else { $c.preferred_username })".Trim()
        } catch { return '' }
    }
    return ''
}
if ($browserMode -and -not (Test-PimMsInteractiveHost)) {
    throw 'Initialize-PimMailSender: no credential was passed, so this run signs in in the BROWSER -- and this session is not interactive. Run it in a PowerShell window, or pass -AdminAppId + -AdminSecret (the Invardia Support app).'
}

function Get-PimMailAdminToken {
    # The admin (onboarding) identity's token for 'graph' | 'arm' | a resource URL: the browser sign-in (the person),
    # the signed-in session with -UseSignedInAccount (PIM-Rest's registered token source: the Invardia Support session,
    # else the person's browser sign-in), else the app's own secret / certificate. Never cached across identities (-Force).
    param([Parameter(Mandatory)][string]$Resource)
    if ($script:PimMailAuthMode -eq 'browser') { return (Get-PimMsBrowserToken -Resource $Resource -TenantId $TenantId) }
    if ($UseSignedInAccount) {
        if (-not ($global:PIM_TokenProvider -is [scriptblock])) { Set-PimSignedInGlobals -TenantId $TenantId }
        $tok = "$(Get-PimRestToken -Resource $Resource -TenantId $TenantId)".Trim()
        if (-not $tok) { throw "Initialize-PimMailSender: the signed-in session gave no token for $Resource in tenant $TenantId -- connect with the Invardia Support app (Connect-InvardiaSupport.ps1 -Environment <handle>), or run it in a PowerShell window and sign in in the browser." }
        return $tok
    }
    return (Get-PimRestToken -Resource $Resource -TenantId $TenantId -ClientId $AdminAppId -ClientSecret $AdminSecret -CertThumbprint $AdminCertThumbprint -Force)
}

# Both refusals happen BEFORE anything is touched: a malformed argument found halfway through leaves
# a half-configured tenant.
# BUG-167: `pwsh -File` delivers an array as one literal string -- normalise it, and name the
# marshalling cause when a value is not an object id (it used to surface as a directory 400).
$miParse = ConvertTo-PimObjectIdList -Value $ManagedIdentityObjectId
if ($miParse.reason) { throw "Initialize-PimMailSender: -ManagedIdentityObjectId: $($miParse.reason)" }
$ManagedIdentityObjectId = @($miParse.ids)
$durCheck = Test-PimAssignmentDuration -Duration $ExchangeAdminDuration
if (-not $durCheck.ok) { throw "Initialize-PimMailSender: -ExchangeAdminDuration: $($durCheck.reason)" }
# MAIL-NAMING (100.14): the company's names, checked before anything is touched.
$nameErr = Test-PimMailboxLocalPart -Value $MailboxName
if ($nameErr) { throw "Initialize-PimMailSender: -MailboxName: $nameErr" }
foreach ($nv in @(@{ n = 'ScopeName'; v = $ScopeName }, @{ n = 'AssignmentNamePrefix'; v = $AssignmentNamePrefix })) {
    $e = Test-PimExoObjectName -Value $nv.v -What "-$($nv.n)"
    if ($e) { throw "Initialize-PimMailSender: $e" }
}
if ("$MailDomain".Trim() -and "$MailDomain".Trim() -notmatch '^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$') { throw "Initialize-PimMailSender: -MailDomain '$MailDomain' is not a domain name" }
if (-not "$AssignmentNamePrefix".Trim()) { $AssignmentNamePrefix = ConvertTo-PimExoNamePart -Value $MailboxName }

$graphResourceAppId = '00000003-0000-0000-c000-000000000000'   # Microsoft Graph
$exoResourceAppId   = '00000002-0000-0ff1-ce00-000000000000'   # Office 365 Exchange Online

$result = [ordered]@{
    ok = $false; sender = ''; tenantId = $TenantId; engineAppId = ''; sendIdentities = @()
    exchangePlan = ''; mailboxCreated = $false; mailSendGranted = $false
    accessPolicyCreated = $false; privilegedGrants = $null; steps = @(); reason = ''; authMode = "$($authPlan.mode)"; persisted = $false
}
function Note($m, $c = 'Gray') { Write-Host "    $m" -ForegroundColor $c }
function Step($m) { Write-Host "`n--- $m ---" -ForegroundColor Cyan }
function Add-Result($name, $state, $detail) { $result.steps += [ordered]@{ step = $name; state = $state; detail = $detail } }

function Write-ResultFile {
    if (-not "$OutFile".Trim()) { return }
    # 12.7: under -WhatIf nothing is written outside the temp folder -- the result file then only goes to a path in it.
    $tmpRoot = [IO.Path]::GetFullPath([IO.Path]::GetTempPath())
    $outFull = try { [IO.Path]::GetFullPath($OutFile) } catch { "$OutFile" }
    if ($WhatIfPreference -and -not $outFull.StartsWith($tmpRoot, [StringComparison]::OrdinalIgnoreCase)) {
        Note "WhatIf: the result file $OutFile is NOT written (it is outside the temp folder)" 'DarkYellow'
        return
    }
    try {
        $dir = Split-Path -Parent $OutFile
        if ($dir -and -not (Test-Path $dir)) { New-Item -ItemType Directory -Force -Path $dir -WhatIf:$false | Out-Null }
        # -WhatIf:$false deliberately. This file is a LOCAL REPORT of what happened (or would
        # happen), not a change to the environment -- and under -WhatIf the write was suppressed
        # while the script still logged "result written", which is a log that lies.
        ($result | ConvertTo-Json -Depth 8) | Set-Content -LiteralPath $OutFile -Encoding utf8 -WhatIf:$false
        Note "result written: $OutFile" 'DarkGray'
    } catch { Write-Warning "could not write -OutFile '$OutFile': $($_.Exception.Message)" }
}
# A failure must still leave a readable result behind -- the orchestrator reads the file, and an
# absent file is indistinguishable from a step that never ran.
function Fail($reason) {
    $result.reason = $reason
    Write-ResultFile
    Write-Host "`nRESULT: FAILED -- $reason" -ForegroundColor Red
    exit 1
}

# =============================================================================================
# PURE DECISION CORES. Extracted from the step bodies below so they can be TESTED without a
# tenant -- they were inline, and inline logic in a provisioning script is logic that only ever
# gets exercised against live infrastructure, one tenant at a time, by somebody watching.
# These two carry the two traps this whole script exists for, so they are exactly the parts that
# must not be verified by eye. No network, no state, no Write-Host: data in, decision out.
# =============================================================================================

function Select-PimExchangeMailboxPlans {
    <#
      🪤 THE TRAP THIS ENCODES: `assignedPlans` reporting `exchange = Enabled` is NOT evidence that
      a mailbox can be created. EXCHANGE_S_FOUNDATION rides along with Entra P2 and reports exactly
      that while provisioning DIRECTORY OBJECTS ONLY -- `New-Mailbox -Shared` still fails. Measured
      on a real tenant: the org looked mail-capable and was not, for a reason the status does not
      hint at.
      So the signal is an Exchange service plan BEYOND Foundation. Returns the qualifying plan
      names (sorted, unique); an EMPTY result means "cannot host a mailbox" and is the fatal case.
      PURE: takes the already-fetched subscribedSkus collection.
    #>
    [CmdletBinding()] param([AllowEmptyCollection()][object[]]$SubscribedSkus = @())
    return @(@($SubscribedSkus).servicePlans |
        Where-Object { $_.servicePlanName -like '*EXCHANGE*' -and $_.servicePlanName -ne 'EXCHANGE_S_FOUNDATION' } |
        ForEach-Object { $_.servicePlanName } | Sort-Object -Unique)
}

function Resolve-PimMailSenderAddress {
    <#
      Where the notification mail comes FROM. The domain is the tenant's INITIAL
      (`onmicrosoft.com`) domain unless -MailDomain overrides it: a freshly-onboarded tenant has no
      custom domain, and guessing one produces a mailbox nobody can receive from.
      Returns @{ sender; domain; reason }. `reason` non-empty means it could not be resolved --
      REPORTED rather than thrown, so the caller decides what is fatal and the decision stays
      testable.
      PURE: takes the already-fetched organization object.
    #>
    [CmdletBinding()] param($Organization, [string]$MailboxName, [string]$MailDomain)
    $initial = @(@($Organization.verifiedDomains) | Where-Object { $_.isInitial } | Select-Object -First 1)
    $initialName = if ($initial.Count) { "$($initial[0].name)".Trim() } else { '' }
    $domain = if ("$MailDomain".Trim()) { "$MailDomain".Trim() } else { $initialName }
    $box = "$MailboxName".Trim()
    if (-not $box)    { return [ordered]@{ sender = ''; domain = $domain; reason = 'no mailbox name was given' } }
    # 🔒 An unresolved domain is a REFUSAL, not a guess. Inventing one yields a mailbox address
    # that provisions cleanly and can never receive anything -- the mail-mute failure this script
    # exists to prevent, arrived at from the other direction.
    if (-not $domain) { return [ordered]@{ sender = ''; domain = ''; reason = 'could not resolve a mail domain (no initial verified domain on the organization)' } }
    return [ordered]@{ sender = "$box@$domain"; domain = $domain; reason = '' }
}

function Resolve-PimMailSenderGraphKey {
    <#
      BUG-296 (found live at a customer 2026-10-07): what the ENGINE must store as MailSender is the key Microsoft Graph
      addresses the mailbox by -- /users/<id | userPrincipalName>/sendMail -- NOT its mail address. Exchange gives a new
      shared mailbox a UPN on the tenant's DEFAULT domain while -PrimarySmtpAddress put its mail on the initial
      (onmicrosoft) domain; Graph then answers 404 for /users/<mail address> and the environment is mail-mute although
      the mailbox, the scope and the send right are all correct.
      PURE. -GraphUsers: the Graph users whose mail or proxyAddresses carry -Sender ($filter=mail eq ... OR
      proxyAddresses/any). Returns @{ key; reason }: the UPN of the ONE matching user; -Sender itself when it already is
      that UPN; '' + a reason when nobody or more than one user matches (refuse rather than pick).
    #>
    [CmdletBinding()] param([Parameter(Mandatory)][string]$Sender, [object[]]$GraphUsers = @())
    $s = "$Sender".Trim()
    $hits = @(@($GraphUsers) | Where-Object { $_ } | Where-Object {
        $u = $_; ("$($u.userPrincipalName)" -ieq $s) -or ("$($u.mail)" -ieq $s) -or (@($u.proxyAddresses) | Where-Object { ("$_" -replace '^(?i)smtp:', '') -ieq $s }) })
    $ids = @($hits | ForEach-Object { "$($_.id)$($_.userPrincipalName)" } | Select-Object -Unique)
    if ($ids.Count -eq 0) { return [ordered]@{ key = ''; reason = "no directory user carries $s (the mailbox is not visible in Microsoft Graph yet)" } }
    if ($ids.Count -gt 1) { return [ordered]@{ key = ''; reason = "more than one directory user carries $s -- refusing to pick one" } }
    return [ordered]@{ key = "$($hits[0].userPrincipalName)".Trim(); reason = '' }
}

Write-Host ("=" * 78) -ForegroundColor Cyan
Write-Host " PIM MAIL SENDER  tenant $TenantId" -ForegroundColor Cyan
Write-Host ("=" * 78) -ForegroundColor Cyan

# --- tokens -------------------------------------------------------------------
# The onboarding SPN authenticates with a SECRET here because that is the credential the estate
# onboarding path already carries for it (workbook / the build key vault). The ENGINE never uses a
# secret -- it is cert-only -- and this script never gives it one.
$adminLabel = if ($browserMode) { 'the administrator signing in in the browser' } else { "the onboarding SPN ($AdminAppId)" }
Step $(if ($browserMode) { 'authenticate (browser sign-in: an Exchange or Global Administrator)' } else { 'authenticate (onboarding SPN)' })
try {
    $graphTok = Get-PimMailAdminToken -Resource 'graph'
} catch { Fail "could not acquire a Graph token as $adminLabel : $($_.Exception.Message)" }
$GH = @{ Authorization = "Bearer $graphTok"; 'Content-Type' = 'application/json' }
function Gr {
    param([string]$Method = 'GET', [Parameter(Mandatory)][string]$Path, [object]$Body)
    $u = if ($Path -like 'http*') { $Path } else { "https://graph.microsoft.com/v1.0/$Path" }
    $a = @{ Method = $Method; Uri = $u; Headers = $GH }
    if ($null -ne $Body) { $a.Body = ($Body | ConvertTo-Json -Depth 20) }
    Invoke-RestMethod @a
}
# 🔴 A COLLECTION READ MUST FOLLOW THE PAGES. Graph returns at most 100 items per page, and the
# onboarding SPN this runs as holds ~100 Graph app roles on its own (measured on two test tenants 2026-09-18),
# so a first-page-only read of its appRoleAssignments could miss Exchange.ManageAsApp, plan a grant,
# and hit 400 "already exists" -- the fatal re-run of BUG-166 (a).
function GrAll {
    param([Parameter(Mandatory)][string]$Path)
    $r = Gr -Path $Path
    $items = @($r.value)
    $pages = 1
    while ($r.PSObject.Properties['@odata.nextLink'] -and "$($r.'@odata.nextLink')".Trim()) {
        if (++$pages -gt 50) { throw "more than 50 pages reading $Path -- refusing to guess the rest" }
        $r = Gr -Path "$($r.'@odata.nextLink')"
        $items += @($r.value)
    }
    return $items
}
if ($browserMode) { Note "signed in as $(Get-PimMsSignedInUpn) (browser sign-in; no app identity is used or granted anything)" 'DarkGray' }
elseif ($personSignedIn) { Note "signed in as $(Get-PimMailSignedInUpn) (a person's own sign-in; no app identity is used or granted anything)" 'DarkGray' }
else { Note "onboarding SPN: $AdminAppId" 'DarkGray' }

# 🔴 THE ONBOARDING SPN CANNOT GRANT ITSELF. The header says this script's identity "already
# elevates itself to Global Administrator + Owner" -- true of the estate's onboarding SPN, and NOT
# true of a customer deploy SPN that was only given the Azure Owner role (create-for-rbac), which holds
# Azure RBAC and nothing in Graph. Every Graph call here uses that SPN's own token, so the two
# grants below -- Exchange.ManageAsApp and the Exchange Administrator role -- ask the SPN to assign
# roles TO ITSELF, needing AppRoleAssignment.ReadWrite.All and RoleManagement.ReadWrite.Directory.
# A create-for-rbac SPN has neither, so the script failed at its own first grant. Measured while
# preparing a live customer's mail sender, 2026-09-08.
#
# The directive this script opens with is "the onboarding scripts must handle this prep unattended",
# so refusing with an instruction to go and grant it by hand is the wrong answer. Instead: fall back
# to a Global Administrator's BROWSER sign-in for the grant only (framework 12.17: no command-line tool session is
# borrowed any more). Only where a person is at the console -- an unattended run gets the refusal, naming the grant.
#
# 🔒 Scope of the fallback is deliberately narrow: READS stay on the SPN token, and only these two
# POSTs may elevate. Anything that is not an authorization failure is rethrown untouched -- a
# fallback that swallowed a real error would hide the thing it was meant to surface.
function Invoke-PimGrant {
    param([Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][object]$Body, [string]$What = 'grant')
    try { Gr -Method POST -Path $Path -Body $Body | Out-Null; return 'onboarding SPN' }
    catch {
        # BUG-131's lesson: the Graph error body is in ErrorDetails, NOT in Exception.Message.
        $m = "$($_.Exception.Message) $($_.ErrorDetails.Message)"
        # BUG-166 (a): a grant that is ALREADY THERE is the goal reached, not a failure. It was fatal,
        # so a second run died before the step that actually still needed doing.
        if (Test-PimAlreadyExistsError -Text $m) { return 'already held (nothing granted)' }
        if ($m -notmatch 'Authorization_RequestDenied|Insufficient privileges|\b403\b|Forbidden') { throw }
        $deny = ("$What was denied to the onboarding SPN. Re-run in a PowerShell window and sign in in the browser as a " +
                 "Global Administrator when asked, or grant $AdminAppId AppRoleAssignment.ReadWrite.All + RoleManagement.ReadWrite.Directory.")
        if (-not (Test-PimMsInteractiveHost)) { throw $deny }
        Note "$What refused for the onboarding SPN (it cannot grant itself) -- sign in in the browser as a Global Administrator for this grant" 'DarkYellow'
        $gaTok = ''
        try { $gaTok = "$(Get-PimMsBrowserToken -Resource 'graph' -TenantId $TenantId)".Trim() } catch { throw "$deny ($($_.Exception.Message))" }
        if (-not $gaTok) { throw $deny }
        try {
            Invoke-RestMethod -Method POST -Uri "https://graph.microsoft.com/v1.0/$Path" `
                -Headers @{ Authorization = "Bearer $gaTok"; 'Content-Type' = 'application/json' } `
                -Body ($Body | ConvertTo-Json -Depth 20) | Out-Null
        } catch {
            if (Test-PimAlreadyExistsError -Text "$($_.Exception.Message) $($_.ErrorDetails.Message)") { return 'already held (nothing granted)' }
            throw
        }
        return 'Global Administrator browser sign-in'
    }
}

function Confirm-Eventually {
    <#
      Verify by READING BACK, but tolerate Graph's eventual consistency.
      🪤 MEASURED, not theoretical: the first live run of this script granted Mail.Send, got a 2xx,
      and then failed its own verification because the assignment was not yet queryable. A single
      read-back after a write is therefore a FLAKY GATE -- it reports a successful grant as a
      failure, and the natural "fix" (drop the verification) would be the wrong one, since the
      whole point is not to trust the POST. Poll instead: still a real gate, just one that gives
      the directory time to converge. Same class as the deleted-users-still-listed lag in the
      session-22 handoff.
    #>
    param([Parameter(Mandatory)][scriptblock]$Test, [int]$Seconds = 90, [string]$What = 'change')
    $stop = (Get-Date).AddSeconds($Seconds); $n = 0
    while ($true) {
        $n++
        try { if (& $Test) { if ($n -gt 1) { Note "$What visible after $n read(s)" 'DarkGray' }; return $true } } catch { }
        if ((Get-Date) -ge $stop) { return $false }
        Start-Sleep -Seconds 5
    }
}

# --- 0. PRECONDITION: a real Exchange plan ------------------------------------
Step '[0] precondition -- Exchange Online plan present'
try { $skus = @((Gr -Path 'subscribedSkus').value) }
catch { Fail "could not read subscribedSkus: $($_.Exception.Message)" }

# BEYOND Foundation is the test. Foundation alone = directory objects only, no mailboxes, while
# assignedPlans still says "exchange = Enabled". The decision itself is Select-PimExchangeMailboxPlans
# (pure, tested offline) -- it used to be inline here, where nothing could exercise it.
$exchangePlans = @(Select-PimExchangeMailboxPlans -SubscribedSkus $skus)
# MAIL-NAMING 100.14 item 4 (owner 2026-10-09, noise): every SKU of the tenant only with -Verbose -- the line that matters
# is the Exchange verdict below (plan found / not found).
foreach ($s in $skus) { Write-Verbose ("sku {0,-28} enabled={1}" -f $s.skuPartNumber, $s.prepaidUnits.enabled) }

if (-not $exchangePlans.Count) {
    Add-Result 'precondition' 'FAILED' 'no Exchange service plan beyond EXCHANGE_S_FOUNDATION'
    Fail @"
no Exchange Online plan in this tenant -- a shared sender mailbox CANNOT be created.
  Found SKUs: $(($skus.skuPartNumber) -join ', ')
  🪤 If you are about to object that 'exchange' shows Enabled: that is EXCHANGE_S_FOUNDATION riding
     along with Entra P2. It provisions DIRECTORY OBJECTS ONLY -- New-Mailbox -Shared still fails.
     The signal is an Exchange-bearing SKU (e.g. EXCHANGESTANDARD -> EXCHANGE_S_STANDARD).
  FIX: assign an Exchange Online plan to the tenant (a trial suffices), then re-run.
       The licence is a human/commercial step by design; everything after it is automated here.
  This is FATAL, not a warning, because continuing would leave a MAIL-MUTE environment that reports
  success everywhere: the engine would render notification mail and never send it, and the first
  symptom would be a TAP that never arrives.
"@
}
$result.exchangePlan = ($exchangePlans -join ', ')
Note "Exchange Online plan: found ($($exchangePlans -join ', '))" 'Green'
Add-Result 'precondition' 'ok' ($exchangePlans -join ', ')

# --- resolve the sender address ------------------------------------------------
Step 'resolve sender address'
try { $org = (Gr -Path 'organization').value[0] } catch { Fail "could not read organization: $($_.Exception.Message)" }
$senderPlan = Resolve-PimMailSenderAddress -Organization $org -MailboxName $MailboxName -MailDomain $MailDomain
if ($senderPlan.reason) { Fail $senderPlan.reason }
$domain = $senderPlan.domain
$sender = $senderPlan.sender
$result.sender = $sender
Note "sender: $sender" 'Green'

# --- resolve the SENDING identity (hosted: the tick job's managed identity) -------------
Step 'resolve the sending identity (managed identity when hosted)'
$miOids = @($ManagedIdentityObjectId | Where-Object { "$_".Trim() } | ForEach-Object { "$_".Trim() })
# MAIL-1 (2026-10-08): ADDED to the identities passed, not only used when none are -- PIM Manager's Get Started passes
# its own managed identity by object id and names the tick job, whose identity it may not be able to read itself.
if ("$SubscriptionId".Trim() -and "$ResourceGroup".Trim() -and "$TickJobName".Trim()) {
    try {
        $armTok = Get-PimMailAdminToken -Resource 'arm'
        $job = Invoke-RestMethod -Headers @{ Authorization = "Bearer $armTok" } `
            -Uri "https://management.azure.com/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.App/jobs/$TickJobName`?api-version=2024-03-01"
    } catch { Fail "could not read tick job '$TickJobName' to resolve its managed identity: $($_.Exception.Message)" }
    $pick = Get-PimJobManagedIdentityPrincipalId -Job $job
    if ($pick.reason) { Fail "tick job '$TickJobName': $($pick.reason)" }
    if ($miOids -notcontains "$($pick.principalId)") { $miOids += "$($pick.principalId)" }
    Note "tick job '$TickJobName' sends as its $($pick.kind)-assigned managed identity $($pick.principalId)" 'DarkGray'
}
if ("$SubscriptionId".Trim() -and "$ResourceGroup".Trim() -and "$ManagerAppName".Trim()) {
    try {
        $armTok = Get-PimMailAdminToken -Resource 'arm'
        $app = Invoke-RestMethod -Headers @{ Authorization = "Bearer $armTok" } `
            -Uri "https://management.azure.com/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.App/containerApps/$ManagerAppName`?api-version=2024-03-01"
    } catch { Fail "could not read the Manager app '$ManagerAppName' to resolve its managed identity: $($_.Exception.Message)" }
    $pick = Get-PimJobManagedIdentityPrincipalId -Job $app
    if ($pick.reason) { Fail "Manager app '$ManagerAppName': $($pick.reason)" }
    if ($miOids -notcontains "$($pick.principalId)") { $miOids += "$($pick.principalId)" }
    Note "Manager app '$ManagerAppName' sends as its $($pick.kind)-assigned managed identity $($pick.principalId)" 'DarkGray'
}
$miSps = @()
foreach ($oid in $miOids) {
    try { $miSps += Gr -Path "servicePrincipals/$oid`?`$select=id,appId,displayName,servicePrincipalType" }
    catch { Fail "managed identity service principal '$oid' not found: $($_.Exception.Message)" }
}

# --- resolve the engine SPN ----------------------------------------------------
Step 'resolve the engine SPN (receives the SCOPED Mail.Send when no managed identity sends)'
if (-not "$EngineAppId".Trim() -and -not $miSps.Count) {
    if (-not ("$KeyVaultName".Trim() -and "$BootstrapAppId".Trim() -and "$BootstrapThumbprint".Trim())) {
        Fail 'no -EngineAppId or -ManagedIdentityObjectId, and no -KeyVaultName/-BootstrapAppId/-BootstrapThumbprint to read Modern-AppId from'
    }
    try {
        $kvTok = Get-PimRestToken -Resource 'https://vault.azure.net' -TenantId $TenantId -ClientId $BootstrapAppId -CertThumbprint $BootstrapThumbprint -Force
        $EngineAppId = (Invoke-RestMethod -Headers @{ Authorization = "Bearer $kvTok" } `
            -Uri "https://$KeyVaultName.vault.azure.net/secrets/Modern-AppId`?api-version=7.4").value
    } catch { Fail "could not read Modern-AppId from $KeyVaultName : $($_.Exception.Message)" }
}
$EngineAppId = "$EngineAppId".Trim()
$result.engineAppId = $EngineAppId
$engineSp = $null
if ($EngineAppId) {
    $engineSp = (Gr -Path "servicePrincipals?`$filter=appId eq '$EngineAppId'").value | Select-Object -First 1
    if (-not $engineSp -and -not $miSps.Count) { Fail "engine service principal not found for appId $EngineAppId" }
    if ($engineSp) { Note "engine SPN: $EngineAppId (objectId $($engineSp.id))" 'DarkGray' }
}
$sendPlan = Resolve-PimMailSendPrincipals -ManagedIdentitySps $miSps -EngineSp $engineSp -AssignmentNamePrefix $AssignmentNamePrefix
if ($sendPlan.reason) { Fail $sendPlan.reason }
$sendPrincipals = @($sendPlan.principals)
$result.sendIdentities = @($sendPrincipals | ForEach-Object { [ordered]@{ kind = $_.kind; appId = $_.appId; objectId = $_.objectId } })
foreach ($p in $sendPrincipals) { Note "sends as: $($p.kind) appId $($p.appId) (objectId $($p.objectId))" 'Green' }

# Resolve the Graph Mail.Send role now, but DO NOT GRANT IT YET -- see the ordering note at the
# grant step near the end of this script. Resolving early keeps the failure "this tenant has no
# Mail.Send role" separate from anything Exchange does.
$graphSp = (Gr -Path "servicePrincipals?`$filter=appId eq '$graphResourceAppId'").value | Select-Object -First 1
if (-not $graphSp) { Fail 'Microsoft Graph service principal not found in tenant' }
$mailSendRole = $graphSp.appRoles | Where-Object { $_.value -eq 'Mail.Send' -and $_.allowedMemberTypes -contains 'Application' } | Select-Object -First 1
if (-not $mailSendRole) { Fail 'Mail.Send app-role not found on the Graph service principal' }

# --- enable the ONBOARDING SPN to drive Exchange -------------------------------
# Transient, and on the provisioning identity by design (see the header). Two things are needed:
# the Exchange.ManageAsApp app-role, and the Exchange Administrator DIRECTORY role -- the app-role
# alone yields a token whose `roles` claim is empty and an admin endpoint that answers 401.
$manageAsAppState = ''; $exchAdminState = $null
# 🔒 BROWSER SIGN-IN: NOTHING IS GRANTED TO ANY APP. The person who signed in acts with their OWN Exchange Administrator /
# Global Administrator role (a delegated token), so the transient app grants below -- Exchange.ManageAsApp, the
# time-boxed Exchange Administrator through PIM -- have no subject and are skipped as a whole. An admin without an
# Exchange role is refused by Exchange itself at the readiness wait below, with Exchange's own message.
if ($delegatedMode) {
    Step 'Exchange administration: the signed-in administrator''s own role (nothing is granted)'
    Note "Exchange is administered as $(Get-PimMailSignedInUpn) -- an Exchange Administrator or Global Administrator role is needed" 'DarkGray'
} else {
Step 'enable Exchange administration for the onboarding SPN (transient, provisioning-time)'
$adminSp =(Gr -Path "servicePrincipals?`$filter=appId eq '$AdminAppId'").value | Select-Object -First 1
if (-not $adminSp) { Fail "onboarding service principal not found for appId $AdminAppId" }

$exoSp = (Gr -Path "servicePrincipals?`$filter=appId eq '$exoResourceAppId'").value | Select-Object -First 1
if (-not $exoSp) { Fail 'Office 365 Exchange Online service principal not found in tenant (no EXO plan provisioned yet?)' }
$manageAsApp = $exoSp.appRoles | Where-Object { $_.value -eq 'Exchange.ManageAsApp' -and $_.allowedMemberTypes -contains 'Application' } | Select-Object -First 1
if (-not $manageAsApp) { Fail 'Exchange.ManageAsApp app-role not found on the Exchange Online service principal' }

# Every page, not the first 100 (see GrAll) -- a missed page planned a duplicate grant.
try {
    $hasManage = @(GrAll -Path "servicePrincipals/$($adminSp.id)/appRoleAssignments" |
        Where-Object { $_.resourceId -eq $exoSp.id -and $_.appRoleId -eq $manageAsApp.id })
} catch { Fail "could not read the onboarding SPN's app-role assignments, so cannot tell whether Exchange.ManageAsApp is already held -- refusing to guess: $($_.Exception.Message)" }
$manageAsAppState = if ($hasManage.Count) { 'held (already)' } else { '' }
if ($hasManage.Count) { Note 'Exchange.ManageAsApp already held' 'DarkGray' }
elseif ($PSCmdlet.ShouldProcess($AdminAppId, 'grant Exchange.ManageAsApp')) {
    try {
        $by = Invoke-PimGrant -Path "servicePrincipals/$($adminSp.id)/appRoleAssignments" `
                -Body @{ principalId = $adminSp.id; resourceId = $exoSp.id; appRoleId = $manageAsApp.id } `
                -What 'Exchange.ManageAsApp'
        Note "Exchange.ManageAsApp: $by" 'Green'
        $manageAsAppState = "held ($by)"
    } catch { Fail "could not grant Exchange.ManageAsApp to the onboarding SPN: $($_.Exception.Message)" }
}

# 🔒 THE EXCHANGE ADMINISTRATOR ROLE IS TIME-BOUND, AND GRANTED THROUGH PIM.
# It used to be POSTed to roleManagement/directory/roleAssignments: a PERMANENT active assignment made
# outside PIM. Measured 2026-09-18 on two test tenants: the tenants' own alerting flagged it ("assigned
# outside of PIM"), and the SPN holding it could NOT remove it -- Graph refuses a self-removal
# ("Removing self from ... built-in role is not allowed"). A privileged-access product must not leave
# exactly the standing privilege it exists to prevent. Now: an active assignment through
# roleAssignmentScheduleRequests that EXPIRES by itself after -ExchangeAdminDuration.
$exchAdminTemplate = '29232cdf-9323-42fd-ade2-1d097af3e4de'   # built-in; definition id == template id
$exchAdminRole = (Gr -Path "roleManagement/directory/roleDefinitions?`$filter=displayName eq 'Exchange Administrator'").value | Select-Object -First 1
$exchAdminRoleId = if ($exchAdminRole) { "$($exchAdminRole.id)" } else { $exchAdminTemplate }
function Read-ExchAdminGrant {
    # Active instances cover BOTH a permanent assignment and a PIM-activated/time-bound one.
    $inst = @(GrAll -Path "roleManagement/directory/roleAssignmentScheduleInstances?`$filter=principalId eq '$($adminSp.id)'")
    Select-PimActiveRoleGrant -Instances $inst -PrincipalId "$($adminSp.id)" -RoleDefinitionId $exchAdminRoleId
}
# 🔴 SELF-HEAL -- RoleManagement.ReadWrite.Directory (2026-09-26, the 13th "MAIL SENDER NOT PROVISIONED").
# Both the read above and the activation below need it. A deploy identity created by
# New-PimDeployIdentity -GrantGraph before 2026-09-26 does not hold it, and every one of those installs
# ended here with 403 and a mail-mute environment. That identity DOES hold AppRoleAssignment.ReadWrite.All,
# which is exactly the right to grant an app role -- including to itself -- so the step grants the missing
# role, mints a FRESH token (roles are baked into the token at issue) and waits for the claim to carry it.
$roleMgmtRole = $graphSp.appRoles | Where-Object { $_.value -eq 'RoleManagement.ReadWrite.Directory' -and $_.allowedMemberTypes -contains 'Application' } | Select-Object -First 1
if (-not $roleMgmtRole) { Fail 'RoleManagement.ReadWrite.Directory app-role not found on the Graph service principal' }
try {
    $hasRoleMgmt = @(GrAll -Path "servicePrincipals/$($adminSp.id)/appRoleAssignments" |
        Where-Object { $_.resourceId -eq $graphSp.id -and $_.appRoleId -eq $roleMgmtRole.id })
} catch { Fail "could not read the onboarding SPN's app-role assignments, so cannot tell whether RoleManagement.ReadWrite.Directory is held -- refusing to guess: $($_.Exception.Message)" }
if ($hasRoleMgmt.Count) { Note 'RoleManagement.ReadWrite.Directory already held' 'DarkGray' }
elseif ($PSCmdlet.ShouldProcess($AdminAppId, 'grant RoleManagement.ReadWrite.Directory (self-heal)')) {
    try {
        $by = Invoke-PimGrant -Path "servicePrincipals/$($adminSp.id)/appRoleAssignments" `
                -Body @{ principalId = $adminSp.id; resourceId = $graphSp.id; appRoleId = $roleMgmtRole.id } `
                -What 'RoleManagement.ReadWrite.Directory'
        Note "RoleManagement.ReadWrite.Directory: $by (self-heal -- the deploy identity predates it)" 'Green'
    } catch { Fail "could not grant RoleManagement.ReadWrite.Directory to the onboarding SPN: $($_.Exception.Message)" }
    # A token minted before the grant carries the OLD roles claim; re-mint until the claim shows the new role.
    $claimSeen = Confirm-Eventually -What 'RoleManagement.ReadWrite.Directory in the token' -Seconds 600 -Test {
        $t = Get-PimMailAdminToken -Resource 'graph'
        $p = "$t".Split('.')[1].Replace('-', '+').Replace('_', '/'); while ($p.Length % 4) { $p += '=' }
        $roles = @(([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json).roles)
        if ($roles -contains 'RoleManagement.ReadWrite.Directory') { $script:GH = @{ Authorization = "Bearer $t"; 'Content-Type' = 'application/json' }; $true } else { $false }
    }
    if (-not $claimSeen) { Fail 'RoleManagement.ReadWrite.Directory was granted but no fresh token carried it within 10 minutes -- re-run this step; the grant itself is in place' }
}
# 🪤 A 403 HERE IS NOT FINAL (measured 2026-09-26, Community): RoleManagement.ReadWrite.Directory was held and IN the
# token, and this read still answered 403 once -- then 200 on every later try. Entra makes a new app permission effective
# on the role-management read path some time after the token already carries it. Retry a 403 with a FRESH token for up
# to 5 minutes before calling the environment mail-mute; anything that is not a 403 still fails at once.
$exchAdminState = $null; $exchReadErr = $null
$exchReadUntil = (Get-Date).AddMinutes(5)
while ($true) {
    try { $exchAdminState = Read-ExchAdminGrant; $exchReadErr = $null; break }
    catch {
        $exchReadErr = $_
        $m = "$($_.Exception.Message) $($_.ErrorDetails.Message)"
        if ($m -notmatch '\b403\b|Forbidden|Authorization_RequestDenied' -or (Get-Date) -ge $exchReadUntil -or $WhatIfPreference) { break }
        Note 'role read answered 403 -- retrying with a fresh token (a new permission takes effect on this path after the token carries it)' 'DarkYellow'
        Start-Sleep -Seconds 20
        $t = Get-PimMailAdminToken -Resource 'graph'
        $script:GH = @{ Authorization = "Bearer $t"; 'Content-Type' = 'application/json' }
    }
}
if ($exchReadErr -and $WhatIfPreference) {
    # 12.7: the read needs RoleManagement.ReadWrite.Directory, which -WhatIf did not grant above -- say so, preview the activation.
    Note "WhatIf: the Exchange Administrator state of the setup app cannot be read yet ($((("$($exchReadErr.Exception.Message)") -split "`n")[0])) -- this step cannot be previewed exactly; run without -WhatIf to apply" 'DarkYellow'
    $exchAdminState = [pscustomobject]@{ active = $false; kind = ''; endDateTime = $null }
    $exchReadErr = $null
}
try { if ($exchReadErr) { throw $exchReadErr } }
catch { Fail "could not read the onboarding SPN's active directory roles, so cannot tell whether Exchange Administrator is already active -- refusing to guess: $($_.Exception.Message)" }
if ($exchAdminState.active) {
    if ($exchAdminState.kind -eq 'permanent') {
        Note 'Exchange Administrator already active -- as a PERMANENT assignment (standing privilege; see the summary)' 'Yellow'
    } else {
        $ol = Test-PimGrantOverlong -Grant $exchAdminState -Duration $ExchangeAdminDuration
        if ($ol.overlong) { Note "Exchange Administrator already active, but it $($ol.reason) -- that is STANDING privilege until then (a portal assignment defaults to one year); shorten it to $ExchangeAdminDuration or remove it after this run" 'Yellow' }
        else { Note "Exchange Administrator already active until $($exchAdminState.endDateTime.ToString('u')) (time-bound, reused)" 'DarkGray' }
    }
}
elseif ($PSCmdlet.ShouldProcess($AdminAppId, "activate Exchange Administrator through PIM for $ExchangeAdminDuration")) {
    try {
        $body = New-PimRoleScheduleRequestBody -PrincipalId "$($adminSp.id)" -RoleDefinitionId $exchAdminRoleId -Duration $ExchangeAdminDuration
        $by = Invoke-PimGrant -Path 'roleManagement/directory/roleAssignmentScheduleRequests' -Body $body -What 'Exchange Administrator (time-bound)'
        Note "Exchange Administrator requested for $ExchangeAdminDuration through PIM (via the $by)" 'Green'
    } catch {
        # BUG-248: both identities can be refused (seen at a customer: 403 as the SPN and as the signed-in Global Administrator --
        # the Azure CLI's token carries no delegated role-management scope). Say what the manual way must look like.
        Fail ("could not activate Exchange Administrator for the onboarding SPN through PIM: $($_.Exception.Message)" +
              " -- MANUAL WAY: in Entra > Roles > Exchange Administrator > Add assignments, assign app $AdminAppId as ACTIVE and TIME-BOUND," +
              " ending within $ExchangeAdminDuration (the portal defaults to ONE YEAR -- change it), then re-run this script; it reuses the assignment.")
    }
    # READ BACK -- a request that was accepted is not yet an active role.
    $seen = Confirm-Eventually -What 'time-bound Exchange Administrator' -Seconds 120 -Test { (Read-ExchAdminGrant).active }
    if (-not $seen) { Fail 'the time-bound Exchange Administrator request was accepted but the role is not active on read-back' }
    $exchAdminState = Read-ExchAdminGrant
    Note "Exchange Administrator active until $(if ($exchAdminState.endDateTime) { $exchAdminState.endDateTime.ToString('u') } else { '(no end)' }) (verified by read-back)" 'Green'
}
}   # end: app identity (not the browser sign-in)

# 12.7 (-WhatIf): from here on Exchange is READ (Get-* cmdlets) and every create / remove / store write is announced
# through ShouldProcess instead of made. An app identity whose Exchange grants were skipped above may not be able to read
# Exchange yet -- then steps [1]-[3] say they cannot be previewed, and only what can be read is shown.
$whatIfRun = [bool]$WhatIfPreference
$exoPreviewable = $true

# --- Exchange Online admin REST ------------------------------------------------
# The transport the EXO V3 module uses internally. Token audience is outlook.office365.com; a token
# minted BEFORE the grants above will carry an empty `roles` claim, so it is always minted fresh
# (-Force) and retried while the grant propagates.
$exoUri = "https://outlook.office365.com/adminapi/beta/$TenantId/InvokeCommand"
# The tenant's INITIAL (*.onmicrosoft.com) domain. `$initialDomain` used to be read here and assigned nowhere, so the
# anchor ended in "@" -- harmless only because EXO falls back when the anchor mailbox does not resolve.
$initialDomain = "$(@(@($org.verifiedDomains) | Where-Object { $_.isInitial } | Select-Object -First 1).name)".Trim()
# A delegated (browser) token anchors on the signed-in person, an app-only one on the system mailbox -- as the EXO V3
# module does (Get-PimMsExoAnchor). The Exchange token is minted first so the person's UPN is known.
if ($browserMode) { try { [void](Get-PimMailAdminToken -Resource 'https://outlook.office365.com') } catch { Fail "could not sign in to Exchange Online: $($_.Exception.Message)" } }
$anchor = if ($personSignedIn) { Get-PimMsExoAnchor -Mode 'browser' -Upn (Get-PimMailSignedInUpn) -InitialDomain $initialDomain }
          else { Get-PimMsExoAnchor -Mode $script:PimMailAuthMode -Upn (Get-PimMsSignedInUpn) -InitialDomain $initialDomain }
function Invoke-Exo {
    param([Parameter(Mandatory)][string]$Cmdlet, [hashtable]$Parameters = @{})
    $tok = Get-PimMailAdminToken -Resource 'https://outlook.office365.com'
    $h = @{ Authorization = "Bearer $tok"; 'Content-Type' = 'application/json'
            'X-ResponseFormat' = 'json'; 'X-AnchorMailbox' = $anchor }
    $body = @{ CmdletInput = @{ CmdletName = $Cmdlet; Parameters = $Parameters } } | ConvertTo-Json -Depth 10
    Invoke-RestMethod -Method POST -Uri $exoUri -Headers $h -Body $body
}

function Read-ExoWithRetry {
    <#
      A READ that distinguishes the three answers the old code collapsed into one:
        found / absent (a single-object -Lookup that Exchange says does not exist) / unreadable.
      Transient failures (401/403 while the role propagates -- measured, 429, 5xx) are retried a
      bounded number of times; what is still failing after that is 'unreadable', and the CALLER
      refuses. Returns @{ outcome; value; error }.
    #>
    param([Parameter(Mandatory)][string]$Cmdlet, [hashtable]$Parameters = @{}, [switch]$Lookup, [int]$Attempts = 6, [int]$DelaySeconds = 15)
    $err = ''
    for ($i = 1; $i -le $Attempts; $i++) {
        try { return @{ outcome = 'found'; value = (Invoke-Exo -Cmdlet $Cmdlet -Parameters $Parameters); error = '' } }
        catch {
            $err = ("$($_.Exception.Message) $($_.ErrorDetails.Message)" -replace '\s+', ' ').Trim()
            if ($Lookup -and (Resolve-PimExoLookupOutcome -ErrorText $err) -eq 'absent') { return @{ outcome = 'absent'; value = $null; error = '' } }
            if (-not (Test-PimTransientReadError -Text $err) -or $i -eq $Attempts) { break }
            Note "$Cmdlet not readable yet (attempt $i/$Attempts): $(($err -split '\. ')[0])" 'DarkGray'
            Start-Sleep -Seconds $DelaySeconds
        }
    }
    return @{ outcome = 'unreadable'; value = $null; error = $err.Substring(0, [Math]::Min(300, $err.Length)) }
}

Step 'wait for Exchange administration to become usable'
# Two independent delays are being absorbed here, and they look identical from outside: app-role
# propagation (seconds to minutes) and EXO org provisioning after a licence lands (can be longer).
# Reporting the elapsed wait is what makes them distinguishable in a log afterwards.
$deadline = (Get-Date).AddSeconds($TimeoutSeconds)
$ready = $false; $lastErr = ''
$attempt = 0
while ((Get-Date) -lt $deadline) {
    $attempt++
    try { [void](Invoke-Exo -Cmdlet 'Get-OrganizationConfig'); $ready = $true; break }
    catch {
        $lastErr = ($_.Exception.Message -split "`n")[0]
        Note "attempt $attempt : not ready yet ($lastErr)" 'DarkGray'
        if ($whatIfRun) { break }   # a preview does not wait for grants it did not make
        Start-Sleep -Seconds 20
    }
}
if (-not $ready -and $whatIfRun) {
    $exoPreviewable = $false
    Note "WhatIf: Exchange administration is not usable for this sign-in yet ($lastErr) -- steps [1]-[3] cannot be previewed; run without -WhatIf to apply. Without -WhatIf they would: create the shared mailbox $sender, register each sending identity in Exchange, create the scope for $sender only and give each identity 'Application Mail.Send' on it." 'DarkYellow'
    Add-Result 'exchange-ready' 'whatif' 'not previewable (Exchange not usable for this sign-in yet)'
}
elseif (-not $ready) {
    Add-Result 'exchange-ready' 'FAILED' $lastErr
    Fail "Exchange admin endpoint never became usable within ${TimeoutSeconds}s (last error: $lastErr). Both app-role propagation and EXO org provisioning can cause this; re-running is safe and idempotent."
}
if ($ready) {
    Note "Exchange administration usable after $attempt attempt(s)" 'Green'
    Add-Result 'exchange-ready' 'ok' "$attempt attempt(s)"
}

# --- 1. CREATE THE SHARED SENDER MAILBOX ---------------------------------------
$mbxPlanned = $false   # -WhatIf: the mailbox does not exist and would be created
if ($exoPreviewable) {
Step "[1] shared sender mailbox  $sender"
$existingMbx = $null
# Not-found is the normal first-run path. ANY OTHER failure is "could not look", and it used to be
# read as "absent" too -- which planned a create against a mailbox that existed. Refuse instead.
$mbxRead = Read-ExoWithRetry -Cmdlet 'Get-Mailbox' -Parameters @{ Identity = $sender } -Lookup
if ($mbxRead.outcome -eq 'unreadable') {
    Add-Result 'mailbox' 'FAILED' "could not read: $($mbxRead.error)"
    Fail "could not check whether the mailbox '$sender' exists ($($mbxRead.error)) -- refusing to create it on a guess. Re-run when Exchange answers."
}
if ($mbxRead.outcome -eq 'found') { $existingMbx = @($mbxRead.value.value) | Select-Object -First 1 }

if ($existingMbx) {
    Note "mailbox already exists (RecipientTypeDetails=$($existingMbx.RecipientTypeDetails))" 'DarkGray'
    Add-Result 'mailbox' 'already' "$($existingMbx.PrimarySmtpAddress)"
} elseif (-not $PSCmdlet.ShouldProcess("Exchange Online mailbox $sender", "create the shared sender mailbox (New-Mailbox -Shared, display name '$DisplayName')")) {
    if (-not $whatIfRun) { Fail "the shared mailbox $sender was not created (declined) -- nothing further is changed" }
    $mbxPlanned = $true
    Add-Result 'mailbox' 'whatif' "would create $sender"
} else {
    try {
        [void](Invoke-Exo -Cmdlet 'New-Mailbox' -Parameters @{
            Shared = $true; Name = $MailboxName; DisplayName = $DisplayName; PrimarySmtpAddress = $sender })
    } catch {
        $m = ($_.Exception.Message -split "`n")[0]
        $detail = if ($_.ErrorDetails.Message) { $_.ErrorDetails.Message.Substring(0, [Math]::Min(400, $_.ErrorDetails.Message.Length)) } else { '' }
        Add-Result 'mailbox' 'FAILED' "$m $detail"
        Fail "could not create the shared mailbox '$sender': $m $detail"
    }
    # Read back. A shared mailbox can take a moment to become queryable, so this is a bounded poll
    # rather than a single read -- and a create that never becomes visible is a FAILURE, not a pass.
    $mbxDeadline = (Get-Date).AddSeconds(180); $seen = $null
    while ((Get-Date) -lt $mbxDeadline) {
        try { $seen = @((Invoke-Exo -Cmdlet 'Get-Mailbox' -Parameters @{ Identity = $sender }).value) | Select-Object -First 1 } catch { $seen = $null }
        if ($seen) { break }
        Start-Sleep -Seconds 10
    }
    if (-not $seen) { Add-Result 'mailbox' 'FAILED' 'created but never became queryable'; Fail "mailbox '$sender' was created but never became queryable within 180s" }
    Note "mailbox created (verified by read-back): $($seen.PrimarySmtpAddress)" 'Green'
    $result.mailboxCreated = $true
    Add-Result 'mailbox' 'created' "$($seen.PrimarySmtpAddress)"
}
}   # end: $exoPreviewable (step [1])

# --- 1b. THE KEY GRAPH SENDS AS (BUG-296) -----------------------------------------
# The engine calls /users/<MailSender>/sendMail. Graph resolves an id or a userPrincipalName, never a bare mail address,
# so the value persisted below is the mailbox's UPN (mail still goes out FROM the primary address $sender).
Step "[1b] how Microsoft Graph addresses $sender"
$graphKey = [ordered]@{ key = ''; reason = '' }; $gkReadError = ''
$gkDeadline = (Get-Date).AddSeconds(180)
if ($mbxPlanned -or -not $exoPreviewable) {
    # -WhatIf: the mailbox does not exist yet, so the key Graph will address it by is known only once it is created.
    Note "WhatIf: the mailbox's directory UPN is known only after it is created -- the preview uses $sender" 'DarkYellow'
    $graphKey = [ordered]@{ key = $sender; reason = '' }
} else {
do {
    try {
        $f = [uri]::EscapeDataString("mail eq '$sender' or userPrincipalName eq '$sender' or proxyAddresses/any(p:p eq 'smtp:$sender')")
        $gu = @(GrAll -Path "users?`$filter=$f&`$select=id,userPrincipalName,mail,proxyAddresses"); $gkReadError = ''
    } catch { $gu = @(); $gkReadError = ($_.Exception.Message -split "`n")[0] }
    $graphKey = Resolve-PimMailSenderGraphKey -Sender $sender -GraphUsers $gu
    if ($graphKey.key -or $gkReadError) { break }
    Start-Sleep -Seconds 15
} while ((Get-Date) -lt $gkDeadline)
if ($gkReadError) {
    # Could not LOOK (e.g. no User.Read.All on the onboarding identity): keep the old behaviour, but say what it risks.
    Note "could not read the directory to find the mailbox's UPN ($gkReadError) -- storing $sender as it is; if Graph cannot resolve it, mail fails with 404: set MailSender to the mailbox's UPN." 'Yellow'
    $graphKey = [ordered]@{ key = $sender; reason = '' }
}
}   # end: the mailbox exists (step [1b] read)
if (-not $graphKey.key) { Add-Result 'graph-key' 'FAILED' $graphKey.reason; Fail "the mailbox $sender exists, but $($graphKey.reason). Re-run in a few minutes." }
$storeSender = $graphKey.key
if ($storeSender -ine $sender) { Note "Graph addresses this mailbox as $storeSender (its UPN); that is what the engine stores. Mail still goes out from $sender." 'Yellow' }
else { Note "Graph addresses it by $storeSender" 'DarkGray' }
Add-Result 'graph-key' 'ok' $storeSender
$result.storeSender = $storeSender

# --- 3. SCOPE THE SEND RIGHT TO THAT ONE MAILBOX -------------------------------
# Exchange Online RBAC FOR APPLICATIONS, not an Application Access Policy. Both express "this app
# may only touch this mailbox"; the RBAC one is chosen because it is the one that WORKS AND CAN BE
# READ BACK. Measured in a test tenant: Get-ApplicationAccessPolicy answers 404 and New-ApplicationAccessPolicy
# answers 400/500, so an AAP could be neither verified nor made idempotent -- and an unverifiable
# security control is not a security control. Get-ManagementRoleAssignment / Get-ManagementScope
# both read cleanly, so every step below is gated on a real read-back.
#
# Three objects:
#   New-ServicePrincipal          register the engine app inside Exchange
#   New-ManagementScope           a recipient scope matching EXACTLY the sender mailbox
#   New-ManagementRoleAssignment  'Application Mail.Send' bound to the app AND that scope
# A first name for the -WhatIf preview (before Exchange is read): -ScopeName, else '<mailbox>-SendScope'. Once the scopes are
# read, Resolve-PimMailSenderScope decides it for real (an existing scope for this mailbox is adopted under its own name).
$scopeName = if ("$ScopeName".Trim()) { "$ScopeName".Trim() } else { Get-PimMailSenderScopeName -Sender $sender }
if ($exoPreviewable) {
Step "[3] scope the send right to $sender (Exchange RBAC for applications)"

# 3a. hydrate the organization. A fresh EXO tenant is "dehydrated" and REFUSES every custom RBAC
#     create with InvalidOperationInDehydratedContextException -- a 400 that reads like a bad
#     request and actually means "not yet".
# 🪤 MEASURED, and this is the trap: Enable-OrganizationCustomization returns success immediately,
#    and Get-OrganizationConfig then reports IsDehydrated=FALSE while the creates STILL fail as
#    dehydrated. So the flag is NOT a readiness signal -- same shape as `exchange = Enabled` being
#    no proof of a mailbox. The only honest readiness test is to attempt the real operation and
#    retry, which is what Wait-Hydrated does. Do not "optimise" this into a flag check.
$dehydratedMarker = 'InvalidOperationInDehydratedContextException'
try {
    $oc = (Invoke-Exo -Cmdlet 'Get-OrganizationConfig').value[0]
    if ("$($oc.IsDehydrated)" -eq 'True') {
        if ($PSCmdlet.ShouldProcess('Exchange Online organization', 'enable organization customization (Enable-OrganizationCustomization; needed before any custom RBAC object)')) {
            Note 'organization is dehydrated -- enabling customization' 'DarkYellow'
            try { [void](Invoke-Exo -Cmdlet 'Enable-OrganizationCustomization') } catch {
                # Already-enabled is reported as an error by this cmdlet; not fatal.
                Note "Enable-OrganizationCustomization: $((($_.Exception.Message) -split "`n")[0])" 'DarkGray'
            }
        }
    } else { Note 'organization reports hydrated' 'DarkGray' }
} catch { Note "could not read organization config: $((($_.Exception.Message) -split "`n")[0])" 'DarkYellow' }

function Invoke-ExoWhenHydrated {
    # Run an EXO create. The outcome of a failure is decided by Resolve-PimExoCreateOutcome (pure,
    # tested offline):
    #   exists     -> SUCCESS (idempotent re-run; BUG-166 -- it used to be fatal)
    #   dehydrated -> wait for organization customization (up to -Seconds)
    #   retry      -> Exchange has not materialised a service principal created moments ago
    #                 (New-ManagementRoleAssignment answers 404; measured on two test tenants) -- bounded wait
    #   fail       -> returned at once: a real failure must not be hidden behind a long wait
    param([Parameter(Mandatory)][string]$Cmdlet, [hashtable]$Parameters = @{}, [int]$Seconds = 3600, [string]$What = 'object',
          [int]$MaterialiseSeconds = 600)
    $stop = (Get-Date).AddSeconds($Seconds); $matStop = (Get-Date).AddSeconds($MaterialiseSeconds); $n = 0
    $notReadyStart = $null; $notReadyN = 0
    while ($true) {
        $n++
        try { return @{ ok = $true; existed = $false; value = (Invoke-Exo -Cmdlet $Cmdlet -Parameters $Parameters) } }
        catch {
            $e = $_
            $raw = "$($e.ErrorDetails.Message)"
            $txt = "$($e.Exception.Message) $raw"
            switch (Resolve-PimExoCreateOutcome -Cmdlet $Cmdlet -ErrorText $txt) {
                'exists' { return @{ ok = $true; existed = $true; value = $null } }
                'dehydrated' {
                    if ((Get-Date) -ge $stop) { return @{ ok = $false; error = 'organization still dehydrated'; detail = $raw } }
                    if ($n -eq 1 -or ($n % 5) -eq 0) { Note "waiting for organization customization to take effect ($What, attempt $n)" 'DarkGray' }
                    Start-Sleep -Seconds 60
                }
                'notready' {
                    # INSTALL-HARDEN-1 item 4: a just-hydrated organization refuses RBAC creates ("delegating role
                    # assignment") for ~40-60 min. Bounded (-ExchangeReadyMinutes, default 75), a plain line every attempt.
                    if (-not $notReadyStart) { $notReadyStart = Get-Date }
                    $notReadyN++
                    $w = Get-PimExoNotReadyWait -Attempt $notReadyN -ElapsedSeconds ((Get-Date) - $notReadyStart).TotalSeconds -BoundSeconds ($ExchangeReadyMinutes * 60) -IntervalSeconds $ExchangeReadyIntervalSeconds -What $What
                    if (-not $w.wait) { return @{ ok = $false; error = $w.message; detail = $raw } }
                    Note $w.message 'DarkYellow'
                    if ($OnProgress) { try { & $OnProgress $w.message | Out-Null } catch { } }
                    Start-Sleep -Seconds $w.sleepSeconds
                }
                'retry' {
                    if ((Get-Date) -ge $matStop) { return @{ ok = $false; error = "Exchange never made the new service principal usable within ${MaterialiseSeconds}s"; detail = $raw } }
                    Note "Exchange has not made the new service principal usable yet ($What, attempt $n) -- waiting" 'DarkGray'
                    Start-Sleep -Seconds 30
                }
                default { return @{ ok = $false; error = ($e.Exception.Message -split "`n")[0]; detail = $raw } }
            }
        }
    }
}

# 3b-3d. PLAN, then execute. What is missing is decided by New-PimMailSenderExoPlan
#     (_PimMailSenderPlan.ps1, tested offline): New-ServicePrincipal for each SENDING identity,
#     New-ManagementScope for the sender mailbox, New-ManagementRoleAssignment 'Application Mail.Send'
#     per identity. An empty plan = already in place; a second run writes nothing.
# 🔴 THE OLD CHECK MATCHED ROLE + SCOPE ONLY. Once the engine SPN held the assignment, the managed
#     identity's was reported "already present" and never created -- and the hosted engine, which
#     sends as that managed identity, was refused with nothing in this log to say why. The plan
#     matches assignments by ASSIGNEE.
# The scope name is decided AFTER the reads below (Resolve-PimMailSenderScope): a scope that already restricts to this
# sender is adopted under its existing name; else -ScopeName; else '<mailbox>-SendScope' (§94: one scope per mailbox).
# 🔴 BUG-166 (b) -- these three used to end in `catch { @() }`, so "I could not read the scopes" became
# "there are no scopes": measured on two test tenants, Get-ManagementScope answered 401 during the Exchange
# Administrator propagation, the plan said "create", and New-ManagementScope then failed with
# ADObjectAlreadyExistsException. A plan is only as good as the reads under it: an unreadable one
# STOPS the run (re-running is safe), it never plans a create.
$exoSpList = $null; $scopes = $null; $assigns = $null
$pre = [ordered]@{
    'Get-ServicePrincipal'         = @{ }
    'Get-ManagementScope'          = @{ }
    'Get-ManagementRoleAssignment' = @{ RoleAssigneeType = 'ServicePrincipal' }
}
$preRead = @{}
foreach ($c in $pre.Keys) {
    $rr = Read-ExoWithRetry -Cmdlet $c -Parameters $pre[$c]
    if ($rr.outcome -ne 'found') {
        Add-Result "exo-read:$c" 'FAILED' $rr.error
        Fail "could not read the existing Exchange configuration ($($c): $($rr.error)) -- refusing to plan changes on a partial picture. Nothing was changed; re-run when Exchange answers."
    }
    $preRead[$c] = @($rr.value.value)
}
$exoSpList = $preRead['Get-ServicePrincipal']; $scopes = $preRead['Get-ManagementScope']; $assigns = $preRead['Get-ManagementRoleAssignment']
$scopePick = Resolve-PimMailSenderScope -Sender $sender -ScopeName $ScopeName -Scopes $scopes
$scopeName = $scopePick.name
if ($scopePick.note) { Note $scopePick.note 'DarkGray' }
$result.scopeName = $scopeName
$engineOid = if ($engineSp) { "$($engineSp.id)" } else { '' }
$exoPlan = @(New-PimMailSenderExoPlan -ExoServicePrincipals $exoSpList -Scopes $scopes -Assignments $assigns `
    -Principals $sendPrincipals -Sender $sender -ScopeName $scopeName -EngineAppId $EngineAppId -EngineObjectId $engineOid `
    -RemoveEngineSpnAssignment:$RemoveEngineSpnAssignment)
if (-not $exoPlan.Count) {
    Note 'Exchange registration, scope and scoped Application Mail.Send assignment(s) already present' 'DarkGray'
    $result.accessPolicyCreated = $true; Add-Result 'exo-scoped-send' 'already' "$scopeName"
    $script:PimScopedSendConfirmed = $true   # MAIL-STEP-PROOF: read cleanly above, every sending identity holds its assignment
}
$exoDone = 0
foreach ($item in $exoPlan) {
    if (-not $PSCmdlet.ShouldProcess("Exchange Online ($sender)", "$($item.cmdlet): $($item.what)")) {
        if (-not $whatIfRun) { Fail "Exchange change declined ($($item.cmdlet): $($item.what)) -- the scoped send right is incomplete; re-run to finish" }
        Add-Result "exo:$($item.cmdlet)" 'whatif' "would $($item.what)"
        continue
    }
    $r = Invoke-ExoWhenHydrated -Cmdlet $item.cmdlet -What $item.what -Parameters $item.parameters
    # 2026-10-21 (a customer install): the scope read came back empty right after the role activation, so the plan tried to CREATE
    # a scope another name already holds with the same filter, and Exchange refused it naming that scope. Adopt the scope
    # Exchange names (the same filter = the same sender) and point this run's assignments at it -- never a second scope.
    if (-not $r.ok -and "$($item.cmdlet)" -eq 'New-ManagementScope') {
        $dupScope = Get-PimExoDuplicateScopeName -Text "$($r.error) $($r.detail)"
        if ($dupScope) {
            $plannedScope = "$($item.parameters.Name)"
            foreach ($later in $exoPlan) { if ($later.parameters -and "$($later.parameters.CustomResourceScope)" -eq $plannedScope) { $later.parameters.CustomResourceScope = $dupScope } }
            $scopeName = $dupScope
            Note "the existing scope '$dupScope' already restricts to $sender -- adopted (Exchange refused a second scope with the same filter)" 'DarkGray'
            Add-Result 'exo:New-ManagementScope' 'already' "adopted $dupScope"
            continue
        }
    }
    # 2026-10-13 (a customer install: "could not scope ... 400 (Bad Request)" and nothing else): the failure line carries Exchange's
    # own answer -- the 400's text was kept in $r.detail and printed nowhere, so the customer could not tell why.
    if (-not $r.ok) {
        $exoSaid = (("$($r.detail)" -replace '\s+', ' ').Trim())
        if ($exoSaid.Length -gt 600) { $exoSaid = $exoSaid.Substring(0, 600) + ' ...' }
        Add-Result "exo:$($item.cmdlet)" 'FAILED' "$($r.error) $($r.detail)"
        Fail ("could not $($item.what): $($r.error)" + $(if ($exoSaid) { " -- Exchange said: $exoSaid" } else { '' }))
    }
    if ($r.existed) { Note "$($item.cmdlet): $($item.what) -- already present, nothing changed" 'DarkGray' }
    else { Note "$($item.cmdlet): $($item.what)" 'Green' }
    $exoDone++
}
if ($exoDone) {
    # Read back -- the whole reason RBAC was chosen over an Application Access Policy. EVERY sending
    # identity must hold its own assignment, not merely "some" assignment in the scope.
    $confirmedScope = Confirm-Eventually -What 'scoped Mail.Send assignment' -Seconds 120 -Test {
        $now = @((Invoke-Exo -Cmdlet 'Get-ManagementRoleAssignment' -Parameters @{ RoleAssigneeType = 'ServicePrincipal' }).value)
        $spNow = @((Invoke-Exo -Cmdlet 'Get-ServicePrincipal').value)
        @($sendPrincipals | Where-Object {
            $ids = Get-PimExoAssigneeIds -ExoServicePrincipals $spNow -AppId $_.appId -ObjectId $_.objectId
            -not @(Select-PimExoMailSendAssignment -Assignments $now -ScopeName $scopeName -AssigneeIds $ids -AssignmentName $_.assignmentName -AlternateNames @($_.legacyAssignmentNames)).Count
        }).Count -eq 0
    }
    if (-not $confirmedScope) { Add-Result 'exo-scoped-send' 'FAILED' 'not present on read-back'; Fail 'the scoped Mail.Send assignment was created but is not present on read-back for every sending identity' }
    Note "scoped Application Mail.Send assignment(s) verified for: $((@($sendPrincipals | ForEach-Object { $_.appId })) -join ', ') -> $scopeName" 'Green'
    $result.accessPolicyCreated = $true; Add-Result 'exo-scoped-send' 'created' "$($exoPlan.Count) change(s) -> $scopeName"
    $script:PimScopedSendConfirmed = $true   # MAIL-STEP-PROOF: verified on read-back for EVERY sending identity
}
if ($EngineAppId -and -not $RemoveEngineSpnAssignment -and @($sendPrincipals | Where-Object { $_.kind -eq 'managed-identity' }).Count) {
    Note "the engine SPN's older scoped assignment (if any) is LEFT in place -- pass -RemoveEngineSpnAssignment to remove it" 'DarkGray'
}
}   # end: $exoPreviewable (step [3])

# --- 2. ENSURE THE ENGINE SPN DOES *NOT* HOLD TENANT-WIDE Mail.Send -------------
# 🔒 THIS IS INVERTED FROM IMP-06 AS WRITTEN, AND THE INVERSION IS THE WHOLE POINT.
# IMP-06 step 3 said "grant the engine SPN Mail.Send" and step 4 said "scope it". Measured in a test tenant:
# doing both leaves the app UNSCOPED. Exchange RBAC for Applications does not RESTRICT a tenant-wide
# Graph consent -- it GRANTS scoped access in its own right, and a tenant-wide consent sitting
# alongside it simply keeps winning.
#
# Proven, both directions, ~60 minutes apart so propagation is not the explanation:
#   * WITH the Graph consent    -- send as the scoped mailbox: ACCEPTED.
#                                  send as a second out-of-scope mailbox: ACCEPTED.  <- unscoped
#   * WITHOUT the Graph consent -- Mail.Send verified GONE from the minted token, then
#                                  send as the scoped mailbox: ACCEPTED.   <- RBAC grants it
#                                  send as a second out-of-scope mailbox: ErrorAccessDenied. <- scoped
#
# So the correct configuration grants NO tenant-wide permission at all: the RBAC assignment created
# above is the entire grant, and it is scoped by construction. That is strictly better than what the
# finding asked for -- there is never a tenant-wide send right to claw back.
#
# An EXISTING grant must therefore be REVOKED, not left alone: its mere presence silently defeats the
# scope, and it is exactly what an earlier run of this very script (and any hand-done IMP-06) would
# have left behind.
Step '[2] ensure NO tenant-wide Graph Mail.Send on any sending identity or the engine SPN (it would defeat the scope)'
# Every identity that can send is checked: the managed identities that now carry the scoped grant,
# AND the engine SPN -- a tenant-wide consent on either defeats the per-mailbox scope.
$tenantWideTargets = @()
foreach ($p in $sendPrincipals) { $tenantWideTargets += [pscustomobject]@{ label = "$($p.kind) $($p.appId)"; spId = $p.objectId } }
if ($engineSp -and -not @($tenantWideTargets | Where-Object { $_.spId -eq "$($engineSp.id)" }).Count) {
    $tenantWideTargets += [pscustomobject]@{ label = "engine SPN $EngineAppId"; spId = "$($engineSp.id)" }
}
$anyRevoked = $false
foreach ($tgt in $tenantWideTargets) {
    # Every page (GrAll): the engine SPN holds ~100 app roles, so a first-page read could miss the very
    # consent this step exists to find -- and report the send right as scoped when it is not.
    try { $existingGrant = @(Select-PimTenantWideMailSend -Assignments @(GrAll -Path "servicePrincipals/$($tgt.spId)/appRoleAssignments") -GraphSpId $graphSp.id -MailSendRoleId $mailSendRole.id) }
    catch { Fail "could not read the app-role assignments of $($tgt.label), so cannot tell whether it holds a tenant-wide Mail.Send -- refusing to report the send right as scoped: $($_.Exception.Message)" }
    if (-not $existingGrant.Count) { Note "no tenant-wide Mail.Send on $($tgt.label) -- correct" 'Green'; continue }
    if (-not $PSCmdlet.ShouldProcess($tgt.label, 'REVOKE tenant-wide Graph Mail.Send')) { Add-Result 'mail-send-tenantwide' 'whatif' "would revoke on $($tgt.label)"; continue }
    Note "found $($existingGrant.Count) tenant-wide Mail.Send assignment(s) on $($tgt.label) -- REVOKING (they defeat the scope)" 'DarkYellow'
    foreach ($a in $existingGrant) {
        try { Gr -Method DELETE -Path "servicePrincipals/$($tgt.spId)/appRoleAssignments/$($a.id)" | Out-Null }
        catch { Fail "could not revoke tenant-wide Mail.Send ($($a.id)) on $($tgt.label): $($_.Exception.Message)" }
    }
    $revoked = Confirm-Eventually -What 'Mail.Send revocation' -Test {
        @(Select-PimTenantWideMailSend -Assignments @(GrAll -Path "servicePrincipals/$($tgt.spId)/appRoleAssignments") -GraphSpId $graphSp.id -MailSendRoleId $mailSendRole.id).Count -eq 0
    }
    if (-not $revoked) { Fail "tenant-wide Mail.Send was deleted on $($tgt.label) but is still present on read-back -- the send right is NOT scoped" }
    Note "tenant-wide Mail.Send revoked on $($tgt.label) (verified by read-back)" 'Green'
    $anyRevoked = $true
}
$result.mailSendGranted = $false
if ($anyRevoked) { Add-Result 'mail-send-tenantwide' 'revoked' 'removed so the RBAC scope governs' }
else { Add-Result 'mail-send-tenantwide' 'absent' 'correct (RBAC grants, scoped)' }

# --- 4. PERSIST THE SENDER (IMP-06a runtime half) --------------------------------
# This is the step that actually makes the environment send. Everything above only made it
# POSSIBLE: without a configured sender the notify path still renders and returns quietly.
Step '[4] persist the sender to pim.Settings'
if (-not "$SqlServerFqdn".Trim()) {
    Note "Saved: no -- no -SqlServerFqdn was given. Finish in PIM Manager: Get Started > Mail sender > Check and send a test mail (mailbox $storeSender)" 'DarkYellow'
    Add-Result 'persist' 'skipped' 'no -SqlServerFqdn'
} elseif (-not $PSCmdlet.ShouldProcess("$SqlServerFqdn / $SqlDatabase (pim.Settings)", "store MailSender = $storeSender and MailMode = sharedMailbox")) {
    # -WhatIf (or declined): no SQL connection is opened at all.
    Add-Result 'persist' 'whatif' "would store MailSender = $storeSender"
} else {
# ===== 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 =====
    # An EXPLICIT credential beats ambient managed identity in New-PimSqlConnection, which matters
    # here: a build machine has an MI of its own, and an MI can only mint tokens for ITS OWN tenant, so an
    # ambient token would authenticate successfully against the WRONG directory (BUG-34). The
    # onboarding SPN is the SQL server's Entra admin, so it is the identity that can write.
    $global:PIM_TenantId     = $TenantId
    $persistErr = ''
    if ($browserMode) {
        # The person's own SQL token (Azure PowerShell public client, from the browser sign-in). No app credential is set,
        # managed identity is switched off (a VM's own would otherwise win), and the token is placed in the store's
        # per-identity token cache under the "no app credential" key -- the cache is read before any other source, so
        # the connection presents exactly this person and nothing ambient (never a tool's default account).
        foreach ($n in 'PIM_ClientId', 'PIM_ClientSecret', 'PIM_CertThumbprint', 'PIM_SqlClientId', 'PIM_SqlClientSecret', 'PIM_SqlCertThumbprint', 'PIM_SqlAccessToken') { Set-Variable -Scope Global -Name $n -Value $null }
        $global:PIM_NoManagedIdentity = $true
        try {
            $sqlTok = Get-PimMailAdminToken -Resource 'https://database.windows.net'
            $script:PimSqlTokenCache = @{ key = 'sql|||False'; token = $sqlTok; expires = (Get-Date).ToUniversalTime().AddMinutes(45) }
            $global:PIM_SetupActor = Get-PimMsSignedInUpn
        } catch { $persistErr = "could not sign in to Azure SQL: $($_.Exception.Message)" }
    }
    elseif ($UseSignedInAccount) {
        # the signed-in session (a member of the SQL admin group) writes the store -- as Set-PimLicense -UseSignedInAccount
# (helper _PimSignedIn.ps1 already inlined above)
        $null = Connect-PimSignedInSql -TenantId $TenantId
    } else {
    $global:PIM_ClientId     = $AdminAppId
    # Set only the credential that was actually supplied, and CLEAR the other -- a stale
    # global of the opposite kind would otherwise win inside Get-PimRestToken's chain and
    # authenticate as something other than what this call asked for. Same reasoning, and the
    # same two lines, as Grant-PimMiSql.
    $global:PIM_ClientSecret   = $AdminSecret
    $global:PIM_CertThumbprint = $AdminCertThumbprint
    }
    $global:PIM_SqlServer    = $SqlServerFqdn
    $global:PIM_SqlDatabase  = $SqlDatabase
    $script:PimMailStoredAll = $null
    $writeSender = {
        if ($persistErr) { throw $persistErr }
        $cs = Get-PimSqlConnectionString -Server $SqlServerFqdn -Database $SqlDatabase
        Set-PimSqlSetting -ConnectionString $cs -Name 'MailSender' -Value $storeSender
        # MAIL-1: this script sets up the SHARED MAILBOX mode, so it also says so (an environment switched to the SMTP
        # relay goes back to the mailbox it was just given).
        Set-PimSqlSetting -ConnectionString $cs -Name 'MailMode' -Value 'sharedMailbox'
        # Read back through the same reader the ENGINE uses, not through a raw SELECT -- the point
        # is to prove what the engine will see, not that a row exists.
        $all = Get-PimAllSqlSettings -ConnectionString $cs
        $st = "$($all['MailSender'])".Trim()
        if ($st -ne $storeSender) { throw "read-back mismatch: store holds '$st', expected '$storeSender'" }
        $script:PimMailStoredAll = $all
        # INSTALL-FIX (100.25 item 4): MailSender is the UPN (above); the PRIMARY SMTP address the customer chose ($sender)
        # is stored beside it, so PIM Manager and the end-of-install check show that address (with the UPN as detail).
        $addrRec = New-PimMailSenderAddressRecord -Sender $storeSender -Address $sender
        if ($addrRec) {
            try { Set-PimSqlSetting -ConnectionString $cs -Name 'MailSenderAddress' -Value $addrRec }
            catch { Note "the mailbox's address could not be stored ($(($_.Exception.Message -split "`n")[0])) -- PIM Manager shows the UPN $storeSender instead" 'Yellow' }
        }
        # MAIL-STEP-PROOF (owner 2026-10-09: "why dont you trigger somehing or accept that we just did a test mail"): store
        # what step [3]'s read-back CONFIRMED -- the scoped Application Mail.Send assignment for every sending identity, in
        # ONE scope on THIS mailbox -- so PIM Manager can show the engine job's send right as granted (with the Manager's
        # own test mail) without waiting for an engine send. Only a confirmed read-back is stored; never a guess. Written
        # here, inside the write, so a temporary firewall rule (-AllowThisIpTemporarily) covers it too.
        $chk = New-PimMailSenderSetupCheck -Confirmed ([bool]$script:PimScopedSendConfirmed) -Sender $storeSender -ScopeName "$scopeName" -Principals $sendPrincipals -By "$($global:PIM_SetupActor)"
        if ($chk) {
            try { Set-PimSqlSetting -ConnectionString $cs -Name 'MailSenderSetupCheck' -Value $chk; Note "stored the setup check for PIM Manager: scoped Mail.Send confirmed for $(@($chk.identities).Count) sending identit$(if (@($chk.identities).Count -eq 1) { 'y' } else { 'ies' }) in $scopeName" 'Green' }
            catch { Note "the setup check could not be stored ($(($_.Exception.Message -split "`n")[0])) -- PIM Manager proves the engine at its first send instead" 'Yellow' }
        }
    }
    # MAIL-NAMING 100.14 item 5: -AllowThisIpTemporarily -- the temporary SQL firewall rule (ARM, as the identity that signed
    # in here). The server is found by its name in -SubscriptionId, else in every subscription that identity can see.
    $sqlServerName = ("$SqlServerFqdn".Trim() -split '\.')[0]
    $script:PimSqlServerId = ''
    $armApi = '2021-11-01'
    $findSqlServer = {
        if ($script:PimSqlServerId) { return $script:PimSqlServerId }
        $h = @{ Authorization = "Bearer $(Get-PimMailAdminToken -Resource 'arm')" }
        $subs = if ("$SubscriptionId".Trim()) { @("$SubscriptionId".Trim()) } else {
            @((Invoke-RestMethod -Headers $h -Uri 'https://management.azure.com/subscriptions?api-version=2020-01-01').value | ForEach-Object { "$($_.subscriptionId)" } | Select-Object -First 50) }
        foreach ($s in $subs) {
            try { $hit = @((Invoke-RestMethod -Headers $h -Uri "https://management.azure.com/subscriptions/$s/providers/Microsoft.Sql/servers?api-version=$armApi").value | Where-Object { "$($_.name)" -ieq $sqlServerName }) | Select-Object -First 1 } catch { $hit = $null }
            if ($hit) { $script:PimSqlServerId = "$($hit.id)"; return $script:PimSqlServerId }
        }
        throw "the SQL server '$sqlServerName' was not found in the subscription(s) this sign-in can see$(if (-not "$SubscriptionId".Trim()) { ' (pass -SubscriptionId)' })"
    }
    $addRule = {
        param($ip)
        $sid = & $findSqlServer
        # framework rule 11e (owner 2026-11-04): a PRIVATE store (public access not Enabled) never gets a firewall / IP rule,
        # not even for the seconds of this write -- refused; the write runs inside the network or is a customer step
        $srvObj = Invoke-RestMethod -Uri "https://management.azure.com$sid`?api-version=$armApi" -Headers @{ Authorization = "Bearer $(Get-PimMailAdminToken -Resource 'arm')" }
        if ("$($srvObj.properties.publicNetworkAccess)" -ne 'Enabled') {
            throw "REFUSED (framework rule 11e): the SQL server '$sqlServerName' is private (publicNetworkAccess=$("$($srvObj.properties.publicNetworkAccess)")) -- no temporary firewall rule is added to a private install; run this from a machine inside its network"
        }
        $rn = New-PimSqlTempFirewallRuleName -Ip $ip
        $u = "https://management.azure.com$sid/firewallRules/$rn`?api-version=$armApi"
        [void](Invoke-RestMethod -Method PUT -Uri $u -Headers @{ Authorization = "Bearer $(Get-PimMailAdminToken -Resource 'arm')"; 'Content-Type' = 'application/json' } `
                   -Body (@{ properties = @{ startIpAddress = $ip; endIpAddress = $ip } } | ConvertTo-Json -Depth 4))
        Note "temporary SQL firewall rule '$rn' added for $ip (it is removed again right after the write)" 'DarkYellow'
        return $u
    }
    $removeRule = {
        param($u)
        [void](Invoke-RestMethod -Method DELETE -Uri $u -Headers @{ Authorization = "Bearer $(Get-PimMailAdminToken -Resource 'arm')" })
    }
    $scriptCmdlet = $PSCmdlet   # THIS script's ShouldProcess (-WhatIf / -Confirm), not the helper function's
    $mayAddRule = { param($ip) $scriptCmdlet.ShouldProcess("SQL server $SqlServerFqdn", "add a TEMPORARY firewall rule for $ip, write the sender, remove the rule") }
    $wr = Invoke-PimSqlWriteWithTemporaryFirewall -Write $writeSender -AllowThisIpTemporarily:$AllowThisIpTemporarily -AddRule $addRule -RemoveRule $removeRule -ShouldProcess $mayAddRule
    if ($wr.ruleAdded) {
        if ($wr.ruleRemoved) { Note 'temporary SQL firewall rule removed again' 'DarkGray' }
        else { Write-Host "    WARNING: the temporary SQL firewall rule could NOT be removed ($($wr.removeError)). Remove it now: SQL server $sqlServerName > Networking > rule $(("$($wr.rule)" -split '/firewallRules/')[-1] -replace '\?.*$', '')" -ForegroundColor Red }
    }
    $finish = "Finish in PIM Manager: Get Started > Mail sender > Check and send a test mail (mailbox $storeSender)"
    if ($wr.ok) {
        $all = $script:PimMailStoredAll
        $stored = "$($all['MailSender'])".Trim()
        Note "Saved: yes -- pim.Settings MailSender = $stored, MailMode = $("$($all['MailMode'])".Trim()) (verified by read-back)" 'Green'
        Add-Result 'persist' 'ok' $stored
        $result.persisted = $true
    } else {
        $m = ("$($wr.error)" -split "`n")[0]
        $short = if ($wr.whatIf) { "Saved: no -- the temporary firewall rule was not added (-WhatIf / declined). $finish" }
                 elseif ($wr.firewall) { "Saved: no -- this PC cannot reach the PIM database (firewall). $finish$(if (-not $AllowThisIpTemporarily) { ', or re-run with -AllowThisIpTemporarily' })." }
                 else { "Saved: no -- $m. $finish." }
        if ($browserMode) {
            # From a person's own PC the store is often out of reach (a private endpoint, a firewall) -- and the hard part,
            # the mailbox and its scoped send right, IS done. So this is NOT a failure here: PIM Manager stores the sender.
            Add-Result 'persist' 'manual' $m
            $result.persisted = $false
            Note $short 'Yellow'
        } else {
            Add-Result 'persist' 'FAILED' $m
            Fail "mailbox + grants are in place, but the sender is not saved. $short"
        }
    }
}

# --- summary --------------------------------------------------------------------
if ($whatIfRun) {
    # 12.7: the preview ends here -- say what WOULD change, and that nothing did.
    $result.ok = $true
    Write-Host ""
    Write-Host ("=" * 78) -ForegroundColor Cyan
    Write-Host " WHATIF / PREVIEW -- nothing was changed" -ForegroundColor Yellow
    Write-Host ("=" * 78) -ForegroundColor Cyan
    foreach ($s in @($result.steps | Where-Object { "$($_.state)" -eq 'whatif' })) { Write-Host "  would: $($s.step) -- $($s.detail)" }
    if (-not @($result.steps | Where-Object { "$($_.state)" -eq 'whatif' }).Count) { Write-Host '  nothing to change: the mailbox, its scoped send right and the stored sender are already in place (as far as could be read).' }
    Write-Host "  Run the same command without -WhatIf to apply."
    Write-ResultFile
    exit 0
}
$result.ok = $true
Write-Host ""
Write-Host ("=" * 78) -ForegroundColor Cyan
Write-Host " MAIL SENDER READY" -ForegroundColor Green
Write-Host ("=" * 78) -ForegroundColor Cyan
Write-Host "  sender        : $sender"
Write-Host "  send right    : Exchange RBAC 'Application Mail.Send' -> scope '$scopeName' -> $sender ONLY"
foreach ($p in $sendPrincipals) {
    # the name the assignment really has: an existing (adopted) one keeps its name, a new one got the planned name
    $held = @(Select-PimExoMailSendAssignment -Assignments $assigns -ScopeName $scopeName -AssigneeIds (Get-PimExoAssigneeIds -ExoServicePrincipals $exoSpList -AppId $p.appId -ObjectId $p.objectId) -AssignmentName $p.assignmentName -AlternateNames @($p.legacyAssignmentNames)) | Select-Object -First 1
    $an = if ($held -and "$($held.Name)".Trim()) { "$($held.Name)".Trim() } else { $p.assignmentName }
    Write-Host "  sends as      : $($p.kind) $($p.appId)  (assignment $an)"
}
Write-Host "  tenant-wide   : NO Graph Mail.Send on any sending identity or the engine SPN -- by design"
Write-Host "  exchange plan : $($result.exchangePlan)"
Write-Host ""
# IMP-31 -- SAY WHAT PRIVILEGE IS LEFT BEHIND, AND UNTIL WHEN. The old run granted the provisioning
# identity tenant-wide Exchange administration and never mentioned it again; the tenant's own alerting
# was how anyone found out.
if ($delegatedMode) {
    # Nothing was granted to any identity in a browser / signed-in person run -- the administrator used their own role, which they keep.
    $result.privilegedGrants = [ordered]@{ identity = (Get-PimMailSignedInUpn); exchangeAdministrator = $null; exchangeManageAsApp = 'not used (delegated sign-in)' }
    Write-Host "  PRIVILEGED GRANTS: none -- the administrator $(Get-PimMailSignedInUpn) used their own role; no app was granted anything." -ForegroundColor Green
    Write-Host ""
} else {
try { $exchAdminNow = Read-ExchAdminGrant } catch { $exchAdminNow = $exchAdminState }
$exAdminLine = if (-not $exchAdminNow.active) { 'not active (expired or never granted)' }
               elseif ($exchAdminNow.kind -eq 'permanent') { 'ACTIVE, PERMANENT (standing privilege outside PIM -- remove it with a DIFFERENT administrator: an identity cannot remove its own directory role)' }
               elseif ((Test-PimGrantOverlong -Grant $exchAdminNow -Duration $ExchangeAdminDuration).overlong) { "ACTIVE until $($exchAdminNow.endDateTime.ToString('u')) -- LONGER than the requested ${ExchangeAdminDuration}: standing privilege until then (shorten or remove it with a different administrator)" }
               else { "active until $($exchAdminNow.endDateTime.ToString('u')), then expires on its own (granted through PIM)" }
$result.privilegedGrants = [ordered]@{
    identity = $AdminAppId
    exchangeAdministrator = [ordered]@{ active = [bool]$exchAdminNow.active; kind = "$($exchAdminNow.kind)"; endUtc = $(if ($exchAdminNow.endDateTime) { $exchAdminNow.endDateTime.ToString('o') } else { '' }) }
    exchangeManageAsApp = "$manageAsAppState"
}
$pc = if ($exchAdminNow.active -and $exchAdminNow.kind -eq 'permanent') { 'Red' } else { 'Yellow' }
Write-Host "  PRIVILEGED GRANTS STILL HELD by the setup identity $AdminAppId :" -ForegroundColor $pc
Write-Host "    Exchange Administrator (directory role) : $exAdminLine" -ForegroundColor $pc
Write-Host "    Exchange.ManageAsApp (app role)         : $(if ($manageAsAppState) { $manageAsAppState } else { 'not held' }) -- no expiry; inert without the directory role" -ForegroundColor $pc
Write-Host ""
}
if ($result.persisted) {
    Write-Host "  NEXT: PIM Manager > Get Started > Mail sender > Send a test mail."
} else {
    Write-Host "  NEXT: PIM Manager > Get Started > Mail sender > Check and send a test mail (mailbox $storeSender)."
}
Write-Host ""
# Say only what was verified BY READ-BACK. An earlier summary asserted "Mail.Send, RESTRICTED to
# that mailbox" while the app was in fact unscoped -- an unverified security claim is worse than
# none, because it stops anyone from checking.
Write-Host "  VERIFIED BY READ-BACK: mailbox exists; scoped RBAC assignment exists; no tenant-wide" -ForegroundColor Green
Write-Host "  Graph Mail.Send is present on any sending identity." -ForegroundColor Green
Write-Host "  The restriction was proven in a test tenant with a second out-of-scope mailbox (in-scope send" -ForegroundColor DarkGray
Write-Host "  accepted, out-of-scope send ErrorAccessDenied). This script does NOT re-prove it in your" -ForegroundColor DarkGray
Write-Host "  tenant -- that would mean creating a decoy mailbox. If you need that assurance here, do it" -ForegroundColor DarkGray
Write-Host "  deliberately and delete the decoy afterwards." -ForegroundColor DarkGray
Write-ResultFile
exit 0
} finally { Stop-PimScriptRun -Script 'Initialize-PimMailSender' }