Skip to main content
This page is the practical, developer-focused reference for every command, keyword, and construct in Kairo v0.1. Each entry explains what the construct does, how it works, its exact syntax, what you need to have in place, and a runnable example. Use it as a scannable lookup while writing code.
Kairo is pre-production. Constructs marked Version Added: 0.1.0.0 belong to the planned v0.1 baseline. Some are reserved for future work and are called out explicitly.
How to read an entry. Every command lists its category, syntax, whether it introduces shared mutable runtime behavior (Thread-Safe), what it depends on, and a short worked example. Command Number / OpCode values are internal documentation references only, not bytecode or ABI commitments.

Index

Project Structure

Syntax: module PascalCase.DotSeparated.NameWhat it does. Declares the logical module a Kairo source file belongs to. The module declaration is authoritative. File paths should align with module names, but paths do not define language meaning.How it works. Each .ak file has exactly one module declaration and it must appear before any imports or declarations. Module names use PascalCase dot-separated segments such as Astra.Customers.Models.Prerequisites. Must be the first non-comment line in the file. Forge validates the declaration.Thread-safe: Yes.
Treat the module declaration as the source of truth. Studio and Forge may warn when paths look messy, but they never guess a module from folder layout.
Syntax: import Module.NameWhat it does. Makes another module’s public surface available to the current file.How it works. import Astra.UIX imports the module Astra.UIX. Kairo intentionally has no wildcard imports and does not guess whether the final segment is a type. Imports must appear after module and before declarations.Prerequisites. The referenced module must resolve through Forge dependency metadata.Thread-safe: Yes.
Syntax: import Module.Name as AliasWhat it does. Imports a module and gives it a local alias for readability. The alias is a naming convenience, not a new module identity.How it works. The alias must be unique inside the file’s import scope. All references in the file then use the alias.Thread-safe: Yes.
Syntax: import type Module.TypeNameWhat it does. Imports one specific type from a module, disambiguating between module names and type names.How it works. Use import type when the code depends on a single type rather than the whole module. Forge validates that the target resolves to a type when metadata is available.Thread-safe: Yes.

File Structure & Manifest

Syntax: *.akWhat it does. Kairo source files use the .ak extension. They are the input Forge compiles.How it works. Standard packages place source under src/ and tests under tests/. Every .ak file must belong to a package with a kairo.toml.Thread-safe: Yes.
Syntax: kairo.toml at the package root.What it does. Declares package identity, kind, version, dependencies, and runtime settings. It is the manifest truth for package-level metadata.How it works. Forge reads kairo.toml to produce the build plan, lock file, and artifacts. Dependency source selection lives in external Forge configuration, not the ordinary manifest.Thread-safe: Yes.

Visibility

Syntax: public declarationWhat it does. Marks a declaration as part of the package’s public API.How it works. Public API must be explicit in Kairo. Anything not marked public (or private) defaults to internal.Thread-safe: Yes.
Syntax: internal declarationWhat it does. Restricts a declaration to the current package. This is the default visibility.How it works. Other packages cannot see internal declarations even after importing the module.Thread-safe: Yes.
Syntax: private declarationWhat it does. Restricts a declaration to its declaring type or file scope, depending on where it appears.How it works. Inside a type, private restricts to that type. At file scope, it restricts to the file. protected, friend, sealed, abstract, and partial are deferred from v0.1.Thread-safe: Yes.

Type Declarations

