Go Interop Guide

This guide explains how to integrate AILANG code with Go applications.

ABI Stability Notice (v0.5.x): The Go interop ABI is considered "stable preview". Breaking changes are allowed until v0.6.0 but will be announced in the CHANGELOG. See ABI Stability for details.

Integration Options

AILANG provides two ways to integrate with Go:

Approach	Use Case	Performance	Complexity
Runtime Embedding	Dynamic transforms, config DSL, scripting	Good (cached)	Low
Compile-time Codegen	Game engines, hot paths, type-safe ABI	Best	Medium

Runtime Embedding (v0.6.4+): Embed AILANG interpreter, call functions at runtime
Compile-time Codegen: Generate Go code with ailang compile --emit-go

Runtime Embedding (v0.6.4+)

The internal/embed package lets you embed AILANG as a scripting/extension language in Go applications.

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/sunholo/ailang/internal/embed"
)

func main() {
    // Create engine with base path for module resolution
    engine := embed.New("/path/to/project")
    defer engine.Close()

    // Call an AILANG function
    result, err := engine.Call(
        "transforms/formatter",  // module path
        "truncate",              // function name
        "Hello, World!",         // args...
        10,
    )
    if err != nil {
        log.Fatal(err)
    }

    // Extract typed result
    text, _ := embed.ToString(result)
    fmt.Println(text)  // "Hello, Wor..."
}

Engine API

// Create a new engine
engine := embed.New(basePath string) *Engine

// Load a module (optional - Call auto-loads)
engine.Load(modulePath string) error

// Call an exported function
engine.Call(modulePath, funcName string, args ...interface{}) (eval.Value, error)

// JSON-based calling (for language-agnostic integration)
engine.CallJSON(modulePath, funcName string, inputJSON []byte) ([]byte, error)

// Evaluate an expression (requires module context)
engine.Eval(code string) (eval.Value, error)

// Introspection
engine.ListExports(modulePath string) ([]string, error)
engine.HasExport(modulePath, name string) bool

// Cleanup
engine.Close() error

Value Conversion

The embed package provides bidirectional conversion between Go and AILANG values:

Go to AILANG (FromGo):

Go Type	AILANG Type
`nil`	`()` (unit)
`bool`	`bool`
`int`, `int8`...`int64`	`int`
`uint`, `uint8`...`uint64`	`int`
`float32`, `float64`	`float`
`string`	`string`
`[]byte`	`bytes`
`[]T`	`[T]` (list)
`[N]T`	array
`map[string]T`	`{...}` (record)
`struct`	`{...}` (record, exported fields)

AILANG to Go (ToGo):

AILANG Type	Go Type
`()` (unit)	`nil`
`bool`	`bool`
`int`	`int`
`float`	`float64`
`string`	`string`
`bytes`	`[]byte`
`[T]` (list)	`[]interface{}`
`{...}` (record)	`map[string]interface{}`

Type-Safe Extractors

For type safety, use the specific extractors:

// Extract specific types
value, err := embed.ToInt(result)
value, err := embed.ToFloat(result)
value, err := embed.ToString(result)
value, err := embed.ToBool(result)
value, err := embed.ToBytes(result)
value, err := embed.ToList(result)
value, err := embed.ToRecord(result)

// Check for unit
if embed.IsUnit(result) {
    // result is ()
}

JSON Integration

For language-agnostic use or HTTP APIs:

// JSON input → AILANG → JSON output
inputJSON := []byte(`{"events": [...], "maxLen": 200}`)
outputJSON, err := engine.CallJSON(
    "transforms/formatter",
    "processEvents",
    inputJSON,
)
// outputJSON ready for HTTP response

// Manual JSON conversion
ailangVal, err := embed.FromJSON(jsonBytes)
jsonBytes, err := embed.ToJSON(ailangVal)

Complete Example

Given this AILANG module:

-- transforms/event_formatter.ail
module transforms/event_formatter

import std/string (length as strlen, substring)

export pure func truncate(text: string, maxLen: int) -> string =
  if maxLen == 0 || strlen(text) <= maxLen
  then text
  else substring(text, 0, maxLen) ++ "..."

export pure func countWords(text: string) -> int =
  length(split(text, " "))

Call it from Go:

package main

import (
    "fmt"
    "github.com/sunholo/ailang/internal/embed"
)

func main() {
    engine := embed.New(".")
    defer engine.Close()

    // Call truncate
    result, _ := engine.Call(
        "transforms/event_formatter",
        "truncate",
        "The quick brown fox jumps over the lazy dog",
        20,
    )
    text, _ := embed.ToString(result)
    fmt.Println(text)  // "The quick brown fox ..."

    // Call countWords
    result, _ = engine.Call(
        "transforms/event_formatter",
        "countWords",
        "hello world foo bar",
    )
    count, _ := embed.ToInt(result)
    fmt.Println(count)  // 4

    // Using structs
    type Event struct {
        TurnNum    int    `json:"turnNum"`
        StreamType string `json:"streamType"`
        Text       string `json:"text"`
    }

    event := Event{TurnNum: 1, StreamType: "text", Text: "Hello"}
    ailangVal, _ := embed.FromGo(event)
    // ailangVal is now an AILANG record
}

Limitations

Pure functions recommended: Embedded modules should be pure for predictability
No hot reloading: Restart engine to pick up module changes
Standalone expressions: Eval("1+2") requires let binding: Eval("let x = 1+2 in x")
Thread safety: Engine is mutex-protected; for parallel calls, use separate engines

When to Use Runtime Embedding

Good for:

Configuration DSLs
Data transformation pipelines
Plugin/extension systems
Scripting in applications
Dynamic rule engines

Consider compile-time codegen instead for:

Performance-critical game loops
Type-safe ABI requirements
Static analysis of generated code

Comparison: Embedding vs Codegen

Feature Comparison

Feature	Runtime Embedding	Compile-Time Codegen
Performance	Good (cached modules)	Best (native Go)
Type safety	Runtime errors	Compile-time errors
Hot reload	Restart engine	Recompile binary
Deployment	Ship .ail files	Single binary
Debugging	AILANG stack traces	Go stack traces
Effects	Pure functions only	Full effect handlers
Complexity	Simple API	Generated code to maintain

Performance Characteristics

Runtime Embedding:

First call:   ~50-100ms (parse + compile + type check)
Cached call:  ~0.1-1ms (lookup + eval)
Memory:       Runtime + cached ASTs

Compile-Time Codegen:

First call:   ~0.001ms (native Go function)
All calls:    ~0.001ms (no interpretation overhead)
Memory:       Static Go code only

When to Choose Each

Choose Runtime Embedding when:

✅ AILANG modules change frequently
✅ End users customize behavior
✅ Plugin/extension architecture
✅ Prototyping and development
✅ Pure data transformation
✅ Minimal integration effort needed

Choose Compile-Time Codegen when:

✅ Performance is critical (game loops, hot paths)
✅ Type-safe ABI with Go required
✅ Need full effect handler support
✅ Single-binary deployment preferred
✅ Static analysis of generated code needed

Hybrid Approach

You can use both approaches in the same project:

// Core game loop: compile-time codegen for performance
import "mygame/gen/game"

func gameLoop() {
    // Native Go speed
    result := game.Step(world, input)
}

// Config/scripting: runtime embedding for flexibility
import "github.com/sunholo/ailang/internal/embed"

func loadMods() {
    engine := embed.New("./mods")
    for _, mod := range modPaths {
        engine.Call(mod, "init", gameState)
    }
}

Code Comparison

Same AILANG module:

module example/math

export pure func add(a: int, b: int) -> int = a + b

With Runtime Embedding:

engine := embed.New(".")
result, err := engine.Call("example/math", "add", 1, 2)
sum, _ := embed.ToInt(result)  // sum = 3

With Compile-Time Codegen:

ailang compile --emit-go --package-name math example/math.ail

import "myproject/gen/math"

sum := math.Add(1, 2)  // sum = 3

Compile-Time Codegen

For performance-critical use cases, compile AILANG to Go code with ailang compile --emit-go.

Type Mapping

AILANG types map to Go types as follows:

AILANG Type	Go Type	Notes
`int`	`int64`	64-bit signed integer
`float`	`float64`	64-bit floating point
`string`	`string`	UTF-8 string
`bool`	`bool`	Boolean
`()`	`struct{}`	Unit type (empty struct)
`[T]`	`[]T`	Slice of element type
`{ field: T }`	`*TypeName`	Pointer to generated struct
ADT variants	`*TypeName`	Pointer to discriminated union

Extern Functions

Extern functions allow you to implement performance-critical code in Go while maintaining type safety with AILANG.

Declaring Extern Functions

In your AILANG file:

-- Declare types
type Coord = { x: int, y: int }
type Path = [Coord]

-- Declare extern function (implemented in Go)
extern func find_path(world: World, from: Coord, to: Coord) -> Path

Generating Stubs

Run the compiler to generate Go stubs:

ailang compile --emit-go world.ail

This generates extern_stubs.go with function signatures to implement:

Multi-File Compilation

When your game has multiple AILANG modules, compile them together. You can pass a directory to automatically discover all .ail files (v0.5.5+):

# Pass a directory - discovers all .ail files automatically
ailang compile --emit-go --package-name game sim/

# Or pass multiple files explicitly
ailang compile --emit-go --package-name game step.ail npc_ai.ail camera.ail

# Mix directories and files
ailang compile --emit-go --package-name game sim/ extra.ail

This generates one output file per source file (v0.5.5+):

gen/game/
├── types.go              # All ADT types (merged from all files)
├── debug_types_debug.go  # Debug effect (//go:build !release)
├── debug_types_release.go# Debug effect no-ops (//go:build release)
├── handlers.go           # Effect handler interfaces
├── runtime.go            # Shared runtime helpers
├── step.go               # Functions from step.ail
├── npc_ai.go             # Functions from npc_ai.ail
└── camera.go             # Functions from camera.ail

Benefits of per-file output:

Smaller, more navigable files
Easier to correlate generated code with source
Better IDE navigation

Important: Compile all your .ail files in a single command. Compiling files separately will overwrite previous output.

# ✅ CORRECT - Compile all files together
ailang compile --emit-go sim/

# ❌ WRONG - Each compile overwrites the previous
ailang compile --emit-go step.ail      # Generates types.go
ailang compile --emit-go npc_ai.ail    # OVERWRITES types.go!

Generated Extern Stubs

The compiler generates extern_stubs.go with function signatures to implement:

// Find_path is an extern function declared in AILANG.
//
// AILANG signature:
//   extern func find_path(world: World, from: Coord, to: Coord) -> Path
//
// Implement this function to provide the behavior.
func Find_path(world *World, from *Coord, to *Coord) []*Coord {
    panic("not implemented: find_path")
}

Implementing Extern Functions

Replace the panic with your implementation:

func Find_path(world *World, from *Coord, to *Coord) []*Coord {
    // Your A* pathfinding implementation here
    return aStarSearch(world, from, to)
}

Restrictions

Monomorphic only: Extern functions cannot use type parameters (generics)

-- ERROR: extern functions cannot be polymorphic
extern func identity[T](x: T) -> T

No underscore prefix: Extern function names cannot start with _

-- ERROR: underscore prefix reserved for builtins
extern func _internal_helper(x: int) -> int

Explicit return type: Extern functions must declare their return type

-- ERROR: must have explicit return type
extern func do_something(x: int)

-- OK
extern func do_something(x: int) -> ()

Error Messages

Common errors and their solutions:

EXT001: Underscore prefix not allowed

EXT001: extern function '_helper' cannot have underscore-prefix (reserved for builtins)
Suggestion: Use a public name without leading underscore

Solution: Remove the leading underscore from the function name.

EXT002: Polymorphic not supported

EXT002: extern functions cannot be polymorphic (no type parameters)
Suggestion: Extern functions must use concrete types like int, float, string

Solution: Use concrete types instead of type parameters.

EXT003: Missing return type

EXT003: extern functions must have explicit return type
Suggestion: Add '-> ReturnType' after parameters

Solution: Add an explicit return type annotation.

Best Practices

Keep extern functions focused: Extern functions should do one thing well
Document type expectations: Add comments explaining any type constraints
Handle errors explicitly: Return error values rather than panic
Test thoroughly: Write Go tests for your extern implementations

ADT to Go Mapping Rules

When AILANG Algebraic Data Types (ADTs) are compiled to Go, the following rules apply:

Record Types

AILANG record types become Go structs with pointer semantics:

type Player = { name: string, health: int, position: Coord }

Generates:

type Player struct {
    Name     string
    Health   int64
    Position *Coord
}

Rules:

Field names are capitalized (exported)
Nested records use pointer types
All record type function parameters/returns use pointers

Sum Types (Variants)

AILANG sum types (ADTs with multiple constructors) become Go structs with a discriminator:

type Option[T] =
  | Some(T)
  | None

Generates:

type Option struct {
    Tag   OptionTag
    Some  *SomeData  // nil if Tag != OptionTagSome
}

type OptionTag int

const (
    OptionTagNone OptionTag = iota
    OptionTagSome
)

type SomeData struct {
    Value interface{}  // Generic types use interface{}
}

Rules:

Discriminator field is named Tag
Constructor data stored in nullable fields
Use type switch on Tag for pattern matching

Effect Handlers

AILANG effects (Rand, Clock, FS, Net, Env, AI) are compiled to Go interface calls. The generated code expects you to implement handler interfaces and initialize them before use.

How Effect Handler Codegen Works

When you compile AILANG code with effects:

module game/step

import std/rand (rand_int)

export func rollDice() -> int ! {Rand} {
  rand_int(1, 6)
}

The compiler generates:

Handler interfaces in effects.go:

// RandHandler provides the Rand effect implementation.
type RandHandler interface {
    RandInt(min, max int64) int64
}

Handlers struct to collect all handlers:

type Handlers struct {
    Debug DebugHandler
    Rand  RandHandler
    Clock ClockHandler
    FS    FSHandler
    Net   NetHandler
    Env   EnvHandler
    AI    AIHandler
}

Init function to initialize the global handlers:

func Init(h Handlers) {
    handlers = h
}

var handlers Handlers

Function code that calls handlers:

func RollDice() int64 {
    return handlers.Rand.RandInt(1, 6)
}

Implementing Handlers

Game developers implement the handler interfaces for their platform:

package main

import "mygame/gen/game"

// Implement RandHandler
type MyRandHandler struct {
    seed uint64
}

func (r *MyRandHandler) RandInt(min, max int64) int64 {
    // Your deterministic RNG implementation
    r.seed = r.seed*1103515245 + 12345
    return min + int64(r.seed)%(max-min+1)
}

func main() {
    // Initialize handlers before using any AILANG code
    game.Init(game.Handlers{
        Rand: &MyRandHandler{seed: 12345},
        // ... other handlers
    })

    // Now you can call AILANG functions
    result := game.RollDice()
}

Available Effect Handlers

