Type-system reference
Type syntax
| Family | Syntax | Representation |
|---|---|---|
| Scalar | int, string, bstring, boolean | Corresponding Go scalar; text contracts remain distinct |
| Multiple results | (T, U) in a callable result position | Separate Go results, not a tuple value |
| Slice | T[] | []T |
| Fixed array | [N]T | [N]T |
| Map | Map<K, V> | map[K]V |
| Pointer | *T | *T |
| Channel | GoChannel<T> | chan T |
| Send channel | GoSendChannel<T> | chan<- T |
| Receive channel | GoReceiveChannel<T> | <-chan T |
| Function | (name: T, ...rest: U[]) => R | Go function type |
| Structural object | { name: T, count: int } | Deterministic anonymous Go struct |
| Named generic | Box<T>, Lookup<K, V> | Instantiated native named type |
| Nullable | T | null | Nil-capable T without a wrapper |
| Result | Result<T> | Function return (T, error) effect |
| Task | Task<T> | Compiler-tracked local task state |
Parentheses and generic brackets disambiguate nested shapes. Result and Task have restricted positions described below.
Fixed-array lengths
Since v0.4.7, [N]T accepts a compile-time integer expression for N, not just an integer literal. The value must be non-negative and fit the selected Go target's int. Integer-valued untyped floating/complex constants are allowed; typed floating values are not. Length is part of type identity: [1 + 2]int and [3]int are the same type.
import go { Println } from "fmt"
const Width = 3
alias Row = [Width + 1]int
class Limits {
public static const count: int = 4
}
function row(): [Limits.count]int {
return [10, 20, 30, 40]
}
function main(): void {
const values: Row = row()
const bytes: [len("湯")]byte = [1, 2, 3]
const smaller: [min(Width, 2)]int = [7, 8]
Println(len(values), values[3], len(bytes), len(smaller))
}The expression can use source or imported Go constants, enum members and accessible static class constants, including forward-declared constants. Ordinary constant arithmetic/conversions and constant len, cap, min and max use the same rules as value expressions. len("湯") is three UTF-8 bytes, not one code point. Compile-time lengths produce ordinary numeric Go array types; there is no runtime allocation or expression evaluation for the length.
A const initialized by a runtime call is not a compile-time constant. Function parameters and let scalar bindings likewise cannot supply runtime lengths:
function dynamic(size: int): int {
const values: [size]int = []
return len(values)
}len/cap of a concrete array or array pointer can be constant even when the array is mutable or the pointer is nil. An explicitly annotated global array's initializer is not needed to obtain its length. Calls or channel receives inside the operand make these operations nonconstant; a generic type-set value also does not supply a constant length. Declaration cycles are rejected:
const Width = len(values)
const values: [Width]int = []The older v0.4.6 compiler requires a non-negative representable integer literal in [N]T. Both versions reject negative lengths and integer overflow.
Built-in correspondence
| Kinmokusei | Go | Notes |
|---|---|---|
boolean | bool | No truthiness |
string | string | Immutable verified UTF-8 text |
bstring | string | Immutable arbitrary bytes; runtime Go string boundary |
int, uint | int, uint | Target machine width |
int8…int64 | same Go type | Fixed signed width |
byte, uint8 | byte, uint8 | Identical aliases |
uint16…uint64 | same Go type | Fixed unsigned width |
float32 | float32 | Fixed width |
float, number, float64 | float64 | Identical types |
complex64, complex128 | same Go type | complex, real, imag, and imaginary constants |
T[] | []T | Slice |
[N]T | [N]T | Fixed array |
Map<K, V> | map[K]V | Comparable key |
T | null | same nil-backed Go type | Checked nullable reference |
Result<T> | (T, error) | Return effect only |
error and imported Go named/interface types keep their original Go package identity. Kinmokusei does not clone or structurally approximate them.
Inference and expected types
Local initialized bindings may infer their type:
const count = 1; // int
const label = "hello"; // string
const values = [1, 2, 3]; // int[]Empty collections, nil, and null need an expected or explicit type when no element/value establishes one. Public fields, parameters, results, and interface members remain explicit. Expected types flow into literals, generic calls, and untyped constants but never perform an implicit numeric conversion.
Assignability
- Identical types are assignable.
- Scalar
stringmay widen tobstring; the reverse requires checked decoding. - Shared storage and function signatures preserve text contracts:
string[]cannot becomebstring[]by assignment or a no-copy conversion. - A representable untyped constant may adopt a compatible expected numeric type.
- Numeric widths and signedness do not change implicitly.
- Go named types preserve package identity and Go assignability.
alias Name = Tis transparent.type Name = distinct Tis nominal and requires an explicit conversion except for compatible untyped constants.- Distinct enum types are not interchangeable with their underlying runtime integer.
- Generic instantiations with different arguments are different types.
Go values use go/types assignability, addressability, method-set, and constraint rules where possible.
Recursive generic instantiations
v0.4.12 diagnoses unbounded generic instantiation during keika check, including checks in the editor. For example, this does not reach Go emission:
function grow<T>(value: T): void {
grow<T[]>([value]);
}The type argument would grow through T, T[], T[][], and so on. The same rule applies across mutually recursive functions, generic methods, and type declarations such as class Node<T> { public next: Node<T[]> | null = null; }. The diagnostic identifies a recursive source use, rather than a generated Go line. Correcting the source clears the editor diagnostic.
Recursion that reuses the same arguments or a finite set of arguments is allowed, including type-parameter permutations. Transparent aliases are checked after their Go 1.23 expansion, so an unused, erased alias argument does not create a false cycle. This restriction concerns compile-time type expansion; ordinary runtime recursion still needs an appropriate stopping condition.
An incompatible initialized binding is rejected at its declaration:
function main(): void {
const temperature: int = "hot";
}Explicit conversions
Write the destination type as a one-argument call:
const wide = int64(count);
const text = string(codePoint);
const id = UserID(raw);
const rawAgain = string(id);- Numeric conversions follow Go width, signedness, truncation, and constant representability.
string(integer)creates the UTF-8 encoding of one Unicode code point; usefmtorstrconvfor decimal formatting.string(bstringValue)andstring(byteSlice)returnResult<string>and reject invalid UTF-8. Conversion to a native definedstringtype likewise returnsResult<ThatType>when the input needs validation.bstring(bytes)preserves arbitrary bytes;string(int32Slice)encodes code points, including compatible named slice types. Converting either string type to a byte/code-point slice uses a corresponding type or transparent alias, for examplealias Bytes = byte[]; Bytes(text). Byte conversions preserve raw bytes; decoding raw bytes into code points replaces invalid encodings with U+FFFD, and encoding invalid code points likewise uses U+FFFD. Checked byte-to-stringdecoding never does that. See strings and Unicode.- Named defined types convert to/from compatible underlying types explicitly.
- Conversions to a non-null source function signature or method-bearing anonymous source interface validate the converted reference at runtime. A nil result panics at the conversion's source filename, line and column. The operand runs once; this includes function aliases, native defined functions and compatible nil-capable generic bounds. Raw Go target types retain Go conversion behavior. An interface holding a typed nil pointer remains a non-nil interface. Direct
niland nullable source operands still need the appropriate explicit guard rather than an unchecked conversion. - Enum conversion is explicit in both directions.
- Slice and fixed array do not convert implicitly; use
copyArrayorviewArrayfor the checked supported boundary. - Class upcasts are implicit only along the declared inheritance chain; downcasts use
as?oras!. - Go interface assertions use
as?/as!. Raw Go target types retain Go assertion failure behavior. When the target is a non-null source function signature,as?also returnsfalsefor a typed nil function;as!panics at the assertion with its source filename, line and column. This includes transparent aliases, native defined function types and nil-capable generic constraints. Use a concrete assertion target for constraints mixing non-null source references with non-nil-capable value types. A nullable function target accepts a matching nil function, so check that payload againstnullbefore calling it. An assertion cannot establish a UTF-8 contract: assertbstring, then decode explicitly rather than assertingstringor a verified-text-containing type.
import go fmt from "fmt";
import go reflect from "reflect";
alias Callback = () => int;
function main(): void {
const prototype: Callback = () => 7;
const boxed = reflect.Zero(reflect.TypeOf(prototype)).Interface();
const [callback, ok] = boxed as? Callback;
if (ok) {
fmt.Println(callback());
} else {
fmt.Println("absent callback");
}
const [nullable, matched] = boxed as? Callback | null;
fmt.Println(matched, nullable === null);
const present: Callback = () => 7;
const checked = reflect.ValueOf(present).Interface() as! Callback;
fmt.Println(checked());
}absent callback
true true
7An explicitly checked non-null conversion or forced source assertion can establish a non-null local snapshot even when its declared type is nullable:
import go fmt from "fmt";
import go http from "net/http";
alias Handler = (writer: http.ResponseWriter, request: *http.Request) => void;
function main(): void {
const raw: http.HandlerFunc = (writer, request) => {
fmt.Println("handled");
};
const checked: Handler | null = Handler(raw);
checked(nil, nil);
const absent: http.HandlerFunc = nil;
const optional: Handler | null = absent;
fmt.Println(optional === null);
}handled
trueFor an optional Go callback, bind it to a nullable source function type and check null before calling it. A raw Go target conversion supplies no proof.
alias Callback = () => int;
function convert(): Callback {
return Callback(nil);
}Conversions do not implicitly change reference ownership, recursively copy reference-bearing collection elements, or turn null into raw Go nil. String/byte/code-point conversions copy or encode/decode their scalar content; later slice mutations do not change an already converted string.
A defined type does not accept its underlying runtime type without that explicit conversion:
type UserID = distinct string;
function invalid(raw: string): UserID {
return raw;
}Copy and alias behavior
Scalar, fixed array, native struct, enum, and structural object assignment copies the value. A copied struct/object is shallow: a nested slice, map, pointer, channel, or class continues to share its referenced storage.
Slice assignment copies a header and aliases backing storage. Map/channel assignment copies a descriptor for the same runtime object. Class assignment copies a reference and preserves identity. Pointer assignment copies an address.
Address acquisition with & requires a named binding, an addressable field/index, or dereferenced pointer. Call results, conversion results, map indexes, string indexes, and other temporary values are not addressable. Pointer receiver methods likewise require a pointer or an addressable value from which the compiler can take one.
Zero values and absence
Generated code preserves the corresponding Go zero value: numeric zero, false, empty string, zeroed array/struct/object, and nil for nil-backed reference shapes. Source-level construction rules may require explicit initialization even when Go has a zero value—for example, every non-null class field must be initialized on every completing constructor path.
| Form | Use |
|---|---|
null | Checked absence for a declared T | null |
nil | Raw Go nil at nil-capable low-level boundaries |
| Missing map key | Plain safe-zero reads retain Go zeros; use checked lookup or a direct ?? default for value payloads |
| Closed channel receive | Plain safe-zero reads retain Go behavior; use checked receive or a direct ?? default for value payloads |
v0.4.12 builds require a safe element zero value for nonempty makeSlice and slice make, and for slice clear. Numbers, booleans, text, T | null, slices, maps and channels have valid zeros. Native structs, structural objects and fixed arrays require safe zeros in every stored field/element; a zero-length array contains no elements. All alternatives of a generic bound must qualify; an unconstrained T does not provide this guarantee. Imported Go implementation state remains a platform boundary rather than a checked native field contract.
A non-null class, pointer, interface or function cannot be zero-initialized:
class User {
public name: string = "Aki";
}
const users = makeSlice<User>(2);Use makeSlice<User | null>(count) when empty slots are intended. Otherwise, use makeSlice<User>(0, capacity) and append initialized users. The empty allocation must have a compile-time zero length. See initialized collection elements.
When a slice's element zero is unsafe or unknown, slicing also checks that the new high bound does not exceed its current length. The check reports the source location and remains active inside fixed-array len/cap expressions. Three-index slicing can reserve capacity beyond the length, but cannot expose those slots. After shortening a view, keep the original longer view if you need its full range. Safe-zero elements retain ordinary Go reslicing up to capacity. Fixed arrays remain fully initialized storage and retain their ordinary slicing behavior.
v0.4.12 builds type a one-value map read as T | null when T has a nil representation and its zero would violate a non-null contract: classes, pointers, interfaces and functions. Use a null guard, ??, or an explicit !. The stored element type is unchanged: Map<int, User> still accepts only a non-null User on writes. Safe Go zeros (including scalar zeros and nil slices/maps/channels) retain their ordinary one-value behavior.
For a struct/array payload, use a checked [value, ok] or a direct values[key] ?? initializedDefault / (<-channel) ?? initializedDefault. The latter tests success and preserves present zero values. An unconstrained T still requires a checked pair because its absence representation is unknown. For ordinary checked map, channel and as? bindings whose payload zero is unsafe or unknown, the checker rejects any use of the payload before its matching flag proves success. A flag cannot prove that an explicitly nullable stored value is non-null; check that independently.
import go { Println } from "fmt"
class User {
constructor(public name: string) {}
}
function getOr<T>(values: Map<string, T>, key: string, fallback: T): T {
const [value, ok] = values[key]
if (!ok) { return fallback }
return value
}
function main(): void {
const users = makeMap<string, User>()
const user = users["missing"] ?? new User("guest")
Println(user.name)
const scores = makeMap<string, int>()
scores["known"] = 7
Println(getOr(scores, "known", 0))
Println(getOr(users, "missing", new User("fallback")).name)
}Use the original local flag in if (ok), if (!ok) with an early exit, a boolean comparison or short-circuit expression. Compile-time boolean constants and nested equality/negation preserve this relation. Boolean switches support switch (ok), switch (!ok), comparisons of the guard, and switch (true/false) with guard case expressions. A failed case false test can prove success for later labels or a default, including a default written first.
import go fmt from "fmt";
const SUCCESS = true;
class User {
constructor(public name: string) {}
}
function read(users: Map<string, User>, id: string): string {
const [user, ok] = users[id];
switch (ok) {
case SUCCESS { return user.name; }
default { return "missing"; }
}
}
function main(): void {
const users = makeMap<string, User>();
users["alice"] = new User("Alice");
fmt.Println(read(users, "alice"));
fmt.Println(read(users, "bob"));
const [user, ok] = users["alice"];
if ((ok === SUCCESS) !== false) {
fmt.Println(user.name);
}
}Alice
missing
AliceEvery path entering a grouped/fallthrough body must prove success. A case label alone does not prove success when failure can fall through into it:
class User {
constructor(public name: string) {}
}
function unsafeRead(users: Map<string, User>): string {
const [user, ok] = users["missing"];
switch (ok) {
case false { fallthrough; }
case true { return user.name; }
}
return "missing";
}Reassigning the flag/payload or letting mutable storage escape can invalidate the relation. Copying a boolean does not copy a proof. Copy a verified payload into a stable local before capturing it; direct assignment of an unverified unsafe payload to global storage is rejected. Safe-zero payloads do not require a presence check.
class User { public name: string = "guest" }
function unsafeLookup(users: Map<string, User>): string {
const [user, found] = users["missing"]
return user.name
}These checks preserve raw Go boundaries: a successful lookup can still contain a nil raw Go pointer/interface explicitly stored by Go. Success proves presence, not the behavior of foreign implementations.
v0.4.12 builds apply the same rule to <-channel: an unsafe-zero reference has type T | null, while an unsafe record/array or unknown generic element requires [value, open]. A checked select binding likewise requires open before an unsafe payload can be read. Nullable payloads still need a null guard after success. Bare receives and _ = <-channel discard without exposing a payload. Safe-zero elements and channel range retain their Go behavior; range does not yield a zero element after close.
import go { Println } from "fmt"
class User {
constructor(public name: string) {}
}
function receiveOr<T>(channel: GoReceiveChannel<T>, fallback: T): T {
select {
case const [value, open] = <-channel {
if (!open) { return fallback }
return value
}
}
}
function main(): void {
const users = goChannel<User>()
closeGoChannel(users)
const user = (<-users) ?? new User("guest")
Println(user.name)
const numbers = goChannel<int>(1)
numbers <- 7
closeGoChannel(numbers)
Println(receiveOr(numbers, 0))
}To require a non-null received reference, use (<-channel)!; for expected absence, use a null guard, ??, or the checked pair. A nil raw Go channel still blocks, and nil select channels still disable their cases. Selected class-to-interface assignment preserves null rather than boxing it into a non-null interface.
null === null without a concrete nullable context is rejected because it supplies no base type. A nullable value must be narrowed before member access, indexing, slicing, calling, dereference, or channel operations that require a concrete non-null receiver.
Comparability
Scalars, pointers, channels, class references, interfaces, and enums are comparable where the corresponding Go value is comparable. Arrays and structs are comparable only when every contained field/element is comparable. Slices, maps, and functions are not comparable except for permitted nil/null checks at their boundary.
Map keys and T extends comparable use the same constraint.
Collections
Fixed array length is part of identity. No implicit array/slice conversion exists. Slice bounds use Go byte/index rules and aliasing; static invalid bounds are rejected and dynamic invalid bounds panic.
Map lookup with one value returns the zero value for a missing key. Two-name binding or reassignment yields [value, present], evaluating map and key once.
Slices support two-index and full three-index slicing. The result aliases the original backing array. append may reuse or replace that array exactly as Go does; use the returned slice. Map iteration order is unspecified. Channel operations retain blocking, close, nil-channel, and panic behavior.
Native named types
struct Namecreates a nominal Go-style value type.class Namecreates a pointer-backed reference type.interface Namecreates an explicitly implemented interface contract.enum Namecreates a nominal integer type and typed constants.type Name = distinct Tcreates a Go-compatible defined type.alias Name = Toralias Name<T> = Ucreates a transparent alias; generic aliases are expanded in generated Go.
Finite recursive struct/defined shapes require slice, map, pointer, function, or channel indirection. Direct and fixed-array-only cycles are rejected.
Structural objects differ from native structs: their field-name/type set determines identity and declaration order is irrelevant. They are useful at Go data-transfer boundaries but cannot declare methods. Native structs and classes are nominal even when their fields match.
Functions, interfaces, and method sets
Function identity includes parameter order/types, variadic status, and result. A variadic (prefix: int, ...values: int[]) => int is not assignable to a function taking one ordinary int[] parameter.
v0.4.12 builds check named non-null source class, interface and function parameters when entering a callable, including Go calls into exported functions or callbacks. A nil argument panics with its source parameter's filename, line and column before body effects. Constructor checks precede field initialization and super(); methods, setters and expression/block arrows follow the same rule. Rest parameters check each element, while an empty rest slice is valid.
import go fmt from "fmt";
class User {
constructor(public id: int) {}
}
export function userID(user: User): int {
return user.id;
}
export function optionalID(user: User | null): int {
if (user === null) {
return 0;
}
return user.id;
}
function main(): void {
const callback: (user: User) => int = (user) => userID(user);
fmt.Println(callback(new User(7)));
fmt.Println(optionalID(null));
}T | null, raw Go pointers/interfaces/function types and explicit _ parameter discards retain their existing behavior. An interface containing a typed nil pointer is still a non-nil interface, following Go semantics. A type parameter receives an entry check only when every constraint alternative requires a nil-comparable non-null source reference. Open/mixed bounds do not prove this. These entry checks validate parameter references, not nested fields or collection elements. Single-value storage/result transfers also have the checks described under nullability.
Interfaces are reference-bearing contracts. Kinmokusei classes name contracts explicitly with implements; imported Go interface connectivity is checked against the generated public method set. Value versus pointer receiver methods affect native struct method sets just as in Go. A pointer method requires addressable storage when automatic addressing is used.
Source and imported Go callables may have multiple results. A matching result list can be destructured, forwarded by return call();, or expanded as the sole argument to a matching call. An explicit return first, second; is also valid. Result lists cannot be stored as tuple values or mixed with additional call arguments. Result<T> remains a separate checked error effect.
v0.4.12 builds check non-null source references when forwarding an ordinary result list or assigning it to existing bindings. The producer runs once; all required slot checks finish before returning values or writing any destination. If a later slot fails, earlier assignment targets retain their old values. Explicit _ assignment targets discard their results without a reference check. Checks preserve raw Go and nullable contracts, as well as interface boxing of typed nil pointers. A boolean in an ordinary function result list does not make another result optional: use a nullable type or an explicit checked/Result API when failure may produce absence.
import go context from "context";
import go fmt from "fmt";
alias Callback = () => void;
function rawPair(): (context.CancelFunc, int) {
const [_, cancel] = context.WithCancel(context.Background());
return cancel, 7;
}
function pair(): (Callback, int) {
// The callback is checked before the result list is returned.
return rawPair();
}
function main(): void {
let cancel: Callback = () => {};
let n = 0;
[cancel, n] = rawPair();
cancel();
const [another, m] = pair();
another();
fmt.Println(n, m);
}Ordinary multiple-result declarations also validate inferred non-null source references. In const [user, count] = createUser(), each named non-null reference is checked before the next source statement, including unused names. An explicit _ discards its result. Private Go companion result types retain their inferred type identity. Nullable and raw Go reference results retain their own contracts.
For an ordinary multiple-result for initializer, validation runs once before the first condition. Go's per-iteration variable behavior is preserved through post statements, captured values and labeled continue/break. A goto that restarts the loop repeats initialization and validation.
import go fmt from "fmt";
class User {
constructor(public name: string) {}
}
function createUser(): (User, int) {
return new User("Alice"), 1;
}
function main(): void {
const [user, count] = createUser();
fmt.Println(user.name, count);
}Checked assignments to existing non-null reference bindings validate the payload on a successful map lookup, receive or assertion. Result assignments use a nil error as the success condition. A successful nil payload panics before either target is written. Failure can still supply a zero payload, and the matching ok proof is required before reading an unsafe zero from a checked lookup, receive or assertion. The check uses the original success value even when its destination is _.
In a select receive assignment, the selected case evaluates its assignment targets before validation and performs the writes after validation.
import go context from "context";
import go fmt from "fmt";
alias Callback = () => void;
function cancelAt(values: Map<int, context.CancelFunc>, key: int): boolean {
let cancel: Callback = () => {};
let present = false;
[cancel, present] = values[key];
if (!present) {
return false;
}
cancel();
return true;
}
function main(): void {
const values = makeMap<int, context.CancelFunc>();
const [_, cancel] = context.WithCancel(context.Background());
values[1] = cancel;
fmt.Println(cancelAt(values, 0), cancelAt(values, 1));
}Checked split declarations such as const [value, ok] = values[key] also validate inferred non-null source reference payloads on success. The producer runs once and validation finishes before the following statements, including when ok is discarded or a named payload is unused. This applies to map reads, receives, as?, Result splits, for initializers and select declarations. An explicit _ payload discards the value. Nullable payloads can contain null.
import go fmt from "fmt";
class User {
constructor(public name: string) {}
}
function findName(users: Map<int, User>, id: int): string {
const [user, found] = users[id];
if (!found) {
return "anonymous";
}
return user.name;
}
function main(): void {
const users = makeMap<int, User>();
users[1] = new User("Alice");
fmt.Println(findName(users, 0), findName(users, 1));
}Generics
Functions, class/struct methods, classes, structs, interfaces, aliases, and distinct defined types accept generic parameters. Bounds support comparable, native constraint declarations, dependent parameters, and imported Go type sets/method interfaces. Exact terms, underlying ~T terms, unions, and intersections are checked rather than approximated.
Generic named types require explicit full instantiation. Function and generic method calls can infer arguments or accept a partial/full explicit prefix. Known type arguments and preceding typed arguments contextualize fresh array and object literals, including nested literals and variadic arguments:
function accept<T>(values: T[]): void {}
accept<bstring>(["a", "b"]);This constructs new raw-text storage; it does not reinterpret an existing string[] as bstring[]. Existing arrays retain their element contracts, even when nested inside a fresh literal. Untyped scalar constants still defer to typed arguments during inference, and argument evaluation stays in source order.
Generic classes support inherited state, virtual dispatch, abstract contracts, and static methods. Static fields/accessors remain shared across instantiations and cannot refer to class type parameters. Generic aliases expand transparently; distinct native-struct definitions preserve nominal identity without inheriting the underlying struct's methods. Native class/interface underlyings remain unsupported for distinct.
Nullability
T | null requires a nil-capable representation, including functions as well as classes, pointers, slices, maps, channels and interfaces. The union does not allocate a wrapper. Scalars, fixed arrays, native structs, structural objects, void and Result cannot be nullable directly.
Since v0.4.11, a type parameter also needs a constraint that guarantees a nil representation for every member of its type set:
constraint Pointer = ~*int;
function orElse<T extends Pointer>(value: T | null, fallback: T): T {
if (value === null) { return fallback; }
return value;
}An unconstrained T | null, or a bound mixing pointers and scalar values, is rejected at the declaration even if the function is never called. *T | null and T[] | null still work with unconstrained element types because the container itself has a nil representation. Use an explicit presence/result representation when arbitrary scalar or struct values may be absent.
v0.4.12 builds validate native non-null alternatives of mixed bounds at parameter entry and value publication. A bound containing a callback and int rejects a nil callback supplied from Go while accepting integer zero. A bound containing a callback and a raw pointer preserves the pointer's nil contract. This also applies to stored/returned values, checked bindings, receives and Result success values; failure zeros remain governed by their success checks.
import go fmt from "fmt";
alias Callback = () => int;
constraint Value = Callback | int;
function identity<T extends Value>(value: T): T {
return value;
}
function main(): void {
const read = identity<Callback>(() => 7);
fmt.Println(identity(0), read());
}When native non-null and raw nil-capable alternatives have the same storage kind, the checker requires a concrete type or separate uniform constraints. It does not infer which source contract a nil value intended. Assertions to a bound mixing reference and value types also require a concrete target.
class User { public n: int = 7; }
constraint Mixed = User | *int;
function identity<T extends Mixed>(value: T): T {
return value;
}The compiler tracks maybe-null, definitely-null, and non-null facts separately from declared types. Facts join by guarantees across reachable flow and are invalidated by writes or effect boundaries that may change storage.
Raw Go nil remains separate and is used at the low-level Go boundary.
v0.4.12 builds reject raw nil assignments and conversions to non-null source classes, native interfaces, source anonymous method contracts and source function signatures. Aliases, native defined function types and generic bounds retain that rule. For example, this is rejected:
class User {
public name: string = "Aki";
}
const user: User = nil;Migrate const user: User = nil to const user: User | null = null, then narrow the value before use. For callbacks, declare an alias such as alias Callback = () => int and use Callback | null. Defensive nil comparisons remain permitted; a nil-backed representation alone does not make raw nil a valid initializer for a non-null source reference.
Raw pointers, slices, maps and channels retain Go nil storage. Imported Go interfaces and callback types, including aliases of those types, also retain Go's raw nil rules. Inferred Go values keep that behavior until consumed by a source non-null storage contract.
v0.4.12 builds insert a runtime reference check when an unproven nil-capable value is stored into a non-null source reference type. This covers explicit local/global bindings, assignments, field and explicitly typed aggregate initializers, single-value returns, each expression in a return list, ok payloads, non-spread append elements and channel sends. A nil result panics at the source value expression before it is published; a failed assignment retains the old destination value. The operand runs once, and checks survive fixed-array len/cap optimization. Ordinary call arguments continue to use callable entry checks after all arguments have been evaluated.
import go errors from "errors";
import go fmt from "fmt";
alias View = interface { Error(): bstring; };
function asView(raw: error): View {
// A nil Go interface would panic here, before returning a non-null View.
return raw;
}
function main(): void {
fmt.Println(asView(errors.New("present")).Error());
const absent: View | null = errors.Unwrap(errors.New("plain"));
fmt.Println(absent === null);
}Nullable destinations retain absence, and raw Go destinations retain Go nil behavior. Interface checks preserve Go's distinction between a nil interface and an interface containing a typed nil pointer. Mixed generic contracts use the selective storage-kind checks described above.
v0.4.12 builds also check native non-null references when reading fields, collection elements, callback results and other storage whose current value is not proven. This protects source references inside aggregates supplied or modified by Go, including nested and cyclic data. A failed check panics with the original .km file, line and column before the reference is used. The expression runs once, and ordinary pointer/interface checks do not scan the object graph. A checked local snapshot retains its identity; subsequent reads of shared fields or elements validate their current values again.
import go fmt from "fmt";
class Item {
constructor(public count: int) {}
}
struct Row {
item: Item;
}
function read(row: Row): int {
// Also checked if Go supplied or replaced row.item with nil.
const snapshot = row.item;
return snapshot.count;
}
function main(): void {
const row = Row{ item: new Item(7) };
fmt.Println(read(row));
}Declare fields as nullable when absence is part of their contract. Raw Go references keep Go nil behavior, and explicit whole-value discards do not require a non-null result. Interface checks concern the interface itself, not hidden implementation pointers. Concurrent mutation from Go still requires normal synchronization. For a checked split into an existing nullable binding, the matching success flag establishes non-null only when the payload type promises a native non-null reference; success alone does not establish that a raw Go pointer or callback is non-nil.
A raw Go pointer, interface or function type does not imply that its value is non-nil. Assigning one to an explicit T | null local or field preserves the nullable state; check it against null before access. Aliases and generic named types obey the same storage rule. Slices, maps and channels also permit nil storage, so their unqualified type alone does not establish a non-null proof. Fresh literals, address-taking, collection allocation, and already checked nullable snapshots can establish a proof without another guard.
import go flag from "flag"
import go { Println } from "fmt"
function main(): void {
const flags = flag.NewFlagSet("example", flag.ContinueOnError)
const option: *flag.Flag | null = flags.Lookup("missing")
if (option === null) {
Println("missing")
return
}
Println(option.Name)
}This prints missing. Converting a source Class | null value to a compatible Interface | null preserves absence: a null class becomes a nil interface, not an interface boxing a typed nil pointer. This also applies to nullable Go interfaces, including error | null. The source expression is evaluated once, and a non-null class retains its reference identity and method dispatch.
An existing raw Go interface containing a typed nil pointer is not a nil interface: its comparison with null is false, just as comparison with nil in Go would be. The guard checks the interface value, not hidden pointees or the behavior of the implementation's methods. Direct raw Go use retains Go's nil behavior; this rule does not add automatic runtime boundary assertions.
Postfix value! explicitly checks a nullable or raw nil-capable reference and yields its non-null type, panicking at the assertion when the value is nil. The operand is evaluated once; an interface check concerns the interface itself, not a typed nil pointer it may contain. This does not validate arbitrary Go-owned mutable storage. See assertions.
v0.4.12 builds also support value ?? fallback: the operand runs once, and a nil value evaluates the fallback. Direct map/receive expressions with non-nil-capable payloads instead use the success flag to select the fallback. A compatible non-null fallback gives a non-null result; a nullable fallback retains T | null. This does not narrow the original binding or inspect typed nil pointees inside Go interfaces. See null coalescing.
v0.4.12 builds support optional chaining: value?.member, value?.[index] and callback?.(arguments). Each optional receiver is captured once. When it is nil, the remaining unparenthesized chain, index expressions and call arguments are skipped. An existing non-nil Go interface holding a typed nil pointer still invokes its implementation, following Go equality.
import go fmt from "fmt";
class User {
constructor(public name: string) {}
public next: User | null = null;
}
function show(user: User | null): void {
fmt.Println(user?.name ?? "anonymous");
fmt.Println(user?.next?.name ?? "no next user");
const [name, present] = user?.name;
if (present) { fmt.Println(name); }
}
function main(): void {
show(null);
show(new User("Alice"));
}A nil-capable result has type T | null. Scalar, struct and fixed-array results cannot represent null directly: consume the checked result with ??, const [value, present] = ..., or checked postfix !. A present zero value is preserved. ! panics at the assertion's source location when the chain is absent. Optional void calls can stand alone as statements. Result, Task and ordinary multiple-result calls require an explicit receiver guard and their normal handling.
The operator protects only the receiver immediately before ?.. For example, if user.next is nullable, use user?.next?.name, rather than user?.next.name. Parentheses end the short-circuited chain: (user?.self()).name requires a null check or assertion. Optional chains are not assignment/address targets and do not narrow the original receiver.
class User {
public name: string = "Alice";
public function self(): User { return this; }
}
function read(user: User | null): string {
return (user?.self()).name;
}Narrowing applies to stable bindings and member paths only while the proof remains valid. Assignment, aliasing writes, address-taking, mutable capture, unknown effects, and control-flow joins may discard it. The declared T | null type does not change; only the current flow fact does.
Loop checks include facts arriving from later iterations; a proof valid only on the first iteration does not make an access safe. v0.4.12 reuses completed nested-loop checks when their full entry state and enclosing analysis context are unchanged. This includes exception handlers, inferred arrows, constructors, field initializers, labels and captured writes. Diagnostics, intermediate exceptional paths and Task ownership checks are preserved; a cache hit never treats a first-iteration proof as valid on later iterations. Checking cost still depends on source size and the number of distinct flow states.
class User { constructor(public name: string) {} }
function display(user: User | null): string {
if (user !== null) {
user = null;
return user.name;
}
return "guest";
}Result and Task
Result<T> is valid only as a function/method return effect. It cannot be stored or nested. Task<T> is a local non-escaping single-consumption capability; it cannot appear in public signatures or storage positions.
Result<void> lowers to one error; Result<T> lowers to (T, error). Task<Result<T>> retains both layers: await joins the worker, and the following ? propagates the operation error. Neither form is an ordinary heap wrapper visible to Go callers.
v0.4.12 builds validate a forwarded Result<T> payload when its error is nil and T requires a nil-comparable non-null source reference. The producer runs once. An invalid nil reports the forwarding expression's source location. Error results retain their payload and error values.
For const value = operation()?, propagation first handles the error branch, then validates a named non-null source reference before following statements. An explicitly typed binding performs interface boxing before validation. Unused named bindings receive the check; _ discards the payload. Raw Go and nullable destinations retain their own contracts. These checks also apply to Task results and returns crossing try/finally.
import go fmt from "fmt";
class User {
constructor(public name: string) {}
}
function loadUser(): Result<User> {
return ok(new User("Alice"));
}
function forwardUser(): Result<User> {
return loadUser();
}
function readName(): Result<string> {
const user = forwardUser()?;
return ok(user.name);
}
function main(): void {
const [name, err] = readName();
if (err !== nil) {
fmt.Println(err);
return;
}
fmt.Println(name);
}When a split Result<T> payload has an unsafe or unknown zero value, v0.4.12 builds require a success check before using it. Check the matching local error binding against nil; an error declared as error | null also supports === null. Early returns, short-circuit conditions and switches carry this proof. A typed-nil pointer held inside an error interface still counts as an error, following Go interface equality.
import go fmt from "fmt";
class User {
constructor(public name: string) {}
}
function loadUser(reject: boolean): Result<User> {
if (reject) { return fail(new Exception("not found")); }
return ok(new User("Alice"));
}
function readName(reject: boolean): string {
const [user, err] = loadUser(reject);
if (err !== nil) { return "anonymous"; }
return user.name;
}
function main(): void {
fmt.Println(readName(false), readName(true));
}Reading, logging or discarding the error does not prove success:
class User {
constructor(public name: string) {}
}
function loadUser(): Result<User> {
return fail(new Exception("not found"));
}
function readName(): string {
const [user, err] = loadUser();
_ = err;
return user.name;
}Error/boolean aliases do not transfer the proof. Reassigning the pair requires a fresh check; shadowing, address escape and mutable captures can invalidate the relation. Once checked, the payload snapshot stays valid if the error alone changes. Check into local bindings before assigning an unsafe-zero payload to global storage. Scalar, nullable and other safe-zero payloads can be read without this proof; ordinary error-use diagnostics still apply. These rules apply to source Result<T>, including Result-annotated callbacks.
Decorator contexts and values
Decorator context types are compiler-provided nominal contracts, not interchangeable structural object literals. DecoratorContext accepts any supported target; target-specific contexts restrict application to a class, field, constructor, method, getter, setter or parameter. See the target table.
All context types expose this surface:
| Fields | Type and meaning |
|---|---|
kind | string: target kind |
identity, classIdentity, baseIdentity | string: target, declaring class and base identities |
overrideChain | string[]: inherited slot identities |
className, memberName, parameterName | string: source names |
parameterIndex | int: zero-based parameter position, otherwise -1 |
static, visibility | boolean, string: member access contract |
valueType, valueIdentity | string: source type description and nominal identity when applicable |
constructible, constructUnavailableReason | boolean, string: construction availability |
construct | (arguments: DecoratorValue[]) => Result<DecoratorValue> |
invocable, invokeUnavailableReason | boolean, string: instance invocation availability |
invoke | (receiver: DecoratorValue, arguments: DecoratorValue[]) => Result<DecoratorValue> |
staticInvocable, staticInvokeUnavailableReason | boolean, string: static invocation availability |
invokeStatic | (arguments: DecoratorValue[]) => Result<DecoratorValue> |
DecoratorValue is opaque apart from its readable typeIdentity: string. Boxing and extraction preserve concrete source contracts, including nullable qualifiers, numeric widths, nominal identities and nested type structure. Extraction does not implicitly convert a concrete implementation to an interface: box using that interface contract explicitly. Open type parameters cannot be transported. The decorator built-ins perform checked boxing and extraction.
Type-related runtime failure
The checker rejects statically known type, range, comparability, addressability, and nullability violations. Operations whose validity depends on runtime data preserve Go behavior, including bounds panic, nil dereference, integer division by zero, send on a closed channel, and forced assertion/downcast panic. Checked lookup, checked receive, as?, Result, and nullable flow are the explicit non-panicking alternatives for their respective boundaries.