docs(guides): add Migration Playbook + frontier-guide v1.0 living-doc header#36
Merged
Conversation
…g-doc header Adds docs/guides/migration-playbook.adoc as the systematic companion to frontier-guide.adoc — the source-of-truth for re-decomposition rules when porting ReScript / TypeScript codebases into AffineScript. Covers: the cardinal rule (re-decompose, do not transliterate), source-pattern indices for ReScript and TypeScript, decision criteria (`Option` vs `Result`, `mut` vs effect, `ref`/`mut`/`own`, linear vs affine), and a file-buffer anti-pattern paired with its re-decomposed form. Bumps frontier-guide.adoc to v1.0: - adds :revnumber: / :revdate: attributes - adds a "canonical, living document" status note pointing at the migration-playbook - cross-links the playbook from "What to Read Next" - adds a Revision History appendix so subsequent edits have a place to land — addresses the gap where the guide had no surface for incremental updates and downstream consumers (idaptik, etc.) had no way to see what had changed. Both files render cleanly with asciidoctor. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…sons-pointer
Adds docs/guides/lessons/migrations/idaptik-user-settings.adoc — the
second migration case study, paired with the existing idaptik-hitbox
entry. Unlike hitbox (a pure-leaf compilable translation), UserSettings
has 5+ external deps (Storage/Audio/DesktopIntegration/GetEngine/Option)
and uses Float arithmetic, neither of which v0.1.0 can resolve, so this
lesson is explicitly marked **design-only**. The walk-through still
pressure-tests the playbook against a realistic, dependency-heavy file.
Stress-test outcome:
- Playbook held cleanly on stringly-typed→sum-type, unit→IO-effect,
Option direct mapping, and let-_-discarded-Result patterns.
- Surfaced three small gaps:
1. Service-locator globals (`GetEngine.get(): Option<engine>`) aren't
named in the source-pattern index. Lift-to-effect is the right
answer; needs one row.
2. Coupled-write composition (one user action that updates both an
in-memory subsystem AND persists) isn't covered by the decision
criteria.
3. The playbook pointed lessons/ at the wrong folder — that's the
10-lesson tutorial track, not the migration case-study channel.
Fixed inline.
Gap 3 fixed in this commit. Gaps 1 and 2 are playbook-text changes
deferred to a v1.1 follow-up so this PR stays focused.
The "Lessons from Real Migrations" section of the playbook now indexes
both case studies so reviewers can see the playbook validated against
two concrete files.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 2, 2026
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
1 participant
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
docs/guides/migration-playbook.adocas the systematic companion tofrontier-guide.adoc— the source-of-truth for re-decomposition rules when porting ReScript / TypeScript codebases into AffineScript.docs/guides/frontier-guide.adocto v1.0 with a "canonical, living document" status note, a cross-link to the playbook, and a Revision History appendix so subsequent edits have a place to land.Why
Downstream consumers of the guide (notably
idaptik, with ~542.resand ~80.tsfiles queued for migration) had no systematic playbook for how to re-decompose during translation — only the unveiling of what AffineScript is. The risk was a faithful-but-monolithic port that type-checks in AffineScript while still carrying the design problems AffineScript was built to solve.This PR establishes the playbook upstream, here, so the rules don't fork into per-consumer docs or AI-agent memory entries.
What's in the playbook
let mutable→mutorStateeffect,exception→Result[T,E],Js.Promise→Asynceffect, classes → owned record + standalone fns, etc.).OptionvsResult,mutvs effect,ref/mut/own, linear (@linear) vs affine (own).closedis a runtime check) paired with the re-decomposed form (open/closed as distinct types, IO in the effect row, ownership consumed byclose).docs/guides/lessons/so the upstream guide stays a living document.Frontier Guide changes
:revnumber: 1.0/:revdate: 2026-04-11.Test plan
asciidoctor --backend=html5 --safe-mode=saferenders both files cleanly (no warnings, no errors).frontier-guide.adoctomigration-playbook.adocresolves in the rendered HTML.🤖 Generated with Claude Code