Skip to content

docs(whale): explain verified casts and explicit IR format 3 identities - #479

Merged
LunaStev merged 2 commits into
wavefnd:masterfrom
LunaStev:docs/whale-ir-identities
Oct 6, 2026
Merged

LunaStev merged 2 commits into
wavefnd:masterfrom
LunaStev:docs/whale-ir-identities

Conversation

@LunaStev

@LunaStev LunaStev commented Oct 6, 2026 •

Copy link
Copy Markdown
Member

Result

The Whale references in all nine existing documentation languages (Korean, English, Japanese, Simplified Chinese, Spanish, German, Russian, Indonesian–Malay and Vietnamese) now show typed IR format 3 and describe the verified cast/checked-operation shapes introduced by Whale #240. AST JSON remains format 2 and semantics version remains 1.

The 54 changed Markdown files (six pages in each of nine languages) cover IR, numeric operations, memory, O0, AMD64 target examples and the support overview:

  • Replace old name-only function/block definitions with explicit function, parameter and block IDs and entry references. Update the call golden link to calls-v3.wir.
  • Explain ID scopes, preservation of supplied IDs, friendly names as annotations, and one common quoting/escaping rule for all string fields.
  • Include a complete verified branch/phi module with repeated friendly names, a sparse result ID, and unambiguous predecessor references.
  • Translate the new semantic explanations in each existing locale and define each cast opcode's permitted source/destination categories and width direction, including Bool-to-integer 0/1 conversion and the signed-i1 exclusion. Include a complete Rust construction/rejection example and its actual printed IR, plus deliberately invalid IR fragments.
  • Explain checked arithmetic signedness, exact operands, tuple<T, bool> results and tuple extraction checks.
  • Update format migration/support status and the AMD64 empty-AST envelope. Preserve explicit limits: no text parser or execution backend, and runtime pointer/conversion enforcement remains unfinished.

Validation

  • python3 tools/check-doc-translations.py: passed across every configured locale; 54 source documents / 432 translations, code/structure/links match. The six partial locales have no existing Whale pages and retain English fallback; no copied-English placeholder pages were introduced.
  • python3 tools/check-doc-examples.py --links-only: passed.
  • Compiled and ran five complete Rust examples on the IR reference pages against the changed Whale library; adjacent module outputs match.
  • The complete versioned JSON example lowers to the documented typed IR format 3 output.
  • Reconstructed and verified the numeric, initialized-memory and O0 modules; their full printed outputs match the updated fences. The new branch/phi module was also constructed, verified and printed.
  • git diff --check: passed.
  • go test ./internal/document ./internal/web/handler: handler passed; document has the same three failures on untouched upstream master b6beae2:
    • TestOfficialDocumentationUsesStableLanguageVocabulary: missing Chinese language-model wording.
    • TestSeedOfficialPublishesSupportedDocumentationLocales: missing official installer command.
    • TestOfficialInstallDocumentsIncludeWindowsInstaller: missing English Windows installer command.

The baseline was checked in a separate detached checkout. Those unrelated language/installation documents and site code are outside this PR. No site routing/functionality change, rebuild, restart or deployment was performed.

Merge dependency

Merge after Whale #240 so the public master links and printed examples match the released repository syntax. This PR changes documentation Markdown only.

@LunaStev
LunaStev merged commit c3c7403 into wavefnd:master Oct 6, 2026
4 checks passed
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