Separate action inputs from associated context (rename DesiredState - forbid Request.Identity)

[blindzero]

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 resolver feature in this issue (separate issue).
• No runtime execution guard feature in this issue (separate issue).