Skip to content

Conversation

@zharinov
Copy link
Member

@zharinov zharinov commented Dec 11, 2025

Refine tagged alternation serialization model

Summary

Updates the JSON serialization design for tagged alternations to use a uniform { $tag, $data } structure, avoiding collisions and simplifying implementation.

Changes

  • $tag discriminator: Changed from tag to $tag to avoid collisions with user-defined @tag captures
  • $data wrapper (always): All payloads wrapped in $data for uniform structure—no conditional flatten-vs-wrap logic
  • Removed strict constraint: Tagged branches accept any payload type (objects, arrays, primitives)
  • Added alternation guidance: Documented when to use untagged (simplicity) vs tagged (precision)
  • Updated docs: README.md, REFERENCE.md, and ADR-0003 reflect the new serialization rules

Serialization format

{ "$tag": "Assign", "$data": { "target": "x", "value": {/* ... */} } }
{ "$tag": "Items", "$data": [1, 2, 3] }
{ "$tag": "Name", "$data": "foo" }

Rationale

  • Uniform structure eliminates conditional logic
  • Always access via .$data — predictable for codegen and LLMs
  • Zero collision risk with user captures
  • Mirrors serde's adjacently-tagged representation (#[serde(tag = "$tag", content = "$data")])

@zharinov zharinov enabled auto-merge (squash) December 11, 2025 01:58
@zharinov zharinov merged commit 245c304 into master Dec 11, 2025
4 checks passed
@zharinov zharinov deleted the refactor/adr-0003-fixes branch December 11, 2025 02:00
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.

2 participants