> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Kairo Command Catalog: Every Language Construct Explained

> A developer-facing catalog of every Kairo v0.1 language construct: what each command does, how it works, its syntax, prerequisites, and a runnable example.

This catalog is a single-page reference for every command, keyword, and core-library construct in the Kairo v0.1 language surface. Each entry answers the same questions: **what does this do**, **how does it work**, **what syntax does it use**, and **what does a real example look like**.

Use it as a learning tool when you are new to Kairo, and as a lookup table when you already know what you need but want the exact rules.

<Info>
  `Command Number / OpCode` values are internal documentation references, not final bytecode or VM instruction IDs. `Version Added: 0.1.0.0` means the construct belongs to the planned production-ready v0.1 baseline unless the entry explicitly says it is reserved or deferred.
</Info>

<Tip>
  **Thread-Safe** describes whether the construct itself introduces shared mutable runtime behavior. Actual program safety still depends on the values, objects, and runtime services you build on top of it.
</Tip>

## Index

| Command                         | Category                 | OpCode   |
| ------------------------------- | ------------------------ | -------- |
| `module`                        | Project Structure        | `0x0101` |
| `import`                        | Project Structure        | `0x0102` |
| `import ... as`                 | Project Structure        | `0x0103` |
| `import type`                   | Project Structure        | `0x0104` |
| `.ak` source file               | File Structure           | `0x0105` |
| `kairo.toml`                    | Package Manifest         | `0x0106` |
| `public`                        | Visibility               | `0x0201` |
| `internal`                      | Visibility               | `0x0202` |
| `private`                       | Visibility               | `0x0203` |
| `value`                         | Type Declaration         | `0x0301` |
| `object`                        | Type Declaration         | `0x0302` |
| `contract`                      | Type Declaration         | `0x0303` |
| Contract conformance `:`        | Type Declaration         | `0x0304` |
| `enum`                          | Type Declaration         | `0x0305` |
| Member field                    | Members                  | `0x0401` |
| Computed property               | Members                  | `0x0402` |
| `func`                          | Callable                 | `0x0501` |
| Instance method                 | Callable                 | `0x0502` |
| `type func`                     | Callable                 | `0x0503` |
| `init`                          | Construction             | `0x0504` |
| `let`                           | Local Binding            | `0x0601` |
| `var`                           | Local Binding / Mutation | `0x0602` |
| `this`                          | Receiver                 | `0x0603` |
| `return`                        | Control Flow             | `0x0701` |
| `if / else`                     | Control Flow             | `0x0702` |
| `match`                         | Control Flow             | `0x0703` |
| `for`                           | Control Flow             | `0x0704` |
| `while`                         | Control Flow             | `0x0705` |
| `async func`                    | Async                    | `0x0801` |
| `await`                         | Async                    | `0x0802` |
| Nullable type `T?`              | Type System              | `0x0901` |
| `null`                          | Literal                  | `0x0902` |
| `true / false`                  | Literal                  | `0x0903` |
| `Text` literal                  | Literal / Core Type      | `0x0904` |
| Numeric literal                 | Literal / Core Type      | `0x0905` |
| Boolean operators               | Operators                | `0x0A01` |
| Equality operators              | Operators                | `0x0A02` |
| Comparison operators            | Operators                | `0x0A03` |
| Arithmetic operators            | Operators                | `0x0A04` |
| Assignment `=`                  | Operators                | `0x0A05` |
| Value construction              | Construction             | `0x0B01` |
| Object construction             | Construction             | `0x0B02` |
| `Result<T, E>`                  | Error Handling           | `0x0C01` |
| `Result.success`                | Error Handling           | `0x0C02` |
| `Result.failure`                | Error Handling           | `0x0C03` |
| Result inspection               | Error Handling           | `0x0C04` |
| `List<T>`                       | Collections              | `0x0D01` |
| `Set<T>`                        | Collections              | `0x0D02` |
| `Map<K, V>`                     | Collections              | `0x0D03` |
| Generic type parameter          | Generics                 | `0x0E01` |
| Generic contract constraint     | Generics                 | `0x0E02` |
| Application entrypoint          | Runtime                  | `0x0F01` |
| `Pulse.Console.out.write`       | Runtime Service          | `0x0F02` |
| `Pulse.Console.out.writeLine`   | Runtime Service          | `0x0F03` |
| `Pulse.Console.error.write`     | Runtime Service          | `0x0F04` |
| `Pulse.Console.error.writeLine` | Runtime Service          | `0x0F05` |

## Project Structure

### `module`

**Category:** Project Structure · **OpCode:** `KAIRO-0101 / 0x0101` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `module PascalCase.DotSeparated.Name`

**What it does.** Declares the logical module that 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.** Kairo allows one module declaration per source file, and it must appear before imports and declarations. Module names use PascalCase dot-separated segments such as `Astra.Customers.Models`. Forge validates the declaration but does not infer it from folder layout.

<Tip>
  Treat the module declaration as the source of truth. Studio and Forge may warn when paths are messy, but they will not guess a module from the folder layout.
</Tip>

```kairo theme={null}
module Sales.Orders
```

### `import`

**Category:** Project Structure · **OpCode:** `KAIRO-0102 / 0x0102` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `import Module.Name`

**What it does.** Imports a module into the current file so its public declarations become available by name.

**How it works.** `import` must appear after `module` and before other declarations. Kairo intentionally avoids wildcard imports and does not guess whether the final segment is a type. Writing `import Astra.UIX` always means "import a module named `Astra.UIX`." To bring a specific type into scope, use `import type` instead.

```kairo theme={null}
module Demo.App

import Astra.Data
import Pulse.Console
```

### `import ... as`

**Category:** Project Structure · **OpCode:** `KAIRO-0103 / 0x0103` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `import Module.Name as Alias`

**What it does.** Imports a module under a local alias for readability.

**How it works.** The alias is scoped to the current file and must be unique among that file's imports. The alias is a readability tool only, not a new module identity.

**Parameter:** `Alias` (identifier, required) is the local name used to reference the imported module.

```kairo theme={null}
module Demo.App

import Astra.Net.Http as Http
```

### `import type`

**Category:** Project Structure · **OpCode:** `KAIRO-0104 / 0x0104` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `import type Module.TypeName`

**What it does.** Imports a single specific type from a module.

**How it works.** `import type` disambiguates cases where the reader (or Forge) might otherwise wonder whether a dotted name refers to a module or a type. If the target metadata is available, Forge validates that the final segment resolves to a type.

<Tip>
  Reach for `import type` whenever the code depends on a specific type rather than the whole module.
</Tip>

```kairo theme={null}
module Demo.App

import type Astra.Data.Database
```

## File Structure and Manifest

### `.ak` source file

**Category:** File Structure · **OpCode:** `KAIRO-0105 / 0x0105` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `*.ak`

**What it does.** Defines the file extension for Kairo source code. Every Kairo file that Forge compiles ends in `.ak`.

**How it works.** A source file must belong to a package that has a `kairo.toml` manifest. Standard packages place source files under `src/` and tests under `tests/`. Forge produces build artifacts from the `.ak` inputs when the package is compiled.

```kairo theme={null}
module Demo.App

public func main(): Int32 {
    return 0
}
```

### `kairo.toml`

**Category:** Package Manifest · **OpCode:** `KAIRO-0106 / 0x0106` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `kairo.toml` package manifest at package root

**What it does.** Declares package identity, package kind, version, dependencies, and application/runtime settings. It is the manifest truth for package-level metadata.

**How it works.** Forge reads `kairo.toml` to build the package graph, resolve dependencies, and locate the application entrypoint when the package is an application. TOML was chosen because it is readable, stable, and diff-friendly under version control.

<Tip>
  `[publish].registry` is a logical publish target only. Dependency source selection belongs to external Forge configuration, not the ordinary manifest.
</Tip>

```toml theme={null}
[package]
name = "Demo.App"
version = "0.1.0.0"
kind = "application"

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

[runtime]
target = "pulse"
```

## Visibility

### `public`

**Category:** Visibility · **OpCode:** `KAIRO-0201 / 0x0201` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `public declaration`

**What it does.** Marks a declaration as visible outside the package boundary. Public API in Kairo is always explicit.

**How it works.** `public` may be applied to declarations and members wherever visibility is allowed. Public items become part of the package's exported metadata.

```kairo theme={null}
public value CustomerId {
    value: Text
}
```

### `internal`

**Category:** Visibility · **OpCode:** `KAIRO-0202 / 0x0202` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `internal declaration`

**What it does.** Marks a declaration as visible inside the same package.

**How it works.** `internal` is the default visibility for declarations that do not explicitly state otherwise. The package is the visibility boundary.

```kairo theme={null}
internal value CustomerDraft {
    name: Text
    email: Text
}
```

### `private`

**Category:** Visibility · **OpCode:** `KAIRO-0203 / 0x0203` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `private declaration`

**What it does.** Restricts a declaration to its declaring type or file scope.

**How it works.** Whether `private` means "type-local" or "file-local" depends on where it appears. `protected`, `friend`, `sealed`, `abstract`, and `partial` were deliberately deferred from v0.1 to keep the visibility model small.

```kairo theme={null}
public object Customer {
    public var name: Text

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

## Type Declarations

### `value`

**Category:** Type Declaration · **OpCode:** `KAIRO-0301 / 0x0301` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `value Name { member: Type }`

**What it does.** Declares a value type. Values model facts: identifiers, measurements, dates, amounts, small domain facts.

**How it works.** Value members are immutable by default and may only store value-like types in v0.1. Comparison is by content, not identity.

<Tip>
  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` instead.
</Tip>

```kairo theme={null}
public value Money {
    amount: Decimal
    currency: Text
}
```

### `object`

**Category:** Type Declaration · **OpCode:** `KAIRO-0302 / 0x0302` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**Syntax:** `object Name { members init(...) { ... } }`

**What it does.** Declares an identity-bearing object type used for participants, entities, and stateful workflows.

**How it works.** Required immutable members must be assigned during construction. Object methods can mutate `var` members; immutable members cannot change after construction. Kairo uses `object` rather than `class` to align with the language constitution.

```kairo theme={null}
public object Customer {
    public id: CustomerId
    public var name: Text

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

### `contract`

**Category:** Type Declaration · **OpCode:** `KAIRO-0303 / 0x0303` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `contract Name { requirements }`

**What it does.** Declares a capability contract: a promise that a value or object provides certain methods and properties.

**How it works.** Contracts may require methods, read-only properties, and read-write properties. They cannot declare stored fields, `init` blocks, `type func` members, or method bodies in v0.1. Kairo uses `contract` instead of `interface` to stay business-domain friendly.

```kairo theme={null}
public contract Named {
    name: Text
}
```

### Contract conformance `:`

**Category:** Type Declaration · **OpCode:** `KAIRO-0304 / 0x0304` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**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 all required properties and methods are present on the declaring type. Enum conformance, default implementations, and generic contract conformance are deferred beyond v0.1.

**Parameter:** `ContractA` (contract type, required) is a contract the value or object claims to satisfy. Multiple contracts are comma-separated.

```kairo theme={null}
public contract Named {
    name: Text
}

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

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

### `enum`

**Category:** Type Declaration · **OpCode:** `KAIRO-0305 / 0x0305` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `enum Name { CaseA CaseB }`

**What it does.** Declares a closed, finite set of named cases. Enums are ideal for status, category, mode, and workflow state.

**How it works.** Case names must be unique within the enum. Full exhaustiveness enforcement on `match` is deferred.

```kairo theme={null}
public enum OrderStatus {
    Draft
    Submitted
    Paid
    Cancelled
}
```

## Members

### Member field

**Category:** Members · **OpCode:** `KAIRO-0401 / 0x0401` · **Version Added:** `0.1.0.0` · **Thread-Safe:** `name: Type` yes; `var name: Type` no

