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
module — declare the module a file belongs to
module — declare the module a file belongs to
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.import — bring a module into scope
import — bring a module into scope
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.import ... as — import a module under a local alias
import ... as — import a module under a local alias
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.import type — import a specific type explicitly
import type — import a specific type explicitly
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
.ak source file
.ak source file
*.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.kairo.toml — the package manifest
kairo.toml — the package manifest
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
public — visible outside the package
public — visible outside the package
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.internal — visible inside the same package
internal — visible inside the same package
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.private — visible only to the declaring type or file
private — visible only to the declaring type or file
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
value — declare a value type
value — declare a value type
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.object — declare an identity-bearing type
object — declare an identity-bearing type
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.contract — declare a required capability
contract — declare a required capability
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.Contract conformance : — declare that a type satisfies contracts
Contract conformance : — declare that a type satisfies contracts
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.enum — declare a closed set of named cases
enum — declare a closed set of named cases
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
Member field — stored data on a value or object
Member field — stored data on a value or object
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.Computed property — get/set on a synthesized member
Computed property — get/set on a synthesized member
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
func — declare a function or method
func — declare a function or method
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.Instance method — behavior owned by a type instance
Instance method — behavior owned by a type instance
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.type func — declare a type-owned function
type func — declare a type-owned function
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.init — initialize an object
init — initialize an object
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
let — declare an immutable local binding
let — declare an immutable local binding
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.var — declare a mutable binding or member
var — declare a mutable binding or member
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.this — the current instance receiver
this — the current instance receiver
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
return — exit the current callable
return — exit the current callable
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.if / else — branch on a boolean condition
if / else — branch on a boolean condition
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.match — branch on patterns
match — branch on patterns
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.for — reserved keyword (deferred)
for — reserved keyword (deferred)
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.while — reserved keyword (deferred)
while — reserved keyword (deferred)
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
async func — declare a suspendable callable
async func — declare a suspendable callable
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.await — mark the suspension point
await — mark the suspension point
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
Nullable type T? — an optional form of a type
Nullable type T? — an optional form of a type
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.null — absence for a nullable target
null — absence for a nullable target
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.true / false — boolean literals
true / false — boolean literals
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.Text literal — a string of characters
Text literal — a string of characters
"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.Numeric literal — integer and fractional numbers
Numeric literal — integer and fractional numbers
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
Boolean operators — not, and, or
Boolean operators — not, and, or
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.Equality operators — == and !=
Equality operators — == and !=
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.Comparison operators — <, <=, >, >=
Comparison operators — <, <=, >, >=
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.Arithmetic operators — +, -, *, /
Arithmetic operators — +, -, *, /
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.Assignment = — write to a mutable target
Assignment = — write to a mutable target
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
Value construction — TypeName { field: value }
Value construction — TypeName { field: value }
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.Object construction — TypeName(argument: value)
Object construction — TypeName(argument: value)
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
Result<T, E> — explicit success or expected failure
Result<T, E> — explicit success or expected failure
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.Result.success — construct a successful Result
Result.success — construct a successful Result
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.Result.failure — construct a failed Result
Result.failure — construct a failed Result
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.Result inspection — isSuccess, isFailure, value, error
Result inspection — isSuccess, isFailure, value, error
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
List<T> — immutable ordered collection
List<T> — immutable ordered collection
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.Set<T> — immutable unique collection
Set<T> — immutable unique collection
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.Map<K, V> — immutable key/value collection
Map<K, V> — immutable key/value collection
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
Generic type parameter — TypeName<T>
Generic type parameter — TypeName<T>
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.Generic contract constraint — T: ContractName
Generic contract constraint — T: ContractName
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
Application entrypoint — where the app starts
Application entrypoint — where the app starts
[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.Pulse.Console.out.write — write to stdout
Pulse.Console.out.write — write to stdout
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.Pulse.Console.out.writeLine — write a line to stdout
Pulse.Console.out.writeLine — write a line to stdout
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.Pulse.Console.error.write — write to stderr
Pulse.Console.error.write — write to stderr
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.Pulse.Console.error.writeLine — write a line to stderr
Pulse.Console.error.writeLine — write a line to stderr
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
forandwhile - 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 entrypointTypes
value, object, enumBehavior
func, init, let, varControl flow
if / else, match, Result<T, E>Related
Language syntax
Type system
Error handling
Result<T, E>, expected failures, and faults.Pulse console
Pulse.Console runtime service.