Bytecode Format: A Real Compile Artifact

BC1 is a text boundary between the compiler and VM. Encode(Bytecode) returns a string; Decode(string) returns a Bytecode or error. Neither helper executes source. Store enough instruction data to reconstruct names, integers, strings, function parameters, and code order without consulting the old AST.

Worked reconstruction

A function plus its call can be represented as:

BC1
FUNC difference a b
LOAD a
LOAD b
SUB
RETURN
END
MAIN
PUSH_NUM 9
PUSH_NUM 2
CALL difference 2
END

The function's code and Main each have their own zero-based instruction coordinates. FUNC and END are format delimiters, not VM instructions. Adding a comment line does not shift an instruction jump target. Running this hand-authored Main returns 7 because it has no final POP.

Quoted content is not whitespace-separated syntax

PUSH_STR "a b" carries one string operand containing a space. Splitting every line with whitespace fields loses that grouping. Use quote-aware parsing and validate exact operand counts. An encoded newline is an escape sequence within one instruction line; decoding reconstructs the newline character in the value. A source string and a bytecode string are different serialization layers, even when they use similar escapes.

What a round trip proves

Compare Decode(Encode(bc)) with the original instruction structure. Then run both artifacts to test behavior. A round trip alone can preserve the same bad jump target in both objects, so it is not a proof of compiler or VM correctness. Use independent known instruction lists and malformed examples as well.

The local format starts with BC1, function sections and Main are delimited by END, and blank/comment lines are ignored. Unknown opcodes, malformed numbers, wrong arities, unterminated strings, or incomplete sections are decoding errors. This is an educational executable artifact, not an authenticated or fully verified bytecode security format.

Debugging lab

A decoder counts every text line when interpreting JUMP 4. Adding a comment changes execution even though the decoded instructions are otherwise identical. What coordinate system was confused?

Compare your diagnosis after attempting the lab

Jump targets are indexes in the decoded instruction slice, not source-text line numbers. Headers, section markers, and comments contribute no instructions. Preserve the integer operand unchanged while parsing section structure.

Transfer task

Write a BC1 string containing a quoted space, escaped quote, and newline escape. Predict the decoded string, then corrupt exactly one delimiter. Compare structural round-trip checks with an independent runtime expected value.

Carry forward

Carry an encoded artifact and a malformed counterpart into the v2 capstone. The VM must be able to run a decoded copy without any AST or parser state.

Build bytecode-io. Keep a before/after trace of one failing test. Use the checkpoint to diagnose specific skills; passing it does not replace implementing and testing the artifact.