Documentation refactoring. No code changes. (0.40.5)

web/documentation/bytecode-format/bytecode-format.md

@@ -0,0 +1,49 @@
+---
+layout: page
+published: true
+noToc: false
+noComments: false
+noDate: false
+title: Fun - Bytecode Format (Overview)
+subtitle: Reference for the bytecode format (split out from internals for convenience).
+description: Reference for the bytecode format (split out from internals for convenience).
+permalink: /documentation/bytecode-format/
+lang: en
+tags:
+- bytecode
+- convenience
+- format
+- internals
+- out
+- reference
+- split
+---
+
+
+This document summarizes the Fun bytecode format. For deep VM details, see [internals](./internals/).
+
+## Goals
+- Compact representation for fast loading and dispatch
+- Stable header with room for versioning
+
+## File layout (typical)
+1. Header
+   - Magic number / signature
+   - Format version
+   - Flags (endianness, feature bits)
+   - Offsets to sections
+2. Constants table
+   - Literals: numbers, strings, compound constants
+3. Code section
+   - Functions/procedures with instruction streams
+   - Line/column mapping (optional for debugging)
+4. Auxiliary tables
+   - Imports/exports, names, debug info (optional)
+
+## Instructions
+- Fixed-size or small-variant opcodes grouped by domain (math, logic, stack, call, control flow, etc.).
+- Operands encoded inline following the opcode (width varies by instruction).
+
+## Versioning and compatibility
+- The header's version field allows the VM to refuse or translate older/newer formats.
+- Keep additions backward-compatible when possible by appending sections or flags.