Introduce Request.Intent / Request.Context; replace DesiredState; forbid Request.Identity

[Copilot]

• Remove DesiredState property from IdleLifecycleRequest class
• Remove -DesiredState parameter, transition window logic, and deprecation warning from New-IdleRequestObject and New-IdleRequest
• Remove Request.Input.* and Request.DesiredState.* from allowed template roots, alias resolution, and escape regex in Resolve-IdleTemplateString
• Remove DesiredState from request snapshot in New-IdlePlanObject
• Remove DesiredState from request export fallback in ConvertTo-IdlePlanExportObject
• Update all test fixtures, tests, docs, and source to use Request.Intent.*/Request.Context.*
• New-IdleRequest.ps1: Add inline comments to both .EXAMPLE blocks; second example includes all params (LifecycleEvent, CorrelationId, IdentityKeys, Intent, Context)
• New-IdleRequest.ps1: $Intent and $Context default to @{} (consistent with $IdentityKeys)
• New-IdleRequestObject.ps1: Remove manual null-checks for $Intent/$Context; use = @{} param defaults instead (consistent with $IdentityKeys)
• Resolve-IdleWorkflowTemplates.Tests.ps1: Added parallel Context tests — multiple placeholders, nested hashtable, missing path — matching Intent test structure
• ConvertTo-IdlePlanExportObject.ps1: Include Request.Context in the exported request.input payload alongside identityKeys, intent, and changes — fixes silent drop regression where context-influenced plans were missing context data from exports and context-only plans produced request.input = null
• 587 tests pass

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Separate action inputs from associated context (rename DesiredState - forbid Request.Identity)</issue_title>
<issue_description>## Problem Statement

The current IdLE request schema uses a block named DesiredState as the primary caller-provided input payload for workflows and steps. Over time this name has become ambiguous:

• DesiredState suggests “target configuration only”, but it is also used for generic workflow inputs that are not strictly “state”.
• Hosts/providers often need to attach additional read-only information (identity snapshots, entitlements, device hints) to support planning-time conditions and safe execution patterns. Without a strict container for this information, ambiguous fields like Request.Identity may be introduced, which blurs input vs state, harms auditability, and increases security risk.

We need a strict, documented, validated separation between:

• Intent: what the workflow should do (caller-provided actionable inputs)
• Context: what the workflow should know (read-only associated data used for conditions/templates/guards)

Proposed Solution

1) Introduce two explicit request blocks (canonical)

Introduce two canonical top-level request blocks:

• Request.Intent.* (canonical block for caller-provided intent/action inputs)
• Request.Context.* (canonical block for associated read-only context)

2) Rename DesiredState to Request.Intent (controlled migration)

Because IdLE prioritizes consistency, this issue defines a controlled breaking change with a short, explicit transition window:

• During the transition window the engine maps DesiredState -> Request.Intent only if Request.Intent is not provided.
• If both are provided, fail fast with a clear validation error (avoid ambiguity).
• Emit a structured deprecation event when DesiredState is used.
• After the transition window, remove support for DesiredState.

The transition window (number of releases) must be documented.

3) Forbid ambiguous request fields

• Request.Identity MUST NOT exist and MUST be rejected by validation.
• Identity-related snapshots belong under Request.Context.Identity.*.

4) Semantics and responsibility

• Request.Intent is caller-owned and may contain desired changes, configuration, and operator-provided flags needed for actions.
• Request.Context is read-only associated context, provided by:
  • the host (pre-enriched), and/or
  • planning-time context resolvers (separate issue), and/or
  • other future internal mechanisms
• Request.Context must never be treated as mutable state within IdLE.

5) Validation rules (fail-fast, agent-safe)

• Both blocks must be data-only and safely serializable:
  • No ScriptBlocks, no executable expressions
  • Only primitives/arrays/hashtables and explicitly allowed safe types
• Prohibit secrets in request payload (tokens/passwords/session keys). Enforcement mechanism is defined in Issue 2, but this issue must establish the rule.

Alternatives Considered

1. Keep DesiredState and introduce Request.Data
   • Keeps the primary action input ambiguous, invites misuse.
2. Rename to InputData instead of Intent
   • Acceptable, but Intent is shorter and expresses purpose clearly.

Impact

• Breaking change for hosts/workflows that reference DesiredState.
• Requires updating docs/examples and internal references.
• Enables clean future additions (context snapshot, resolvers, runtime guards) without semantic confusion.

Definition of Done (Step-0-Ready / Agent-Safe)

Design / Contracts

• Document semantics and ownership boundaries of Request.Intent vs Request.Context.
• Define the transition window and removal policy for DesiredState.
• Define the minimal recommended sub-structure for Request.Context:
  • Request.Context.Identity.*
  • Request.Context.Devices.*
  • extension rules for additional namespaces

Implementation

• Implement request normalization for the transition window:
  • Map DesiredState -> Request.Intent only if Request.Intent is missing.
• Implement fail-fast validation:
  • Reject requests that provide both DesiredState and Request.Intent.
  • Reject requests that contain Request.Identity.
