Issues/10 provider contracts entitlement operations get grant revoke

AGENTS.md

@@ -33,14 +33,17 @@ Authoritative docs:
 ## 2. How to behave as an agent
 
 ### 2.1 No assumptions
+
 - If something is unclear, **ask targeted questions**.
 - Prefer a sensible default proposal, but **explicitly label it** as a default.
 
 ### 2.2 One change-set at a time
+
 - Keep PRs focused: one issue / one theme.
 - Avoid drive-by refactors unless the issue is specifically about refactoring.
 
 ### 2.3 Determinism over cleverness
+
 - Prefer explicit validation and deterministic behavior.
 - Avoid “magic” behavior, hidden fallbacks, or implicit global state.
 
@@ -57,10 +60,12 @@ Follow `STYLEGUIDE.md` for the full rule set. In short:
 - Inline comments should explain **why**, not what
 
 ### 3.1 Public vs. Private
+
 - Keep a clean separation between Public and Private functions.
 - Treat exported commands as stable contracts.
 
 ### 3.2 Configuration is data-only (no code in config)
+
 - Workflow definitions (PSD1) must be **data-only**:
   - No `ScriptBlock`
   - No dynamic PowerShell expressions
@@ -71,18 +76,21 @@ Follow `STYLEGUIDE.md` for the full rule set. In short:
 ## 4. Architectural constraints
 
 ### 4.1 Headless core
+
 The engine (`IdLE.Core`) must **not** depend on:
 
 - UI frameworks
 - interactive prompts
 - service hosts / web servers
 
 ### 4.2 Steps vs. Providers
+
 - **Steps**: convergence logic, idempotent intent, no authentication
 - **Providers**: system adapters, handle authentication and external calls
 - Steps should only write to declared `State.*` outputs.
 
 ### 4.3 Eventing
+
 Use the single event contract:
 
 - `Context.EventSink.WriteEvent(Type, Message, StepName, Data)`
@@ -109,6 +117,7 @@ Follow `docs/advanced/testing.md` and `CONTRIBUTING.md`.
 - Update docs when changing contracts, configuration schema, public cmdlets, step behavior, or provider contracts.
 
 ### 6.1 Generated references
+
 The cmdlet and step references under `docs/reference/` are generated.
 Do **not** edit generated files by hand—regenerate via the repository tools as documented in `CONTRIBUTING.md`.
 
@@ -156,4 +165,3 @@ Prefer:
 - explicit validation over implicit behavior
 - small PRs over large rewrites
 - documentation + tests as part of the same change
-

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/reference/steps.md

@@ -61,3 +61,37 @@ The step is idempotent by design: it converges state to the desired value.
 | Value | Yes |
 
 ---
+
+## EnsureEntitlement
+
+- **Step Name**: $stepType
+- **Implementation**: $commandName
+- **Idempotent**: $idempotent
+- **Contracts**: $contracts
+- **Events**: Unknown
+
+**Synopsis**
+
+Ensures that an entitlement assignment is present or absent for an identity.
+
+**Description**
+
+This provider-agnostic step uses entitlement provider contracts to converge
+an assignment to the desired state. The host must supply a provider instance
+via `Context.Providers[<ProviderAlias>]` that implements:
+- ListEntitlements(identityKey)
+- GrantEntitlement(identityKey, entitlement)
+- RevokeEntitlement(identityKey, entitlement)
+
+The step is idempotent and only calls Grant/Revoke when the assignment needs
+to change.
+
+**Inputs (With.\*)**
+
+| Key | Required |
+| --- | --- |
+| IdentityKey | Yes |
+| Entitlement | Yes |
+| State | Yes |
+
+---

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
 }