.NET: Fix: Checkpoint Deserialization breaks when JSON metadata properties are out of order

[lokitoth]

Motivation and Context

JSON Checkpoint serialization is currently strict in the ordering of the metadata properties, such as the polymorphic type specifier. This causes problems when deserializing checkpoints stored as JSONB in Postgres, which provides a different order on read.

Description

Create a way to let the user specify that a relaxed ordering is also allowed.

• Fixes .NET: Checkpoint JSON deserialization fails when using PostgreSQL jsonb #2962

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull request overview

This PR makes JSON checkpoint deserialization resilient to out-of-order polymorphic metadata (e.g., $type) so that checkpoints stored in PostgreSQL jsonb (and other sources that reorder properties) can be deserialized successfully.

Changes:

• Extend JsonMarshaller to respect a new JsonCheckpointManagerOptions.AllowOutOfOrderMetadataProperties flag via its internal JsonSerializerOptions.
• Introduce JsonCheckpointManagerOptions and thread it through CheckpointManager.CreateJson so callers can opt into relaxed metadata ordering behavior.
• Add targeted unit tests (and a helper) to reproduce the jsonb metadata-ordering issue and validate that enabling the new option restores successful deserialization.

Reviewed changes

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

File	Description
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/JsonSerializationTests.cs	Adds regression tests simulating out-of-order $type metadata and verifying default failure vs. success when AllowOutOfOrderMetadataProperties is enabled, plus a helper to reorder JSON properties.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/JsonMarshaller.cs	Updates the marshaller to accept JsonCheckpointManagerOptions and configure AllowOutOfOrderMetadataProperties on its internal JsonSerializerOptions.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/JsonCheckpointManagerOptions.cs	Introduces a public options class with a flag to allow out-of-order metadata properties during JSON deserialization, with XML documentation.
dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointManager.cs	Extends CreateJson with an optional JsonCheckpointManagerOptions parameter and passes it to JsonMarshaller so callers can opt in to relaxed metadata ordering.

[westey-m]

Consider renaming customOptions to jsonSerializerOptions to disambiguate it better from checkpointOptions.

[westey-m]

Also, it feels a bit unintuitive to have an AllowOutOfOrderMetadataProperties on checkpointOptions, which is also on customOptions. The comment for checkpointOptions is that it is to configure JSON serialization behavior. I would expect that that is what the customOptions is for. Without reading the code I would be confused.

[lokitoth]

The customOptions is for configuring the serialization behaviour of user types. It does not impact the serialization of system types. Will think on how to make what is going on here clearer with names / docs.

Maybe look for that field in the user-specified options and rely on it?

[lokitoth]

I think I like the idea of looking on the actual property on the type the user passes in. It seems unreasonable to only need to support it for one layer since we only ever give out the combined json clob to the underlying persistence layer, so if keys are randomized in some places, I'd expect them to be randomized in others.