Skip to content

docs: round-trip byte-stability scope + minusOne/minusOneFast state counts#230

Merged
mellonis merged 1 commit into
v7from
docs/post-alpha-8-catchup
Jun 2, 2026
Merged

docs: round-trip byte-stability scope + minusOne/minusOneFast state counts#230
mellonis merged 1 commit into
v7from
docs/post-alpha-8-catchup

Conversation

@mellonis

@mellonis mellonis commented Jun 2, 2026

Copy link
Copy Markdown
Owner

Summary

Post-merge follow-up to #229. Refines the round-trip stability claim across docs and syncs the in-source state-count comments to match the test fixtures.

What changed

Round-trip stability framing β€” narrowed

Previous wording across CLAUDE.md, packages/machine/README.md, and test/round-trip.spec.ts said `toMermaid β†’ fromMermaid β†’ toGraph β†’ toMermaid` was "stable for all wrapped states including shared-bare cases" after #174's callable-subtree emit. That overstated the guarantee.

The accurate model:

  • Simple wrappers (e.g. `scanToX(eraseHere)`): bytewise stable. The #139 regression test pins this.
  • Shared-bare cases (e.g. `library-binary-numbers/minusOne` where `invertNumber` backs both the outermost bare and wrapper-W1's bare): emit a single de-duped node with `&`-joined call arrows; the sharing survives the round-trip. But `GraphNode` ids are runtime `State` ids reassigned on every `fromGraph` rebuild, and a shared bare's post-rebuild id no longer follows the original emission order, so the byte stream reorders. Verify behavioural identity with `equivalentOn β†’ allAgree: true` instead.

Updated in three places:

  • `CLAUDE.md` β€” "Visualization & round-trip" β†’ "Round-trip" paragraph.
  • `packages/machine/README.md` β€” the round-trip callout under the wrapped-state example, AND the v7 alpha.1 changelog entry for #174.
  • `test/round-trip.spec.ts` β€” the explanatory comment above the "bytewise stable for wrapped states" test.

State-count comments synced

`packages/library-binary-numbers/src/index.ts`:

  • `minusOne`: `15` β†’ `18` nodes
  • `minusOneFast`: `8` β†’ `10` nodes

The `graphs.spec.ts` fixture (lines 17-18) already pins these via `summarizeGraph(graph).stateCount`. The source comments were lagging behind the test-pinned source of truth.

Test plan

  • `npm test` β€” 30 files, 664 tests pass (including `library-binary-numbers state graphs` parametric: 31 cases pass).
  • `npm run lint` β€” clean.
  • No runtime behaviour change β€” doc + comment-only diff.

…ounts

Refine the round-trip stability claim across CLAUDE.md, the engine
README, and test/round-trip.spec.ts. Previous wording said "stable for
all wrapped states including shared-bare cases" β€” that overstated the
guarantee. The accurate model:

- Simple wrappers (scanToX(eraseHere)-style): bytewise stable across
  toMermaid β†’ fromMermaid β†’ toGraph β†’ toMermaid. The #139 regression
  test pins this.
- Shared-bare cases (library-binary-numbers/minusOne where
  invertNumber backs both the outermost bare and wrapper-W1's bare):
  emit a SINGLE de-duped node with &-joined call arrows; sharing
  survives the round-trip. But GraphNode ids are runtime State ids
  reassigned on every fromGraph rebuild, and a shared bare's
  post-rebuild id no longer follows the original emission order, so
  the byte stream reorders. Verify behavioural identity with
  equivalentOn β†’ allAgree:true instead.

Also syncs in-source state-count comments for minusOne (15 β†’ 18) and
minusOneFast (8 β†’ 10) β€” the graphs.spec.ts test fixture already pins
these counts via summarizeGraph(graph).stateCount, so the comments
were lagging behind the source of truth.
@mellonis mellonis merged commit 77d2671 into v7 Jun 2, 2026
1 check passed
@mellonis mellonis deleted the docs/post-alpha-8-catchup branch June 2, 2026 19:14
@github-project-automation github-project-automation Bot moved this from Todo to Done in @mellonis's machines Jun 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant