v4 Capstone: full pipeline to executable program

This module joins all v4 features (closures, maps, arrays, loops, short-circuit, errors) into one working toolchain.

1) Pipeline truth

Lex -> Parse -> Analyze -> Compile -> Encode -> Decode -> Link -> VM.Run

Each stage has one owner:

• parser produces AST
• analyzer validates symbols/control flow
• compiler emits per-module bytecode
• encode/decode is the contract boundary
• linker rewrites closure ids and inits
• VM executes

The capstone exercises not only successful execution, but boundary contracts.

2) Ownership and no stage leakage

• parser/analyzer do not emit bytecode
• compiler does not interpret source tokens
• linker does not assume parser internals
• VM sees only bytecode

If one stage leaks behavior into another, hidden coupling appears in every later module.

3) Failure ordering

For stable user experience and grading:

1. lex/parse
2. analyzer
3. compile
4. encode
5. decode
6. link
7. runtime

Do not continue if a stage fails.

4) Why encode/decode in capstone

Executing raw compiled bytecode can hide serialization bugs. Decoding immediately before link/runtime verifies:

• textual format stability
• parser/serializer compatibility
• deterministic linker input shape

Even though it adds work, this is the only reliable way to assert compile/runtime decoupling.

5) Deterministic compile/link behavior

For same source, results should be stable:

• exported order stable
• function id rewrites stable
• final function count stable
• output value stable

Practical checks:

• avoid unstable map iteration in export/import paths
• keep loops over modules/statements deterministic
• stable id assignment order during compile and link

6) VM start semantics

Execution starts from linked main entry only after all initialization steps and link rewrites. Runtime returns either:

• a value from top-level execution
• runtime error for operation mismatch
• no partial state from earlier stages if earlier stages fail

7) Practice checkpoints (almost solved)

1) Error precedence + If parse and semantic errors exist, parser/lexer should fail first; analyzer only after parse success.

2) Runtime suppression + If analyzer emits undefined-name, compile/run must not proceed.

3) Round-trip integrity + CompileAndRun should enforce decode success before link and run.

4) Determinism + Two runs of same source should produce same module/init layout and result.

5) Link/ID stability + Func ids should be rebased deterministically by module order before runtime.

6) Failure locality + A runtime type/arity error should still be surfaced by VM when front-end passes.

Capstone here is integration quality, not just “all features connected.”