feat: add CPython bytecode introspection layer

README.md

@@ -52,6 +52,22 @@ work.
 > remains an aspirational target — see `tests/regrtest/expectations.toml`
 > for the per-test baseline. Expect small breaking changes
 > around the edges as the long tail catches up.
+>
+> `RFC 0033` makes WeavePy *introspectable like CPython*. It ships a
+> CPython-faithful **code-object surface** (`co_code`, `co_linetable`
+> (PEP 626), `co_exceptiontable`, `co_positions()` (PEP 657),
+> `co_stacksize`, `co_qualname`, `co_lines()`, `replace()`, …) backed by
+> a new `cpython_code` codec that re-encodes WeavePy's instruction stream
+> into CPython 3.13's 16-bit `_Py_CODEUNIT` form (`EXTENDED_ARG` + inline
+> `CACHE` entries). On top of that it lands the four introspection
+> modules every serious tool reaches for — `import ast`, `import dis`,
+> `import opcode`, `import symtable` — as frozen Python over thin Rust
+> cores (`_ast`, `_symtable`), a `marshal` that serialises code objects
+> byte-compatibly with CPython 3.13 (`TYPE_CODE` + `FLAG_REF` shared refs
+> + exact 15-bit bigint digits), and real `.pyc` read/write under
+> `__pycache__` using CPython's `b"\xf3\r\r\n"` magic + PEP 552 header
+> (kept collision-safe by a distinct `weavepy-3.13` cache tag). Six
+> bundled regrtests cross-check the whole surface against CPython 3.13.
 
 ## Repository layout
 

crates/weavepy-compiler/src/bytecode.rs

@@ -55,6 +55,24 @@ impl CompareKind {
             Self::GtE => ">=",
         }
     }
+
+    /// The opcode argument that encodes this comparison.
+    pub fn as_arg(self) -> u32 {
+        self as u32
+    }
+
+    /// Recover a [`CompareKind`] from its opcode argument.
+    pub fn from_arg(arg: u32) -> Option<Self> {
+        Some(match arg {
+            0 => Self::Lt,
+            1 => Self::LtE,
+            2 => Self::Eq,
+            3 => Self::NotEq,
+            4 => Self::Gt,
+            5 => Self::GtE,
+            _ => return None,
+        })
+    }
 }
 
 impl BinOpKind {
@@ -75,6 +93,31 @@ impl BinOpKind {
             Self::MatMult => "@",
         }
     }
+
+    /// The opcode argument that encodes this binary operator.
+    pub fn as_arg(self) -> u32 {
+        self as u32
+    }
+
+    /// Recover a [`BinOpKind`] from its opcode argument.
+    pub fn from_arg(arg: u32) -> Option<Self> {
+        Some(match arg {
+            0 => Self::Add,
+            1 => Self::Sub,
+            2 => Self::Mult,
+            3 => Self::Div,
+            4 => Self::FloorDiv,
+            5 => Self::Mod,
+            6 => Self::Pow,
+            7 => Self::LShift,
+            8 => Self::RShift,
+            9 => Self::BitOr,
+            10 => Self::BitXor,
+            11 => Self::BitAnd,
+            12 => Self::MatMult,
+            _ => return None,
+        })
+    }
 }
 
 /// Unary op tag for [`OpCode::UnaryOp`].
@@ -96,6 +139,22 @@ impl UnaryKind {
             Self::Invert => "~",
         }
     }
+
+    /// The opcode argument that encodes this unary operator.
+    pub fn as_arg(self) -> u32 {
+        self as u32
+    }
+
+    /// Recover a [`UnaryKind`] from its opcode argument.
+    pub fn from_arg(arg: u32) -> Option<Self> {
+        Some(match arg {
+            0 => Self::Pos,
+            1 => Self::Neg,
+            2 => Self::Not,
+            3 => Self::Invert,
+            _ => return None,
+        })
+    }
 }
 
 /// Opcodes emitted by the WeavePy compiler. The argument's meaning