[FEAT]: Canonical versioned trace/result serializer (WS0-05 PR 1)

[Nina Chikanov (nina-msft)]

WS0-05 — PR 1: Canonical versioned trace/result serializer

Establishes the neutral schema API and migration policy. Existing reporting and xdist consumers are not rewired in this PR.

What this lands

• Result.to_dict() / Result.from_dict() — the canonical, unversioned body codec, backed by one cached Pydantic adapter over Result. The existing standard dataclasses remain the live models; there is no parallel body model or set of nested encode/decode functions. Encoding uses Python-mode adapter output with explicit enum/datetime serializers, followed by a canonical reader pass before returning the body. This extra pass preserves existing reader depth support without introducing a new depth cap; interpreter/parser recursion limits still apply.
• Adapter-local policies — a private GetPydanticSchema hook configures copies of generated core-schema nodes. Public fields retain plain dictionary/datetime annotations; no class-wide Pydantic configuration or trace validators are attached to the live dataclasses. Other Pydantic adapters retain their normal behavior. The canonical adapter explicitly supplies its datetime/Path resolution namespace; types.py is unchanged from the PR base.
• Thin ResultRecord envelope in rampart/core/serialization.py. serialize_record(record=...) -> str serializes an explicitly constructed ResultRecord to JSON text; deserialize_record(data=...) -> ResultRecord reads JSON text. ResultRecord.to_dict() / from_dict() remain available for dictionary conversion and projections. Every record carries the single root version rampart.trace.v1; unsupported versions fail closed through the decoder registry. Body dicts are fragments, not standalone durable records.
• Optional attribution — pytest_nodeid and result_index, omitted when not recorded. Stable identity fields and durable artifact descriptors remain deferred until their implementations exist.
• Strict boundary validation — all nine nested types, finite numbers, JSON-only free-form maps, closed enums, and passthrough harm-category strings. Missing fields use declared defaults without retaining original field presence; explicit null is accepted only for nullable fields. Payload IDs are required on read rather than generated. Python ISO timestamp formatting is preserved. Strings and mapping keys, including attribution, must contain Unicode scalar values: Python surrogate code points are rejected without lossy normalization, while valid JSON surrogate-pair escapes for characters such as emoji remain supported. Malformed JSON, unsupported values, recursion-limit failures, and adapter serialization ValueErrors surface as SchemaError.
• Trace-only payload restrictions — binary formats and non-null artifacts fail before filesystem access; ordinary live binary payload construction and independent Pydantic validation are unchanged.
• Nonmutating metadata hygiene — ResultRecord.to_dict() filters only top-level transport bookkeeping from encoded output, including _rampart_source_worker. Body-only serialization and record decoding retain these keys. Re-encoding filters them from output without modifying the referenced result; nested user maps remain intact.
• Generated open JSON Schema at schemas/trace.v1.schema.json. ResultRecord.json_schema() composes the adapter-derived body and versioned envelope, with narrow customizations for trace payload restrictions and the Request invariant. Runtime class docstrings are omitted in favor of concise trace-specific descriptions. scripts/generate_trace_schema.py --check is the CI drift gate.
• Explicit structural/semantic distinction — passing JSON Schema validation is necessary but not sufficient for decoding. Integer notation, Unicode scalar strings, Python ISO datetime parseability, and finite representable numbers remain decoder requirements. These requirements and runtime nesting limits are documented rather than claimed as JSON Schema guarantees.
• Migration and integration policy at docs/concepts/trace-schema.md: additive optional fields require no bump; structural changes require a new major; absence means not recorded, not a semantic negative. Reserved future field names and the release-based support window are documented. Transport normalization must prepare a separate result before encoding; a binary text placeholder is a lossy transport view, not a durable replay artifact.

Coverage

Hypothesis-generated body and record round-trips over nested JSON values, all nine nested types, enums, optional fields, and timestamps. Example-based coverage includes field exhaustiveness, version dispatch, attribution, additive tolerance, invalid JSON/types/cycles, independent-adapter isolation, schema semantics, and payload rejection before filesystem access. Additional regressions cover surrogate-containing text and mapping keys, valid Unicode/JSON surrogate-pair escapes, deep-nesting round-trips, and recursion/error boundaries with exception chaining. A prepared-copy boundary case demonstrates canonical reuse without modifying or relaxing the original result. hypothesis and jsonschema are development-only dependencies.

Scope

Reporting projections, xdist/failure-attachment adoption, and stable identity remain separate follow-up implementations. Existing transport coercion and payload-display behavior require explicit preparation and compatibility work, not a mechanical serializer replacement. No public transport-preparation API or artifact representation is introduced here.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.