Handler	Methods	Purpose
`DebugHandler`	`Log(msg, loc)`, `Assert(cond, msg, loc)`, `Collect()`	Debugging and tracing
`RandHandler`	`RandInt(min, max)`, `RandFloat()`	Deterministic random numbers
`ClockHandler`	`Now()`, `DeltaTime()`	Time and game loop timing
`FSHandler`	`Exists(path)`, `ReadFile(path)`, `WriteFile(path, content)`	File system operations
`NetHandler`	`HttpGet(url)`, `HttpPost(url, body)`	Network requests
`EnvHandler`	`GetEnv(key)`	Environment variables
`AIHandler`	`Call(prompt, opts)`	AI model calls

Handler Implementation Tips

Keep handlers stateless if possible - easier to test and reason about
Use deterministic implementations for Rand - enables replay and testing
Mock handlers for testing - inject test doubles via Init()
Initialize once at startup - don't call Init() multiple times

Legacy: Extern Functions

For custom operations not covered by the built-in effect handlers, you can use extern functions (see Extern Functions above).

Debug Effect Host Contract

The Debug effect provides structured tracing for debugging and testing. It is a ghost effect - erasable in release mode for zero-cost production builds.

Generated Files

Running ailang compile --emit-go generates:

File	Purpose	Build Tag
`debug_types_debug.go`	Full implementation (collects traces)	`//go:build !release`
`debug_types_release.go`	No-op implementation (zero cost)	`//go:build release`

DebugContext Interface

The generated DebugContext implements this contract:

type DebugContext struct {
    // ... internal state
}

// Host lifecycle methods (HOST-ONLY - not callable from AILANG)
func NewDebugContext() *DebugContext
func (d *DebugContext) SetTimestamp(t int64)  // Host sets logical time
func (d *DebugContext) Collect() DebugOutput  // Host reads accumulated data
func (d *DebugContext) Reset()                // Clear for next step

// Effect operation handlers (called by generated AILANG code)
func (d *DebugContext) Log(msg, location string)
func (d *DebugContext) Assert(cond bool, msg, location string)

// Query methods
func (d *DebugContext) HasFailedAssertions() bool
func (d *DebugContext) FailedAssertions() []AssertionResult

Output Types

type DebugOutput struct {
    Logs       []LogEntry
    Assertions []AssertionResult
}

type LogEntry struct {
    Message   string  // Log message
    Location  string  // Source location (file.ail:42)
    Timestamp int64   // Logical time (host-defined)
}

type AssertionResult struct {
    Passed   bool    // Whether assertion passed
    Message  string  // Assertion message
    Location string  // Source location (file.ail:42)
}

Host Integration Example

func main() {
    debugCtx := game.NewDebugContext()

    for tick := 0; tick < 1000; tick++ {
        // 1. Reset and set timestamp for this step
        debugCtx.Reset()
        debugCtx.SetTimestamp(int64(tick))

        // 2. Run AILANG code (Debug.log/assert calls accumulate)
        world, output, err := game.Step(world, input, debugCtx)
        if err != nil {
            log.Fatal(err)
        }

        // 3. Host collects and handles debug output
        debugData := debugCtx.Collect()

        // Check for assertion failures
        if debugCtx.HasFailedAssertions() {
            for _, a := range debugCtx.FailedAssertions() {
                log.Printf("ASSERTION FAILED at %s: %s", a.Location, a.Message)
            }
        }
    }
}

Building Debug vs Release

# Debug mode (default) - Debug effect collects traces
go build .

# Release mode - Debug effect is zero-cost no-ops
go build -tags release .

JSON Schema for DebugOutput

The DebugOutput structure can be serialized to JSON for external tooling:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "DebugOutput",
  "type": "object",
  "properties": {
    "logs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "location": { "type": "string", "pattern": "^.+:\\d+$" },
          "timestamp": { "type": "integer" }
        },
        "required": ["message", "location", "timestamp"]
      }
    },
    "assertions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "passed": { "type": "boolean" },
          "message": { "type": "string" },
          "location": { "type": "string", "pattern": "^.+:\\d+$" }
        },
        "required": ["passed", "message", "location"]
      }
    }
  },
  "required": ["logs", "assertions"]
}

