Command Explorer

The Command Explorer is a developer walkthrough of every command in the v0.1 language surface. Each entry answers three questions:

What does it do?
How does it work?
When would I use it?

Then it shows a minimal working example. If you want the full spec-style entry with opcodes, thread-safety, and changelog notes, see the Command Catalog.

Kairo v0.1 is pre-production. Everything here is part of the ratified v0.1 baseline unless the entry explicitly says “reserved” or “deferred.”

How to use this page

Browsing?

Skim the section headers. Each command lives in a collapsed accordion so you can open only what you need.

Looking something up?

Use Ctrl/Cmd+F for the command name (e.g. match, Result, type func).

Learning the language?

Read top-to-bottom. Categories are ordered from project structure down to runtime services.

Need the deep spec?

The catalog has opcodes, prerequisites, thread-safety, and changelog notes for every entry.

Project Structure

module - declare the module a file belongs to

What it does. Declares the logical module identity of a .ak source file.How it works. The module line must be the first non-comment declaration in the file. Module names are PascalCase and dot-separated (Astra.Customers.Models). The module name is authoritative; file paths should align with it, but paths do not define language meaning.When to use it. Every Kairo source file needs exactly one module declaration at the top.

module Sales.Orders

import - bring another module into scope

What it does. Makes the public API of another module available in the current file.How it works. import Astra.Data imports the module named Astra.Data. Kairo does not do wildcard imports and does not guess whether the final segment is a type name.When to use it. Any time you need to reference something declared in a different module.

module Demo.App

import Astra.Data
import Pulse.Console

import ... as - alias an imported module

What it does. Imports a module under a shorter local name.How it works. The alias is a readability aid inside the current file. It does not create a new module identity.When to use it. When a module has a long dotted name you reference frequently.

import Astra.Net.Http as Http

import type - import a specific type

What it does. Imports a single named type from a module.How it works. Forces the target to be a type, not a module. Prevents ambiguous cases where the final segment could be either.When to use it. When the code only depends on one type from a large module, or when disambiguating module/type names.

import type Astra.Data.Database

.ak source file - the Kairo file extension

What it does. Marks a file as Kairo source input to Forge.How it works. Standard packages place source files under src/ and tests under tests/. Every .ak file must declare a module.When to use it. Every time you create a new Kairo source file.

kairo.toml - the package manifest

What it does. Declares package identity, kind, version, dependencies, and runtime settings.How it works. Sits at the root of a package. Forge reads it to plan builds. It is the single source of truth for package metadata.When to use it. Every package needs one.

[package]
name = "Demo.App"
version = "0.1.0.0"
kind = "application"

[application]
entry = "Demo.App.main"

[runtime]
target = "pulse"

Visibility

public - visible outside the package

What it does. Exposes a declaration as part of the package’s public API.How it works. Public declarations are compiled into the package metadata and can be imported by any consumer.When to use it. For anything you want other packages to use.

public value CustomerId {
    value: Text
}

internal - visible inside the same package (default)

What it does. Restricts a declaration to the same package.How it works. internal is the default when no visibility is written.When to use it. For helpers, drafts, and cross-file collaborators that should not leak out of the package.

internal value CustomerDraft {
    name: Text
    email: Text
}

private - visible to the declaring type or file

What it does. Restricts a declaration to its enclosing type or file.How it works. Scope depends on where private appears. On a member, it is scoped to the type. On a top-level declaration, it is scoped to the file.When to use it. For type-internal helpers you want to hide from the rest of the package.

public object Customer {
    public var name: Text

    private func validateName(name: Text): Bool {
        return name != ""
    }
}

Type Declarations

value - declare a value type

What it does. Declares a value-like type used to model facts: identifiers, amounts, dates, small domain data.How it works. Value members must themselves be value-like. Values are immutable by default and compared structurally.When to use it. When the concept has no identity and does not change over time.

public value Money {
    amount: Decimal
    currency: Text
}