Syntax: value Name { member: Type }What it does. Declares a value type. Values model facts (identifiers, measurements, dates, amounts, small domain facts) and are immutable by default.How it works. Value members may only store value-like types in v0.1. Values are compared by content, not identity.Thread-safe: Yes.
Use value when identity and mutation are not part of the concept. If the thing participates in workflows and changes over time, model it as an object.
Syntax: object Name { members init(...) { ... } }What it does. Declares an object type. Objects model participants, entities, workflows, and stateful concepts.How it works. Required immutable members must be assigned during init. Object methods can mutate var members. Object methods are not thread-safe when mutating state.Thread-safe: No.
Syntax: contract Name { requirements }What it does. Declares a capability that a value or object can promise to provide.How it works. Contracts may require methods, read-only properties, and read-write properties. They cannot declare stored fields, init blocks, type functions, or method bodies in v0.1.Thread-safe: Yes.
Contracts describe what a type provides, not how it stores or implements it.
Syntax: object Name : ContractA, ContractB { ... }What it does. Declares that a value or object explicitly conforms to one or more contracts.How it works. Forge verifies that required properties and methods are present. Enum conformance, default implementations, and generic contract conformance are deferred.Thread-safe: Yes.
Syntax: enum Name { CaseA CaseB }What it does. Declares a finite set of named values. Enums are useful for status, category, mode, and workflow state.How it works. Case names must be unique. Enums are typically used with match for exhaustive branching.Thread-safe: Yes.

Members

Syntax: name: Type or var name: TypeWhat it does. Declares data stored on a value or object.How it works. Members are immutable by default. Use var only when the member must be mutable. Value members must be value-like.Thread-safe: Immutable member name: Type is thread-safe. var name: Type is not.
Syntax: name: Type { get { ... } set(value: Type) { ... } }What it does. Declares an explicit computed property. Kairo does not hide getter/setter generation behind shorthand.How it works. get returns the property value; set receives an input matching the property type. Read-only properties omit set.Thread-safe: No.

Callables

Syntax: func name(parameter: Type): ReturnType { ... }What it does. Declares a function. At module level it is a free function. Inside a value, object, or contract, it is an instance method or requirement.How it works. Parameter and return types must resolve. Omitting the return type means the function returns no value.Thread-safe: Yes for the declaration itself.
Syntax: func methodName(parameter: Type): ReturnType { ... } declared inside a type.What it does. Declares behavior owned by an instance of a value, object, or contract.How it works. Value methods receive an immutable value receiver. Object methods receive an identity-bearing receiver and may mutate var members.Thread-safe: Value methods yes; object methods no when mutating state.
Syntax: type func name(parameter: Type): ReturnType { ... }What it does. Declares a function owned by the type rather than an instance. There is no this receiver, and it is called through the type name.How it works. type func must be declared inside a value or object. It is Kairo’s replacement for static in v0.1.Thread-safe: Yes.
Use type func for named factories and type-owned helpers.
Syntax: init(parameter: Type) { ... }What it does. Initializes an object. Required immutable members must be assigned before init completes.How it works. Only allowed inside object. Exactly one primary init is allowed in v0.1. init cannot return a value. Constructor overloading, delegation, and lifecycle hooks are deferred.Thread-safe: No.

Bindings & Receiver

Syntax: let name: Type = expressionWhat it does. Declares an immutable local binding.How it works. Kairo supports local let inference when the initializer type is obvious. Once bound, a let cannot be reassigned.Thread-safe: Yes.
Syntax: var name: Type = expressionWhat it does. Declares a mutable local binding or mutable member.How it works. Mutability is explicit in Kairo. Local var requires an explicit type in v0.1.Thread-safe: No.
Syntax: this.memberWhat it does. References the current value or object instance.How it works. Available only inside instance methods and object init. Not available in free functions or type func.Thread-safe: No.

Control Flow

Syntax: return expression or returnWhat it does. Exits the current function or method, optionally with a value.How it works. The returned expression must be assignment-compatible with the declared return type. Functions with no declared return type must not return a value.Thread-safe: Yes.
Syntax: if condition { ... } else { ... }What it does. Executes a branch based on a boolean condition.How it works. Kairo has no truthy or falsy conversions. The condition must be Bool.Thread-safe: Yes.
Syntax: match expression { Pattern => value else => fallback }What it does. Branches based on patterns. Supports both statement and expression form.How it works. Statement matches use block arms. Expression matches use arrow arms and must be exhaustive with else in v0.1. Supported patterns are literals, enum cases, null, type names, and else. Destructuring and guards are deferred.Thread-safe: Yes.
Use match when the code is choosing between named domain states, especially enums and nullable outcomes.
Status: Reserved in 0.1.0.0; executable semantics deferred.What it does. for is part of the frozen keyword vocabulary, but v0.1 loop semantics are not ratified. It should not be used as executable syntax yet.
Status: Reserved in 0.1.0.0; executable semantics deferred.What it does. while is reserved, but production loop semantics are not yet part of the v0.1 executable subset.

Async

Syntax: async func name(...): ReturnType { ... }What it does. Marks a function or method that may suspend. Kairo requires suspension capability to be visible in the signature.How it works. async may appear on module functions, instance methods, type functions, and contract method requirements. It is rejected on init and type declarations. The language shape is stable in v0.1; the async runtime is deferred.Thread-safe: Yes.
Syntax: await asyncCall(...)What it does. Marks the visible suspension point at the call site.How it works. Only valid inside async func. await waits for async work; it does not unwrap Result<T, E> and does not create hidden background execution.Thread-safe: Yes.

Type System & Literals

Syntax: Type?What it does. Represents either a value of type T or null.How it works. Only single-level nullability is supported in v0.1; nested forms like T?? are not allowed. Inside a value, CustomerId? is allowed when CustomerId is value-like. Customer? is not allowed as a stored value member when Customer is an object.Thread-safe: Yes.
Syntax: nullWhat it does. Represents absence for nullable types.How it works. null cannot be assigned to non-nullable types. It is matched against nullable targets with match.Thread-safe: Yes.
Syntax: true, falseWhat it does. The two Bool literals.How it works. Kairo has no truthy or falsy values. Boolean contexts require Bool.Thread-safe: Yes.
Syntax: "text"What it does. Creates a Text value. Kairo uses Text rather than String for the core textual type.How it works. The string must be terminated.Thread-safe: Yes.
Syntax: 123, 123.45What it does. Represents numeric values with business-safe defaults: integer literals default to Int64, fractional literals default to Decimal, and Float64 requires explicit typing or conversion.How it works. Overflow is a compile-time error when the literal does not fit the target type.Thread-safe: Yes.

Operators

Syntax: not expression, left and right, left or rightWhat it does. Performs boolean negation and combination.How it works. Operands must be Bool. Kairo uses readable operator words rather than symbols for boolean logic.Thread-safe: Yes.
Syntax: left == right, left != rightWhat it does. Compares two compatible values for equality or inequality.How it works. Operand types must be compatible. Custom equality rules are not part of the early executable subset.Thread-safe: Yes.
Syntax: left < right, left <= right, left > right, left >= rightWhat it does. Compares ordered values such as numeric values and supported comparable core types.How it works. Operands must be compatible. Kairo does not perform broad implicit numeric conversions.Thread-safe: Yes.
Syntax: left + right, left - right, left * right, left / rightWhat it does. Performs basic arithmetic for compatible numeric types. + also supports Text concatenation.How it works. No silent promotion across broad numeric families. Both operands must share a compatible type.Thread-safe: Yes.
Syntax: target = expressionWhat it does. Assigns a value to a mutable local or mutable member.How it works. The target must be mutable and the expression must be assignment-compatible. Immutable let bindings and immutable members cannot be reassigned outside valid construction rules.Thread-safe: No.

Construction

Syntax: TypeName { field: value }What it does. Constructs a value using a field initialization block. Values are assembled from explicit field values.How it works. All required fields must be supplied exactly once.Thread-safe: Yes.
Syntax: TypeName(argument: value)What it does. Constructs an object through its explicit init signature.How it works. Object construction requires named arguments in v0.1. There is no hidden default constructor for objects with required members.Thread-safe: No.

Error Handling

Syntax: Result<SuccessType, FailureType>What it does. Represents an explicit expected outcome: either success with a T value or failure with an E value.How it works. Result<T, E> is part of the Kairo Core prelude and requires no import. The failure type E must be value-like. Unexpected runtime explosions are faults, not Result values.Thread-safe: Yes.
Syntax: Result.success(value: T): Result<T, E>What it does. Creates a successful Result value.How it works. The payload must be assignment-compatible with the expected success type. Must be contextually typed as Result<T, E> in v0.1.Thread-safe: Yes.
Syntax: Result.failure(error: E): Result<T, E>What it does. Creates a failed Result value for an expected business failure.How it works. The failure payload must be value-like. Must be contextually typed as Result<T, E> in v0.1.Thread-safe: Yes.
Syntax: result.isSuccess, result.isFailure, result.value, result.errorWhat it does. Inspects a Result without relying on destructuring patterns.How it works. Accessing value on a failed result or error on a successful result is a runtime fault. Guard access with isSuccess first.Thread-safe: Yes.

