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

    Functions and generics

    Lambda parameters use parentheses even when there is one

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    If a single parameter can omit parentheses, lambda syntax changes with arity. This can also mix with other expressions in a control header.

    Decision

    Put parentheses around every lambda parameter list.

    Examples

    Parenthesized lambda parameter lists

    example.tpzParenthesized lambda parameter listsOpen in Playground →
    1. import std.io { writeLine }
    2. let zero: () -> int = () => 0
    3. let one: (int) -> int = (value) => value + 1
    4. let typed: (int) -> int = (value: int) => value + 1
    5. let pair: (int, int) -> int = (left, right) => left + right
    6. writeLine("{zero()}")
    7. writeLine("{one(1)}")
    8. writeLine("{typed(2)}")
    9. writeLine("{pair(3, 4)}")
    Expected outputExit code 0
    0
    2
    3
    7
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 0
    2. 2
    3. 3
    4. 7

    A bare lambda parameter is rejected

    example.tpzA bare lambda parameter is rejectedOpen in Playground →
    1. let step: (int) -> int = value => value + 1
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      expected-statement-separator at example.tpz:1:32

    Alternatives considered

    • Keep the bare single-parameter form. The same lambda would retain two spellings.

    Why

    A lambda's parameter list is recognizable at any arity.

    Changed rules Lambda parameter lists →

    Variadic parameters have no defaults

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    A variadic parameter can receive no trailing arguments or an empty spread. A default would make it unclear whether an effectful expression runs in either case.

    Decision

    Reject a default on a variadic parameter.

    Examples

    A variadic parameter rejects a default initializer

    example.tpzA variadic parameter rejects a default initializer
    1. function count(...values: int = [1]) -> int { values.length }
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      function-variadic-default at example.tpz:1:31

    A fixed default does not permit a variadic default

    example.tpzA fixed default does not permit a variadic default
    1. function count(base: int = 10, ...values: int = [1]) -> int { base + values.length }
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      function-variadic-default at example.tpz:1:47

    Alternatives considered

    • Use the default when no trailing arguments arrive. Empty spreads would need a separate policy for defaults and their effects.
    • Always ignore the default and give an empty tail as an empty array. The evaluation and effects of the ignored expression would be unclear.

    Why

    An empty tail does not compete with evaluating a default. A function body chooses a fallback for an empty tail by checking its length.

    Changed rules Variadic parameters →Variadic placement, defaults, and call arguments →

    Resolved pending items Default values on variadic parameters →

    A type parameter's capabilities are explicit protocol bounds

    Adopted November 18, 2026 · 6.0.0 · Being verified

    Problem

    Accepting t.field in a generic function could require examining every concrete type used at calls. The requirements would be hidden until instantiation.

    Decision

    • A type parameter or opaque projection with no static member contract cannot read a field or call a method through a dot. The generic definition produces TPZ5006 during checking.
    • Apply the same check after alias expansion and optional unwrapping. Using ?. on a non-optional receiver produces TPZ5001.
    • Declare a required capability with T: P and call P.method(value).

    Examples

    A type parameter has no dot field

    example.tpzA type parameter has no dot field
    1. function read<T>(value: T) -> () {
    2. let field = value.field
    3. ()
    4. }
    Expected outputNonzero exit
    $ 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 concrete instantiation does not enable a generic dot method

    example.tpzA concrete instantiation does not enable a generic dot method
    1. record Item {}
    2. impl Item {
    3. function foo(self) -> int { 1 }
    4. }
    5. function invoke<T>(value: T) -> () {
    6. let result = value.foo()
    7. ()
    8. }
    9. invoke(Item {})
    Expected outputNonzero exit
    $ 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 declared protocol method is called through the protocol

    example.tpzA declared protocol method is called through the protocol
    1. protocol Readable {
    2. function read(value: Self) -> int
    3. }
    4. record Item { value: int }
    5. impl Readable<Item> {
    6. function read(value: Item) -> int { value.value }
    7. }
    8. function read<T: Readable>(value: T) -> int {
    9. value.read()
    10. }
    Expected outputNonzero exit
    $ 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.

    Optional unwrapping retains the rigid member restriction

    example.tpzOptional unwrapping retains the rigid member restriction
    1. function invoke<T>(value: Option<T>) -> () {
    2. let result = value?.foo()
    3. ()
    4. }
    Expected outputNonzero exit
    $ 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.

    Optional access requires an optional receiver

    example.tpzOptional access requires an optional receiverOpen in Playground →
    1. function invoke<T>(value: T) -> () {
    2. let result = value?.foo()
    3. ()
    4. }
    Expected outputNonzero exit
    $ 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.

    An opaque structural projection has no hidden method

    example.tpzAn opaque structural projection has no hidden method
    1. function inspect<T>(value: T) -> () {
    2. match (value) {
    3. case { child: child } => {
    4. let result = child.hidden()
    5. ()
    6. }
    7. case _ => ()
    8. }
    9. }
    Expected outputNonzero exit
    $ 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 protocol bound makes the required generic call explicit

    example.tpzA protocol bound makes the required generic call explicitOpen in Playground →
    1. protocol Readable {
    2. function read(value: Self) -> int
    3. }
    4. record Item { value: int }
    5. impl Readable<Item> {
    6. function read(value: Item) -> int { value.value }
    7. }
    8. function read<T: Readable>(value: T) -> int {
    9. Readable.read(value)
    10. }
    11. let result: int = read(Item { value: 7 })
    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

    • Resolve dot members only after substituting a concrete type. Every instantiation would have to decide capabilities and diagnostics again, including access to private members.
    • Keep the current behavior. Access to private methods would leak.

    Why

    Developers can read the function's requirements in its declaration and check them at its definition.

    Changed rules Declaring type parameters →

    Calls use positional arguments and records carry named options

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    Moving a call into a callback gets harder when functions use different rules for named and positional arguments. Independent options still need readable names.

    Decision

    • Use positional arguments for calls. Named call arguments are unavailable.
    • Place required parameters before defaulted parameters and the variadic parameter last.
    • Pass independent options in a record with named fields.

    Examples

    Named form

    example.tpzNamed form
    1. function pick(value: int) -> int { value }
    2. pick(value: 3)
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during parse. Nonzero exit.

    • TPZ2001 →

      function-named-call-syntax at example.tpz:2:11

    Positional defaults

    example.tpzPositional defaultsOpen in Playground →
    1. import std.io { writeLine }
    2. function add(left: int, right: int = 2) -> int { left + right }
    3. let callback: (int, int) -> int = (left, right) => left + right
    4. writeLine("{add(3)}:{add(3, 4)}:{callback(3, 4)}")
    Expected outputExit code 0
    5:7:7
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 5:7:7

    Record fields preserve settings when reordered

    example.tpzRecord fields preserve settings when reorderedOpen in Playground →
    1. import std.io { writeLine }
    2. function dimensions(settings: { width: int, height: int }) -> string {
    3. "{settings.width}x{settings.height}"
    4. }
    5. let width = 80
    6. let height = 24
    7. let describe: ({ width: int, height: int }) -> string = dimensions
    8. writeLine(dimensions({ width: width, height: height }))
    9. writeLine(dimensions({ height: height, width: width }))
    10. writeLine(describe({ height: height, width: width }))
    Expected outputExit code 0
    80x24
    80x24
    80x24
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 80x24
    2. 80x24
    3. 80x24

    Alternatives considered

    • Let each declaration choose its calling style. Passing a function value would also require knowing that declaration's calling rules.
    • Add named arguments to every call. Function types and callbacks need one call rule.

    Why

    Functions and callbacks share one call syntax, and option names belong to the data.

    Changed rules Argument shapes →Variadic placement, defaults, and call arguments →

    Explicit type arguments follow a name or member access

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    Putting <T> after a grouped callee creates another place where a comparison and a call must be distinguished. The distinction can depend on how the callee was written.

    Decision

    Write explicit type arguments after a name or member access. A <T> after a parenthesized expression does not supply type arguments to a call.

    Examples

    A name accepts explicit type arguments

    example.tpzA name accepts explicit type argumentsOpen in Playground →
    1. import std.io { writeLine }
    2. function identity<T>(value: T) -> T { value }
    3. let value: int = identity<int>(1)
    4. writeLine("{value}")
    Expected outputExit code 0
    1
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 1

    A member access accepts explicit type arguments

    example.tpzA member access accepts explicit type arguments
    1. import std.io { writeLine }
    2. import helpers
    3. let value: int = helpers.identity<int>(2)
    4. writeLine("{value}")
    Expected outputExit code 0
    2
    
    $ topaz run example.tpz --language-version 6.0
    helpers.tpzA member access accepts explicit type arguments
    1. export function identity<T>(value: T) -> T { value }
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 2

    A parenthesized callee infers type arguments

    example.tpzA parenthesized callee infers type argumentsOpen in Playground →
    1. import std.io { writeLine }
    2. function identity<T>(value: T) -> T { value }
    3. let value: int = (identity)(3)
    4. writeLine("{value}")
    Expected outputExit code 0
    3
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 3

    A parenthesized expression does not introduce explicit type arguments

    example.tpzA parenthesized expression does not introduce explicit type arguments
    1. function identity<T>(value: T) -> T { value }
    2. let value: int = (identity)<int>(1)
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5002 →

      function-parenthesized-callee-type-argument at example.tpz:2:29

    Alternatives considered

    • Allow type arguments after any callee expression. The parser would have more places to distinguish type arguments from comparisons.

    Why

    A grouped callee still refers to its declaration. Call the name directly to specify types or let the compiler infer them. If real use appears, explicit type arguments on a computed callee will be reviewed again.

    Changed rules Generic calls →

    Whitespace between type arguments and the call does not change the parse

    Adopted November 16, 2026 · 6.0.0 · In progress

    Problem

    A space could make identity<int>(1) and identity<int> (1) parse differently. The grammar needs a way to distinguish an intended comparison.

    Decision

    • After a name or member, parse type arguments when < and > enclose a type-list shape and the next token is (. Ignore whitespace and line breaks for this test.
    • Otherwise < begins a comparison. Parentheses can make an intended comparison explicit.
    • Checking rejects a non-generic callee or an invalid type argument and suggests parenthesizing an intended comparison.

    Examples

    Adjacent explicit type argument

    example.tpzAdjacent explicit type argumentOpen in Playground →
    1. function identity<T>(value: T) -> T {
    2. value
    3. }
    4. let explicit: int = identity<int>(1)
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Spaced explicit type argument

    example.tpzSpaced explicit type argumentOpen in Playground →
    1. function identity<T>(value: T) -> T {
    2. value
    3. }
    4. let explicit: int = identity<int> (1)
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    A non-generic call has no type arguments

    example.tpzA non-generic call has no type argumentsOpen in Playground →
    1. function identity(value: int) -> int { value }
    2. identity<int>(1)
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5512 →

      function-non-generic-type-arguments at example.tpz:2:1

    Alternatives considered

    • Read it as a call only when the closing angle and opening parenthesis touch. One space would change the meaning of the program.
    • Spell type arguments at a call with a separate leading symbol. Type arguments would then have two spellings for the same intent.
    • Reject the form as ambiguous in the parser. The parser cannot tell a type from a value, so it would also reject valid generic calls inside an argument list.
    • Make comparison operators non-associative. It does not resolve the case inside a comma-separated argument list.

    Why

    The same tokens specify the same call regardless of layout.

    Changed rules Generic calls →

    An argument in a union call has one type across branches

    Adopted November 18, 2026 · 6.0.0 · In progress

    Problem

    A method or function field can be called on a receiver with several possible types. Previously, the same unannotated lambda could be checked with a different type in each branch.

    Decision

    • Use independent arguments to instantiate the branch signatures first. Use context for a position such as a lambda parameter or result only if all concrete branches give that position the same type.
    • Give each argument expression one final type and check it against each concrete branch. Missing context produces TPZ5020, while a known incompatible type produces TPZ5001 during checking.
    • A branch represented by a rigid type parameter provides no context. The result combines the possible branch results into a union.
    • Evaluate the callee and explicit arguments once in source order, then fill in only the actual branch’s defaults.

    Examples

    Matching callback parameters provide one lambda context

    example.tpzMatching callback parameters provide one lambda contextOpen in Playground →
    1. function call(value: { f: ((int) -> int) -> int } | { f: ((int) -> int) -> string }) -> int | string {
    2. value.f((n) => n + 1)
    3. }
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Common parameter context survives different return expectations

    example.tpzCommon parameter context survives different return expectationsOpen in Playground →
    1. function call(value: { f: ((int) -> int) -> int } | { f: ((int) -> (int | string)) -> string }) -> int | string {
    2. value.f((n) => n + 1)
    3. }
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Divergent callback parameters require an annotation in 6.0

    example.tpzDivergent callback parameters require an annotation in 6.0
    1. function call(value: { f: ((int) -> int) -> int } | { f: ((string) -> int) -> int }) -> int {
    2. value.f((n) => 0)
    3. }
    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.

    One annotated lambda satisfies both parameter contracts

    example.tpzOne annotated lambda satisfies both parameter contractsOpen in Playground →
    1. function call(value: { f: ((int) -> int) -> int } | { f: ((string) -> int) -> int }) -> int {
    2. value.f((n: int | string) => 0)
    3. }
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    An annotation cannot repair a contradictory callback type

    example.tpzAn annotation cannot repair a contradictory callback type
    1. function call(value: { f: ((int) -> int) -> int } | { f: ((string) -> int) -> int }) -> int {
    2. value.f((n: int) => 0)
    3. }
    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.

    Independent arguments establish shared generic callback context

    example.tpzIndependent arguments establish shared generic callback context
    1. record First {}
    2. record Second {}
    3. impl First {
    4. function apply<U>(self, seed: U, callback: (U) -> int) -> int { callback(seed) }
    5. }
    6. impl Second {
    7. function apply<V>(self, seed: V, callback: (V) -> int) -> int { callback(seed) }
    8. }
    9. function call(value: First | Second) -> int {
    10. value.apply(1, (n) => n + 1)
    11. }
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Different collection arms do not choose an empty array type

    example.tpzDifferent collection arms do not choose an empty array type
    1. function call(value: { f: (Array<int>) -> int } | { f: (Array<string>) -> int }) -> int {
    2. value.f([])
    3. }
    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

    • Check the lambda separately in each branch. A single expression would have different types and diagnostics depending on the branch.
    • Merge expected types across branches, or require identical signatures. Merging would need a second set of inference rules. Requiring identical signatures would reject arguments that satisfy every branch.

    Why

    Argument types and diagnostics are independent of branch order, and one annotation can express the caller’s intent when context is missing.

    Changed rules Parameter annotations, lambdas, and receivers →Evaluation, binding, and type inference at a call →

    Each parameter name appears once in its list

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    If two parameters have the same name, a reference in the body needs a way to choose between their arguments. Shadowing can leave one argument inaccessible by name.

    Decision

    Reject a repeated name within one parameter list in named functions and lambdas.

    Examples

    Distinct parameter names in functions and lambdas

    example.tpzDistinct parameter names in functions and lambdasOpen in Playground →
    1. import std.io { writeLine }
    2. function add(left: int, right: int) -> int { left + right }
    3. let addLambda: (int, int) -> int = (left, right) => left + right
    4. writeLine("{add(1, 2)}")
    5. writeLine("{addLambda(3, 4)}")
    Expected outputExit code 0
    3
    7
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 3
    2. 7

    A named function rejects a repeated parameter name

    example.tpzA named function rejects a repeated parameter name
    1. function choose(value: int, value: int) -> int { value }
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5008 →

      bindings-local-same-scope-redeclaration at example.tpz:1:29

    A lambda rejects a repeated parameter name

    example.tpzA lambda rejects a repeated parameter name
    1. let choose: (int, int) -> int = (value, value) => value
    Expected outputNonzero exit
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5008 →

      bindings-local-same-scope-redeclaration at example.tpz:1:41

    Separate parameter lists may reuse a name

    example.tpzSeparate parameter lists may reuse a nameOpen in Playground →
    1. import std.io { writeLine }
    2. function outer(value: int) -> int {
    3. let next: (int) -> int = (value) => value + 1
    4. next(value)
    5. }
    6. writeLine("{outer(4)}")
    Expected outputExit code 0
    5
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 5

    Alternatives considered

    • Accept both arguments by position, let the later name shadow the earlier one, and reject only an ambiguous named argument. A name must mean one thing in the declaration and in a named call.

    Why

    Each parameter name identifies one argument.

    Changed rules Unique parameter names →

    Resolved pending items Complete parameter sequences, lambda typing, and receivers →