• Update internal codepaths, templates, and condition/template helpers to reference Request.Intent and Request.Context.

Tests (Pester)

• DesiredState only -> Request.Intent is populated (transition window).
• Both DesiredState and Request.Intent -> validation error.
• Request.Identity present -> validation error.
• Condition and template resolution can access Request.Intent.* and Request.Context.*.

Docs / Examples

• Update all documentation and examples to use Request.Intent / Request.Context.
• Add a migration note for host implementers.

Non-Goals

• No planning-time context res...

• Fixes Separate action inputs from associated context (rename DesiredState - forbid Request.Identity) #212

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[blindzero]

@copilot Remove all remarks, documentation, comments or technical implementations (e.g. aliases, mappings) to be compatible for previous "DesiredState". We are pre 1.0 and do not care about breaking-changes.

[Copilot]

@copilot Remove all remarks, documentation, comments or technical implementations (e.g. aliases, mappings) to be compatible for previous "DesiredState". We are pre 1.0 and do not care about breaking-c...

Done in 1690fc6. All DesiredState backward compatibility has been removed:

• IdleLifecycleRequest no longer has a DesiredState property
• -DesiredState parameter, transition window logic, and deprecation warning removed from New-IdleRequestObject/New-IdleRequest
• Request.Input.* and Request.DesiredState.* removed from template allowed roots, alias resolution, and escape regex
• All test fixtures, tests, docs, and source updated to use Request.Intent.* exclusively

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eac3d7eaf0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This pull request implements a significant architectural improvement to IdLE's request model by introducing explicit separation between caller-provided action inputs (Request.Intent) and read-only associated context (Request.Context), while completely removing the ambiguous DesiredState property.

Changes:

• Replaced Request.DesiredState with Request.Intent for caller-provided action inputs
• Introduced Request.Context for read-only associated context (host/resolver-provided data)
• Added validation to explicitly reject Request.Identity property (identity data must go under Request.Context.Identity)
• Removed Request.Input alias support and updated template resolution to use new canonical roots
• Updated all 587 tests, documentation, examples, and workflow templates across the codebase

Reviewed changes

Copilot reviewed 66 out of 66 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/IdLE.Core/Private/IdleLifecycleRequest.ps1	Core domain class updated with Intent and Context properties; removed DesiredState
src/IdLE.Core/Public/New-IdleRequestObject.ps1	Factory function updated to accept Intent and Context parameters with validation
src/IdLE/Public/New-IdleRequest.ps1	Public cmdlet updated with Intent/Context parameters and inline example comments
src/IdLE.Core/Public/New-IdlePlanObject.ps1	Added Request.Identity rejection validation; updated request snapshot to use Intent/Context
src/IdLE.Core/Private/Resolve-IdleTemplateString.ps1	Updated allowed roots to Intent/Context; removed Input alias logic
src/IdLE.Core/Private/Get-IdleValueByPath.ps1	Updated comment to reference Intent instead of DesiredState
src/IdLE.Core/Private/ConvertTo-IdlePlanExportObject.ps1	Updated plan export to use 'intent' field instead of 'desiredState'
tests/_testHelpers.ps1	Updated test helper to support Intent and Context parameters
tests/Core/New-IdleRequest.Tests.ps1	Added tests for Intent/Context parameters, DesiredState absence, and Request.Identity rejection
tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1	Updated all tests to use Intent/Context; removed Request.Input alias tests
tests/Core/Invoke-IdlePlan.MailboxTemplates.Tests.ps1	Updated mailbox step tests to use Request.Intent
tests/Core/Export-IdlePlan.Tests.ps1	Updated plan export test to use Intent
tests/Core/CapabilityDeprecation.Tests.ps1	Updated deprecation tests to use Intent
tests/Core/Assert-IdleNoScriptBlock.Tests.ps1	Updated ScriptBlock validation tests to use Intent
tests/fixtures/workflows/template-tests/*.psd1	All 28 template test fixtures updated to use Request.Intent/Context
tests/fixtures/plan-export/expected/plan-export.json	Updated expected export format to use "intent" field
src/IdLE.Steps.Mailbox/README.md	Updated step pack README examples to use Request.Intent
src/IdLE.Steps.Mailbox/Public/Invoke-IdleStepMailboxOutOfOfficeEnsure.ps1	Updated documentation and examples to use Request.Intent
examples/workflows/templates/*.psd1	All 8 example workflows updated to use Request.Intent
examples/Invoke-LeaverWithManagerOOF.ps1	Updated example script to use enrichedIntent
docs/use/workflows.md	Updated template documentation to describe Intent and Context roots
docs/use/quickstart.md	Updated quickstart guide examples to use Intent
docs/use/walkthrough/*.md	All 3 walkthrough docs updated to use Intent
docs/reference/cmdlets/New-IdleRequest.md	Updated cmdlet reference with Intent and Context parameters
docs/reference/providers/provider-mock.md	Updated mock provider docs to reference Intent
docs/extend/extensibility.md	Updated lifecycle request contract to list Intent and Context

[github-actions]

Code Coverage Report

Overall Project	72.13%	🍏

There is no coverage information present for the Files changed