Collections

Syntax: List<ElementType>What it does. Represents an immutable ordered collection of T.How it works. A List<T> is value-like only when T is value-like. Immutable collections are the default collection model in v0.1.Thread-safe: Yes.
Syntax: Set<ElementType>What it does. Represents an immutable collection of unique values of T.How it works. A Set<T> is value-like only when T is value-like.Thread-safe: Yes.
Syntax: Map<KeyType, ValueType>What it does. Represents an immutable map from keys to values.How it works. A Map<K, V> is value-like only when both K and V are value-like. Map<CustomerId, Customer> is not value-like when Customer is an object.Thread-safe: Yes.

Generics

Syntax: TypeName<T>What it does. Defines or references a type parameterized by another type.How it works. Type argument arity must match the declaration. Generic values may not store unconstrained generic parameters in value members in v0.1 unless a future value-like constraint is ratified.Thread-safe: Yes.
Syntax: T: ContractNameWhat it does. Constrains a generic parameter to types that satisfy a contract.How it works. The constraint target must resolve to a contract. Multiple constraints and non-contract constraints are deferred.Thread-safe: Yes.

Runtime

Syntax: [application] entry = "Module.function" in kairo.toml, plus the matching module-level function.What it does. Defines where a Kairo application starts.How it works. The entrypoint is determined by manifest configuration, not filename guessing. main is the recommended convention, but not a hidden requirement. Supported v0.1 entry returns are Int32 and Result<Int32, E>.Thread-safe: No.
Syntax: Pulse.Console.out.write(value)What it does. Writes text to standard output without appending a newline.How it works. This is a runtime service call, not a language keyword and not an ambient global. Import Pulse.Console to use it. Requires an application targeting Pulse or a backend that supports the Pulse console surface.Thread-safe: No.
Syntax: Pulse.Console.out.writeLine(value)What it does. Writes a value to standard output and appends a newline.How it works. Referenced through the explicit Pulse.Console runtime service. Import Pulse.Console to use it.Thread-safe: No.
Syntax: Pulse.Console.error.write(value)What it does. Writes a value to standard error without appending a newline.How it works. Keeps stdout and stderr routing explicit. Import Pulse.Console to use it.Thread-safe: No.
Syntax: Pulse.Console.error.writeLine(value)What it does. Writes a value to standard error and appends a newline.How it works. Part of the Pulse runtime MVP console surface. Import Pulse.Console to use it.Thread-safe: No.

Deferred Language Areas

The following language areas are intentionally not documented as production-ready commands yet:
  • Destructuring match patterns
  • Match guards
  • Full enum exhaustiveness enforcement
  • Full loop semantics for for and while
  • Async runtime execution and task scheduling
  • Fire-and-forget background work
  • Fault catching and recovery syntax
  • Constructor overloading and delegation
  • Extension methods
  • Overload resolution
  • Generic function inference
  • Multiple generic constraints
  • Value-like generic constraints such as T: value
  • Mutable collection model
  • Broad numeric promotion rules
  • Full dependency registry protocol
  • Studio IntelliSense and language-server behavior

Sandbox Subset

For the first public sandbox, prefer examples that stay inside the supported executable MVP subset:

Structure

module, import Pulse.Console, application entrypoint

Types

value, object, enum

Behavior

func, init, let, var

Control flow

if / else, match, Result<T, E>
Avoid sandbox examples that rely on deferred features such as loops, async execution, destructuring match patterns, or dependency registry restore.

Language syntax

The full syntax overview: files, modules, declarations, and control flow.

Type system

Values, objects, contracts, generics, and nullable types.

Error handling

Result<T, E>, expected failures, and faults.

Pulse console

Full reference for the Pulse.Console runtime service.