object - declare an identity-bearing object

What it does. Declares an object type used to model participants: entities, workflows, stateful concepts.How it works. Objects have identity and may mutate their var members. Immutable members must be assigned during init and cannot change afterwards.When to use it. When the concept has identity, state, or lifecycle.

public object Customer {
    public id: CustomerId
    public var name: Text

    public init(id: CustomerId, name: Text) {
        this.id = id
        this.name = name
    }
}

contract - declare a capability

What it does. Declares a capability a value or object can promise to provide.How it works. Contracts can require methods and properties. They cannot declare stored fields, init blocks, or method bodies in v0.1.When to use it. When several types need to share a shape without sharing an implementation.

public contract Named {
    name: Text
}

: contract conformance

What it does. Declares that a value or object conforms to one or more contracts.How it works. Forge verifies that all required members are present with matching signatures.When to use it. Whenever a type must satisfy a contract.

public object Customer : Named {
    public id: CustomerId
    public var name: Text

    public init(id: CustomerId, name: Text) {
        this.id = id
        this.name = name
    }
}

enum - declare a closed set of named cases

What it does. Declares a finite set of named cases.How it works. Case names are unique within the enum. In v0.1, enum cases have no payload.When to use it. For status, mode, category, and workflow state.

public enum OrderStatus {
    Draft
    Submitted
    Paid
    Cancelled
}

Members

member field - store data on a value or object

What it does. Declares a stored field on a value or object.How it works. name: Type is immutable. var name: Type is mutable. Value members must be value-like.When to use it. Any time a type needs to remember data.

public object Customer {
    public id: CustomerId
    public var name: Text
}

computed property - derived member with explicit get/set

What it does. Declares a property whose value is computed from other data.How it works. You write an explicit get block, and optionally a set(value: Type) block. There is no shorthand syntax in v0.1.When to use it. For derived views like fullName from firstName and lastName.

public object Customer {
    public var firstName: Text
    public var lastName: Text

    public fullName: Text {
        get {
            return firstName + " " + lastName
        }
    }
}

Callables

func - declare a function

What it does. Declares a callable. At module level it is a free function. Inside a type it is an instance method or contract requirement.How it works. Parameters and return type must be explicit. Omitting : ReturnType means the function returns no value.When to use it. Any time you need reusable behavior.

public func calculateTotal(order: Order): Money {
    return order.total
}

instance method - behavior owned by an instance

What it does. Declares behavior that runs against a specific value or object instance.How it works. Uses the same func keyword, but appears inside a type body. Value methods have an immutable receiver; object methods may mutate var members.When to use it. When the behavior depends on the receiver’s state.

public object Customer {
    public var name: Text

    public func rename(newName: Text) {
        this.name = newName
    }
}

type func - function owned by the type itself

What it does. Declares a function called through the type name, without a this receiver.How it works. Sits inside a value or object body but is invoked as TypeName.function(...). Kairo intentionally does not use static.When to use it. For named factories and type-owned helpers.

public value EmailAddress {
    value: Text

    public type func create(value: Text): EmailAddress {
        return EmailAddress {
            value: value
        }
    }
}

init - construct an object

What it does. Initializes an object instance.How it works. Only allowed inside object. Required immutable members must be assigned before init completes. init cannot return a value. Exactly one primary init per object in v0.1.When to use it. Every object with required members needs one.

public init(id: CustomerId, name: Text) {
    this.id = id
    this.name = name
}

Local Bindings

let - immutable local binding

What it does. Binds a name to a value that cannot be reassigned.How it works. Type can be explicit or inferred from the initializer.When to use it. Default choice for locals. Reach for var only when mutation is genuinely required.

let name: Text = "Pete"
let active = true

var - mutable local or mutable member

What it does. Declares a binding that can be reassigned.How it works. Local var requires an explicit type in v0.1. var on a type member declares a mutable field.When to use it. When the value must change over time.

var count: Int32 = 0
count = count + 1

