Repository navigation
docs: propose canonical flow documents - #51
Merged
Merged
Conversation
Make the document the whole truth so editing is parse, change the model, serialize: per-node `note` instead of YAML comments, ordered maps, and one canonical serialization pinned by the corpus in both languages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GNFHhzw4ZsqCFnv6ERigjd
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GNFHhzw4ZsqCFnv6ERigjd
4 tasks done
wavekat-eason
added this pull request to stack #53
October 17, 2026 11:19
wavekat-eason
marked this pull request as ready for review
October 17, 2026 22:38
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A design proposal:
docs/01-canonical-document.md. It replaces the closed #50.The flow YAML should be the single source of truth, with nothing meaningful outside the model. Then any tool, in any language and offline, edits by parsing → changing the model → serializing, with no text splicing or CST surgery.
noteon every node (and the flow) replaces YAML comments. It's a compatible addition to v1 and v2, with no version bump. Comments become acomment_ignoredwarning.IndexMapthrough typify'swith_map_type, andserde_jsongetspreserve_orderforui.to_yamland TSserializeFlowproduce byte-identical output. A newconformance/canonical/corpus pins it, including fixed-point and lossless round-trip checks.mutate.tskeeps its API but edits through the model. Editors refuse to save a document with unknown fields, so a round trip can't silently drop data.note.The open questions are resolved in the doc (flow-level
note: yes; multi-line strings: double-quoted with\n; one general flow-style rule). The doc also has a Consumers section: what the platform, CLI and voice daemon each change.Test plan
🤖 Generated with Claude Code
https://claude.ai/code/session_01GNFHhzw4ZsqCFnv6ERigjd