Fix mock provider entitlements and capability ordering

docs/advanced/provider-capabilities.md

@@ -28,7 +28,15 @@ Naming convention:
 - dot-separated segments
 - no whitespace
 - starts with a letter
-- examples: `Identity.Read`, `Identity.Disable`, `Entitlement.Write`
+- examples: `Identity.Read`, `Identity.Disable`, `IdLE.Entitlement.List`
+
+### Entitlement capability set
+
+Providers that support entitlement assignments should advertise the minimal trio:
+
+- `IdLE.Entitlement.List` — list entitlements assigned to a specific identity
+- `IdLE.Entitlement.Grant` — assign an entitlement to an identity
+- `IdLE.Entitlement.Revoke` — remove an entitlement from an identity
 
 ## High-level flow
 

docs/usage/steps.md

@@ -71,6 +71,13 @@ IdLE uses a fail-fast execution model in V1:
 - a failing step stops plan execution
 - results and events capture what happened
 
+## Built-in steps (starter pack)
+
+IdLE ships with a small set of built-in steps to keep demos and tests frictionless:
+
+- **IdLE.Step.EnsureAttribute**: converges an identity attribute to the desired value using `With.IdentityKey`, `With.Name`, and `With.Value`. Requires a provider with `EnsureAttribute` and usually the `Identity.Attribute.Ensure` capability.
+- **IdLE.Step.EnsureEntitlement**: converges an entitlement assignment to `Present` or `Absent` using `With.IdentityKey`, `With.Entitlement` (Kind + Id + optional DisplayName), `With.State`, and optional `With.Provider` (default `Identity`). Requires provider methods `ListEntitlements` plus `GrantEntitlement` or `RevokeEntitlement` and typically the capabilities `IdLE.Entitlement.List` plus `IdLE.Entitlement.Grant|Revoke`.
+
 ## Related
 
 - [Workflows](workflows.md)

examples/README.md

@@ -22,6 +22,10 @@ Workflow samples are located in:
 
 - `examples/workflows/`
 
+Highlighted samples:
+
+- `joiner-ensureentitlement.psd1` — ensures a demo group assignment via the built-in EnsureEntitlement step
+
 Workflows are **data-only** PSD1 files. A minimal workflow looks like:
 
 ```powershell

examples/workflows/joiner-ensureentitlement.psd1

@@ -0,0 +1,18 @@
+@{
+    Name           = 'Joiner - Ensure Entitlement'
+    LifecycleEvent = 'Joiner'
+    Steps          = @(
+        @{
+            Name                 = 'Ensure Department'
+            Type                 = 'IdLE.Step.EnsureAttribute'
+            With                 = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT'; Provider = 'Identity' }
+            RequiresCapabilities = 'Identity.Attribute.Ensure'
+        },
+        @{
+            Name                 = 'Assign demo group'
+            Type                 = 'IdLE.Step.EnsureEntitlement'
+            With                 = @{ IdentityKey = 'user1'; Entitlement = @{ Kind = 'Group'; Id = 'demo-group'; DisplayName = 'Demo Group' }; State = 'Present'; Provider = 'Identity' }
+            RequiresCapabilities = @('IdLE.Entitlement.List', 'IdLE.Entitlement.Grant')
+        }
+    )
+}

src/IdLE.Core/Private/Get-IdleProviderCapabilities.ps1

@@ -38,30 +38,44 @@ function Get-IdleProviderCapabilities {
     )
 
     $capabilities = @()
+    $capabilitySource = 'none'
 
     # Prefer explicit advertisement (provider-controlled, deterministic).
     $hasGetCapabilitiesMethod = $Provider.PSObject.Methods.Name -contains 'GetCapabilities'
     if ($hasGetCapabilitiesMethod) {
         $capabilities = @($Provider.GetCapabilities())
+        $capabilitySource = 'explicit'
     }
     elseif ($AllowInference) {
         # Migration helper: infer a minimal set from known method names.
         # We keep this conservative to avoid accidentally overstating capabilities.
         $methodNames = @($Provider.PSObject.Methods.Name)
 
-        if ($methodNames -contains 'GetIdentity') {
-            $capabilities += 'Identity.Read'
+        if ($methodNames -contains 'GrantEntitlement') {
+            $capabilities += 'IdLE.Entitlement.Grant'
+        }
+        if ($methodNames -contains 'ListEntitlements') {
+            $capabilities += 'IdLE.Entitlement.List'
+        }
+        if ($methodNames -contains 'RevokeEntitlement') {
+            $capabilities += 'IdLE.Entitlement.Revoke'
         }
         if ($methodNames -contains 'EnsureAttribute') {
             $capabilities += 'Identity.Attribute.Ensure'
         }
         if ($methodNames -contains 'DisableIdentity') {
             $capabilities += 'Identity.Disable'
         }
+        if ($methodNames -contains 'GetIdentity') {
+            $capabilities += 'Identity.Read'
+        }
+
+        $capabilitySource = 'inferred'
     }
 
     # Normalize, validate, and return a stable list.
-    $normalized = @()
+    $normalized = New-Object System.Collections.Generic.List[string]
+    $seen = New-Object System.Collections.Generic.HashSet[string]
     foreach ($c in @($capabilities)) {
         if ($null -eq $c) {
             continue
@@ -81,8 +95,16 @@ function Get-IdleProviderCapabilities {
             throw "Provider capability '$s' is invalid. Expected dot-separated segments like 'Identity.Read' or 'Entitlement.Write'."
         }
 
-        $normalized += $s
+        if ($seen.Add($s)) {
+            $null = $normalized.Add($s)
+        }
+    }
+
+    if ($capabilitySource -eq 'explicit') {
+        return @($normalized | Sort-Object -Unique)
     }
 
-    return @($normalized | Sort-Object -Unique)
+    # Preserve inference ordering to keep well-known capabilities in priority order
+    # (e.g., entitlement operations before identity operations).
+    return @($normalized)
 }

src/IdLE.Core/Private/Get-IdleStepRegistry.ps1

@@ -121,5 +121,12 @@ function Get-IdleStepRegistry {
         }
     }
 
+    if (-not $registry.ContainsKey('IdLE.Step.EnsureEntitlement')) {
+        $handler = Resolve-IdleStepHandlerName -CommandName 'Invoke-IdleStepEnsureEntitlement' -ModuleName 'IdLE.Steps.Common'
+        if (-not [string]::IsNullOrWhiteSpace($handler)) {
+            $registry['IdLE.Step.EnsureEntitlement'] = $handler
+        }
+    }
+
     return $registry
 }