this - the current instance

What it does. References the current value or object instance from inside an instance method or init.How it works. Only valid inside instance methods and object init. Not available in free functions or type func.When to use it. When you need to disambiguate a member from a parameter, or make the receiver explicit.

public func rename(newName: Text) {
    this.name = newName
}

Control Flow

return - exit the current callable

What it does. Exits the current function or method, optionally with a value.How it works. The returned expression must match the declared return type. Functions with no declared return type must not return a value.When to use it. To produce a result or short-circuit a callable.

public func answer(): Int32 {
    return 42
}

if / else - conditional branching

What it does. Runs one of two branches based on a boolean condition.How it works. The condition must be Bool. Kairo has no truthy or falsy conversions.When to use it. For simple two-way branches.

if customer.name == "" {
    return 1
} else {
    return 0
}

match - pattern-based branching

What it does. Branches on a value against a set of patterns.How it works. Statement matches use block arms. Expression matches use arrow arms and must be exhaustive with else. Supported patterns in v0.1: literals, enum cases, null, type names, and else. Destructuring and guards are deferred.When to use it. When choosing between named domain states, especially enums and nullable outcomes.

let label: Text = match status {
    Draft => "Draft"
    Submitted => "Submitted"
    Paid => "Paid"
    else => "Unknown"
}

for - reserved keyword

What it does. Reserved for future loop semantics.How it works. for is part of the frozen keyword vocabulary, but v0.1 does not yet ratify executable loop semantics.When to use it. Not yet. Model iteration with recursion or upcoming iteration APIs.

while - reserved keyword

What it does. Reserved for future loop semantics.How it works. Same status as for: reserved keyword, deferred executable behavior.When to use it. Not yet.

Async

async func - suspendable function

What it does. Marks a function that may suspend during execution.How it works. Async is visible in the signature. It can appear on module functions, instance methods, type functions, and contract requirements. It is rejected on init and type declarations. The runtime for async execution is deferred to a future Pulse release.When to use it. When the callable performs I/O or other work that may suspend.

public async func fetchCustomer(id: CustomerId): Customer {
    return await CustomerApi.get(id)
}

await - visible suspension point

What it does. Waits for an async callable to complete and produces its result.How it works. Only valid inside async func. await does not unwrap Result<T, E> and does not spawn background work.When to use it. At every call site where you consume an async callable.

let customer = await fetchCustomer(customerId)

Type System

T? - nullable type

What it does. Represents either a value of type T or null.How it works. Only single-level nullables are supported in v0.1 (no T??). A value member typed Customer? is not allowed if Customer is an object.When to use it. When absence is a legitimate state.

public func findCustomer(id: CustomerId): Customer? {
    return null
}

null - the absence value

What it does. Represents absence for nullable types.How it works. Can only be assigned to or matched against a nullable target. Never assignable to a non-nullable type.When to use it. Whenever you need to express “there isn’t one.”

let label: Text = match email {
    null => "No email"
    else => "Has email"
}

true / false - boolean literals

What it does. The two Bool literal values.How it works. Boolean contexts require a Bool. Kairo does not convert other types to boolean automatically.When to use it. Wherever you need a literal truth value.

let active: Bool = true

Text literal - core textual type

What it does. Creates a Text value.How it works. Delimited by double quotes. Kairo uses Text instead of String for the core textual type.When to use it. For any inline string.

let message: Text = "Customer updated"

numeric literal - integer and decimal literals

What it does. Represents numeric values.How it works. Integer literals default to Int64. Fractional literals default to Decimal. Float64 requires explicit typing or conversion. Overflow at compile time is a compile error.When to use it. Any inline number. Prefer Decimal for money and business math.

let count: Int64 = 100
let price: Decimal = 125.50

Operators

boolean operators - not, and, or

What it does. Negates and combines boolean values.How it works. Operands must be Bool. Kairo uses word operators instead of symbols to keep boolean logic readable.When to use it. In any boolean expression.

