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

    Structures

    Decimal rounding modes form an ordinary enum

    Adopted November 17, 2026 · 6.0.0 · Being verified

    Problem

    A special rounding type can look like an enum while behaving differently in patterns or map keys. Code that handles every mode can then fail unexpectedly.

    Decision

    • RoundingMode is an ordinary enum with six variants. Write RoundingMode.HalfEven() as a value and case HalfEven() as a pattern.
    • Use ordinary enum rules for exhaustiveness, equality, display and map or set keys.

    Examples

    Six constructor patterns exhaust RoundingMode

    example.tpzSix constructor patterns exhaust RoundingMode
    1. import std.decimal { RoundingMode }
    2. import std.io { writeLine }
    3. function describe(mode: RoundingMode) -> string {
    4. match (mode) {
    5. case HalfEven() => "half even"
    6. case HalfUp() => "half up"
    7. case TowardZero() => "toward zero"
    8. case AwayFromZero() => "away from zero"
    9. case Down() => "down"
    10. case Up() => "up"
    11. }
    12. }
    13. for mode in ([RoundingMode.HalfEven(), RoundingMode.HalfUp(), RoundingMode.TowardZero(), RoundingMode.AwayFromZero(), RoundingMode.Down(), RoundingMode.Up()]) {
    14. writeLine(describe(mode))
    15. }
    Expected outputExit code 0
    half even
    half up
    toward zero
    away from zero
    down
    up
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. half even
    2. half up
    3. toward zero
    4. away from zero
    5. down
    6. up

    Omitting one RoundingMode variant is not exhaustive

    example.tpzOmitting one RoundingMode variant is not exhaustive
    1. import std.decimal { RoundingMode }
    2. function describe(mode: RoundingMode) -> string {
    3. match (mode) {
    4. case HalfEven() => "half even"
    5. case HalfUp() => "half up"
    6. case TowardZero() => "toward zero"
    7. case AwayFromZero() => "away from zero"
    8. case Down() => "down"
    9. }
    10. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    RoundingMode values are Map keys and Set elements

    example.tpzRoundingMode values are Map keys and Set elements
    1. let modes: Map<RoundingMode, int> = map { RoundingMode.HalfEven(): 1 }
    2. let selected: Set<RoundingMode> = set { RoundingMode.HalfEven(), RoundingMode.Up() }
    Expected outputExit code 0
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    A bare HalfEven binder collides with the enum constructor

    example.tpzA bare HalfEven binder collides with the enum constructor
    1. function describe(mode: RoundingMode) -> int {
    2. match (mode) {
    3. case HalfEven => 1
    4. }
    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:3:10

    Alternatives considered

    • Keep a special type and add constructor patterns alone. Patterns would work while keys and other uses retained separate rules.
    • Forbid patterns and allow only ==. An exhaustive match would be rejected, and there would be two kinds of constructors.

    Why

    Rounding modes use the same conventions as other enum variants without payloads.

    Changed rules Variants without payloads →Every match is exhaustive →

    An enum payload can use a union containing an enum

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A variant may carry one of several types, including another enum. Requiring a wrapper only when the type is written as a union adds an extra step.

    Decision

    Permit a union containing an enum as a variant payload.

    Examples

    Construct and match both union payload alternatives

    example.tpzConstruct and match both union payload alternatives
    1. import std.io { writeLine }
    2. enum Inner { Leaf }
    3. enum Outer { Wrapped(Inner | int) }
    4. function describe(value: Outer) -> string {
    5. match (value) {
    6. case Wrapped(payload) => match (payload) {
    7. case number: int => "{number}"
    8. case _ => "leaf"
    9. }
    10. }
    11. }
    12. writeLine(describe(Outer.Wrapped(Inner.Leaf())))
    13. writeLine(describe(Outer.Wrapped(7)))
    Expected outputExit code 0
    leaf
    7
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. leaf
    2. 7

    Alternatives considered

    • Require a wrapper for such unions. Storing the same values would require an extra type declaration.
    • Forbid unions that contain enums. Whether a type is allowed should not depend on how directly it is written.

    Why

    The declared type can be used directly in the payload.

    Changed rules Variants with payloads →Enum declarations and payload types →

    Enum variants can use prelude constructor names

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    A domain enum may naturally have a variant called None or Ok. A repeated name needs to be disambiguated by type.

    Decision

    • Allow None, Some, Ok and Err as enum variant names. The declaring nominal type identifies the variant.
    • If a union makes the name ambiguous, narrow it with an existing type pattern.

    Examples

    Enum variants and prelude constructors retain separate identities

    example.tpzEnum variants and prelude constructors retain separate identities
    1. import std.io { writeLine }
    2. enum Reply { None, Some(int), Ok(string), Err(bool) }
    3. function describe(value: Reply) -> string {
    4. match (value) {
    5. case None() => "enum none"
    6. case Some(number) => "enum some {number}"
    7. case Ok(text) => "enum ok {text}"
    8. case Err(flag) => if (flag) { "enum error" } else { "enum false" }
    9. }
    10. }
    11. function option(value: Option<int>) -> string {
    12. match (value) {
    13. case None() => "option none"
    14. case Some(number) => "option some {number}"
    15. }
    16. }
    17. function result(value: Result<int, string>) -> string {
    18. match (value) {
    19. case Ok(number) => "result ok {number}"
    20. case Err(text) => "result error {text}"
    21. }
    22. }
    23. writeLine(describe(Reply.None()))
    24. writeLine(describe(Reply.Some(4)))
    25. writeLine(describe(Reply.Ok("yes")))
    26. writeLine(describe(Reply.Err(true)))
    27. writeLine(option(None()))
    28. writeLine(option(Some(5)))
    29. writeLine(result(Ok(6)))
    30. writeLine(result(Err("no")))
    Expected outputExit code 0
    enum none
    enum some 4
    enum ok yes
    enum error
    option none
    option some 5
    result ok 6
    result error no
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. enum none
    2. enum some 4
    3. enum ok yes
    4. enum error
    5. option none
    6. option some 5
    7. result ok 6
    8. result error no

    Typed narrowing distinguishes an enum Ok from a Result Ok

    example.tpzTyped narrowing distinguishes an enum Ok from a Result Ok
    1. import std.io { writeLine }
    2. enum Reply { Ok(int) }
    3. function describe(value: Reply | Result<int, string>) -> string {
    4. match (value) {
    5. case reply: Reply => match (reply) { case Ok(number) => "reply {number}" }
    6. case result: Result<int, string> => match (result) {
    7. case Ok(number) => "result {number}"
    8. case Err(text) => text
    9. }
    10. }
    11. }
    12. let result: Result<int, string> = Ok(8)
    13. writeLine(describe(Reply.Ok(7)))
    14. writeLine(describe(result))
    Expected outputExit code 0
    reply 7
    result 8
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. reply 7
    2. result 8

    Reject a shared bare constructor head before inspecting its payload

    example.tpzReject a shared bare constructor head before inspecting its payload
    1. enum Left { Shared(int) }
    2. enum Right { Shared(int) }
    3. function describe(value: Left | Right) -> int {
    4. match (value) {
    5. case Shared(number) => number
    6. case _ => 0
    7. }
    8. }
    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 →

      structures-ambiguous-constructor-pattern at example.tpz:5: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

    Alternatives considered

    • Reserve prelude names inside enum declarations. An unrelated type could not use the same name for its own variant.
    • Add qualified enum names to patterns. The existing type pattern is already the one way to narrow an ambiguous case.

    Why

    Names belong to their declaring types, and normal narrowing resolves ambiguity.

    Changed rules Variant names and prelude constructors →

    A structural record update writes each field once

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    When a field occurs twice in an update, the result can depend on order. The earlier change may silently disappear.

    Decision

    Reject duplicate field names in the same structural record update.

    Examples

    A structural update cannot repeat a field

    example.tpzA structural update cannot repeat a field
    1. let point = { x: 1 }
    2. let moved = point {
    3. x: 2,
    4. x: 3,
    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.

    • TPZ5008 →

      duplicate-record-field-initializer at example.tpz:4:3

    One explicit initializer can replace a copied field

    example.tpzOne explicit initializer can replace a copied fieldOpen in Playground →
    1. import std.io
    2. record Point { x: int }
    3. let original = { x: 1 }
    4. let updated = original { x: 2 }
    5. let named = Point { x: 3 }
    6. let copied = Point { ...named, x: 4 }
    7. io.writeLine("{updated.x}:{original.x}:{copied.x}:{named.x}")
    Expected outputExit code 0
    2:1:4:3
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 2:1:4:3

    Alternatives considered

    • Let the last value win. Reordering fields could change the result.

    Why

    Each field has one explicit update value.

    Changed rules Repeated structural update fields →

    A constructor requires arguments even in a value position

    Adopted November 18, 2026 · 6.0.0 · Being verified

    Problem

    A constructor name used like a function value could pass checking and fail later. Different constructors could give different diagnostics for the same spelling.

    Decision

    • Use Name(arguments) in a value position. A missing argument list produces TPZ5004 during checking. Bare None produces TPZ2012 during parsing under the reserved-name rule.
    • To pass a constructor operation as a function value, call it with arguments inside a lambda.

    Examples

    Bare payload variant is rejected

    example.tpzBare payload variant is rejectedOpen in Playground →
    1. enum Choice { Full(int), Empty }
    2. let make = Choice.Full
    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.

    Bare empty variant is rejected

    example.tpzBare empty variant is rejected
    1. enum Choice { Full(int), Empty }
    2. let value = Choice.Empty
    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.

    Bare Some is rejected

    example.tpzBare Some is rejected
    1. let make = Some
    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.

    Bare Ok is rejected

    example.tpzBare Ok is rejected
    1. let make = Ok
    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.

    Empty variant uses parentheses

    example.tpzEmpty variant uses parenthesesOpen in Playground →
    1. enum Choice { Full(int), 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.

    Alternatives considered

    • Treat payload constructors as first-class functions. The same name could be a constructor or a callable function depending on position.
    • Keep the existing diagnostic that differs by constructor. The same mistake would get a different diagnostic per constructor, without one fix.

    Why

    Code shows when it constructs a value and when it creates a function to invoke later.

    Changed rules Bare constructor references →Bare None in value position →Constructors in function values →

    Self names the type that conforms to a protocol

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    A parameter naming the conforming type could give the same role a different name in each protocol. That role needs to be recognizable.

    Decision

    Protocol declarations take no type parameters of their own. Write Self for the conforming type.

    Examples

    Reject an explicit protocol receiver binder

    example.tpzReject an explicit protocol receiver binder
    1. protocol Labelled<T> {
    2. function label(value: T) -> string
    3. }
    4. record Item { name: string }
    5. impl Labelled<Item> {
    6. function label(value: Item) -> string { value.name }
    7. }
    8. let text: string = Labelled.label(Item { name: "Moss" })
    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 →

      protocol-explicit-receiver-binder at example.tpz:1:18

    Use Self for the conforming type

    example.tpzUse Self for the conforming typeOpen in Playground →
    1. protocol Labelled {
    2. function label(value: Self) -> string
    3. }
    4. record Item { name: string }
    5. impl Labelled<Item> {
    6. function label(value: Item) -> string { value.name }
    7. }
    8. let text: string = Labelled.label(Item { name: "Moss" })
    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

    • Alias the receiver with protocol P<T>. The same role would have a different name across protocols.

    Why

    The conforming type is recognizable in any protocol declaration.

    Changed rules Protocol declarations use Self →

    Protocol signatures use ordinary function declaration rules

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A protocol function could otherwise need its own syntax for parameters and defaults. With no body, there is also no expression from which to infer a return type.

    Decision

    • Use ordinary generic, variadic and default parameter rules. The first value parameter need not be Self.
    • Write the return type when the signature has no body.

    Examples

    Implementation binders and renamed method binders remain distinct

    example.tpzImplementation binders and renamed method binders remain distinct
    1. import std.io { writeLine }
    2. protocol Echo {
    3. function echo<U: Show>(value: Self, item: U) -> U
    4. }
    5. record Box<T> { value: T }
    6. impl<T> Echo<Box<T>> {
    7. function echo<V: Show>(value: Box<T>, item: V) { item }
    8. }
    9. let box: Box<int> = Box { value: 3 }
    10. writeLine(Echo.echo<Box<int>, string>(box, "ok"))
    11. let inferred: int = Echo.echo(box, 9)
    12. writeLine("{inferred}")
    Expected outputExit code 0
    ok
    9
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. ok
    2. 9

    Protocol defaults and a variadic implementation share one call plan

    example.tpzProtocol defaults and a variadic implementation share one call plan
    1. import std.io { writeLine }
    2. protocol Sum {
    3. function sum(value: Self, start: int = 10, ...items: int) -> int
    4. }
    5. record Item { offset: int }
    6. impl Sum<Item> {
    7. function sum(value: Item, start: int, ...items: int) {
    8. let mut total = value.offset + start
    9. for item in (items) { total = total + item }
    10. total
    11. }
    12. }
    13. let item = Item { offset: 1 }
    14. writeLine("{Sum.sum(item)}")
    15. writeLine("{Sum.sum(item, 2, ...[3, 4], 5)}")
    16. writeLine("{Sum.sum(item, ...[2, 3])}")
    Expected outputExit code 0
    11
    15
    16
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 11
    2. 15
    3. 16

    An omitted implementation result uses the protocol result context

    example.tpzAn omitted implementation result uses the protocol result context
    1. protocol Choose {
    2. function choose(value: Self) -> int | string
    3. }
    4. record Item {}
    5. impl Choose<Item> {
    6. function choose(value: Item) { 7 }
    7. }
    8. let chosen: int | string = Choose.choose(Item {})
    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

    • Add a protocol-specific callable syntax. The same function contract would need two grammars.
    • Keep forbidding function signatures in protocols. Functions need one declaration rule.

    Why

    Ordinary function declarations prepare readers for protocol signatures.

    Changed rules Matching the protocol signature →Protocol bodies →

    Protocol implementations inherit defaults and visibility from their contracts

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    Redeclaring a default or visibility in each implementation can change the meaning of one protocol call. Overlapping implementations also need a clear rule.

    Decision

    • Implementation methods may be generic or variadic and omit return annotations. They cannot redeclare defaults or export themselves separately.
    • Reject overlap across the dependency graph for both manual and derived implementations.

    Examples

    Implementation binders and renamed method binders remain distinct →

    Protocol defaults and a variadic implementation share one call plan →

    An omitted implementation result uses the protocol result context →

    Conformance visibility makes a separate method export invalid

    example.tpzConformance visibility makes a separate method export invalidOpen in Playground →
    1. protocol Labelled {
    2. function label(value: Self) -> string
    3. }
    4. record Item {}
    5. impl Labelled<Item> {
    6. export function label(value: Item) -> string { "item" }
    7. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    An implementation cannot introduce its own omitted argument

    example.tpzAn implementation cannot introduce its own omitted argumentOpen in Playground →
    1. protocol Labelled {
    2. function label(value: Self, suffix: string) -> string
    3. }
    4. record Item {}
    5. impl Labelled<Item> {
    6. function label(value: Item, suffix: string = "!") -> string { suffix }
    7. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    A conditional derive and a manual specialization share the overlap check

    example.tpzA conditional derive and a manual specialization share the overlap check
    1. record Box<T> derives<T: Eq> Eq<Box<T>> { value: T }
    2. impl Eq<Box<int>> {
    3. function equals(a: Box<int>, b: Box<int>) -> bool { a.value == b.value }
    4. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5521 →

      duplicate-protocol-conformance at example.tpz:1:30

    Alternatives considered

    • Use separate implementation functions and a precedence rule. Callers would have to recheck defaults and visibility, and order would affect which implementation runs.
    • Keep the current restriction on implementation methods. Defaults and visibility need one owner.

    Why

    The contract establishes call defaults and implementations remain unambiguous.

    Changed rules Implementation methods use ordinary functions →One conformance across the dependency graph →

    Imported conformance visibility does not depend on how it is defined

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    If manual and derived conformances have different visibility, changing how one is declared could break an importing caller. A manual method also needs a defined implementation to run.

    Decision

    Manual and derived conformances follow the same import visibility. A manual method invokes the implementation from its defining module.

    Examples

    A manual conformance is visible through a nominal import

    example.tpzA manual conformance is visible through a nominal import
    1. import remote { Item as RemoteItem }
    2. let imported = RemoteItem { n: 1 }
    3. let same = Eq.equals(imported, imported)
    Expected outputExit code 0
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    remote.tpzA manual conformance is visible through a nominal import
    1. export record Item { n: int }
    2. impl Eq<Item> {
    3. function equals(a: Item, b: Item) -> bool { a.n == b.n }
    4. }
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    A derived conformance is visible through a nominal import

    example.tpzA derived conformance is visible through a nominal import
    1. import remote { Item as RemoteItem }
    2. let imported = RemoteItem { n: 1 }
    3. let same = Eq.equals(imported, imported)
    Expected outputExit code 0
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    remote.tpzA derived conformance is visible through a nominal import
    1. export record Item derives Eq { n: int }
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    An imported protocol call executes its manual method

    example.tpzAn imported protocol call executes its manual method
    1. import std.io { writeLine }
    2. import remote { Item as RemoteItem }
    3. let left = RemoteItem { n: 1 }
    4. let right = RemoteItem { n: 11 }
    5. writeLine("{Eq.equals(left, right)}")
    Expected outputExit code 0
    true
    
    $ topaz run example.tpz --language-version 6.0
    remote.tpzAn imported protocol call executes its manual method
    1. export record Item { n: int }
    2. impl Eq<Item> {
    3. function equals(a: Item, b: Item) -> bool { a.n % 10 == b.n % 10 }
    4. }
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. true

    Alternatives considered

    • Give the two kinds of conformance different visibility. Changing how a conformance is provided could change importing code.

    Why

    Importing code can read one visibility contract.

    Changed rules Conformance across modules →

    Manual JSON conformance uses encode and decode

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A type may need a custom JSON conversion. Users need a place to define the operations and a consistent way to decode an existing tree.

    Decision

    • Manual conformance supplies ordinary encode and decode methods.
    • Decode a tree with JSON.decode<T>(tree). The JSONValue.decode<T>() method is removed.

    Examples

    A manual JSON implementation supplies both conversions

    example.tpzA manual JSON implementation supplies both conversions
    1. import std.json { JSONValue }
    2. record Token { text: string }
    3. impl JSON<Token> {
    4. function encode(value: Token) -> Result<JSONValue, string> {
    5. JSON.encode(value.text)
    6. }
    7. function decode(value: JSONValue) -> Result<Token, string> {
    8. match (value.asString()) {
    9. case Some(text) => Ok(Token { text: text })
    10. case None() => Err("expected token string")
    11. }
    12. }
    13. }
    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.

    Text and tree conversion use the same manual JSON implementation

    example.tpzText and tree conversion use the same manual JSON implementation
    1. import std.io { writeLine }
    2. import std.json { JSONValue, parse, parseAs, stringify }
    3. record Token { text: string }
    4. impl JSON<Token> {
    5. function encode(value: Token) -> Result<JSONValue, string> {
    6. JSON.encode(value.text)
    7. }
    8. function decode(value: JSONValue) -> Result<Token, string> {
    9. match (value.asString()) {
    10. case Some(text) => Ok(Token { text: text })
    11. case None() => Err("expected token string")
    12. }
    13. }
    14. }
    15. writeLine(match (stringify(Token { text: "paper" })) {
    16. case Ok(text) => text
    17. case Err(message) => message
    18. })
    19. writeLine(match (parseAs<Token>("\"paper\"")) {
    20. case Ok(value) => value.text
    21. case Err(message) => message
    22. })
    23. writeLine(match (parseAs<Token>("17")) {
    24. case Ok(value) => value.text
    25. case Err(message) => message
    26. })
    27. writeLine(match (parse("\"ink\"")) {
    28. case Ok(tree) => match (JSON.decode<Token>(tree)) {
    29. case Ok(value) => value.text
    30. case Err(message) => message
    31. }
    32. case Err(_) => "parse failed"
    33. })
    Expected outputExit code 0
    "paper"
    paper
    expected token string
    ink
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. "paper"
    2. paper
    3. expected token string
    4. ink

    An empty JSON marker omits the required conversion methods

    example.tpzAn empty JSON marker omits the required conversion methodsOpen in Playground →
    1. record Token { text: string }
    2. impl JSON<Token> {}
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    JSONValue decoding uses the ordinary protocol call

    example.tpzJSONValue decoding uses the ordinary protocol call
    1. import std.json { JSONValue }
    2. function read(tree: JSONValue) -> Result<int, string> {
    3. tree.decode<int>()
    4. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0 --format json
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    Decode a JSONValue with one protocol-qualified form

    example.tpzDecode a JSONValue with one protocol-qualified form
    1. import std.json { JSONValue }
    2. function read(tree: JSONValue) -> Result<int, string> {
    3. JSON.decode<int>(tree)
    4. }
    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

    • Keep marker-only conformance or prohibit manual implementations. Custom and derived conversions could not share the same operation contract.

    Why

    Custom and derived conversions use the same operations, with a single entry point for decoding a tree.

    Changed rules JSON conformance →

    Using cleans up on normal and structured early exit

    Adopted November 7, 2026 · 5.21 line · Being verified

    Problem

    A file opened in a using block needs closing when the block finishes or returns early. Callers also need to know what a fault or a second close means for that guarantee.

    Decision

    • using cleanup runs on normal and structured early exit.
    • Cleanup during ordinary runtime faults and repeated close calls fall outside the cross-host guarantee.

    Examples

    Acquire once, run body defers, then close

    example.tpzAcquire once, run body defers, then close
    1. import std.io
    2. let mut acquisitions = 0
    3. let mut later: () -> string = () => "unset"
    4. function acquire() -> Result<File, string> {
    5. acquisitions += 1
    6. io.open("input.txt")
    7. }
    8. function scenario() -> Result<int, string> {
    9. using file = (acquire()?) {
    10. later = () => match (file.read()) {
    11. case Ok(text) => text
    12. case Err(e) => e
    13. }
    14. defer { io.writeLine(match (file.read()) {
    15. case Ok(text) => "defer:{text}"
    16. case Err(e) => "defer:{e}"
    17. }) }
    18. io.writeLine("body")
    19. 99
    20. }
    21. Ok(7)
    22. }
    23. let ignored = scenario()
    24. io.writeLine("acquisitions:{acquisitions}")
    25. io.writeLine(later())
    Expected outputExit code 0
    body
    defer:payload
    acquisitions:1
    file is closed
    
    $ topaz run example.tpz · Target product 5.21.3
    input.txtAcquire once, run body defers, then close
    1. payload
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. body
    2. defer:payload
    3. acquisitions:1
    4. file is closed

    Close on return, propagation, break, and continue

    example.tpzClose on return, propagation, break, and continue
    1. import std.io
    2. let mut later: () -> string = () => "unset"
    3. function fail() -> Result<int, string> { Err("stop") }
    4. function onReturn() -> Result<int, string> {
    5. using file = (io.open("input.txt")?) {
    6. later = () => match (file.read()) {
    7. case Ok(text) => text
    8. case Err(e) => e
    9. }
    10. return Ok(7)
    11. }
    12. Ok(0)
    13. }
    14. let ignoredonReturn = onReturn()
    15. io.writeLine("onReturn:{later()}")
    16. function onQuestion() -> Result<int, string> {
    17. using file = (io.open("input.txt")?) {
    18. later = () => match (file.read()) {
    19. case Ok(text) => text
    20. case Err(e) => e
    21. }
    22. fail()?
    23. }
    24. Ok(0)
    25. }
    26. let ignoredonQuestion = onQuestion()
    27. io.writeLine("onQuestion:{later()}")
    28. function onBreak() -> Result<int, string> {
    29. let mut i = 0
    30. while (i < 1) {
    31. using file = (io.open("input.txt")?) {
    32. later = () => match (file.read()) {
    33. case Ok(text) => text
    34. case Err(e) => e
    35. }
    36. break
    37. }
    38. }
    39. Ok(0)
    40. }
    41. let ignoredonBreak = onBreak()
    42. io.writeLine("onBreak:{later()}")
    43. function onContinue() -> Result<int, string> {
    44. let mut i = 0
    45. while (i < 1) {
    46. using file = (io.open("input.txt")?) {
    47. later = () => match (file.read()) {
    48. case Ok(text) => text
    49. case Err(e) => e
    50. }
    51. i += 1
    52. continue
    53. }
    54. }
    55. Ok(0)
    56. }
    57. let ignoredonContinue = onContinue()
    58. io.writeLine("onContinue:{later()}")
    Expected outputExit code 0
    onReturn:file is closed
    onQuestion:file is closed
    onBreak:file is closed
    onContinue:file is closed
    
    $ topaz run example.tpz · Target product 5.21.3
    input.txtClose on return, propagation, break, and continue
    1. payload
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. onReturn:file is closed
    2. onQuestion:file is closed
    3. onBreak:file is closed
    4. onContinue:file is closed

    Evaluate the return value, then close nested resources

    example.tpzEvaluate the return value, then close nested resources
    1. import std.io
    2. let mut outerClosed: () -> bool = () => false
    3. let mut innerClosed: () -> bool = () => false
    4. function isClosed(file: File) -> bool {
    5. match (file.read()) {
    6. case Ok(text) => false
    7. case Err(error) => true
    8. }
    9. }
    10. function makeResult() -> Result<int, string> {
    11. io.writeLine("return-value")
    12. Ok(7)
    13. }
    14. function scenario() -> Result<int, string> {
    15. using outer = (io.open("input.txt")?) {
    16. outerClosed = () => isClosed(outer)
    17. defer { io.writeLine("outer-defer:inner-closed={innerClosed()}") }
    18. using inner = (io.open("input.txt")?) {
    19. innerClosed = () => isClosed(inner)
    20. defer { io.writeLine("inner-defer") }
    21. return makeResult()
    22. }
    23. }
    24. Ok(0)
    25. }
    26. let outcome = scenario()
    27. io.writeLine(match (outcome) {
    28. case Ok(value) => "result:{value}"
    29. case Err(error) => "open:{error}"
    30. })
    31. io.writeLine("outer-closed:{outerClosed()}")
    32. io.writeLine("inner-closed:{innerClosed()}")
    Expected outputExit code 0
    return-value
    inner-defer
    outer-defer:inner-closed=true
    result:7
    outer-closed:true
    inner-closed:true
    
    $ topaz run example.tpz · Target product 5.21.3
    input.txtEvaluate the return value, then close nested resources
    1. payload
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. return-value
    2. inner-defer
    3. outer-defer:inner-closed=true
    4. result:7
    5. outer-closed:true
    6. inner-closed:true

    The native File read result makes closing observable. The outer body defer sees the inner resource closed before the outer resource closes.

    An ordinary fault skips remaining cleanup

    example.tpzAn ordinary fault skips remaining cleanup
    1. import std.io
    2. function divide(divisor: int) -> int {
    3. 42 / divisor
    4. }
    5. function scenario() -> Result<int, string> {
    6. using file = (io.open("input.txt")?) {
    7. defer { io.writeLine("cleanup-observed") }
    8. divide(0)
    9. }
    10. Ok(0)
    11. }
    12. let result = scenario()
    Expected outputExit code 1
    No stdout.
    $ topaz run example.tpz · Target product 5.21.3
    input.txtAn ordinary fault skips remaining cleanup
    1. payload
    Expected result

    Expected result

    Rejection during run. Exit code 1.

    The division fault stops execution. The remaining defer and using cleanup are skipped under the fault cleanup rule. Standard output contains no cleanup message.

    Alternatives considered

    • Guarantee cleanup on faults and repeatable close on every host. Hosts would need to implement and commit to stronger cleanup and close contracts.
    • Require every host to publish its own cleanup and close contract. The promise covers what the implementation keeps today, and a stronger portable contract is decided with its implementation.

    Why

    Callers know which exit paths can rely on using to close the file.

    Changed rules Using acquisition and cleanup order →Explicit close and failure boundaries →

    Resolved pending items Using cleanup on each exit path →

    Version history

    Derived conformance calls the nested type's conformance

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A field can have custom comparison or JSON conversion. Inspecting only its structure while deriving the outer record would lose that behavior.

    Decision

    • Invoke the inner type's manual or derived conformance. Connect recursive declarations through descriptor references.
    • A JSON value cycle returns Err. A comparison cycle produces TPZ5007.

    Examples

    Derived equality and operators use the inner manual equality

    example.tpzDerived equality and operators use the inner manual equality
    1. import std.io { writeLine }
    2. record Token { key: int, noise: int }
    3. impl Eq<Token> {
    4. function equals(a: Token, b: Token) -> bool { a.key == b.key }
    5. }
    6. record Box derives Eq { item: Token }
    7. let a = Box { item: Token { key: 1, noise: 10 } }
    8. let b = Box { item: Token { key: 1, noise: 20 } }
    9. let c = Box { item: Token { key: 2, noise: 10 } }
    10. writeLine("{Eq.equals(a, b)}")
    11. writeLine("{a == b}")
    12. writeLine("{Eq.equals(a, c)}")
    13. writeLine("{a != c}")
    Expected outputExit code 0
    true
    true
    false
    true
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. true
    2. true
    3. false
    4. true

    Derived ordering and operators use the inner manual ordering

    example.tpzDerived ordering and operators use the inner manual ordering
    1. import std.io { writeLine }
    2. record Rank { score: int }
    3. impl Order<Rank> {
    4. function compare(a: Rank, b: Rank) -> int {
    5. if (a.score > b.score) { -1 } else if (a.score < b.score) { 1 } else { 0 }
    6. }
    7. }
    8. record Box derives Order { item: Rank }
    9. let a = Box { item: Rank { score: 9 } }
    10. let b = Box { item: Rank { score: 3 } }
    11. writeLine("{Order.compare(a, b)}")
    12. writeLine("{a < b}")
    13. writeLine("{Order.compare(b, a)}")
    14. writeLine("{b > a}")
    Expected outputExit code 0
    -1
    true
    1
    true
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. -1
    2. true
    3. 1
    4. true

    Derived JSON uses the nested manual codec in both directions

    example.tpzDerived JSON uses the nested manual codec in both directions
    1. import std.io { writeLine }
    2. import std.json { JSONValue, parseAs, stringify }
    3. record Token { text: string }
    4. impl JSON<Token> {
    5. function encode(value: Token) -> Result<JSONValue, string> {
    6. JSON.encode(value.text)
    7. }
    8. function decode(value: JSONValue) -> Result<Token, string> {
    9. match (value.asString()) {
    10. case Some(text) => Ok(Token { text: text })
    11. case None() => Err("expected token string")
    12. }
    13. }
    14. }
    15. record Envelope derives JSON { token: Token }
    16. let text = match (stringify(Envelope { token: Token { text: "paper" } })) {
    17. case Ok(value) => value
    18. case Err(message) => message
    19. }
    20. writeLine(text)
    21. writeLine(match (parseAs<Envelope>(text)) {
    22. case Ok(value) => value.token.text
    23. case Err(message) => message
    24. })
    Expected outputExit code 0
    {"token":"paper"}
    paper
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. {"token":"paper"}
    2. paper

    A finite recursive enum value encodes and decodes

    example.tpzA finite recursive enum value encodes and decodes
    1. import std.io { writeLine }
    2. import std.json { parseAs, stringify }
    3. enum Chain derives Eq, JSON { End, Next(int, Chain) }
    4. let original = Chain.Next(7, Chain.End())
    5. let text = match (stringify(original)) {
    6. case Ok(value) => value
    7. case Err(message) => message
    8. }
    9. writeLine(text)
    10. writeLine(match (parseAs<Chain>(text)) {
    11. case Ok(value) => "{Eq.equals(value, original)}"
    12. case Err(message) => message
    13. })
    Expected outputExit code 0
    {"tag":"Next","values":[7,{"tag":"End"}]}
    true
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. {"tag":"Next","values":[7,{"tag":"End"}]}
    2. true

    Inserted values keep recursive JSON finite

    example.tpzInserted values keep recursive JSON finite
    1. import std.io { writeLine }
    2. import std.json { stringify }
    3. record Node derives JSON { children: Array<Node> }
    4. let mut children: Array<Node> = []
    5. let root = Node { children: children }
    6. children.push(root)
    7. writeLine("{root.children.length}:{children.length}")
    8. writeLine(match (stringify(root)) {
    9. case Ok(value) => "Ok {value}"
    10. case Err(_) => "unexpected error"
    11. })
    Expected outputExit code 0
    0:1
    Ok {"children":[]}
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 0:1
    2. Ok {"children":[]}

    Inserted values keep recursive comparison finite

    example.tpzInserted values keep recursive comparison finiteOpen in Playground →
    1. import std.io { writeLine }
    2. record Node derives Eq { children: Array<Node> }
    3. let mut children: Array<Node> = []
    4. let root = Node { children: children }
    5. let peer = Node { children: children }
    6. children.push(root)
    7. writeLine("{Eq.equals(root, peer)}:{root.children.length}:{children.length}")
    Expected outputExit code 0
    true:0:1
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. true:0:1

    Alternatives considered

    • Inspect the nested value structurally as a special case. The same protocol could produce different results for a value used alone or inside another type.
    • Forbid recursive declarations altogether. It is enough that the inner implementation keeps its meaning inside the outer derivation.

    Why

    A nested type retains the conformance it defines.

    Changed rules Nested and recursive derivation requirements →

    Newtypes derive conformances explicitly

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A base type can support a protocol that the new named type may or may not want. Inheriting it automatically hides the decision in the new declaration.

    Decision

    Use an explicit derives clause on a newtype, just as for records and enums.

    Examples

    Derive the existing protocols for a newtype

    example.tpzDerive the existing protocols for a newtype
    1. newtype Item derives Eq, Order, Show, JSON = int
    2. function jsonIdentity<T: JSON>(value: T) -> T { value }
    3. let value = Item(7)
    4. let same: bool = Eq.equals(value, value)
    5. let order: int = Order.compare(value, Item(8))
    6. let shown: string = Show.show(value)
    7. let retained: Item = jsonIdentity(value)
    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

    • Inherit all conformances from the base type. The new declaration would no longer say which protocols it provides.
    • Keep forbidding derivation for newtypes. Every nominal type should gain conformance by the same rule.

    Why

    Nominal types all show derived capabilities the same way.

    Changed rules Nested and recursive derivation requirements →Newtype derivation →

    Equality, ordering, and JSON each have their own requirements

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    A value can support equality without being ordered or JSON-encodable. Reordering declarations should also have a defined effect on comparison.

    Decision

    • Map and Set equality compare membership.
    • Order is a composable total order. Field and variant names determine comparison order independently of declaration order.
    • JSON follows specified conversion rules, including finite floats and Result.

    Examples

    Map and Set equality follows membership while Map values use Eq

    example.tpzMap and Set equality follows membership while Map values use Eq
    1. import std.io { writeLine }
    2. record Token { key: int, label: string }
    3. impl Eq<Token> {
    4. function equals(a: Token, b: Token) -> bool { a.key == b.key }
    5. }
    6. record Index derives Eq { values: Map<string, Token>, keys: Set<int> }
    7. let a = Index {
    8. values: map { "a": Token { key: 1, label: "first" }, "b": Token { key: 2, label: "second" } },
    9. keys: set { 1, 2 },
    10. }
    11. let b = Index {
    12. values: map { "b": Token { key: 2, label: "changed" }, "a": Token { key: 1, label: "changed" } },
    13. keys: set { 2, 1 },
    14. }
    15. let c = Index {
    16. values: map { "a": Token { key: 9, label: "first" }, "b": Token { key: 2, label: "second" } },
    17. keys: set { 1, 2 },
    18. }
    19. writeLine("{Eq.equals(a, b)}")
    20. writeLine("{a == b}")
    21. writeLine("{Eq.equals(a, c)}")
    Expected outputExit code 0
    true
    true
    false
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. true
    2. true
    3. false

    Reordering record fields or enum declarations does not change derived order

    example.tpzReordering record fields or enum declarations does not change derived order
    1. import std.io { writeLine }
    2. record First derives Order { z: int, a: int }
    3. record Second derives Order { a: int, z: int }
    4. enum Forward derives Order { Zed, Alpha }
    5. enum Reordered derives Order { Alpha, Zed }
    6. writeLine("{Order.compare(First { z: 0, a: 2 }, First { z: 100, a: 1 })}")
    7. writeLine("{Order.compare(Second { z: 0, a: 2 }, Second { z: 100, a: 1 })}")
    8. writeLine("{Order.compare(Forward.Alpha(), Forward.Zed())}")
    9. writeLine("{Order.compare(Reordered.Alpha(), Reordered.Zed())}")
    Expected outputExit code 0
    1
    1
    -1
    -1
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 1
    2. 1
    3. -1
    4. -1

    Finite floats have one JSON number conversion and preserve negative zero

    example.tpzFinite floats have one JSON number conversion and preserve negative zero
    1. import std.io { writeLine }
    2. import std.json { parseAs, stringify }
    3. record Reading derives JSON { value: float }
    4. writeLine(match (stringify(Reading { value: 1.5 })) {
    5. case Ok(text) => text
    6. case Err(message) => message
    7. })
    8. writeLine(match (stringify(-0.0)) {
    9. case Ok(text) => text
    10. case Err(message) => message
    11. })
    12. writeLine(match (stringify(1000.0)) {
    13. case Ok(text) => text
    14. case Err(message) => message
    15. })
    16. writeLine(match (parseAs<float>("-0")) {
    17. case Ok(value) => "{(1.0 / value) < 0.0}"
    18. case Err(message) => message
    19. })
    20. writeLine(match (parseAs<float>("1")) {
    21. case Ok(value) => "{value == 1.0}"
    22. case Err(message) => message
    23. })
    24. writeLine(match (stringify(0.0 / 0.0)) {
    25. case Ok(_) => "unexpected value"
    26. case Err(_) => "nonfinite rejected"
    27. })
    28. writeLine(match (parseAs<float>("1e9999")) {
    29. case Ok(_) => "unexpected value"
    30. case Err(_) => "overflow rejected"
    31. })
    Expected outputExit code 0
    {"value":1.5}
    -0
    1000
    true
    true
    nonfinite rejected
    overflow rejected
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. {"value":1.5}
    2. -0
    3. 1000
    4. true
    5. true
    6. nonfinite rejected
    7. overflow rejected

    Result data uses the same tagged representation as enum data

    example.tpzResult data uses the same tagged representation as enum data
    1. import std.io { writeLine }
    2. import std.json { parseAs, stringify }
    3. record Outcome derives JSON { value: Result<int, string> }
    4. let value = Outcome { value: Err("paper") }
    5. let text = match (stringify(value)) {
    6. case Ok(encoded) => encoded
    7. case Err(message) => message
    8. }
    9. writeLine(text)
    10. writeLine(match (parseAs<Outcome>(text)) {
    11. case Ok(decoded) => match (decoded.value) {
    12. case Ok(number) => "{number}"
    13. case Err(message) => message
    14. }
    15. case Err(message) => message
    16. })
    Expected outputExit code 0
    {"value":{"tag":"Err","values":["paper"]}}
    paper
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. {"value":{"tag":"Err","values":["paper"]}}
    2. paper

    Map membership has no implicit total ordering

    example.tpzMap membership has no implicit total orderingOpen in Playground →
    1. record Lookup derives Order { values: Map<string, int> }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5530 →

      structures-derive-order-field at example.tpz:1:23

    A Set needs an explicitly chosen JSON representation

    example.tpzA Set needs an explicitly chosen JSON representationOpen in Playground →
    1. record Membership derives JSON { values: Set<int> }
    Expected outputNonzero exit
    No stdout.
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5530 →

      structures-derive-json-field at example.tpz:1:27

    Alternatives considered

    • Use a fixed allowlist or admit every type. A fixed list does not express the different requirements, while unconditional admission would include types that cannot satisfy the operation.

    Why

    The meaning of each operation tells you whether a type supports it.

    Changed rules Field capability domains for derivation →

    Protocols follow ordinary module name rules

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    A protocol can move to another file, and two modules can define protocols with the same name. The spelling a caller uses need not be the protocol’s identity.

    Decision

    • Apply the regular export, import, and name resolution rules to protocols.
    • The defining module and declaration identify a protocol through aliases and distinguish it from same-named protocols.

    Examples

    A selected protocol alias preserves a public conformance

    example.tpzA selected protocol alias preserves a public conformance
    1. import std.io { writeLine }
    2. import contracts { Labelled as Described }
    3. import item { Item }
    4. function describe<T: Described>(value: T) -> string { Described.label(value) }
    5. writeLine(describe(Item { text: "selected" }))
    Expected outputExit code 0
    selected
    
    $ topaz run example.tpz --language-version 6.0
    contracts.tpzA selected protocol alias preserves a public conformance
    1. export protocol Labelled { function label(value: Self) -> string }
    item.tpzA selected protocol alias preserves a public conformance
    1. import contracts { Labelled }
    2. export record Item { text: string }
    3. impl Labelled<Item> {
    4. function label(value: Item) -> string { value.text }
    5. }
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. selected

    A namespace-qualified protocol resolves in bounds, impl heads, and calls

    example.tpzA namespace-qualified protocol resolves in bounds, impl heads, and calls
    1. import std.io { writeLine }
    2. import contracts as api
    3. import item { Item }
    4. function describe<T: api.Labelled>(value: T) -> string { api.Labelled.label(value) }
    5. writeLine(describe(Item { text: "qualified" }))
    Expected outputExit code 0
    qualified
    
    $ topaz run example.tpz --language-version 6.0
    contracts.tpzA namespace-qualified protocol resolves in bounds, impl heads, and calls
    1. export protocol Labelled { function label(value: Self) -> string }
    item.tpzA namespace-qualified protocol resolves in bounds, impl heads, and calls
    1. import contracts as api
    2. export record Item { text: string }
    3. impl api.Labelled<Item> {
    4. function label(value: Item) -> string { value.text }
    5. }
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. qualified

    Equal protocol spellings in different modules keep different conformances

    example.tpzEqual protocol spellings in different modules keep different conformances
    1. import std.io { writeLine }
    2. import first { Marked as First }
    3. import second { Marked as Second }
    4. import value { Item }
    5. function printBoth<T: First + Second>(value: T) -> () {
    6. writeLine(First.mark(value))
    7. writeLine(Second.mark(value))
    8. }
    9. printBoth(Item { text: "value" })
    Expected outputExit code 0
    first value
    second value
    
    $ topaz run example.tpz --language-version 6.0
    value.tpzEqual protocol spellings in different modules keep different conformances
    1. export record Item { text: string }
    first.tpzEqual protocol spellings in different modules keep different conformances
    1. import value { Item }
    2. export protocol Marked { function mark(value: Self) -> string }
    3. impl Marked<Item> { function mark(value: Item) -> string { "first {value.text}" } }
    second.tpzEqual protocol spellings in different modules keep different conformances
    1. import value { Item }
    2. export protocol Marked { function mark(value: Self) -> string }
    3. impl Marked<Item> { function mark(value: Item) -> string { "second {value.text}" } }
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. first value
    2. second value

    Alternatives considered

    • Keep protocols module-local or give them global names. Either choice would need separate rules or give up the name isolation provided by modules.

    Why

    Code can span modules without changing the meaning of its public protocol contracts.

    Changed rules Conformance follows nominal origin across imports →

    Generic conformance bounds go in the leading parameter list

    Adopted November 7, 2026 · 6.0.0 · In progress

    Problem

    Separate syntax for function and implementation bounds would make developers relearn the same constraint. Conditional derivation can use the same form.

    Decision

    • Put bounds in the leading parameter list, as in impl<T: Eq> Eq<Box<T>>.
    • Write conditional derivation as derives<T: Eq> Eq<Box<T>>.

    Examples

    Implement equality for a generic wrapper

    example.tpzImplement equality for a generic wrapper
    1. record Box<T> { value: T }
    2. impl<T: Eq> Eq<Box<T>> {
    3. function equals(a: Box<T>, b: Box<T>) -> bool {
    4. Eq.equals(a.value, b.value)
    5. }
    6. }
    7. let left: Box<int> = Box { value: 3 }
    8. let right: Box<int> = Box { value: 3 }
    9. let same: bool = Eq.equals(left, right)
    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.

    Derive equality under an element bound

    example.tpzDerive equality under an element bound
    1. record Box<T> derives<T: Eq> Eq<Box<T>> { value: T }
    2. let left: Box<int> = Box { value: 3 }
    3. let right: Box<int> = Box { value: 3 }
    4. let same: bool = Eq.equals(left, right)
    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.

    Use the conditional derive binder on a newtype

    example.tpzUse the conditional derive binder on a newtype
    1. newtype Box<T> derives<T: Eq> Eq<Box<T>> = T
    2. let left: Box<int> = Box(3)
    3. let right: Box<int> = Box(3)
    4. let same: bool = Eq.equals(left, right)
    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

    • Add a special trailing where clause. The same bound would use different syntax in functions and implementations.

    Why

    Protocol requirements are visible in the same place in both declarations.

    Changed rules Generic binders and conditional conformance →

    Resolved pending items Generic implementation syntax →

    Version history

    Generic protocol implementations use the same bounds syntax as functions

    Adopted November 7, 2026 · 6.0.0 · In progress · Version 3

    Problem

    A generic type without conformance may need separate functions for equality or display. That creates a second way to express an existing operation.

    Decision

    • A protocol implementation can declare explicit generic parameters and bounds, and it can be conditional or conditionally derived.
    • Write forms such as impl<T: Eq> Eq<Box<T>> and derives<T: Eq> Eq<Box<T>>.

    Examples

    Implement equality for a generic wrapper →

    Derive equality under an element bound →

    Alternatives considered

    • Retain the restriction on generic conformance. Generic types would still define the same equality or display operations outside the protocol.

    Why

    Functions and implementations share one syntax for bounds, and generic types can use existing protocol operations.

    Changed rules Generic binders and conditional conformance →

    Resolved pending items Generic implementations and conditional derivation →Generic implementation syntax →

    Version history
    • Version 2 · Adopted November 7, 2026 · The second decision deferred generic protocol implementations

      Retained the existing restriction and deferred generic conformance.

    • Version 1 · Adopted November 7, 2026 · The first decision allowed generic protocol implementations

      Set the initial direction for generic protocol implementations.

    • Restores · Adopted November 7, 2026 · The first decision allowed generic protocol implementations topaz.decision.generic-conformance.1
    • Restores · Adopted November 7, 2026 · Generic conformance bounds go in the leading parameter list topaz.decision.generic-conformance-syntax.1

    Collections receive expected types from context

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    An empty array has no value that can identify its element type. Context can also supply the result type for a set or map.

    Decision

    Propagate expected types consistently to arrays, sets, maps and comprehensions.

    Examples

    Array comprehension with an expected literal type

    example.tpzArray comprehension with an expected literal type
    1. let array: Array<1> = [for item in ([0]) => 1]
    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.

    Set comprehension with an expected literal type

    example.tpzSet comprehension with an expected literal type
    1. let keys: Set<1> = set { for item in ([0]) => 1 }
    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.

    Map comprehension with an expected literal type

    example.tpzMap comprehension with an expected literal type
    1. let table: Map<1, "one"> = map { for item in ([0]) => 1: "one" }
    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.

    Give empty collections a contextual type

    example.tpzGive empty collections a contextual typeOpen in Playground →
    1. let values: Array<int> = []
    2. let names: Set<string> = set {}
    3. let counts: Map<string, int> = map {}
    Expected outputExit code 0
    example.tpz: types-ok (1 module)
    example.tpz: resolve-ok (1 module)
    
    $ topaz check example.tpz --language-version 6.0
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    Expected stdout
    1. example.tpz: types-ok (1 module)
    2. example.tpz: resolve-ok (1 module)

    Alternatives considered

    • Propagate context only to arrays. Changing collection kind would change the inference rule.
    • Infer every collection's element type independently of context. One inference rule should apply to every collection kind, and this option ignores context that is there.

    Why

    The way developers state the result type works across collection kinds.

    Changed rules Context for empty collections →Array comprehension type →Set comprehension type →Map comprehension type →

    Callbacks chain transformations and comprehensions build collections

    Adopted November 7, 2026 · 6.0.0 · Being verified

    Problem

    The same array can come from chaining existing functions or joining and filtering several sources. The two programs have different structure.

    Decision

    • Keep callback methods such as arr.map(f) for chained transformations. Use comprehensions to combine and filter sources when building a collection.
    • Where the two forms give the same result, the specification also states when and in which order each form evaluates.

    Examples

    Reuse functions through callback methods

    example.tpzReuse functions through callback methodsOpen in Playground →
    1. import std.io
    2. function addPadding(width: int) -> int { width + 2 }
    3. function double(width: int) -> int { width * 2 }
    4. let widths = [10, 20]
    5. let chained = widths.map(addPadding).map(double)
    6. let constructed = [for width in (widths) => double(addPadding(width))]
    7. for width in (chained) {
    8. io.writeLine("callback {width}")
    9. }
    10. for width in (constructed) {
    11. io.writeLine("comprehension {width}")
    12. }
    Expected outputExit code 0
    callback 24
    callback 44
    comprehension 24
    comprehension 44
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. callback 24
    2. callback 44
    3. comprehension 24
    4. comprehension 44

    Construct a collection from filtered sources

    example.tpzConstruct a collection from filtered sourcesOpen in Playground →
    1. import std.io
    2. let widths = [10, 20]
    3. let paddings = [1, 2]
    4. let outerWidths = [for width in (widths) if (width > 10) for padding in (paddings) => width + padding * 2]
    5. for width in (outerWidths) {
    6. io.writeLine("{width}")
    7. }
    Expected outputExit code 0
    22
    24
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 22
    2. 24

    Observe complete callback passes and per-element comprehension work

    example.tpzObserve complete callback passes and per-element comprehension workOpen in Playground →
    1. import std.io
    2. function source() -> Array<int> {
    3. io.writeLine("source")
    4. [1, 2, 3]
    5. }
    6. function selected(value: int) -> bool {
    7. io.writeLine("select {value}")
    8. value > 1
    9. }
    10. function convert(value: int) -> int {
    11. io.writeLine("convert {value}")
    12. value * 10
    13. }
    14. function predicate() -> (int) -> bool {
    15. io.writeLine("predicate")
    16. selected
    17. }
    18. function transformation() -> (int) -> int {
    19. io.writeLine("transformation")
    20. convert
    21. }
    22. io.writeLine("callback chain")
    23. let chained = source().filter(predicate()).map(transformation())
    24. io.writeLine("comprehension")
    25. let constructed = [for value in (source()) if (selected(value)) => convert(value)]
    26. io.writeLine("results")
    27. for value in (chained) {
    28. io.writeLine("callback {value}")
    29. }
    30. for value in (constructed) {
    31. io.writeLine("comprehension {value}")
    32. }
    Expected outputExit code 0
    callback chain
    source
    predicate
    select 1
    select 2
    select 3
    transformation
    convert 2
    convert 3
    comprehension
    source
    select 1
    select 2
    convert 2
    select 3
    convert 3
    results
    callback 20
    callback 30
    comprehension 20
    comprehension 30
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. callback chain
    2. source
    3. predicate
    4. select 1
    5. select 2
    6. select 3
    7. transformation
    8. convert 2
    9. convert 3
    10. comprehension
    11. source
    12. select 1
    13. select 2
    14. convert 2
    15. select 3
    16. convert 3
    17. results
    18. callback 20
    19. callback 30
    20. comprehension 20
    21. comprehension 30

    Alternatives considered

    • Keep only one form. Code would lose a direct way to express one of those intents even when the results match.

    Why

    Readers can distinguish a function chain from collection construction.

    Changed rules Callback methods and comprehensions →

    Arrays, sets and ranges share callback methods

    Adopted November 14, 2026 · 6.0.0 · Being verified

    Problem

    An array transformation may also be useful on a set or range. Changing the receiver need not require rewriting it as a loop.

    Decision

    • Provide eager map, filter and reduce for arrays, sets and ranges.
    • map and filter return arrays in iteration order. reduce returns the accumulator.

    Examples

    Transform sets and ranges with callback methods

    example.tpzTransform sets and ranges with callback methodsOpen in Playground →
    1. import std.io
    2. let marks = set { 3, 1, 2 }
    3. let doubled: Array<int> = marks.map((value: int) => value * 2)
    4. let evens: Array<int> = (1..6).filter((value: int) => value % 2 == 0)
    5. let total = (1..4).reduce(0, (sum: int, value: int) => sum + value)
    6. for value in (doubled) {
    7. io.writeLine("set {value}")
    8. }
    9. for value in (evens) {
    10. io.writeLine("range {value}")
    11. }
    12. io.writeLine("total {total}")
    Expected outputExit code 0
    set 6
    set 2
    set 4
    range 2
    range 4
    range 6
    total 10
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. set 6
    2. set 2
    3. set 4
    4. range 2
    5. range 4
    6. range 6
    7. total 10

    Reuse functions through callback methods →

    Alternatives considered

    • Offer callback methods on arrays alone. Transformations would need different rules across types that already support iteration.

    Why

    The same transformation chain works across receivers.

    Changed rules Callback methods and comprehensions →

    Maps and sets preserve insertion order

    Adopted November 9, 2026 · 6.0.0 · Being verified

    Problem

    Replacing a key or deleting one item need not reshuffle enumeration. Equality asks a different question from iteration order.

    Decision

    • Map keys, values, entries, iteration and display follow insertion order. Replacing a value keeps its key in place.
    • Deleting from a map or set preserves the relative order of the remaining items.
    • Equality ignores order. JSON object key ordering has its own rule.

    Examples

    Keep a Map key in place when replacing its value

    example.tpzKeep a Map key in place when replacing its valueOpen in Playground →
    1. import std.io { writeLine }
    2. let mut values = map { "first": 1, "middle": 2, "last": 3 }
    3. values.insert("middle", 20)
    4. for key in (values.keys) { writeLine(key) }
    5. for value in (values.values) { writeLine("{value}") }
    6. for entry in (values.entries) { writeLine("{entry.key}={entry.value}") }
    7. writeLine("{values}")
    Expected outputExit code 0
    first
    middle
    last
    1
    20
    3
    first=1
    middle=20
    last=3
    Map{first: 1, middle: 20, last: 3}
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. first
    2. middle
    3. last
    4. 1
    5. 20
    6. 3
    7. first=1
    8. middle=20
    9. last=3
    10. Map{first: 1, middle: 20, last: 3}

    Keep surviving Map entries in order after removal

    example.tpzKeep surviving Map entries in order after removalOpen in Playground →
    1. import std.io { writeLine }
    2. let mut values = map { "first": 1, "removed": 2, "third": 3, "last": 4 }
    3. values.remove("removed")
    4. for entry in (values.entries) { writeLine("{entry.key}={entry.value}") }
    5. writeLine("{values}")
    Expected outputExit code 0
    first=1
    third=3
    last=4
    Map{first: 1, third: 3, last: 4}
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. first=1
    2. third=3
    3. last=4
    4. Map{first: 1, third: 3, last: 4}

    Keep surviving Set elements in order after removal

    example.tpzKeep surviving Set elements in order after removalOpen in Playground →
    1. import std.io { writeLine }
    2. let mut values = set { 3, 1, 4, 2 }
    3. values.add(1)
    4. values.remove(1)
    5. for value in (values) { writeLine("{value}") }
    6. writeLine("{values}")
    Expected outputExit code 0
    3
    4
    2
    Set{3, 4, 2}
    
    $ topaz run example.tpz --language-version 6.0
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. 3
    2. 4
    3. 2
    4. Set{3, 4, 2}

    Alternatives considered

    • Fill a deleted slot with the last item. Deleting one entry would change the order of entries the caller kept.
    • Leave the order unspecified. Results would not repeat.
    • Use sorted order. Insertion order matches Set and the current behavior, so examples do not change.

    Why

    Insertion and deletion have predictable effects on iteration and display.

    Changed rules Map and Set insertion order →Set order and duplicate elements →