Skip to content
Topazdocs

Search documentation

Specification 6.0

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Download →

    Design decisions

    Bindings and types

    A binding has at most one type annotation

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    A declaration and its pattern can each carry a type annotation. Repeating a type raises an unnecessary question about which annotation owns the binding.

    Decision

    Reject a declaration that uses both a binding annotation and a pattern annotation for the same binding.

    Examples

    Repeat a let annotation

    example.tpzRepeat a let annotationOpen in Playground →
    1. let answer: int: int = 1
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      bindings-duplicate-type-annotation at example.tpz:1:16

    Repeat an exported let annotation

    example.tpzRepeat an exported let annotationOpen in Playground →
    1. export let answer: int: int = 1
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      bindings-duplicate-type-annotation at example.tpz:1:23

    Repeat a mutable binding annotation

    example.tpzRepeat a mutable binding annotationOpen in Playground →
    1. let mut answer: int: int = 1
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      bindings-duplicate-type-annotation at example.tpz:1:20

    Repeat a constant annotation

    example.tpzRepeat a constant annotationOpen in Playground →
    1. const answer: int: int = 1
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      bindings-duplicate-type-annotation at example.tpz:1:18

    Annotate each binding once

    example.tpzAnnotate each binding onceOpen in Playground →
    1. let local: int = 1
    2. export let published: int = local
    3. let mut count: int = local
    4. const label: string = "Topaz"
    5. export const publishedLabel: string = label
    Expected outputExit code 0
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Allow both annotations together. The same binding type could be written in two places.

    Why

    The reader can find the binding's type in one place.

    Changed rules Binding declaration forms →

    A binding cannot reuse a visible constructor name

    Adopted November 18, 2026 · 6.0.0 · Being verified · Version 2

    Problem

    A function or local value sharing a constructor name can change what an existing use means. Accepting let UserId = 5 would make UserId a variable in calls and a constructor in patterns. Names hidden in other modules do not need to be reserved.

    Decision

    • Write Choice.Empty() for a nullary variant. Reject conflicts with visible constructors in bindings, parameters, function names and patterns.
    • In a value position, None(1) calls the prelude constructor with too many arguments. Qualify a user enum's None with its enum name.
    • Binding a visible newtype constructor name produces TPZ5712 during checking. The name remains available as a type.
    • For aliased imports, check the visible alias. Different declarations in separate modules remain distinct.

    Examples

    A qualified nullary constructor keeps its parentheses

    example.tpzA qualified nullary constructor keeps its parenthesesOpen in Playground →
    1. enum Choice { Empty }
    2. let value: Choice = Choice.Empty()
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    A let binding cannot replace the Some constructor

    example.tpzA let binding cannot replace the Some constructor
    1. let Some = 1
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5712 →

      pattern-constructor-binding-collision at example.tpz:1:5

    A function cannot replace a visible enum variant

    example.tpzA function cannot replace a visible enum variant
    1. enum Choice { Empty }
    2. function Empty() -> int { 1 }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5712 →

      pattern-constructor-binding-collision at example.tpz:2:10

    A qualified enum None uses its declared payload

    example.tpzA qualified enum None uses its declared payload
    1. import std.io { writeLine }
    2. enum Reply { None(int) }
    3. let reply = Reply.None(7)
    4. writeLine(match (reply) { case None(value) => "{value}" })
    Expected outputExit code 0
    7
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 7

    The prelude None does not accept a payload

    example.tpzThe prelude None does not accept a payload
    1. let value: Option<int> = None(1)
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    The required primary-location contract is Pending.

    A let binding cannot replace a newtype constructor

    example.tpzA let binding cannot replace a newtype constructor
    1. newtype UserId = int
    2. let UserId = 5
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5712 →

      pattern-constructor-binding-collision at example.tpz:2:5

    A function cannot replace a newtype constructor

    example.tpzA function cannot replace a newtype constructor
    1. newtype UserId = int
    2. function UserId() -> int { 1 }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5712 →

      pattern-constructor-binding-collision at example.tpz:2:10

    The imported alias is a visible newtype constructor

    example.tpzThe imported alias is a visible newtype constructor
    1. import ids { UserId as Id }
    2. let Id = 5
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    ids.tpzThe imported alias is a visible newtype constructor
    1. export newtype UserId = int
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5712 →

      pattern-constructor-binding-collision at example.tpz:2:5

    A newtype alias does not reserve the original unimported spelling

    example.tpzA newtype alias does not reserve the original unimported spelling
    1. import ids { UserId as Id }
    2. let UserId = 5
    3. let user: Id = Id(7)
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    ids.tpzA newtype alias does not reserve the original unimported spelling
    1. export newtype UserId = int
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Separate modules may declare the same newtype name

    example.tpzSeparate modules may declare the same newtype name
    1. import first { UserId as FirstId }
    2. import second { UserId as SecondId }
    3. let left: FirstId = FirstId(1)
    4. let right: SecondId = SecondId(2)
    5. let UserId = 3
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    first.tpzSeparate modules may declare the same newtype name
    1. export newtype UserId = int
    second.tpzSeparate modules may declare the same newtype name
    1. export newtype UserId = int
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Check only pattern binders for conflicts. A function or variable could still hide the constructor.
    • Treat the newtype name as a type name and permit a conflicting value binding. Calls and patterns could give the same spelling different roles.

    Why

    Constructor names keep their role in every binding position, and only names that are actually visible are restricted.

    Changed rules Reserved None binding name →Variant names and prelude constructors →Newtype constructor argument type →Constructor syntax and binding names →

    Version history
    • Version 1 · Adopted November 17, 2026 · A binding cannot shadow a visible constructor name

      Reject visible constructor-name conflicts in every binding position.

    Mutation diagnostics identify the cause

    Adopted November 18, 2026 · 6.0.0 · Being verified

    Problem

    let mut can fix an immutable binding. A discarded temporary or a detached method needs a different repair.

    Decision

    • Checking reports TPZ5003 for an immutable root and points to its reference.
    • Discarding the result of a mutating call on a temporary produces TPZ5027 at the call.
    • Detaching a mutator produces TPZ5028 at the member access. For one access, detachment takes precedence over an immutable root, which takes precedence over a discarded temporary.

    Examples

    Immutable Option root, present

    example.tpzImmutable Option root, present
    1. let xs: Option<Array<int>> = Some([1])
    2. xs?.push(2)
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    The required primary-location contract is Pending.

    Statement result discarded

    example.tpzStatement result discarded
    1. function make() -> Array<int> { [1, 2] }
    2. make().pop()
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    The required primary-location contract is Pending.

    Detached mutator wins over immutable root

    example.tpzDetached mutator wins over immutable root
    1. let xs = [1]
    2. let f = xs.push
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    The required primary-location contract is Pending.

    Alternatives considered

    • Report all three conditions as TPZ5003. Making a binding mutable would give the wrong advice for temporary values and detached methods.
    • Combine detaching and temporary mutation into one new diagnostic. The two cases differ in cause and fix, so one diagnostic could not name one cause.

    Why

    The diagnostic points to the right repair, such as a mutable binding, using a result or wrapping the call in a lambda.

    Changed rules Assignment requires a mutable root →Mutation result consumption →

    Optional mutation still needs a mutable root binding

    Adopted November 18, 2026 · 6.0.0 · Being verified

    Problem

    An optional mutation of an immutable collection could fail only when the value was present. Testing with absence could hide the error.

    Decision

    • Follow fields, indices, parentheses and ?. back to the root binding. A call result ends the path.
    • An immutable root produces TPZ5003 during checking regardless of whether the value is present.
    • Mutation through a mutable capture updates the shared variable. Make a mutable local copy when starting from an immutable parameter or loop binding.

    Examples

    Immutable Option root, present →

    Immutable Option root, absent

    example.tpzImmutable Option root, absent
    1. let xs: Option<Array<int>> = None()
    2. xs?.push(2)
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    The required primary-location contract is Pending.

    Optional call through immutable field root

    example.tpzOptional call through immutable field root
    1. record R { items: Option<Array<int>> }
    2. let r = R { items: Some([1]) }
    3. r.items?.push(2)
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    The required primary-location contract is Pending.

    Mutable optional root can change

    example.tpzMutable optional root can changeOpen in Playground →
    1. let mut xs: Option<Array<int>> = Some([1])
    2. xs?.push(2)
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Accept the check and fail at runtime on a present value. The error could appear or disappear with the input.
    • Accept the call only when the value is absent. The check result would depend on a runtime value.

    Why

    Assignment and mutating calls follow the same mutability rule.

    Changed rules Assignment requires a mutable root →

    A local function name refers to one declaration throughout its block

    Adopted November 19, 2026 · 6.0.0 · In progress

    Problem

    When an inner and outer function shared a name, one call site could invoke the outer function before the inner declaration ran and the inner function afterward. The checker and runtime sometimes picked different functions, so checks could pass even when their return types differed.

    Decision

    • A local function declaration shadows an outer value with the same name throughout its block. Local functions in the same block can call each other regardless of declaration order.
    • An immediate read before the declaration produces TPZ3018 during name resolution.
    • A read in a function body, a lambda or another deferred expression produces TPZ5002 at runtime if the declaration has yet to execute.
    • A function resolves its outer names at the point where it is defined.
    • Names declared by let and const remain visible after their declarations. A repeated value name in one block produces TPZ5008 at the second declaration.
    • When an eligible constant expression such as const G = f refers to a function, G can be called before the declaration of f. An ordinary read cannot come before the declaration.

    Alternatives considered

    • Make a function name visible only after its declaration. An earlier function could not call a later one, which breaks mutual recursion.
    • Initialize all local functions on entry to the block. Early calls would move initialization errors into function bodies. Local and module functions would follow different timing rules.
    • At runtime, choose the function with that name that is ready. One call site could invoke functions with different return types. The checked type could disagree with the value returned.

    Why

    Each reference has a stable target for checking and execution. Local functions can call each other, and initialization errors point to the failed read.

    Changed rules Nested block scope →Initialization through branches, calls, and closures →Redeclaration and nested shadowing →

    Early reads are diagnosed at their evaluation boundary

    Adopted November 19, 2026 · 6.0.0 · Being verified

    Problem

    An initializer may refer to a binding declared later in the module. An earlier example labeled a read reached during execution as a check-time error.

    Decision

    • A read before initialization in an immediately evaluated expression, such as a condition or match subject, produces TPZ3018 during name resolution.
    • If execution reaches such a read in a branch, pattern, guard, short-circuit right operand, optional call argument, loop body, or later comprehension step, it raises TPZ5002.
    • Nested expressions inherit their surrounding conditional boundary, even when the condition is a literal.

    Examples

    A skipped branch does not read a later binding

    example.tpzA skipped branch does not read a later bindingOpen in Playground →
    1. import std.io
    2. let chosen: int = if (false) { after } else { 2 }
    3. let after: int = 7
    4. io.writeLine("{chosen}:{after}")
    Expected outputExit code 0
    2:7
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 2:7

    The condition is an immediate initializer read

    example.tpzThe condition is an immediate initializer read
    1. let chosen: int = if (after) { 1 } else { 2 }
    2. let after: bool = true
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during resolve. Nonzero exit.

    • TPZ3018 →

      module-initializer-not-ready at example.tpz:1:23

    An executed branch faults before a later binding initializes

    example.tpzAn executed branch faults before a later binding initializesOpen in Playground →
    1. let chosen: int = if (true) { after } else { 0 }
    2. let after: int = 7
    Expected outputNonzero exit
    No stdout.
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ5002 →

      bindings-runtime-uninitialized-read at example.tpz:1:31

    Alternatives considered

    • Follow literal conditions and reject the read during checking. Replacing a condition with a variable would change the diagnostic phase.

    Why

    The evaluation boundary in the source tells you when the read will be checked.

    Changed rules Initialization through branches, calls, and closures →

    Matching evaluates pattern expressions as it reaches them

    Adopted November 19, 2026 · 6.0.0 · In progress

    Problem

    In the range pattern (x? .. end()), the ? in the lower endpoint can return from the function before the upper endpoint runs. Treating the upper endpoint as immediate because the input is an integer wrongly rejects the program for declaration order. The same problem made while let behave differently from other conditions.

    Decision

    • The expression providing the value follows its surrounding evaluation path. This covers the right side of = in let, if let and while let, the subject of match and the iterable in for.
    • An expression inside a pattern runs only when the matcher reaches it. Reading an uninitialized outer binding there produces TPZ5002 at runtime.
    • Source structure determines when a read occurs. The input type and literal value leave that classification unchanged.
    • The checker resolves names and checks types inside pattern expressions even when execution skips them.
    • A comprehension evaluates only its first source with the enclosing expression. Later sources, filters and the result expression evaluate during iteration.

    Alternatives considered

    • Treat range endpoints as immediate when the input is known to be an integer. An early return in the lower endpoint or a failed outer pattern can skip the upper endpoint. This approach rejects valid programs.
    • Prove during type checking that execution reaches the endpoint. The diagnostic for a single read could move between name resolution, checking and runtime depending on whether the proof succeeds.

    Why

    Read the source to tell when an early read will fail. Type information and compiler rewrites leave the diagnostic phase unchanged.

    Changed rules Initialization through branches, calls, and closures →Integer range patterns →

    A name refers to the same declaration in checking and execution

    Adopted November 19, 2026 · 6.0.0 · In progress

    Problem

    In a function body, RoundingMode.HalfEven() read the standard RoundingMode before a module let with the same name was initialized, and that let afterward. A function could therefore pass checking and still return a value of a different type than its declared result. Whether the checker knew the type of a binding declared later depended on the order in which it visited declarations. An assignment to an immutable binding was rejected during checking or only at runtime, depending on declaration order.

    Decision

    • Each place that uses a name has one target for its role, and checking and execution use that same target. The initialization state at runtime never changes it. An ordinary value name finds only value declarations in its lexical scope. Positions with their own syntax, such as constructor calls and type references, use their own lookup. The head of Name.member prefers a visible binding and refers to a type or standard static operation with that name only when no binding is visible. The same declaration with the same type arguments is one type, however it is spelled. When a binding holds a function value, the binding is the target, and the call reads the function from it at runtime.
    • An imported name is a top-level binding of the current module. Declaring that name again at module top level remains TPZ3008, and importing under an alias leaves the original spelling free. Standard names visible without an import, such as RoundingMode, Some and Show, live in a scope outside the module top level. A module top-level binding with the same name shadows such a name for every value reference in that module. Declarations inside a block keep the block scope rules.
    • Only a binder that was never created is left out as a target. A binder that collides with a constructor name is one example, and its name then refers to the outer declaration. A declaration with an error in its annotation or initializer remains the target and never hands the name to the next candidate. A name declared twice in one block reports TPZ5008 once. Each read or write of that name is judged against every visible candidate and adds only errors that every candidate would produce. These rules decide follow-up diagnostics in programs that already contain errors.
    • Readiness is checked on the chosen binding when execution first reads or writes it. Code that runs immediately at module top level and reads or writes an uninitialized binding gets TPZ3018 during name resolution. A delayed read in a function body or branch before initialization faults with TPZ5002 at runtime. An assignment is checked at the step of its evaluation order that first touches the binding. So x = value() and r.a = value() evaluate the right side first, while xs[0] = value() and x += value() read the target first. Unless name resolution rejects it first, changing an immutable binding by assignment or a mutating method call gets TPZ5003 during checking. Declaration order and whether the code runs make no difference.
    • The type of a target comes from its declaration, whether or not the checker has visited that declaration yet. Annotations and function signatures come first, and the rest is derived from initializers and function bodies in dependency order. A type that cannot be finite, such as one that must contain itself, is a contradiction and reports TPZ5001 at the expression that causes it. A cycle without enough information reports one TPZ5020 or TPZ5022 for each group of mutually dependent declarations. Only judgments that need the unknown type are deferred, and questions the declaration answers are still checked.
    • A binding that shadows a standard name can be renamed together with its references to an unused name. Each reference then keeps its target declaration, its static type, and whether it reads immediately or later. Roles set from outside, such as the entry point main or a public export name, must stay unchanged. A function value shows its name, as in <function Show>, so a program that picks its path from that text can behave differently after renaming.

    Alternatives considered

    • Choose the target from the initialization state at runtime. One place could see declarations of different types, so a function that passes checking could return a value of another type.
    • Let checking and execution choose targets separately. The checked declaration and the executed declaration could differ, so the check would not describe the actual run.
    • Let a module binding shadow a standard name only after its declaration. A module function body already refers to module bindings declared later. Keeping that rule when a name matches a standard name requires shadowing across the whole module. Shadowing from the declaration onward is the block scope rule and still applies in blocks.
    • Reject a read with TPZ5020 while the checker has yet to learn the target's type. Whether a program is accepted would depend on the order in which the checker visits declarations.
    • Skip a declaration with an error and use the next candidate with that name. One annotation error would silently move the name to a standard declaration and produce misleading follow-up diagnostics.
    • Defer every judgment that depends on a constant expression reading a module let. The missing value would also stop checks that the known type can already answer.
    • Check the readiness of the assigned binding before the right side in every assignment. Assignments such as x = value() evaluate the right side first. Checking earlier would change that order and drop the right side's output and first fault.
    • Check write permission at runtime. An assignment to the same immutable let would be rejected during checking or postponed to runtime depending on declaration order.

    Why

    A program that passes checking runs with the declarations that were checked. What a name means at one place depends neither on execution order, nor on the order the checker visits declarations, nor on whether its spelling matches a standard name. Readiness is checked when execution actually reaches the binding, so evaluation order and the first effect stay the same.

    Changed rules Initialization through branches, calls, and closures →Operand and assignment evaluation order →

    Parentheses around a callee preserve its constant eligibility

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    Grouping a callee for readability could change whether its call was accepted in a constant expression. The parentheses did not change the target.

    Decision

    A call's eligibility in a const initializer stays the same with or without parentheses around its callee.

    Examples

    Group admitted numeric callees

    example.tpzGroup admitted numeric callees
    1. const bits: int = ((5).and)(3)
    2. const rounded: int = ((2.2).ceil)()
    Expected outputExit code 0
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Group admitted length callees

    example.tpzGroup admitted length callees
    1. import std.typeset
    2. const physical: Length<Pt> = ((1in).toPt)()
    3. const relative: Length<Pt> = ((2em).resolve)(12pt)
    Expected outputExit code 0
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    An ordinary call remains a runtime computation

    example.tpzAn ordinary call remains a runtime computationOpen in Playground →
    1. function answer() -> int { 3 }
    2. const direct: int = answer()
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 →

      bindings-const-ordinary-call at example.tpz:2:21

    Grouping does not make an ordinary call constant

    example.tpzGrouping does not make an ordinary call constantOpen in Playground →
    1. function answer() -> int { 3 }
    2. const grouped: int = (answer)()
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 →

      bindings-const-ordinary-call at example.tpz:2:22

    Alternatives considered

    • Let grouping change eligibility. Formatting the same callee could make a call accepted or rejected.

    Why

    Constant restrictions follow the callee itself.

    Changed rules Constant expressions and retained values →

    Assigning and passing collections gives independent values

    Adopted November 9, 2026 · 6.0.0 · Being verified

    Problem

    Updating a new variable after assigning it an array could also change the original array. The assignment did not make that reach visible.

    Decision

    • Arrays, maps and sets are values. Assignment, argument passing, return and field storage provide values that can change independently.
    • An implementation can share storage until a write.
    • Resources such as file streams use shared handles. Mutable captures still share the variable.

    Examples

    Assignment keeps array values independent

    example.tpzAssignment keeps array values independentOpen in Playground →
    1. import std.io
    2. let a = [1, 2]
    3. let mut b = a
    4. b.push(3)
    5. io.writeLine("{a.length}:{b.length}")
    Expected outputExit code 0
    2:3
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 2:3

    Return a changed local value from a function

    example.tpzReturn a changed local value from a functionOpen in Playground →
    1. import std.io
    2. function appended(values: Array<int>) -> Array<int> {
    3. let mut local = values
    4. local.push(3)
    5. local
    6. }
    7. let items = [1, 2]
    8. let changed = appended(items)
    9. io.writeLine("{items.length}:{changed.length}")
    Expected outputExit code 0
    2:3
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 2:3

    A saved record keeps its collection field

    example.tpzA saved record keeps its collection fieldOpen in Playground →
    1. import std.io
    2. let mut r = { items: [1, 2] }
    3. let saved = r
    4. r.items[0] = 5
    5. io.writeLine("{saved.items[0]}:{r.items[0]}")
    Expected outputExit code 0
    1:5
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 1:5

    Insert and remove entries in an independent Map value

    example.tpzInsert and remove entries in an independent Map valueOpen in Playground →
    1. import std.io
    2. let entries = map { "one": 1 }
    3. let mut changed = entries
    4. changed.insert("two", 2)
    5. io.writeLine("{entries.length}:{changed.length}")
    6. changed.remove("one")
    7. io.writeLine("{entries.keys[0]}:{changed.keys[0]}")
    Expected outputExit code 0
    1:2
    one:two
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 1:2
    2. one:two

    Add and remove members in an independent Set value

    example.tpzAdd and remove members in an independent Set valueOpen in Playground →
    1. import std.io
    2. let values = set { 1 }
    3. let mut changed = values
    4. changed.add(2)
    5. io.writeLine("{values.length}:{changed.length}")
    6. changed.remove(1)
    7. io.writeLine("{1 in values}:{1 in changed}")
    Expected outputExit code 0
    1:2
    true:false
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 1:2
    2. true:false

    A mutable capture changes one variable and preserves earlier values

    example.tpzA mutable capture changes one variable and preserves earlier valuesOpen in Playground →
    1. import std.io
    2. let mut items = [1]
    3. let before = items
    4. let append: () -> () = () => { items.push(2) }
    5. append()
    6. io.writeLine("{items.length}:{before.length}")
    Expected outputExit code 0
    2:1
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 2:1

    Alternatives considered

    • Share mutable storage when assigning a collection. Changing an alias could affect readers of the original value.

    Why

    Collection updates have a visible target, while shared handles still represent shared resources.

    Changed rules Collection values →Values observed by existing and escaping closures →

    A lambda defers a mutating method call

    Adopted November 16, 2026 · 6.0.0 · Being verified

    Problem

    After saving grid[i].push and changing i, it matters which cell the method updates. A read method and a mutator could capture different things under the same spelling.

    Decision

    • Reject a detached mutator such as let add = xs.push during checking.
    • Use let add = (v) => xs.push(v) to defer the call. Read methods can still be obtained as values.

    Examples

    Detached mutator wins over immutable root →

    Builtin read method may be detached

    example.tpzBuiltin read method may be detachedOpen in Playground →
    1. let xs = [1]
    2. let read = xs.get
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Lambda expresses a mutating callback

    example.tpzLambda expresses a mutating callbackOpen in Playground →
    1. let mut xs = [1]
    2. let add = (value: int) => xs.push(value)
    3. add(2)
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Alternatives considered

    • Let a detached mutator capture the receiver's variable or cell. Read methods would capture values while mutators capture variables. A changed index could make the method differ from a lambda.

    Why

    The lambda shows what will be evaluated and changed at the time of the call.

    Changed rules Mutation result consumption →

    Mutating a temporary requires using the result

    Adopted November 16, 2026 · 6.0.0 · Being verified

    Problem

    A call such as make().push(2) writes to a returned value with no binding to store it in. If the result is discarded as well, an intended update can silently do nothing.

    Decision

    • Reject a mutating call that has no root binding and discards its result during checking.
    • A call that uses its result is allowed, as in let last = make().pop().

    Examples

    Statement result discarded →

    Function argument consumes result

    example.tpzFunction argument consumes resultOpen in Playground →
    1. function make() -> Array<int> { [1, 2] }
    2. function log(value: Option<int>) -> () {}
    3. log(make().pop())
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Parentheses propagate discard

    example.tpzParentheses propagate discard
    1. function make() -> Array<int> { [1, 2] }
    2. (make().pop())
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    The required primary-location contract is Pending.

    Alternatives considered

    • Accept calls even when the result is discarded. A migration to value semantics could lose an update without a diagnostic.

    Why

    Use the needed result or put the receiver in a mutable binding before changing it.

    Changed rules Mutation result consumption →

    If without else always returns unit

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    With no else, it was unclear whether a caller could use the value from the true branch. The checker and code generator could disagree on that value's type.

    Decision

    An if without an else returns () even in a value context. Discard the value of the true branch.

    Examples

    An omitted else discards values and preserves selected effects

    example.tpzAn omitted else discards values and preserves selected effects
    1. import std.io
    2. let taken = if (true) {
    3. io.writeLine("then")
    4. 7
    5. }
    6. let skipped = if (false) {
    7. io.writeLine("unexpected")
    8. 9
    9. }
    10. io.writeLine("{taken}")
    11. io.writeLine("{skipped}")
    Expected outputExit code 0
    then
    ()
    ()
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. then
    2. ()
    3. ()

    A unit context accepts discarded non-unit branch values

    example.tpzA unit context accepts discarded non-unit branch values
    1. let taken: () = if (true) { 7 }
    2. let skipped: () = if (false) { "discarded" }
    Expected outputExit code 0
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    The inferred result can be assigned to unit

    example.tpzThe inferred result can be assigned to unit
    1. let inferred = if (true) { 7 }
    2. let checked: () = inferred
    Expected outputExit code 0
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    An omitted else cannot produce an int result

    example.tpzAn omitted else cannot produce an int resultOpen in Playground →
    1. let value: int = if (true) { 7 }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 →

      if-without-else-result-type-mismatch at example.tpz:1:18

    Alternatives considered

    • Return a union of the true branch's type and unit. The checker would assign a different type from the unit value already produced in execution.
    • Require else in a value position when the then value is not unit. It would not fit statement use or the current code generation, which always produces unit.

    Why

    The true branch can perform effects without changing the result type.

    Changed rules The unit type of if without else →Choosing an if branch →

    Resolved pending items Resolved: the unit result of if without else →Resolved: the unit result of if without else →

    A map fallback uses get with the defaulting operator

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A lookup can use a fallback when no value is found. If the fallback has an effect, its evaluation time matters.

    Decision

    • Write m.get(k) ?? fallback. The getOr method is removed.
    • Bind the fallback with let first if it needs to run before the lookup.

    Examples

    Evaluate a Map fallback when its key is absent

    example.tpzEvaluate a Map fallback when its key is absentOpen in Playground →
    1. import std.io
    2. function makeMap() -> Map<string, int> {
    3. io.writeLine("map")
    4. map { "present": 7 }
    5. }
    6. function makeKey(name: string) -> string {
    7. io.writeLine("key")
    8. name
    9. }
    10. function makeDefault() -> int {
    11. io.writeLine("fallback")
    12. 99
    13. }
    14. let present = makeMap().get(makeKey("present")) ?? makeDefault()
    15. io.writeLine("present={present}")
    16. let absent = makeMap().get(makeKey("missing")) ?? makeDefault()
    17. io.writeLine("absent={absent}")
    18. let inner: Option<int> = None()
    19. let nested = map { "present": inner }
    20. let payload: Option<int> = nested.get("present") ?? Some(99)
    21. io.writeLine("inner={payload ?? 77}")
    Expected outputExit code 0
    map
    key
    present=7
    map
    key
    fallback
    absent=99
    inner=77
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. map
    2. key
    3. present=7
    4. map
    5. key
    6. fallback
    7. absent=99
    8. inner=77

    Preserve eager fallback effects with ordered bindings

    example.tpzPreserve eager fallback effects with ordered bindingsOpen in Playground →
    1. import std.io
    2. function makeMap() -> Map<string, int> {
    3. io.writeLine("map")
    4. map { "present": 7 }
    5. }
    6. function makeKey(name: string) -> string {
    7. io.writeLine("key")
    8. name
    9. }
    10. function makeDefault() -> int {
    11. io.writeLine("fallback")
    12. 99
    13. }
    14. let receiver = makeMap()
    15. let key = makeKey("present")
    16. let default = makeDefault()
    17. let present = receiver.get(key) ?? default
    18. io.writeLine("present={present}")
    19. let absent = receiver.get("missing") ?? default
    20. io.writeLine("absent={absent}")
    Expected outputExit code 0
    map
    key
    fallback
    present=7
    absent=99
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. map
    2. key
    3. fallback
    4. present=7
    5. absent=99

    Alternatives considered

    • Keep getOr alongside the operator. The same lookup and fallback would have two forms.

    Why

    The code shows whether the fallback is evaluated on demand or in advance.

    Changed rules Map lookup and optional fallback →