Skip to content

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

Draft
Nina Chikanov (nina-msft) wants to merge 1 commit into
microsoft:mainfrom
nina-msft:nina-msft-trace-result-schema-gate
Draft

[FEAT]: Canonical versioned trace/result serializer (WS0-05 PR 1)#185
Nina Chikanov (nina-msft) wants to merge 1 commit into
microsoft:mainfrom
nina-msft:nina-msft-trace-result-schema-gate

Conversation

@nina-msft

Copy link
Copy Markdown
Contributor

WS0-05 — PR 1: Canonical versioned trace/result serializer (Decision D6 gate)

First PR of the WS0-05 execution plan. Pure addition — no existing consumer is
rewired here, so nothing breaks; later PRs project reporting/xdist onto this module.

What this lands

  • **
    ampart/core/serialization.py** — the single, neutral full-fidelity
    Resultdict round-trip. Public surface is ResultRecord.to_dict /
    from_dict plus thin serialize_result / deserialize_result wrappers.
  • Single root version rampart.trace.v1 stamped on every record; decoding
    dispatches through a _DECODERS registry and fails closed on an unknown major.
    Independent of the xdist transport envelope version (rampart.xdist.v2).
  • Value-domain-only canonical layer (design §5): enums → .value and fail
    closed on unknown; harm_category passthrough string; floats must be finite;
    free-form maps must be JSON-safe (no repr()/default=str fallback — that
    stays in the xdist transport). Reserved xdist bookkeeping keys are stripped from
    the canonical body.
  • Binary payloads fail closed on encode and decode pending the WS7 artifact
    resolver, rather than being coerced to PayloadFormat.TEXT.
  • Covers all 9 nested types including the new PopulationRef.
  • Migration policy committed at docs/concepts/trace-schema.md (design §4):
    additive-optional = no bump; structural = major bump; missing = not recorded;
    named reserved additive slots so WS8 provenance needs no hard migration.

Tests

tests/unit/core/test_serialization.py — round-trip, field-exhaustiveness via
dataclasses.fields()
, version dispatch + fail-closed, additive tolerance,
missing-field defaults, value-domain fail-closed, and binary-payload fail-closed.
18 pass; full core suite (398) green; ruff + ty clean.

Still to do in this PR (draft)

  • Generate the open trace.v1.schema.json from encoder output over a fixtures
    corpus + a CI git diff --exit-code drift gate (design deliverable).
  • Design sign-off (§7 checklist) recorded before merge — the entry gate.

Refs WS0-05 (#10594). Blocks WS6/WS7; shares the serializer with #10596 (xdist merge).

Introduce rampart/core/serialization.py as the single, neutral
full-fidelity Result <-> dict round-trip (Decision D6 gate). Every
record carries a single root version (rampart.trace.v1) and decoding
dispatches on it, failing closed on an unknown major.

The canonical layer defines the supported value domain only: enums
encode to .value and fail closed on unknown values, harm_category is a
passthrough string, floats must be finite, and free-form maps must be
JSON-safe. Transport hygiene (ANSI stripping, float normalization,
repr() fallback, size caps) stays at the xdist boundary and is not
duplicated here. Binary payloads fail closed pending the WS7 artifact
resolver rather than being coerced to text.

Also lands the written migration policy (docs/concepts/trace-schema.md):
additive-optional = no bump, structural = major bump, missing = not
recorded, readers fail closed on unknown major, with named reserved
additive slots so WS8 provenance needs no hard migration.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@azure-pipelines

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant