Align ContextResolver parameters with Step.With + document AuthSession support

[blindzero]

Problem Statement

Context Resolvers must behave exactly like Steps regarding parameter shape and provider/auth handling.

Today there are two inconsistencies:

1. Provider parameter shape is inconsistent

   • Steps pass execution parameters via With.* (including With.Provider).
   • Context Resolvers currently accept Provider as a root-level key (outside of With).
   • This creates two different workflow “dialects” and increases misconfiguration risk.

2. AuthSession is implemented but under-documented

   • The engine already supports With.AuthSessionName and With.AuthSessionOptions for Context Resolvers via the same AuthSessionBroker pattern as Steps.
   • The public docs do not document this consistently.

This issue is a breaking change by design:

• No legacy compatibility, no aliases, no “migration” docs, no “deprecated” comments.

Proposed Solution

1) Canonical ContextResolver schema (same as Steps)

Context Resolvers MUST use Step-like With.* parameters:

ContextResolvers = @(
  @{
    Capability = 'IdLE.Identity.Read'
    With = @{
      IdentityKey        = '{{Request.IdentityKeys.Primary}}'
      Provider           = 'Identity'           # optional
      AuthSessionName    = 'Tier0'              # optional
      AuthSessionOptions = @{ Role = 'Tier0' }  # optional hashtable
    }
  }
)

Rules:

• Capability stays a required root key (unchanged).
• Provider at resolver root is removed (breaking; invalid schema).
• With.IdentityKey is required per capability:
  • required for IdLE.Identity.Read
  • required for IdLE.Entitlement.List
• With.Provider is optional, but provider selection MUST follow Step-like behavior (see below).
• With.AuthSessionName / With.AuthSessionOptions are supported and MUST behave like Steps.

2) Provider selection behavior (must match Steps)

Provider selection for Context Resolvers MUST be performed by the engine (not by providers), and MUST behave like Steps:

• If With.Provider is set: use that provider alias.
• If With.Provider is not set:
  • Find providers that advertise the resolver capability.
  • 0 matches → fail-fast (clear error).
  • 1 match → use that provider.
  • >1 matches → fail-fast (ambiguity; user must specify With.Provider).

No “pick first”, no hidden ordering-based behavior.

3) AuthSession behavior (must match Steps)

Context Resolvers MUST use the same AuthSessionBroker mechanism as Steps:

• If With.AuthSessionName is specified:
  • Require an AuthSessionBroker in Providers.
  • Acquire session via broker using name and options.
  • Pass AuthSession into provider methods that accept it (backwards-compatible via parameter detection).
• If no With.AuthSessionName is specified:
  • Behavior MUST be identical to Steps (keep the same default-acquisition rules Steps use today).

Security boundary:

• With.AuthSessionOptions must be a hashtable.
• ScriptBlocks inside AuthSessionOptions are rejected (same guardrails as Steps).

4) Implementation changes

4.1 Workflow schema validation

Update IdLE.Core/Private/Test-IdleWorkflowSchema.ps1:

• ContextResolvers allowed keys at resolver root:
  • Capability
  • With
• Remove root key Provider from the allowlist.
• Validate:
  • With must be a hashtable if present.
  • With.Provider must be a non-empty string if present.
  • With.AuthSessionOptions must be a hashtable if present.

Capability-specific required keys like With.IdentityKey are validated at dispatch time (see below), but may also be enforced at schema-validation time if desired (optional).

4.2 Resolver execution

Update IdLE.Core/Private/Invoke-IdleContextResolvers.ps1:

• Provider alias must be read from With.Provider (not from resolver root).
• Provider selection must follow the behavior defined above (0/1/>1 matches).
• Auth session acquisition must match Steps (align with Invoke-IdleProviderMethod behavior).
• Dispatch must continue to validate capability-specific required inputs (e.g., With.IdentityKey for current allowlisted capabilities).

5) Documentation updates (required)

Update docs (no legacy notes, no migration section, no deprecated comments):

• Context Resolver docs in docs/use/workflows/...:
  • show canonical schema with With.Provider
  • document With.IdentityKey, With.Provider, With.AuthSessionName, With.AuthSessionOptions
  • include at least one example using AuthSessionBroker (With.AuthSessionName)
• Provider docs template + provider docs:
  • Context Resolver provider section must describe:
    • which Context Resolver capabilities are supported
    • what is written into Request.Context.*
    • how AuthSession applies (same pattern as Steps)

Alternatives Considered

1. Support both schemas (Provider root + With.Provider)
   Rejected: violates consistency goals and adds permanent complexity.

2. Only document AuthSession but keep root Provider
   Rejected: inconsistency remains.

Impact

• Breaking change for workflows using ContextResolvers with root-level Provider.
• The change is intentionally strict:
  • no compatibility aliases
  • no legacy comments in code or docs
  • no migration docs (feature treated as “new/unknown” and quick-fixed)

Additional Context

• Context Resolver auth session acquisition is already implemented with With.AuthSessionName and With.AuthSessionOptions via AuthSessionBroker.
• Provider selection currently uses root-level Provider; this issue standardizes it to With.Provider and enforces Step-like ambiguity handling.