**Syntax:** `name: Type` or `var name: Type`

**What it does.** Declares data stored on a `value` or `object`.

**How it works.** Members are immutable by default. Mark a member with `var` only when it must be mutable. Value members must be value-like; object members may reference objects.

```kairo theme={null}
public object Customer {
    public id: CustomerId
    public var name: Text
}
```

### Computed property

**Category:** Members · **OpCode:** `KAIRO-0402 / 0x0402` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**Syntax:** `name: Type { get { ... } set(value: Type) { ... } }`

**What it does.** Declares a computed property backed by explicit `get` and optional `set` blocks.

**How it works.** `get` is required for a readable property; `set` is optional and its parameter type must match the property type. Kairo does not hide getter/setter generation behind shorthand syntax in v0.1.

**Parameter:** `value` (property type, required for `set`) is the input passed to the setter.

```kairo theme={null}
public object Customer {
    public var firstName: Text
    public var lastName: Text

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

## Callables

### `func`

**Category:** Callable · **OpCode:** `KAIRO-0501 / 0x0501` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**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 at compile time. Omitting the return type means the function returns no value.

```kairo theme={null}
public func calculateTotal(order: Order): Money {
    return order.total
}
```

### Instance method

**Category:** Callable · **OpCode:** `KAIRO-0502 / 0x0502` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Value methods yes; object methods no when mutating state

**Syntax:** `func methodName(parameter: Type): ReturnType { ... }` inside a type

**What it does.** Declares behavior owned by a type instance.

**How it works.** Value methods receive an immutable value receiver. Object methods receive an identity-bearing object receiver and may mutate `var` members. Extension methods were deferred from v0.1 to keep ownership clear.

```kairo theme={null}
public object Customer {
    public var name: Text

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

### `type func`

**Category:** Callable · **OpCode:** `KAIRO-0503 / 0x0503` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `type func name(parameter: Type): ReturnType { ... }`

**What it does.** Declares a function owned by a type rather than an instance. Called through the type name.

**How it works.** A `type func` has no `this` receiver and must be declared inside a `value` or `object`. Kairo rejected `static` for v0.1 and chose `type func` for readability.

<Tip>
  Use `type func` for named factories and type-owned helpers.
</Tip>

```kairo theme={null}
public value EmailAddress {
    value: Text

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

### `init`

**Category:** Construction · **OpCode:** `KAIRO-0504 / 0x0504` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**Syntax:** `init(parameter: Type) { ... }`

**What it does.** Initializes an object. `init` cannot return a value.

**How it works.** Required immutable members must be assigned before `init` completes. Only `object` types may declare `init`, and exactly one primary init is allowed in v0.1. Constructor overloading, delegation, and lifecycle hooks are deferred.

```kairo theme={null}
public object Customer {
    public id: CustomerId
    public var name: Text

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

## Local Bindings and Receivers

### `let`

**Category:** Local Binding · **OpCode:** `KAIRO-0601 / 0x0601` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `let name: Type = expression`

**What it does.** Declares an immutable local binding.

**How it works.** Type annotation may be omitted when the initializer type is obvious to the compiler. Once bound, a `let` cannot be reassigned.

```kairo theme={null}
let name: Text = "Pete"
let active = true
```

### `var`

**Category:** Local Binding / Mutation · **OpCode:** `KAIRO-0602 / 0x0602` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**Syntax:** `var name: Type = expression`

**What it does.** Declares a mutable local binding or a mutable member.

**How it works.** Local `var` requires an explicit type in v0.1. Mutability is deliberately visible in Kairo: if the reader sees `var`, they know the binding can change.

```kairo theme={null}
var count: Int32 = 0
count = count + 1
```

### `this`

**Category:** Receiver · **OpCode:** `KAIRO-0603 / 0x0603` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**Syntax:** `this.member`

**What it does.** References the current value or object instance from inside an instance method or `init`.

**How it works.** `this` is not available in free functions or in `type func`. Value receivers are immutable; object receivers are identity-bearing references.

```kairo theme={null}
public func rename(newName: Text) {
    this.name = newName
}
```

## Control Flow

### `return`

**Category:** Control Flow · **OpCode:** `KAIRO-0701 / 0x0701` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `return expression` or `return`

**What it does.** Exits the current function or method, optionally producing 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.

```kairo theme={null}
public func answer(): Int32 {
    return 42
}
```

### `if / else`

**Category:** Control Flow · **OpCode:** `KAIRO-0702 / 0x0702` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `if condition { ... } else { ... }`

**What it does.** Executes one of two branches based on a boolean condition.

**How it works.** The condition must be `Bool`. Kairo has no truthy or falsy conversions, so numeric or string values cannot stand in for a boolean.

```kairo theme={null}
if customer.name == "" {
    return 1
} else {
    return 0
}
```

### `match`

**Category:** Control Flow · **OpCode:** `KAIRO-0703 / 0x0703` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `match expression { Pattern => value else => fallback }`

**What it does.** Branches based on patterns. Statement matches use block arms; expression matches use arrow arms.

**How it works.** Expression matches must be exhaustive with an `else` arm in v0.1. Supported patterns are literals, enum cases, `null`, type names, and `else`. Destructuring and guards are deferred.

<Tip>
  Reach for `match` when the code is choosing between named domain states, especially enums and nullable outcomes.
</Tip>

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

```kairo theme={null}
match status {
    Draft {
        Pulse.Console.out.writeLine("Draft")
    }

    else {
        Pulse.Console.out.writeLine("Other")
    }
}
```

### `for`

**Category:** Control Flow · **OpCode:** `KAIRO-0704 / 0x0704` · **Version Added:** Reserved in `0.1.0.0`; executable semantics deferred · **Thread-Safe:** Yes

**Syntax:** Reserved keyword.

**What it does.** Reserves the `for` keyword for a future ratified loop construct.

**How it works.** `for` is part of Kairo's frozen keyword vocabulary, but its detailed loop semantics have not yet been ratified. Do not treat it as production-ready executable syntax in the current MVP.

```kairo theme={null}
// for loop syntax is reserved for a later ratified stage.
```

### `while`

**Category:** Control Flow · **OpCode:** `KAIRO-0705 / 0x0705` · **Version Added:** Reserved in `0.1.0.0`; executable semantics deferred · **Thread-Safe:** Yes

**Syntax:** Reserved keyword.

**What it does.** Reserves the `while` keyword alongside `for` for future loop semantics.

**How it works.** `while` is a reserved word today, but v0.1 production loop semantics are not yet ratified in this catalog.

```kairo theme={null}
// while loop syntax is reserved for a later ratified stage.
```

## Async

### `async func`

**Category:** Async · **OpCode:** `KAIRO-0801 / 0x0801` · **Version Added:** `0.1.0.0` language shape; async runtime deferred · **Thread-Safe:** Yes

**Syntax:** `async func name(...): ReturnType { ... }`

**What it does.** Marks a function or method that may suspend during execution.

**How it works.** Suspension capability is always visible in the signature. `async` may appear on module functions, instance methods, type functions, and contract method requirements. It is rejected on `init` and on type declarations themselves.

```kairo theme={null}
public async func fetchCustomer(id: CustomerId): Customer {
    return await CustomerApi.get(id)
}
```

### `await`

**Category:** Async · **OpCode:** `KAIRO-0802 / 0x0802` · **Version Added:** `0.1.0.0` language shape; async runtime deferred · **Thread-Safe:** Yes

**Syntax:** `await asyncCall(...)`

**What it does.** Marks a visible suspension point at the call site.

**How it works.** `await` is only valid inside an `async func`. It waits for the awaited async work to complete. It does not unwrap `Result<T, E>` and it does not create hidden background execution. Task spawning, cancellation, and fire-and-forget behavior are deferred.

```kairo theme={null}
let customer = await fetchCustomer(customerId)
```

## Type System and Literals

### Nullable type `T?`

**Category:** Type System · **OpCode:** `KAIRO-0901 / 0x0901` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `Type?`

**What it does.** Represents either a value of type `T` or `null`.

**How it works.** Kairo supports single-level nullability only; `T??` is not part of v0.1. Inside a `value`, `CustomerId?` is allowed when `CustomerId` is value-like, but `Customer?` is not allowed as a stored value member if `Customer` is an object.

```kairo theme={null}
public func findCustomer(id: CustomerId): Customer? {
    return null
}
```

### `null`

**Category:** Literal · **OpCode:** `KAIRO-0902 / 0x0902` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `null`

**What it does.** Represents absence for a nullable type.

**How it works.** `null` may only be assigned to or matched against a nullable target. Kairo does not allow assigning `null` to a non-nullable type.

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

### `true` / `false`

**Category:** Literal · **OpCode:** `KAIRO-0903 / 0x0903` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `true` or `false`

**What it does.** Boolean literals producing a `Bool` value.

**How it works.** Kairo has no truthy or falsy values; boolean contexts require `Bool`.

```kairo theme={null}
let active: Bool = true
```

### `Text` literal

**Category:** Literal / Core Type · **OpCode:** `KAIRO-0904 / 0x0904` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `"text"`

**What it does.** Creates a `Text` value.

**How it works.** Kairo uses `Text` rather than `String` for the core textual type. Strings must be terminated on the same line.

```kairo theme={null}
let message: Text = "Customer updated"
```

### Numeric literal

**Category:** Literal / Core Type · **OpCode:** `KAIRO-0905 / 0x0905` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `123`, `123.45`

**What it does.** Represents numeric values in source code.

**How it works.** Kairo picks business-safe numeric defaults: integer literals default to `Int64`, fractional literals default to `Decimal`, and `Float64` requires explicit contextual typing or conversion. Overflow is a compile-time error when a literal cannot fit its target type.

```kairo theme={null}
let count: Int64 = 100
let price: Decimal = 125.50
```

## Operators

### Boolean operators

**Category:** Operators · **OpCode:** `KAIRO-0A01 / 0x0A01` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `not expression`, `left and right`, `left or right`

**What it does.** Performs boolean negation and combination, producing a `Bool`.

**How it works.** Operands must already be `Bool`. Kairo uses the readable operator words `not`, `and`, and `or` instead of symbolic operators.

```kairo theme={null}
if not isValid or hasExpired {
    return false
}
```

### Equality operators

**Category:** Operators · **OpCode:** `KAIRO-0A02 / 0x0A02` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `left == right`, `left != right`

**What it does.** Compares two compatible values for equality or inequality, producing a `Bool`.

**How it works.** Operands must be compatible types. Custom equality rules are not part of the early executable subset.

```kairo theme={null}
if status == Paid {
    return true
}
```

### Comparison operators

**Category:** Operators · **OpCode:** `KAIRO-0A03 / 0x0A03` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `left < right`, `left <= right`, `left > right`, `left >= right`

**What it does.** Compares ordered values such as numeric values or supported comparable core types.

**How it works.** Operands must be compatible comparable types. Broad implicit numeric conversions are not performed, keeping type behavior predictable.

```kairo theme={null}
if total > 0 {
    return true
}
```

### Arithmetic operators

**Category:** Operators · **OpCode:** `KAIRO-0A04 / 0x0A04` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `left + right`, `left - right`, `left * right`, `left / right`

**What it does.** Performs basic arithmetic on compatible numeric types. `+` also performs supported `Text` concatenation.

**How it works.** Kairo does not silently promote across broad numeric families in v0.1; operands must be compatible.

```kairo theme={null}
let subtotal: Decimal = 100.00
let tax: Decimal = 10.00
let total: Decimal = subtotal + tax
```

### Assignment `=`

**Category:** Operators · **OpCode:** `KAIRO-0A05 / 0x0A05` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**Syntax:** `target = expression`

**What it does.** Assigns a value to a mutable local or a 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 their valid construction rules.

```kairo theme={null}
var count: Int32 = 0
count = count + 1
```

## Construction

### Value construction

**Category:** Construction · **OpCode:** `KAIRO-0B01 / 0x0B01` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `TypeName { field: value }`

**What it does.** Constructs a value by supplying each declared field explicitly.

**How it works.** All required fields must be supplied exactly once. Values are assembled from explicit field values rather than through a constructor call.

**Parameter:** Each field name and its declared type is required unless future defaults are ratified.

```kairo theme={null}
let total = Money {
    amount: 125.50
    currency: "AUD"
}
```

### Object construction

**Category:** Construction · **OpCode:** `KAIRO-0B02 / 0x0B02` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**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.

**Parameter:** Each `init` parameter is required and passed by name.

```kairo theme={null}
let customer = Customer(
    id: customerId,
    name: "Pete"
)
```

## Error Handling

### `Result<T, E>`

**Category:** Error Handling · **OpCode:** `KAIRO-0C01 / 0x0C01` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `Result<SuccessType, FailureType>`

**What it does.** Represents an explicit expected outcome: either success carrying a `T` value or failure carrying an `E` value.

**How it works.** `Result` is part of the Kairo Core prelude and does not require an import. `E` must be value-like. Unexpected runtime explosions are faults, not ordinary `Result` values.

**Type parameters:** `T` (any type, required) is the success payload; `E` (value-like type, required) is the expected failure payload.

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

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

### `Result.success`

**Category:** Error Handling · **OpCode:** `KAIRO-0C02 / 0x0C02` · **Version Added:** `0.1.0.0` · **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. The call must be contextually typed as `Result<T, E>` in v0.1.

**Parameter:** `value` (`T`, required) is the success payload.

```kairo theme={null}
return Result.success(0)
```

### `Result.failure`

**Category:** Error Handling · **OpCode:** `KAIRO-0C03 / 0x0C03` · **Version Added:** `0.1.0.0` · **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 and the call must be contextually typed as `Result<T, E>` in v0.1.

**Parameter:** `error` (`E`, required) is the expected failure payload.

```kairo theme={null}
return Result.failure(CreateCustomerFailure.InvalidName)
```

### Result inspection

**Category:** Error Handling · **OpCode:** `KAIRO-0C04 / 0x0C04` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `result.isSuccess`, `result.isFailure`, `result.value`, `result.error`

**What it does.** Inspects a `Result` without relying on destructuring patterns.

**How it works.** `result` must be a `Result<T, E>`. Accessing `value` on failure or `error` on success is a runtime fault. This surface was chosen because Stage 2 match patterns do not yet include destructuring.

```kairo theme={null}
let result = createEmail("pete@example.com")

match result.isSuccess {
    true {
        let email = result.value
        Pulse.Console.out.writeLine(email.value)
    }

    false {
        let failure = result.error
        Pulse.Console.error.writeLine("Could not create email")
    }
}
```

## Collections

### `List<T>`

**Category:** Collections · **OpCode:** `KAIRO-0D01 / 0x0D01` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `List<ElementType>`

**What it does.** Represents an immutable ordered collection of elements.

**How it works.** `List<T>` requires one type argument. It is value-like only when `T` is value-like.

**Type parameter:** `T` (any type, required) is the element type.

```kairo theme={null}
public value CustomerPage {
    ids: List<CustomerId>
}
```

### `Set<T>`

**Category:** Collections · **OpCode:** `KAIRO-0D02 / 0x0D02` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `Set<ElementType>`

**What it does.** Represents an immutable collection of unique values.

**How it works.** `Set<T>` requires one type argument and is value-like only when `T` is value-like. Mutable collection ergonomics are deferred.

**Type parameter:** `T` (any type, required) is the element type.

```kairo theme={null}
public value CustomerTags {
    tags: Set<Text>
}
```

### `Map<K, V>`

**Category:** Collections · **OpCode:** `KAIRO-0D03 / 0x0D03` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `Map<KeyType, ValueType>`

**What it does.** Represents an immutable mapping from keys to values.

**How it works.** `Map<K, V>` requires two type arguments and is value-like only when both `K` and `V` are value-like. For example, `Map<CustomerId, Customer>` is not value-like when `Customer` is an object.

**Type parameters:** `K` (required) is the key type; `V` (required) is the value type.

```kairo theme={null}
public value ExchangeRates {
    rates: Map<Text, Decimal>
}
```

## Generics

### Generic type parameter

**Category:** Generics · **OpCode:** `KAIRO-0E01 / 0x0E01` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**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.

**Type parameter:** `T` (required) is the placeholder type.

```kairo theme={null}
public contract Formatter<T> {
    func format(value: T): Text
}
```

### Generic contract constraint

**Category:** Generics · **OpCode:** `KAIRO-0E02 / 0x0E02` · **Version Added:** `0.1.0.0` · **Thread-Safe:** Yes

**Syntax:** `T: ContractName`

**What 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.

**Parameter:** `ContractName` (contract, required) is the capability the type parameter must provide.

```kairo theme={null}
public contract Displayable {
    func display(): Text
}

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

## Runtime

### Application entrypoint

**Category:** Runtime · **OpCode:** `KAIRO-0F01 / 0x0F01` · **Version Added:** `0.1.0.0` · **Thread-Safe:** No

**Syntax:** `[application] entry = "Module.function"` plus a matching module-level function

**What it does.** Defines where an application starts.

**How it works.** The entrypoint name is determined by the manifest, not by filename guessing. `main` is the recommended convention but not a hidden requirement. Supported v0.1 entry return types are `Int32` and `Result<Int32, E>`. The package kind must be `application`.

```toml theme={null}
[application]
entry = "Demo.App.main"
```

```kairo theme={null}
module Demo.App

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

### `Pulse.Console.out.write`

**Category:** Runtime Service · **OpCode:** `KAIRO-0F02 / 0x0F02` · **Version Added:** `0.1.0.0` · **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. Kairo deliberately avoided a `PRINT` keyword; console output goes through explicit Pulse services.

**Parameter:** `value` (supported display value, required) is what gets written to stdout.

```kairo theme={null}
import Pulse.Console

public func main(): Int32 {
    Pulse.Console.out.write("Hello")
    return 0
}
```

### `Pulse.Console.out.writeLine`

**Category:** Runtime Service · **OpCode:** `KAIRO-0F03 / 0x0F03` · **Version Added:** `0.1.0.0` · **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.** Must be referenced through the explicit `Pulse.Console` runtime service and requires the application to target Pulse or a backend supporting that surface.

**Parameter:** `value` (supported display value, required) is what gets written to stdout.

```kairo theme={null}
import Pulse.Console

public func main(): Int32 {
    Pulse.Console.out.writeLine("Kairo is running")
    return 0
}
```

### `Pulse.Console.error.write`

**Category:** Runtime Service · **OpCode:** `KAIRO-0F04 / 0x0F04` · **Version Added:** `0.1.0.0` · **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; there is no ambient error stream.

**Parameter:** `value` (supported display value, required) is what gets written to stderr.

```kairo theme={null}
import Pulse.Console

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

### `Pulse.Console.error.writeLine`

**Category:** Runtime Service · **OpCode:** `KAIRO-0F05 / 0x0F05` · **Version Added:** `0.1.0.0` · **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.** The line is routed to the process's standard error stream by the Pulse runtime.

**Parameter:** `value` (supported display value, required) is what gets written to stderr.

```kairo theme={null}
import Pulse.Console

public func main(): Int32 {
    Pulse.Console.error.writeLine("Something went wrong")
    return 1
}
```

## Currently Deferred Language Areas

The following 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 Guidance

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

* `module`
* `import Pulse.Console`
* `value`
* `object`
* `enum`
* `func`
* `init`
* `let`
* `var`
* `if / else`
* `match`
* `Result<T, E>`
* `Pulse.Console.out.writeLine`
* Application entrypoints returning `Int32` or `Result<Int32, E>`

Avoid sandbox examples that rely on deferred features such as loops, async execution, destructuring match patterns, or dependency registry restore.