kama type model — value / resource / view / enum / contract / intrinsic

Every type declaration is introduced by a type marker, followed by one of five kind words (type value / type resource / type view / type enum / type contract); the sixth kind, intrinsic, is the built-ins, which are declared by the language and named in a contract's for list. A type adapter block gives a type a contract outside the type's declaration, from the contract's own module. The vocabulary + access-control rules below are enforced by the compiler. This doc is the durable rationale — see also GOALS.md §3c.

The type marker#

Every type declaration begins with type, followed by a kind — exactly parallel to fn on every function. This makes declarations greppable and self-describing (grep -n '^type '). The kind words value / resource / view / contract / adapter appear only right after type (and intrinsic only in a contract's for list), so they are contextual, not reserved — they stay ordinary identifiers everywhere else (int32 value = 5;, a field or method named resource, etc.). type itself is contextual too: it leads a declaration only where one can begin, and may name a field or a local (C headers name fields type). The exceptions are enum, which is reserved because it predates the type marker, and the qualifiers virtual / abstract / final, which are reserved words.

type value Name     { … }            // owns nothing — copies
type resource Name  { … }            // owns / has identity — moves, RAII-dropped
type view Name      { … }            // borrows a range it doesn't own — a stack-only slice/span
type contract Name for value { … }   // a public-only guarantee (an interface)
type enum Name      { … }            // one of a closed set of variants — a sum type
type adapter <int32> implements C { … }   // gives a type you don't declare a contract's methods

Why reframe#

class / struct / pod (and value-vs-reference) are C/C++ legacy framings that encode the wrong axis. The axis a no-GC / RAII language actually turns on is: does this type own a resource? Rust (Copy vs move), Hylo/Val (value semantics), Swift (~Copyable), and Mojo are all converging here. kama makes ownership the declared nature of a type, so the designer picks the right lever at design time — a "type designer" language that retrains humans and LLMs to think ownership-first.

The kinds#

These are the nature nouns. virtual / abstract / final are qualifiers (below), not kinds.

intrinsic is the odd one and belongs here anyway: it is the kind a primitive is, and nobody declares one. A built-in gains a contract's methods through a type adapter block, one block covering a whole set of widths (type adapter <int8, int16, int32, int64> implements Hashable { … }). You name the kind constantly, because every contract's mandatory for clause lists the kinds allowed to implement it, and primitives are spelled intrinsic there: type contract Hashable for value, resource, enum, intrinsic. See SPEC.md § type adapter.

value — owns nothing, copied#

A value is defined by its bits: copying it is a memcpy, and it owns nothing to free. It is the stricter cousin of a "value type" — where a C# struct can smuggle a heap reference (copying it shares that object), a kama value owns nothing, so its copy has no hidden shared ownership.

import { std::math::sqrt };

type value Vec2 {
    public float32 x;       // fields choose visibility per field
    public float32 y;
    public ctor make(float32 x, float32 y) { this.x = x; this.y = y; }
    public const fn float32 length() { float32 q = this.x*this.x + this.y*this.y; return sqrt(x: q); }
}

type value Rect {
    float32 x; float32 y; float32 w; float32 h;   // private (default) — guards its own invariant
    public ctor make(float32 x, float32 y, float32 w, float32 h) { this.x = x; this.y = y; this.w = w; this.h = h; }
    public const fn bool contains(Vec2 p) {
        return p.x >= this.x && p.x < this.x + this.w && p.y >= this.y && p.y < this.y + this.h;
    }
}                                          // still copies freely — it owns nothing

• A "plain-old-data" type is just a value whose fields are all public. Encapsulation (public vs private fields) is a per-field choice, not a separate kind; memcpy semantics hold either way.
• Checked intent: a value that (transitively) owns a resource is a compile error ("declare resource"). Like override — derivable, but a checked assertion that catches a design/field disagreement, and it closes a latent hole (a value holding an Owned → double-free).
• A value is sealed and has no destructor — declaring ~dtor on a value is an error whose message is the lesson: "a value owns nothing — a ~dtor makes it a resource."

resource — owns something (or has identity), moved#

A resource is moved by default and RAII-dropped. It becomes destructible by declaring a ~dtor or by owning a resource member (transitively) — you rarely hand-write a dtor; you compose owning members (Owned/Shared/Weak/collections).

import { std::collections::DynamicArray };

type resource Buffer {
    DynamicArray<uint8> data;                      // owned → Buffer is a resource; fields stay private
    public ctor empty() { this.data = DynamicArray.empty(); }
    public const fn isize size() { return this.data.length(); }
}

type resource Token { }   // owns nothing, but move-only by *identity* — a capability / linear token

• resource fields are private-only — ownership (owned handles, invariants) stays encapsulated; expose behavior through methods.
• An empty resource (Token) is valid: "move" is decoupled from "has-a-dtor." It's the linear / capability / witness pattern. (A genuinely-unused one is caught by the general dead-code lint, not a special rule.)
• A non-owning member does not make you a resource: a raw UnsafePtr<T> / UnsafeConstPtr<T> (unsafe borrow) or a borrowed contract value confers no ownership → still a value.

view — borrows a range it doesn't own, stack-only#

A view is a non-owning, second-class borrow of a contiguous run of memory — a slice / span. The flagship is the stdlib pair View<T> ({ UnsafePtr<T> data; isize len }) and its read-only half ConstView<T> ({ UnsafeConstPtr<T> data; isize len }), but the kind is general: an engine can declare its own type view StridedView<T>, type view Grid2D<T>, type view EcsQuery { UnsafePtr<World> world; … } — a view borrows through raw pointers, since a field is never a ref, or through other views it holds: a type that holds a view is a view, so a zero-copy tokenizer is type view Tokens { ConstView<uint8> rest; … }, with a public constructor because it holds no raw pointer, and Optional<ConstView<uint8>> is a view too (SPEC Views compose). It is kama's answer to a safe span without a borrow checker — the same shape as C# ref struct (Span<T>, ReadOnlySpan<T>, Utf8JsonDeserializer).

type view View<T> {                               // a slice/span over a buffer it borrows
    UnsafePtr<T> data; isize len;                 // fields are private-only (the raw UnsafePtr must not leak)
    unsafe ctor over(UnsafePtr<T> at, isize count) { this.data = at; this.len = count; }   // private: it holds a raw pointer
    public const fn isize length() { return this.len; }
    public unsafe ref T operator[](isize i) { /* bounds-checked */ return this.data[i]; }
}

DynamicArray<float32> verts = …;
uploadToGpu(window: verts.slice(from: 2, count: 6));   // zero copy, no ownership transfer — a read-only `ConstView`

A view's constructor is always private: a view is handed out by the container that owns the buffer (viewMut(), slice(...)), never built from an arbitrary pointer at a call site.

• Codegens like a value — inline, bitwise-copied, no dtor. But it is not a transparent data-bag: it has an invariant (a borrowed UnsafePtr<T> that must not leak, ptr/len kept consistent), so — like a resource — its fields are private-only.
• Owns nothing. A view may not have an owning/resource field (that would make it try to free memory it doesn't own). It may declare a ~dtor, which frees nothing: it closes its window — the borrow or foreach that minted the view runs it when the window closes, on every path out (a transaction that rolls back unless it committed, a map's drain() that empties it however the loop ends). Such a view is pinned to its window: a helper takes it ref/const ref, and nothing copies it (SPEC The window).
• Second-class borrow (the escape rule). Exactly like a contract value, a view may be a parameter or a local but not a field, a collection element, or an enum payload — and it may be returned only when it borrows this or a ref/view parameter (so the buffer outlives the call, the same structural rule as a ref T / const ref T place-return). A view over a local can't be returned — it would dangle. To hand back data, own it (copy into a DynamicArray). Read-only intent at a call site is a ConstView<T> parameter, which a View<T> narrows to implicitly. No lifetime tracking is needed — the escape check is purely structural.

contract — a public-only guarantee#

"Interface" is overloaded (the public surface of any type vs the abstract type). A contract is the abstract thing: a public-only guarantee a type promises to satisfy. A type's public members are just "its API."

type contract Drawable for value, resource { fn void draw(); }
type contract Animated for value, resource implements Drawable { fn void step(float32 dt); }   // refines: requires Drawable + more

• All members are public (a contract is public) — no visibility modifiers, no fields, no bodies (no default methods, v1), no dtor. Besides methods a contract may require a ctor or a static fn, which is how a bound gets to construct rather than only to call.
• Explicit satisfaction only (a type declares it satisfies a contract) — never structural/implicit.
• Granularity: keep contracts small; an API requires the narrowest one it needs. Contracts refine each other (capability layering) without class inheritance.
• A contract that mentions its implementing type pins it: type contract Comparable<T is This>, written implements Comparable<This> at the conformer.

enum — one of a closed set of variants#

An enum is a sum type: a value is exactly one of its variants, and a variant may carry named fields. match is the only way to take one apart, and it is exhaustive. (Asking which variant it is — isSome(), isOk() on the prelude's two — takes nothing apart.)

type enum Shape implements Error {
    Circle(float64 radius), Rect(float64 w, float64 h), Empty;
    public const fn string message() { return "a shape"; }
}

• It owns nothing of its own — only what its payloads own. So it copies like a value, unless a variant's payload holds a resource, in which case it moves like one.
• A variant is not a type: Rect is a name in Shape's scope, reached as Shape::Rect(w: …, h: …).
• It takes methods, contracts, named ctors and friend grants like any other kind, and is sealed. Optional<T> and Result<T, E> are ordinary generic enums from the prelude.

intrinsic — how a built-in joins the model#

int32, float64, bool, char and string are built in, and intrinsic is their kind. A type adapter block is how kama code gives them contracts, so no conformance is hard-coded in the compiler. It declares no type and no state — only methods — and one block covers a whole set of targets:

type adapter <int8, int16, int32, int64, uint8, uint16, uint32, uint64, isize, usize> implements Hashable {
    public const fn uint64 hash() { return cast<uint64>(this); }     // the prelude's own
}

• this is the primitive value; This is each target in turn.
• It is how int32 is Hashable, Comparable<This>, Sendable and Formattable — in prelude/global.kama, where go-to-definition lands.

type adapter — a contract for a type you don't declare#

The same block serves every type its author does not declare: a std type, another package's type, one instance of a generic (DynamicArray<uint8>), or a generic's every instance (Optional, narrowed by when [T: C]). It is written in ONE place, the module that declares the contract, and never over a type that module declares (that type says implements C itself). So a type's conformance lives in its own declaration or in its contract's module, never in a third place:

// app::db declares DbParam, and adapts the model's types to it; app::model never imports the db layer.
type adapter <User> implements DbParam { public const fn int32 code() { return this.id; } }
type adapter <Optional> implements DbParam when [T: DbParam] { … }

Its methods are reached only through the contract, never off the type, so an adapter adds no API to the type it decorates. See SPEC.md § type adapter for the rules and why they are what they are.

Polymorphism: substitutability, not reuse#

Using polymorphism/inheritance for DRY is the anti-pattern. The goal of subtyping is substitutability ("is-a", Liskov — swap an implementation behind a guarantee); DRY is a side effect. Inheritance is overused because it bundles two goals. kama unbundles them:

• reuse / DRY → generics (monomorphized, write-once-stamped-per-type, zero cost for values) and composition; shared implementation up an owned hierarchy → virtual/abstract resource.
• substitutability / swap → contracts.
• (ownership → value / resource, orthogonal to both.)

A contract alone gives no reuse (it's a pure guarantee); reuse comes from a generic — optionally bounded by a contract (fn sort<T: Comparable<T>>(...)). Together, generics + contracts give value types everything inheritance did — reuse and is-a — without inheritance's coupling.

Two dispatch mechanisms (differ by where the vtable lives)#

• Inheritance (virtual/abstract): the vtable pointer is embedded in the object; polymorphic instances are used only through owned handles (Owned/Shared<Base>) and need a virtual destructor. Resource-world by construction — a value can't be virtual (an embedded vtable breaks free copy / invites slicing).
• Contract (external / erased): the value's layout is unchanged. Dispatch is either
  • a generic bound (T: Drawable) → monomorphized: direct, inlinable calls, no vtable, no dtor, zero runtime cost (type set fixed at compile time; cost = code size + compile time); or
  • a runtime contract value → a fat pointer (data + witness vtable, 2 words) + one indirect call, no inlining — buys runtime swappability.

Both value and resource satisfy contracts. Storing a contract over a resource you keep needs an owning handle (Shared<Drawable>); over a value it's a second-class borrow (can't escape/store). Ownership introduces the destructor — polymorphism does not (except the virtual dtor for owned hierarchies).

The lever cheat-sheet#

• Owns something / needs identity? → resource. Else → value.
• A fixed set of alternatives, some carrying data? → an enum (and match on it).
• A borrowed window onto someone else's buffer? → a view.
• Your contract for a type you don't declare (a built-in, a std type, another package's)? → a type adapter, in the contract's module.
• Reuse an algorithm across types? → a generic (zero-cost; bound it with a contract if it needs behavior). Don't inherit for reuse.
• Need to swap implementations? → a contract (works on value too, and cheaper — don't reach for resource to get polymorphism; that's the contract's job).
  • interchangeable at compile time → contract as a bound (monomorphized, zero runtime cost).
  • interchangeable at runtime (plugins / heterogeneous / DI) → a contract value (indirect).
• Default: no contract (concrete-first; add abstraction only when a 2nd impl / real decoupling appears — YAGNI / GOALS §4).

Access control + extensibility#

Default visibility everywhere: private. Full per-member matrix (default in bold; protected† = only inside a virtual/abstract resource):

An enum's methods and constructors follow the value column (a variant's payload fields are its data, not members). A type adapter declares methods only.

Eight rules make the grid memorable:

1. Default = private everywhere.
2. protected ⟺ an extensible resource (virtual/abstract). It's meaningless without a subclass, so it's an error on a value, a view, a sealed resource, or a contract.
3. overridable ⟹ protected. virtual/abstract methods are protected-only — private can't be meaningfully overridden, and public-overridable is bad design. The public polymorphic face is a contract (or a public non-virtual method). This bakes in NVI (Non-Virtual Interface).
4. public fields ⟺ value; a resource (ownership encapsulated) and a view (its borrowed raw UnsafePtr must not leak) keep fields private.
5. ~dtor frees ⟺ resource (forbidden on a value, which owns nothing to free; a view may declare one that frees nothing and closes its window).
6. virtual/abstract/final ⟺ resource (values and views are sealed → use contracts; a contract already is the abstraction).
7. contract = all-public signatures (methods, and optionally a ctor/static fn requirement), no fields, no bodies, no dtor; may refine other contracts. A friend grant on a contract is an error — every member is already public.
8. view codegens like a value (inline, bit-copied, sealed, no ~dtor) but adds two guards: private-only fields and the second-class borrow rule — a parameter/local/return-that-borrows- this, never a field, collection element, or enum payload (see the view section above).

Extensibility qualifiers#

• plain resource = sealed (the default).
• type virtual(maxDepth: N) resource = an extensible base (vtable + shared implementation); subclasses extends it and override. maxDepth is the hierarchy's declared depth budget — how many levels may derive below this base — so a hierarchy cannot grow deep by accident.
• type abstract(maxDepth: N) resource = extensible + non-instantiable; an abstract method (no body) forces the enclosing type to be abstract.
• final = seal a virtual method (no further override) or a subclass branch. Redundant on a plain resource (already sealed).

The NVI consequence#

Because public-virtual is banned, a contract method that must vary per subclass is satisfied by a public non-virtual method that delegates to a protected virtual/abstract customization point:

type contract Shape for resource { fn float32 area(); }

type abstract(maxDepth: 1) resource Polygon implements Shape {
    public ctor make() { }                                    // a subclass installs it as its base
    public fn float32 area() { return this.computeArea(); }   // public, non-virtual: the stable face
    protected abstract fn float32 computeArea();              // the protected customization point
    ~Polygon() { }
}

Callers use the public/contract face; subclasses override the protected virtual. Rare in practice — most polymorphism is contracts + monomorphized generics; virtual inheritance is only for shared-impl.

Hand-off marker rule — every kind is movable; the default is declared, a marker overrides#

There is no !Movable and no "ambiguous → must annotate": every owning kind is movable, each kind has a natural bare hand-off, and a give/copy marker overrides it. A hand-off is a named value handed off in an initializer, assignment, argument, or return; a fresh new/ctor/call result never takes a marker.

• value → copy (a value's "move" is a copy; the source stays valid).
• view → copy (a bit-copy of the borrow — {ptr, len} — so the source stays valid, exactly like a value). A view owns nothing, so give is meaningless and copy is redundant; and because a view is a second-class borrow, no hand-off can outlive the buffer it borrows (the escape rule, above).
• resource without a copy contract (move-only) → move on a bare hand-off (the source is consumed); give is optional emphasis; copy is an error — nothing to copy with — until it opts in.
• resource with a copy contract → it must declare its bare default at opt-in: implements Copyable<This>(bare: give) (bare moves) or Copyable<This>(bare: copy) (bare deep-copies via its public ctor copy(ref This source)). Without (bare: …) it is a compile error. give x moves, copy x deep-copies — a marker always overrides the declared default.
• Shared/Weak (shared ownership, implements Copyable<This>(bare: copy)) → a bare hand-off retains (refcount++); copy is the explicit retain; give moves the handle — the ref transfers and the source is consumed (how a Shared returns from a factory without a spurious retain/drop).
• enum → a payload-free or bitwise one copies like a value. One whose payload owns something moves on a bare hand-off, and copy deep-copies it exactly when every payload it can hold copies — the active variant's payloads, each its own way (a string's buffer, a collection's elements, a Copyable resource's copy ctor, a Shared by one more reference). An enum declares nothing for it: it has no identity of its own, so unlike a resource there is no copy for it to choose, and Copyable stays a resource's declaration. A recursive enum (List(DynamicArray<Value> items)) copies when the rest of it does.
• contract → no hand-off of its own. A contract holds no state and isn't instantiable, so a contract-typed binding is always a concrete implementor (a value/resource) or a smart pointer over one — the hand-off follows that type's rule. In a generic <T: SomeContract>, a T hand-off is whatever T's kind dictates (a value T copies, a resource T moves).

A bare hand-off is never a silent copy of a resource (the double-drop hole is closed in every case) and never a silent move of a Shared you meant to share (a Shared's bare default is retain). This is compile-time move tracking with zero runtime overhead by construction — a value moved on some-but-not-all paths that is still live at scope exit is rejected, not tracked with a runtime drop-flag (Optional<T> is the explicit escape hatch for genuinely-conditional ownership). The full give/copy behavior matrix (every cell backed by a fixture) is in SPEC.md.

Edit this page on GitHub