docs(syntax): Allign docs and clean redaction.

Author: dylan-sutton-chavez

docs/pages/implementation/syntax.md

@@ -15,12 +15,12 @@ Each instruction is a tagged 4-byte record:
 
 ```rust
 pub struct Instruction {
-    pub opcode: OpCode, // 1 byte (with #[repr(u8)] planned)
-    pub operand: u16, // 2 bytes
+  pub opcode: OpCode, // 1 byte (with #[repr(u8)] planned)
+  pub operand: u16, // 2 bytes
 }
 ```
 
-The operand is a 16-bit slot, its meaning depends on the opcode. Common shapes:
+The operand is a 16-bit slot; its meaning depends on the opcode. Common shapes:
 
 | OpCode | Operand interpretation |
 |---------------------------|------------------------------------------------------|
@@ -44,20 +44,20 @@ Operands and the constant pool, name table, and instruction stream per chunk are
 `expr_bp(min_bp)` runs the Pratt loop. `parse_atom` advances one token and routes by kind:
 
 ```text
-Name   -> name() (handles assignment, walrus, calls)
-String   -> emit Str constant; concatenate adjacent String tokens
-Int / Float   -> emit numeric constant; literal beyond 2⁴⁷ is a parse error
-True/False/None/Ellipsisv-> emit dedicated load opcode
-FstringStart   -> fstring()
-Lbrace   -> brace_literal()  (dict, set, comprehension)
-Lsqb   -> list_literal()   (list, comprehension)
-Lpar   -> grouped expr, tuple, generator, or empty tuple
-Lambda   -> parse_lambda()
+Name                     -> name() (handles assignment, walrus, calls)
+String                   -> emit Str constant; concatenate adjacent String tokens
+Int / Float              -> emit numeric constant; literal beyond 2⁴⁷ is a parse error
+True/False/None/Ellipsis -> emit dedicated load opcode
+FstringStart             -> fstring()
+Lbrace                   -> brace_literal() (dict, set, comprehension)
+Lsqb                     -> list_literal() (list, comprehension)
+Lpar                     -> grouped expr, tuple, generator, or empty tuple
+Lambda                   -> parse_lambda()
 ```
 
-After an atom, `postfix_tail()` handles trailers, subscript, attribute, call, iterating until none apply. Lets `fns[0](-3)`, `obj.method()`, `(lambda x: x)(3)`, `compose(f, g)(x)` parse uniformly.
+After an atom, `postfix_tail()` handles trailers (subscript, attribute, call), iterating until none apply. Lets `fns[0](-3)`, `obj.method()`, `(lambda x: x)(3)`, `compose(f, g)(x)` parse uniformly.
 
-`*args` / `**kwargs` are accepted in **call** position only, starred unpacking inside literals (`[*a, *b]`, `{**d1, **d2}`, `(1, *xs, 2)`) is not supported.
+`*args` / `**kwargs` are accepted in **call** position only; starred unpacking inside literals (`[*a, *b]`, `{**d1, **d2}`, `(1, *xs, 2)`) is not supported.
 
 ## Operator precedence
 
@@ -88,7 +88,7 @@ Comparison chaining (`a < b < c`) is handled by `infix_bp`: when a comparison op
 a and b
 
 LoadName a
-JumpIfFalseOrPop  ->  end
+JumpIfFalseOrPop -> end
 LoadName b
 end:
 ```
@@ -108,12 +108,12 @@ y = x # y_1, references x_2
 ```text
 chunk.names = ["x_1", "x_2", "y_1"]
 chunk.instructions:
-   LoadConst 0   (1)
-   StoreName 0   (x_1)
-   LoadConst 1   (2)
-   StoreName 1   (x_2)
-   LoadName 1   (x_2)
-   StoreName 2   (y_1)
+  LoadConst 0   (1)
+  StoreName 0   (x_1)
+  LoadConst 1   (2)
+  StoreName 1   (x_2)
+  LoadName 1    (x_2)
+  StoreName 2   (y_1)
 ```
 
 Undefined names target version 0 (`x_0`), filled by the host before execution (VM seeds globals like `print_0`). Still unbound at load time -> `NameError`.
@@ -132,9 +132,9 @@ Each `Phi` carries the target slot (new version after join) in its operand; sour
 
 ```python
 if cond:
-    x = 1
+  x = 1
 else:
-    x = 2
+  x = 2
 print(x)
 ```
 
@@ -153,34 +153,34 @@ LoadName x_3
 CallPrint 1
 ```
 
