magpie-engineer

Magpie Language Programming Guide

Use this skill whenever you write, debug, or review Magpie .mp programs.

---

0) Non-negotiable Rules

1. Binary-first: treat compiler diagnostics as ground truth.
   • Run magpie explain <CODE> for any error code you don't recognize.
   • Use --output json for machine-readable diagnostics.
2. Diagnose by error code first, then apply the smallest fix.
3. Smallest reproducer first -- one tiny .mp file, then grow.
4. Change one dimension at a time (syntax, then types, then ownership, then backend).
5. Prove fixes with commands and exit codes.

---

1) What is Magpie

Magpie is a compiled, SSA-based language with explicit ownership, ARC memory management, and first-class GPU support. Programs are written in a low-level IR-like textual format (CSNF).

Key characteristics:

• SSA form -- every value is defined once, used by name (%x, %y)
• Explicit ownership -- you manually borrow.shared, borrow.mut, share, clone.shared
• ARC-managed heap -- the compiler inserts reference counting; you manage ownership transitions
• Block-structured -- functions contain labeled basic blocks (bb0:, bb1:) with explicit terminators
• No implicit conversions -- types must match exactly; const suffixes must match declared types
• 5 GPU backends -- SPIR-V, Metal (MSL), PTX (CUDA), HIP (AMD), WGSL (WebGPU)

How Magpie differs from familiar languages:

• There are no expressions or statements -- only SSA instructions and terminators
• Control flow uses br, cbr, switch -- not if/else/for/while
• Variables are SSA locals (%name) -- assigned exactly once
• Functions are @name -- always prefixed with @
• Types are TName -- user-defined types start with T
• Comments use ; (not // or #); doc comments use ;;

---

2) Module Structure

Every .mp file must have a strict header in exactly this order:

module <module.path>
exports { <exported symbols> }
imports { <import groups> }
digest "<hex string>"