> ## 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 Type Declarations: value, object, contract, enum

> Reference for all Kairo type declarations: value, object, contract, and enum, including visibility modifiers, conformance syntax, and construction forms.

Kairo provides four top-level type declaration keywords — `value`, `object`, `contract`, and `enum` — each designed to model a distinct kind of domain concept. This page covers the full syntax, rules, and construction forms for each declaration kind, along with visibility modifiers and stored member syntax.

## `value` Declaration

A `value` declares an immutable, content-compared domain type. Think of it as a record or struct: two `value` instances are equal when all their fields are equal, regardless of where in memory they live.

**Rules:**

* All stored members of a `value` are immutable — you cannot use `var` inside a `value`.
* Members must themselves be value-like types; you cannot store an `object`-typed member inside a `value`.
* Comparison is by content, not identity.
* Construct a `value` with the brace initialiser form: `TypeName { field: expression }`.

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

let price: Money = Money { amount: 9.99, currency: "USD" }
let other: Money = Money { amount: 9.99, currency: "USD" }

// price == other is true — content comparison
```

<Tip>
  Use `value` for domain concepts that are defined by their data: money amounts, addresses, coordinates, identifiers. If two instances carry the same data, they represent the same thing.
</Tip>

## `object` Declaration

An `object` declares an identity-bearing, stateful type. Two `object` instances are never equal just because their fields match — each instance is a distinct entity in the program.

**Rules:**

* Use `var` to mark mutable stored members.
* Each `object` has exactly one `init` initialiser in v0.1.
* Construct an `object` using named arguments: `TypeName(param: value)`.
* Comparison is by identity, not content.

```kairo theme={null}
public object Counter {
    var count: Int32

    init(start: Int32) {
        this.count = start
    }

    func increment() {
        this.count = this.count + 1
    }

    func current(): Int32 {
        return this.count
    }
}

let c: Counter = Counter(start: 0)
c.increment()
c.increment()
// c.current() returns 2
```

<Note>
  v0.1 allows only one `init` per `object`. Multiple initialisers are planned for a future release.
</Note>

## `contract` Declaration

A `contract` declares a capability promise — a named set of method and property requirements that a type can commit to fulfilling. Contracts serve the same role as interfaces in other languages.

**Rules:**

* A `contract` declares requirements but never provides implementations.
* Use `var` in a `contract` to indicate a writable property requirement.
* A `contract` cannot declare conformance to another `contract` in v0.1.
* Only `value` and `object` types can declare conformance.

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

public contract Priceable {
    var price: Decimal
    func formattedPrice(): Text
}
```

## Contract Conformance

Declare that a `value` or `object` conforms to one or more contracts by listing them after a `:` following the type name, before the opening brace. Conformance is always explicit — Kairo does not infer structural conformance.

**Rules:**

* Separate multiple contract names with `,`.
* Every name in the conformance list must resolve to a `contract` declaration.
* The type must implement all requirements declared by each listed contract.
* Conformance cannot be declared elsewhere (e.g., in an extension); it belongs on the type itself.

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

    init(name: Text) {
        this.name = name
    }
}
```

```kairo theme={null}
public value Product : Named, Priceable {
    name: Text
    price: Decimal
    priceLabel: Text

    func formattedPrice(): Text {
        return priceLabel
    }
}
```

<Warning>
  If you list a contract in the conformance clause but omit a required member or method, the compiler produces a diagnostic error. There is no partial conformance.
</Warning>

## `enum` Declaration

An `enum` declares a closed set of named cases. Use `enum` to represent a fixed vocabulary of distinct states or options.

**Rules:**

* Cases are listed one per line inside the braces; no explicit values are assigned in v0.1.
* Case names are PascalCase identifiers (e.g., `Draft`, `Submitted`).
* `enum` types cannot declare contract conformance in v0.1.
* Reference a case as `EnumName.CaseName`.

```kairo theme={null}
public enum Direction {
    North
    South
    East
    West
}

let heading: Direction = Direction.North
```

```kairo theme={null}
public enum OrderStatus {
    Pending
    Confirmed
    Shipped
    Delivered
    Cancelled
}
```

<Note>
  Contract conformance for `enum` types is planned for a future version of Kairo.
</Note>

## Visibility Modifiers

Every declaration has a visibility level that controls where it can be accessed. Visibility is declared with a keyword before the declaration keyword (e.g., `public value`, `private func`).

| Modifier   | Where accessible                        | Notes                                             |
| ---------- | --------------------------------------- | ------------------------------------------------- |
| `public`   | Anywhere, including outside the package | Use for your public API surface                   |
| `internal` | Within the same package only            | Default when no modifier is written               |
| `private`  | Within the declaring type only          | Only valid on members, not top-level declarations |

```kairo theme={null}
public value Invoice { ... }       // accessible everywhere
internal value DraftOrder { ... }  // package-private (same as omitting modifier)
```

<Tip>
  You can omit the visibility modifier to get `internal` access. Being explicit with `internal` is fine, but it is never required.
</Tip>

## Stored Member Syntax

Members declared inside a `value` or `object` body are stored members — they hold data for each instance.

| Syntax           | Kind                    | Allowed in        |
| ---------------- | ----------------------- | ----------------- |
| `name: Type`     | Immutable stored member | `value`, `object` |
| `var name: Type` | Mutable stored member   | `object` only     |

```kairo theme={null}
public value Address {
    street: Text       // immutable — required in value
    city: Text
    postCode: Text
}

public object Session {
    var token: Text    // mutable — valid in object
    var expiresAt: DateTime
    userId: Text       // immutable member also valid in object
}
```

<Warning>
  Using `var` inside a `value` declaration is a compile-time error. All members of a `value` must be immutable.
</Warning>