-Runtime resolves `Phi` by reading whichever source slot is `Some`, exactly one branch executed.
+Runtime resolves `Phi` by reading whichever source slot is `Some` — exactly one branch executed.
 
 ## Statement dispatch
 
 `stmt()` peeks the leading token and routes:
 
 ```text
-if   -> if_stmt   (with elif chain, optional else)
-for   -> for_stmt_inner   (sync iter, optional else)
-while   -> while_stmt   (with break/continue patches)
-match   -> match_stmt
-def   -> func_def_inner
-class   -> class_def   (__init__, attributes, methods)
-with   -> with_stmt_inner   (multi-target, async variant)
-try   -> try_stmt   (except, else, finally, raise)
-import   -> import_stmt   (compile-time resolver lookup)
-from   -> parse_from_stmt   (named / star imports, same path)
-type -> type-alias declaration
-yield   -> yield expr / yield from
-async   -> async def / for / with
-@   -> decorator stack + def or class   (peeks `class` after the @-list)
+if       -> if_stmt (with elif chain, optional else)
+for      -> for_stmt_inner (sync iter, optional else)
+while    -> while_stmt (with break/continue patches)
+match    -> match_stmt
+def      -> func_def_inner
+class    -> class_def (__init__, attributes, methods)
+with     -> with_stmt_inner (multi-target, async variant)
+try      -> try_stmt (except, else, finally, raise)
+import   -> import_stmt (compile-time resolver lookup)
+from     -> parse_from_stmt (named / star imports, same path)
+type     -> type-alias declaration
+yield    -> yield expr / yield from
+async    -> async def / for / with
+@        -> decorator stack + def or class (peeks `class` after the @-list)
 return   -> expr + ReturnValue
-raise   -> expr + Raise / RaiseFrom
-break   -> emits Jump, back-patched to the loop exit
-continue   -> jump to current loop_start
+raise    -> expr + Raise / RaiseFrom
+break    -> emits Jump, back-patched to the loop exit
+continue -> jump to current loop_start
 del / global / nonlocal / pass -> direct emit
 assert   -> Assert opcode; the `, msg` form lowers to a conditional raise of AssertionError(msg)
-Name   -> name_stmt   (assignment, augmented, indexed, attribute, call)
+Name     -> name_stmt (assignment, augmented, indexed, attribute, call)
 ```
 
 Each statement returns a bool: did it leave a value on the stack. Driver emits `PopTop` after expression-shaped statements (`x.method()`, `1 + 2` at module level), not after statement-shaped (assignment, control flow).
@@ -195,14 +195,14 @@ Lambdas and `def` both compile their body into a *fresh* SSAChunk:
 
 ```rust
 self.with_fresh_chunk(|s| {
-    s.ssa_versions = outer_versions.clone();
-    for p in &params { s.ssa_versions.insert(p.clone(), 0); }
-    s.expr(); // or compile_block_body for def
-    s.chunk.emit(OpCode::ReturnValue, 0);
+  s.ssa_versions = outer_versions.clone();
+  for p in &params { s.ssa_versions.insert(p.clone(), 0); }
+  s.expr(); // or compile_block_body for def
+  s.chunk.emit(OpCode::ReturnValue, 0);
 });
 ```
 
-Free variables (non-parameters with no local binding) are looked up in the outer chunk. `MakeFunction` captures matching slots from the enclosing scope into `captures` (snapshotted, no cell objects). Nested `def`/`lambda` push their free names back into the parent's name table, capture propagates through any depth (`A -> B -> C` where `C` references a var in `A`).
+Free variables (non-parameters with no local binding) are looked up in the outer chunk. `MakeFunction` captures matching slots from the enclosing scope into `captures` (snapshotted, no cell objects). Nested `def`/`lambda` push their free names back into the parent's name table; capture propagates through any depth (`A -> B -> C` where `C` references a var in `A`).
 
 Parameter slots: `Normal`, `Star` (`*args`), `DoubleStar` (`**kwargs`). Lone `*` separator marks following params as keyword-only. Defaults live in `HeapObj::Func.defaults` and apply to the last-N positional slots. Annotations (`x: T`, `-> T`) parse and drain to `chunk.annotations` (tooling-only).
 
@@ -213,9 +213,10 @@ Parameter slots: `Normal`, `Star` (`*args`), `DoubleStar` (`**kwargs`). Lone `*`
 Parsed for source compatibility, discarded at runtime:
 
 ```python
-counter: int = 0   # annotation 'int' parsed and stored, slot still gets 0
-def f(x: int) -> int:   # annotations on params and return parsed and skipped
-    return x
+counter: int = 0 # annotation 'int' parsed and stored, slot still gets 0
+def f(x: int) -> int:
+  # annotations on params and return parsed and skipped
+  return x
 ```
 
 Recorded in `chunk.annotations: HashMap<String, String>` for tooling; no code emitted. `f.__annotations__` is not exposed at runtime, but `f.__name__` is (resolved in `resolve_attr`, also on type objects and classes).
@@ -238,17 +239,17 @@ Lowers to:
 
 ```text
 LoadConst "hello "
-LoadName  name_v
+LoadName name_v
 FormatValue 0
 LoadConst ", age "
-LoadName  age_v
+LoadName age_v
 FormatValue 0
 BuildString 5
 ```
 
 `FormatValue`'s 16-bit operand is a small flags field:
-* bit 0, set when a format spec string is on the stack just below the value (collected as the raw text between `:` and `}` and emitted as a constant).
-* bits 1,2, conversion: `0` none, `1` `!r`, `2` `!s`, `3` `!a`.
+- bit 0, set when a format spec string is on the stack just below the value (collected as the raw text between `:` and `}` and emitted as a constant).
+- bits 1–2, conversion: `0` none, `1` `!r`, `2` `!s`, `3` `!a`.
 
 VM applies conversion first, then the spec mini-language `[[fill]align][sign][#][0][width][,][.precision][type]` with type chars `s d b o x X f F e E g G n % c`. `n` aliases `d` (no locale). `=` self-documenting form (`{expr=}`) emits a literal `expr=` prefix. Adjacent string literals concatenate at parse time. Spec parse failures -> `ValueError` at runtime.