feat(infra) ARM-backed CosmosBootstrapper supersedes broken PR #62 RBAC

[jkeeley2073]

Summary

Supersedes PR #62. PR #62 attempted to fix the --ensure-cosmos-containers 403 against deployed Cosmos by defining a custom Cosmos data-plane role with Microsoft.DocumentDB/databaseAccounts/sqlDatabases/* in dataActions. Azure rejected the deploy with "the provided data action string does not correspond to any valid SQL data action" — confirming Cosmos's data-plane RBAC genuinely does NOT model schema-mutation actions, regardless of role definition. PR #62 was therefore non-functional code that landed in main; the deploy never actually applied.

This PR re-architects: schema bootstrap routes through Azure Resource Manager (the management plane) instead of attempting to extend data-plane RBAC.

What's new

ICosmosProvisioner abstraction with two implementations:

• ArmCosmosProvisioner — uses Azure.ResourceManager.CosmosDB against the management endpoint. Required for AAD-authed clients (deployed Cosmos). Auth check is by Azure RBAC at account scope: dev developer's subscription Owner inheritance covers it; production runtime principal will need Cosmos DB Operator (230815da-be43-4aae-9cb4-875f7bd000aa) at account scope.
• DataPlaneCosmosProvisioner — uses the existing Microsoft.Azure.Cosmos SDK. Used for the Aspire preview emulator path (master-key auth permits data-plane schema CRUD without ARM).

CosmosBootstrapper now delegates to the provisioner. Selection in AddCosmosPersistence based on whether Cosmos:AccountResourceId is configured.

New configuration: CosmosOptions.AccountResourceId (string?) sourced from the new Bicep output cosmosAccountResourceId.

Bicep changes:

• Revert PR fix(infra) custom Cosmos data-plane role permits database creation #62's invalid cosmosDeveloperRole resource.
• Restore PR feat(infra) grant Cosmos data-plane RBAC to developer principal in Bicep #60's well-known Cosmos DB Built-in Data Contributor (00000000-0000-0000-0000-000000000002) — correct for runtime data-plane operations (item CRUD, query, change feed, which MachineRepository / IngestionSourceRepository / OpdbSyncService actually exercise).
• Expose cosmosAccountResourceId as a new output (in modules/shared.bicep + passthrough in main-shared.bicep) so operators copy the value into $env:Cosmos__AccountResourceId after deploy.

Idempotency: Both provisioners use probe-then-create symmetry. ArmCosmosProvisioner.EnsureDatabaseAndContainersAsync probes the database via ExistsAsync before issuing CreateOrUpdateAsync, mirroring the container path's drift-detection contract.

Friendly-error guard: IsLikelyCosmosAccountResourceId pre-check at DI-resolution time throws InvalidOperationException with a remediation message naming the right az cosmosdb show ... --query id invocation when an operator pastes the wrong value (e.g., documentEndpoint URL instead of the ARM resource ID). ResourceIdentifier's ctor doesn't validate input strings.

Test Plan