Example JSON output:

{
  "logs": [
    {"message": "tick=1: delta=4", "location": "impl.go:Step", "timestamp": 1},
    {"message": "tick=2: delta=-2", "location": "impl.go:Step", "timestamp": 2}
  ],
  "assertions": [
    {"passed": true, "message": "tick should increase", "location": "impl.go:Step"},
    {"passed": true, "message": "seed should be preserved", "location": "impl.go:Step"}
  ]
}

Design Principles

Write-only from AILANG: Code can only write Debug.log/Debug.assert, cannot read its own trace
Host-controlled lifecycle: Only the host can Collect() and Reset()
Ghost effect: Erased at build time in release mode, not just no-op at runtime
Auto-injected locations: Source positions added by compiler, not passed by user
Abstract timestamps: Host defines what timestamp means (tick, test index, etc.)

Working Example

See examples/sim_stub/ for a complete working example demonstrating:

Type definitions in AILANG
Extern function declarations
Generated Go types and stubs
Go implementation
Deterministic simulation
Debug effect usage with host-controlled lifecycle

# Run the example (debug mode)
cd examples/sim_stub
make run

# Build in release mode (Debug operations become no-ops)
go build -tags release .
./sim_stub

ABI Stability

Stability Promise (v0.5.x)

The Go interop ABI is considered "stable preview" for v0.5.x:

Component	Stability	Notes
Type mapping (primitives)	Stable	int→int64, float→float64, etc.
Record type generation	Stable	Struct field ordering preserved
Extern function signatures	Stable	Generated stubs won't break
ADT discriminator format	Preview	May change before v0.6.0
Generic type handling	Preview	Currently uses interface

What "Stable Preview" Means

Safe to use in production for non-generic, non-ADT code
Breaking changes announced in CHANGELOG with migration path
Full stability guaranteed starting v0.6.0

Migration Guide: v0.4.x to v0.5.x

If upgrading from v0.4.x:

New compile subcommand: Use ailang compile --emit-go instead of any previous codegen method
Extern functions: New feature - no migration needed
Type mapping unchanged: Existing type correspondences still apply
Generated code location: Now outputs to gen/<package>/ by default

Reporting Issues

If you encounter ABI-related issues:

Check the CHANGELOG for known issues
File an issue at github.com/sunholo-data/ailang/issues
Include: AILANG version, Go version, generated code sample

Integration Options​

Runtime Embedding (v0.6.4+)​

Quick Start​

Engine API​

Value Conversion​

Type-Safe Extractors​

JSON Integration​

Complete Example​

Limitations​

When to Use Runtime Embedding​

Comparison: Embedding vs Codegen​

Feature Comparison​

Performance Characteristics​

When to Choose Each​

Hybrid Approach​

Code Comparison​

Compile-Time Codegen​

Type Mapping​

Extern Functions​

Declaring Extern Functions​

Generating Stubs​

Multi-File Compilation​

Generated Extern Stubs​

Implementing Extern Functions​

Restrictions​

Error Messages​

EXT001: Underscore prefix not allowed​

EXT002: Polymorphic not supported​

EXT003: Missing return type​

Best Practices​

ADT to Go Mapping Rules​

Record Types​

Sum Types (Variants)​

Effect Handlers​

How Effect Handler Codegen Works​

Implementing Handlers​

Available Effect Handlers​

Handler Implementation Tips​

Legacy: Extern Functions​

Debug Effect Host Contract​

Generated Files​

DebugContext Interface​

Output Types​

Host Integration Example​

Building Debug vs Release​

JSON Schema for DebugOutput​

Design Principles​

Working Example​

ABI Stability​

Stability Promise (v0.5.x)​

What "Stable Preview" Means​

Migration Guide: v0.4.x to v0.5.x​

Reporting Issues​