Centralize JSON serialization and add type-aware payload encoding/decoding

[andystaples]

Summary

This PR centralizes all JSON serialization/deserialization of user payloads and adds optional, type-aware encoding/decoding driven by user-supplied type hints — while keeping the on-the-wire format and existing behavior unchanged.

All payload serialization (orchestrator inputs/outputs, activity arguments and results, sub-orchestrator payloads, entity inputs/outputs, and client inputs) now flows through a single shim, replacing the scattered json.dumps(…, default=_serialize_custom_object) / json.loads(…, object_hook=_deserialize_custom_object) calls.

What changed

Centralized serialization (models/utils/df_serialization.py)

• New df_dumps / df_loads helpers act as a thin shim over the Azure Functions SDK serializers.
• When the installed azure-functions exposes df_dumps / df_loads (the centralized serializers with type-validation and strict-typing support), they are used directly so our serialization matches the SDK's ActivityTriggerConverter at the host boundary.
• Otherwise it falls back to the legacy _serialize_custom_object / _deserialize_custom_object hooks, which exist in every supported azure-functions release, keeping both sides symmetric.
• The wire format is unchanged: builtins serialize to plain JSON, and custom objects continue to use the {"__class__", "__module__", "__data__"} convention.

Type-aware decoding

• df_loads(s, expected_type=...) validates/decodes the deserialized payload against an expected type when the SDK supports it (the argument is accepted but ignored on older azure-functions releases).
• Return-type discovery (models/utils/type_discovery.py): best-effort resolution of the concrete return annotation from a V2 decorated activity / sub-orchestrator, used to supply expected_type automatically. Failures degrade gracefully to module-only resolution and, ultimately, the legacy decoder.
• call_activity / call_sub_orchestrator gain an optional expected_type argument that takes precedence over the discovered annotation; the resolved type is threaded through Task → TaskOrchestrationExecutor so custom classes can be decoded without consulting sys.modules / importlib.
• @app.orchestration_trigger(input_type=...): a decorator-declared input type is stashed on the orchestrator handle and propagated so context.get_input() (and get_input(expected_type=...)) can decode the input type-safely.

Entities

• DurableEntityContext now keeps persisted state in its raw (undecoded) form and decodes it lazily on get_state(..., expected_type=...). set_state clears the raw flag so a later get_state in the same batch does not attempt to re-decode an already-live value.

Behavior / compatibility

• Loose (default) mode preserves legacy behavior with no breaking changes; new type-related warnings are emitted when a type is not specified, does not match, or is unavailable.
• Opt-in strict typing causes inputs to fail deserialization when they do not match the specified type (when supported by the installed SDK).

CI

• Build/validate pipelines now exercise both serialization branches: the legacy fallback (Python 3.9, where the SDK serializers cannot be installed) and the SDK-delegated path (Python 3.13 with the azure-functions beta that first ships df_dumps / df_loads).
• Linting runs only on the canonical Python version to avoid PEP 701 f-string tokenization false positives on Python 3.12+.

Tests

• Added coverage for expected_type round-trips, decorator input_type, call-site override precedence, and an entity set-then-get regression across a batch with pre-existing raw state.

Notes

• Pipeline TODOs mark the temporary azure-functions>=2.2.0b5 override; these should switch to azure-functions>=2.2.0 once 2.2.0 GA ships, dropping the explicit install/override steps.

[nytian]

Left a few comments. Thanks for the PR!

[nytian]

So seem like we will only decode when calling set/get entity state, but EntityState.tojson however will always encode the json at end of batch operations. Is it possible we are accessing a entity without get/set then this will have double encode?

[andystaples]

Good catch — this was a real bug. If a batch never called get_state/set_state, the state stayed in its raw (single-encoded) form but EntityState.to_json still ran df_dumps on it, double-encoding it.

Fixed by tracking whether the state is still raw (state_is_raw) and threading that through to serialization: untouched raw state is now written back verbatim, while live values are still encoded once. Added a regression test (test_entity_untouched_raw_state_is_not_double_encoded) covering a batch that never touches state.

[nytian]

This warns at import time, so every 3.9 user sees it even if they never hit this path. Can we defer it to first use instead? Or maybe use debug level?

[andystaples]

Agreed. Switched from an import-time warnings.warn to a one-time logger.debug emitted on first actual use of the fallback serializers, so users who never hit the fallback path see nothing and those who do get a single actionable hint at debug level.

[nytian]

get-serialize-default is private, should we include here?

[andystaples]

Removed it from __all__ — it stays importable for its unit test but is no longer advertised as public API.

[nytian]

expected_type is accepted but ignored on 3.9, so type-aware decoding is silently not support here, right? If it's y design, maybe we should add a comment so that customer is aware of this behavior?

[andystaples]

Correct — on the fallback path expected_type is accepted for call-site compatibility but ignored, since type validation only exists in the SDK's df_loads. This is by design and is documented in the fallback df_loads docstring; the new first-use debug log also calls out that type validation is unavailable on that path.

Worth noting too: Python 3.9 is no longer supported in Azure Functions, so we'll be dropping it (and eventually this whole fallback branch) from this repo soon.

[nytian]

Is entity_operation_input_type still kept for backward compatibility? It looks like this is dead code and we can remove. Or if we need to keep it for old versions, lets add a comment for this class that it doens't support at new version.

[andystaples]

You're right, it was unused (always returned None and only referenced by its own test). Removed entity_operation_input_type and its tests; we'll reintroduce a proper implementation if/when class-based entity dispatch lands.