if not isValid or hasExpired {
    return false
}

equality operators - == and !=

What it does. Compares two values for equality or inequality.How it works. Operands must be compatible types. Custom equality rules are not part of the v0.1 executable subset.When to use it. Wherever you check whether two values are the same.

if status == Paid {
    return true
}

comparison operators - <, <=, >, >=

What it does. Compares ordered values.How it works. Operands must be comparable types. No broad numeric promotion in v0.1.When to use it. For threshold checks and ordering.

if total > 0 {
    return true
}

arithmetic operators - +, -, *, /

What it does. Performs basic arithmetic. + also concatenates Text.How it works. Operands must be compatible numeric types. Kairo does not silently promote across numeric families.When to use it. Any numeric computation.

let subtotal: Decimal = 100.00
let tax: Decimal = 10.00
let total: Decimal = subtotal + tax

= - assignment

What it does. Assigns a value to a mutable target.How it works. Target must be a var local or a var member. Immutable let bindings and immutable members cannot be reassigned.When to use it. Every time you update a mutable binding.

var count: Int32 = 0
count = count + 1

Construction

value construction - TypeName { field: value }

What it does. Constructs a value using a field-initialization block.How it works. All required fields must be supplied exactly once. Values are assembled from their fields, not built through a constructor.When to use it. Anywhere you produce a value.

let total = Money {
    amount: 125.50
    currency: "AUD"
}

object construction - TypeName(arg: value)

What it does. Constructs an object by calling its init with named arguments.How it works. Arguments are named in v0.1. There is no hidden default constructor.When to use it. Anywhere you produce a new object.

let customer = Customer(
    id: customerId,
    name: "Pete"
)

Error Handling

Result<T, E> - explicit outcome type

What it does. Represents either success with a T payload or an expected failure with an E payload.How it works. Part of the Kairo Core prelude. E must be value-like. Unexpected runtime explosions become faults, not Result values.When to use it. Whenever a callable can fail in a way callers should handle.

public func createEmail(value: Text): Result<EmailAddress, EmailFailure> {
    if value == "" {
        return Result.failure(EmailFailure.Empty)
    }

    return Result.success(EmailAddress { value: value })
}

Result.success - construct a successful Result

What it does. Wraps a value as a successful Result<T, E>.How it works. Must be contextually typed as a Result in v0.1.When to use it. On the success path of any function returning Result.

return Result.success(0)

Result.failure - construct a failed Result

What it does. Wraps an error payload as a failed Result<T, E>.How it works. Payload must be value-like. Must be contextually typed as a Result.When to use it. On the failure path of any function returning Result.

return Result.failure(CreateCustomerFailure.InvalidName)

Result inspection - isSuccess, isFailure, value, error

What it does. Inspects a Result without pattern destructuring.How it works. result.isSuccess and result.isFailure return Bool. result.value reads the success payload; result.error reads the failure payload. Reading the wrong one is a runtime fault.When to use it. When acting on the outcome of a Result in v0.1 (destructuring patterns are deferred).

match result.isSuccess {
    true {
        let email = result.value
        Pulse.Console.out.writeLine(email.value)
    }
    false {
        Pulse.Console.error.writeLine("Could not create email")
    }
}

Collections

List<T> - immutable ordered collection

What it does. Represents an ordered, immutable collection of T.How it works. Value-like only when T is value-like. Requires one type argument.When to use it. Ordered sequences of data.

public value CustomerPage {
    ids: List<CustomerId>
}

Set<T> - immutable unique collection

What it does. Represents an unordered, immutable collection of unique T values.How it works. Value-like only when T is value-like.When to use it. Membership tests, tag collections, distinct sets.

public value CustomerTags {
    tags: Set<Text>
}

Map<K, V> - immutable key/value collection

What it does. Represents an immutable mapping from K to V.How it works. Value-like only when both K and V are value-like.When to use it. Lookup tables, dictionaries of facts.

public value ExchangeRates {
    rates: Map<Text, Decimal>
}

Generics

generic type parameter - TypeName<T>

What it does. Parameterizes a type by another type.How it works. Type argument arity must match at every reference site. Generic values cannot store unconstrained generic parameters in v0.1.When to use it. For reusable types and callables that operate over many element types.

public contract Formatter<T> {
    func format(value: T): Text
}

generic contract constraint - T: ContractName

What it does. Restricts a generic parameter to types that satisfy a contract.How it works. Constraint target must resolve to a contract. Multiple constraints and non-contract constraints are deferred.When to use it. When a generic callable needs to invoke members promised by a contract.

public contract Displayable {
    func display(): Text
}

public contract Formatter<T: Displayable> {
    func format(value: T): Text
}

Runtime

application entrypoint - where execution starts

What it does. Defines the function Pulse invokes when the application launches.How it works. The manifest names the entrypoint under [application] entry. The named function must return Int32 or Result<Int32, E>. main is conventional but not required.When to use it. In every application-kind package.

[application]
entry = "Demo.App.main"

module Demo.App

public func main(): Result<Int32, AppFailure> {
    return Result.success(42)
}

Pulse.Console.out.write - write to stdout without a newline

What it does. Writes a value to standard output without appending a newline.How it works. A runtime service call, not a language keyword. Requires import Pulse.Console.When to use it. To emit output in pieces without line breaks.

Pulse.Console.out.write("Hello")

Pulse.Console.out.writeLine - write a line to stdout

What it does. Writes a value to standard output and appends a newline.How it works. Same service surface as write, with a newline at the end.When to use it. For normal line-based output.

Pulse.Console.out.writeLine("Kairo is running")

Pulse.Console.error.write - write to stderr without a newline

What it does. Writes a value to standard error without appending a newline.How it works. Same shape as out.write, but routed to the standard error stream.When to use it. To emit diagnostics or warnings.

Pulse.Console.error.write("Warning")

Pulse.Console.error.writeLine - write a line to stderr

What it does. Writes a value to standard error and appends a newline.How it works. Same shape as out.writeLine, but routed to stderr.When to use it. For error messages that should be readable line-by-line.

Pulse.Console.error.writeLine("Something went wrong")

Deferred for v0.1

These commands and features are intentionally not yet ratified as production-ready:

for and while executable loop semantics
Async runtime execution and task scheduling
Fault catching and recovery syntax
Destructuring match patterns and match guards
Constructor overloading and delegation
Extension methods
Multiple generic constraints
Mutable collection types
Broad numeric promotion rules

Next steps

Command Catalog

Full spec-style reference with opcodes, prerequisites, and changelog notes.

How Kairo works

Guided narrative of the language design and philosophy.

Syntax

Introductory syntax overview with worked examples.

Quickstart

Build and run your first Kairo application.

Get Started

Language

Packages & Modules

Toolchain

Ecosystem

How to use this page

Browsing?

Looking something up?

Learning the language?

Need the deep spec?

Project Structure

Visibility

Type Declarations

Members

Callables

Local Bindings

Control Flow

Async

Type System

Operators

Construction

Error Handling

Collections

Generics

Runtime

Deferred for v0.1

Next steps

Command Catalog

How Kairo works

Syntax

Quickstart

​How to use this page

Browsing?

Looking something up?

Learning the language?

Need the deep spec?

​Project Structure

​Visibility

​Type Declarations

​Members

​Callables

​Local Bindings

​Control Flow

​Async

​Type System

​Operators

​Construction

​Error Handling

​Collections

​Generics

​Runtime

​Deferred for v0.1

​Next steps

Command Catalog

How Kairo works

Syntax

Quickstart

How to use this page

Project Structure

Visibility

Type Declarations

Members

Callables

Local Bindings

Control Flow

Async

Type System

Operators

Construction

Error Handling

Collections

Generics

Runtime

Deferred for v0.1

Next steps