index.md

Kōdo Documentation

Welcome to the Kōdo documentation. Kōdo is a compiled programming language designed for AI agents to write, reason about, and maintain software — while remaining fully transparent and auditable by humans.

Learn Kōdo

Getting Started

• Installing Kōdo — prerequisites, build from source, and your first program
• A Tour of Kōdo — a quick walkthrough of the language's key features
• Your First Kōdo Program — hello world, compile, and run

Language

• Language Basics — modules, functions, types, variables, and control flow
• Data Types and Pattern Matching — structs, enums, and match expressions
• Generics — generic types and generic functions
• Error Handling — using Option<T> and Result<T, E> for safe error handling
• Closures — closures, lambda lifting, and higher-order functions
• Traits — trait definitions and static dispatch
• Inherent Methods — struct methods without traits
• String Interpolation — f-strings with {expression} embedding
• Pattern Matching — exhaustive match on enums
• Contracts — requires and ensures for runtime verification
• Modules and Imports — multi-file programs and the standard library
• Ownership — linear ownership with own, ref, and mut
• Agent Traceability — annotations, trust policies, and confidence propagation
• HTTP, JSON & Networking — HTTP client and server, JSON parsing and building
• CLI Tools, File I/O & Math — args(), readln, exit, file operations, extended math
• Actors — actor model with state and message passing
• Collections — List, Map, Set, and JSON
• Iterators — for-in loops, iterator protocol, collection traversal
• Functional Combinators — map, filter, fold, count, any, all, reduce, pipelines
• Concurrency & Spawn — spawn with captured variables
• Testing — built-in test framework with assertions and kodoc test
• Real-World Examples — complete programs: todo app, URL shortener, word counter, config validator, health checker

Standard Library

• Standard Library Reference — complete reference for all built-in functions and methods
• Regex Builtins — regex_match, regex_find, regex_replace

Tools

• CLI Reference — all kodoc commands, flags, and environment variables, including confidence-report, fix, and audit
• MCP Server — AI agent integration via Model Context Protocol (6 tools, JSON-RPC over stdio)

Reference

• Language Specification — the full language design document
• Formal Grammar — LL(1) grammar in EBNF
• Error Index — catalog of all compiler error codes
• Academic References — foundational theory behind each compiler phase

Examples

The examples/ directory contains compilable programs demonstrating every feature:

Example	Feature
hello.ko	Minimal program
fibonacci.ko	Recursion
while_loop.ko	Loops and mutable variables
contracts_demo.ko	Runtime contracts
structs.ko	Struct types
struct_params.ko	Structs as function parameters and return values
enums.ko	Enum types and pattern matching
enum_params.ko	Enums as function parameters
generics.ko	Generic enum types
generic_fn.ko	Generic functions
option_demo.ko	Standard library Option<T>
result_demo.ko	Standard library Result<T, E>
multi_file/	Multi-file compilation with imports
intent_demo.ko	Intent-driven programming
intent_math.ko	Math module intent resolver
intent_composed.ko	Composing multiple intents
agent_traceability.ko	Agent annotations and trust policies
closures.ko	Closures and direct closure calls
closures_functional.ko	Higher-order functions and indirect calls
float_math.ko	Float64 arithmetic operations
string_concat_operator.ko	String concatenation with + operator
intent_http.ko	HTTP intent resolver
intent_cli.ko	CLI tool intent resolver
intent_http_server.ko	HTTP server intent resolver
intent_file_processor.ko	File processor intent resolver
intent_worker.ko	Worker loop intent resolver
stdlib_demo.ko	Standard library math functions
async_real.ko	Cooperative spawn with deferred execution
ownership.ko	Linear ownership with own and ref
borrow_rules.ko	Borrow rules: multiple ref borrows
move_semantics.ko	Move semantics, Copy vs non-Copy types
list_demo.ko	List<T> built-in collection
map_demo.ko	Map<K,V> built-in collection
map_string_string.ko	Map<String, String> — generic map with String keys and values
map_string_int.ko	Map<String, Int> — generic map with String keys
map_int_string.ko	Map<Int, String> — generic map with String values
string_demo.ko	String methods including split
file_io_demo.ko	File I/O operations
contracts_smt_demo.ko	SMT-verified contracts
smt_verified.ko	SMT contract verification
http_client.ko	HTTP GET with Result<String, String>
http_api.ko	HTTP server with JSON responses
cli_args.ko	Reading command-line arguments with args()
json_builder.ko	JSON construction with json_new_object, json_set_*, json_stringify
math_demo.ko	Extended math: rand_int
async_tasks.ko	Spawn with captured variables
actors.ko	Actor state and message passing
actor_demo.ko	Actor demonstration
type_inference.ko	Local type inference for let bindings
intent_database.ko	Database intent resolver
intent_json_api.ko	JSON API intent resolver
intent_cache.ko	Cache intent resolver
intent_queue.ko	Queue intent resolver
parallel_demo.ko	Structured concurrency with parallel {}
channel_string.ko	Generic typed channels
refinement_smt.ko	SMT-verified refinement types
struct_predicates.ko	Struct field predicates in contracts
generic_bounds.ko	Generic trait bounds (<T: Ord>)
sorted_list.ko	Bounded generics with sorted collections
methods.ko	Inherent impl blocks
string_interpolation.ko	F-string interpolation
memory_management.ko	Reference counting
tuples.ko	Tuple types, indexing, and destructuring
for_in.ko	For-in loops over collections
iterator_basic.ko	Basic iterator protocol
iterator_list.ko	Iterating over List<T>
iterator_map_filter.ko	map and filter combinators on iterators
iterator_fold.ko	fold combinator for aggregation
functional_pipeline.ko	Functional pipelines with chained combinators
todo_app.ko	Real-world: CLI todo app with structs, enums, contracts
url_shortener.ko	Real-world: URL shortener with Map and validation
word_counter.ko	Real-world: Word counter with string ops and fold
config_validator.ko	Real-world: Config validator with contracts and enums
health_checker.ko	Real-world: Health checker with file checks and fold aggregation