• dotnet build PinballWizard.slnx -> 0 warnings, 0 errors
• dotnet test PinballWizard.slnx -> 507 / 507 passing (was 503 — CosmosProvisionerSelectionTests adds 4 tests covering ARM-vs-data-plane provisioner registration, the bootstrapper's DI shape, and the friendly-error remediation message)
• bicep build clean (CI gate)
• Live verification: after merge, re-deploy with pwsh ./infra/scripts/Deploy-SharedResources.ps1 -Environment dev (rolls back PR fix(infra) custom Cosmos data-plane role permits database creation #62's broken role definition; re-applies PR feat(infra) grant Cosmos data-plane RBAC to developer principal in Bicep #60's built-in Data Contributor assignment which never actually changed in Azure since the PR fix(infra) custom Cosmos data-plane role permits database creation #62 deploy failed mid-flight). Then:

$env:Cosmos__AccountEndpoint   = az cosmosdb show -n pinwiz-cosmos-dev-hlpz4 -g rg-pinwiz-shared-dev --query documentEndpoint -o tsv
$env:Cosmos__AccountResourceId = az cosmosdb show -n pinwiz-cosmos-dev-hlpz4 -g rg-pinwiz-shared-dev --query id              -o tsv
dotnet run --project src/PinballWizard.Cli -- --ensure-cosmos-containers

Expected: "Database 'pinwiz' already present via ARM." plus "Container '<name>' already present via ARM (partition key /<path>)." for each container — idempotent against the entities created manually during PR #62's diagnostic session.

Out of Scope

• Mocked-ArmClient integration tests. Reviewer flagged that the probe-then-create / drift-detection paths in ArmCosmosProvisioner aren't exercised by any test; only the DI-time selection is. Deferred — Azure.ResourceManager.CosmosDB's test fixture story is non-trivial (requires MockableArmResource/MockResponse plumbing), and the live re-deploy + smoke-test gives the canonical signal.
• Logging-message parity. Reviewer noted ARM logs "already present via ARM" / "created via ARM" while the data-plane logs "ready via data-plane SDK" (single message regardless of created vs existed). Cosmetic; defer.

Checklist

• CI is green (build + test + coverage + CodeQL + sanitization + bicep)
• PR title follows the Conventional Commits format above
• If this is a new architectural decision, an ADR has been added under docs/adr/ — N/A (this is the architecturally correct shape PR fix(infra) custom Cosmos data-plane role permits database creation #62 should have had; the underlying decision "Cosmos schema CRUD goes through ARM" is forced by Azure's data-plane RBAC, not chosen)
• If user-visible behavior changes, README.md and/or docs/ are updated in the same PR — README gains a "Running against deployed Cosmos" subsection
• If a memory in ~/.claude/projects/c--projects-PinballWizard/memory/ is now stale, it has been updated or removed in the same PR — handoff memory will be updated post-merge once the smoke-test is observed to succeed
• No TODO / FIXME / commented-out code committed
• No new entries in <NoWarn> without a comment explaining why and the removal criterion

Pre-push self-audit

Step 0 — /local-review (qualitative)

• Ran /local-review and addressed every critical finding before push
• Local review outcome: 3 critical (all fixed) / 3 minor (all fixed) / 4 categories clean
  • Critical fixed: AzureLocation(account.Id.Name) constructed a region from a resource name. Replaced with AzureLocation.EastUS2 (matches CosmosOptions.PreferredRegions default and the deployment region) at both database and container call sites.
  • Critical fixed: Bicep didn't actually emit cosmosAccountResourceId. Added the output to modules/shared.bicep + passthrough in main-shared.bicep.
  • Critical fixed: Database CreateOrUpdateAsync was unconditional (no probe-then-create like the container path). Added ExistsAsync probe with explicit "created" / "already present" log differentiation.
  • Minor fixed: friendlier error when Cosmos:AccountResourceId is malformed (IsLikelyCosmosAccountResourceId pre-check + remediation message naming the right az query).
  • Minor fixed: AddCosmosPersistence XML doc updated to mention ICosmosProvisioner registration.
  • Minor fixed: bug-class concern about ResourceIdentifier ctor not validating input — addressed by the pre-check.

Step 1 — Mechanical checklist

• Every new *Options property has at least one real getter call in src/ — CosmosOptions.AccountResourceId is read by AddCosmosPersistence (provisioner selection) AND consumed by ArmCosmosProvisioner ctor
• Sibling-diffed against the closest existing implementation — ArmCosmosProvisioner matches DataPlaneCosmosProvisioner for ctor null-checks, idempotent shape, drift-detection error message string, and probe-then-create symmetry post-fix
• No bare catch { } — only scoped catch (RequestFailedException ex) when (ex.Status == 404) for the container-missing case
• New ISourceScraper? — N/A
• Tests assert behavior, not just structure — CosmosProvisionerSelectionTests pins type-of-resolved-provisioner (selection contract), bootstrapper DI resolution, and the load-bearing remediation-message contents
• Build is zero-warning
• git log -1 --format='%an <%ae>' shows personal noreply, not work email