Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.42.0

0.42.0 / src / std / core.lucb

#==============================================================================================
#
#   core - The compiler's runtime support
#
#   DESCRIPTION:
#       The runtime the compiler emits calls to: startup and thread identity, the `format` and
#       f-string buffer, integer and boolean formatting, hashing, and the checked, saturating
#       and converting integer arithmetic.
#
#==============================================================================================

from windows_abi import WideCharToMultiByte
import c
import float_text
import platform
import memory
import strings
extern func set_binary_mode as "_setmode"(descriptor: i32, mode: i32) -> i32
extern func GetCurrentThreadId() -> u32
var initial_thread: u32

## Whether the caller is the process's initial thread.
pub func on_initial_thread() -> bool:
    if platform.windows:
        return initial_thread != 0 and GetCurrentThreadId() == initial_thread
    return false

## Standard streams carry language bytes, including LF, without CRT text translation.
pub func process_start():
    if platform.windows:
        initial_thread = GetCurrentThreadId()
        _ = set_binary_mode(0, 32768)
        _ = set_binary_mode(1, 32768)
        _ = set_binary_mode(2, 32768)

extern func posix_write as "write"(descriptor: i32, buffer: const void*, count: usize) -> isize
extern func windows_write as "_write"(descriptor: i32, buffer: const void*, count: u32) -> i32

func write(descriptor: i32, buffer: const void*, count: usize) -> isize:
    if platform.windows:
        return (isize)windows_write(descriptor, buffer, (u32)(count if count < 2147483647 else 2147483647))
    return posix_write(descriptor, buffer, count)

extern func c_exit as "exit"(code: i32) -> never
extern func malloc(size: usize) -> void*?
extern func realloc(block: void*?, size: usize) -> void*?
extern func c_free as "free"(block: void*?)
extern func memcpy(target: void*, source: const void*, count: usize) -> void*
extern func memmove(target: void*, source: const void*, count: usize) -> void*
extern func memcmp(a: const void*, b: const void*, count: usize) -> i32
extern func strlen(text: c.str) -> usize

## Stop the program with its reason on stderr (§8.7).
pub func trap(message: c.str) -> never:
    begin_trap()
    write_diagnostic("trap: ".bytes)
    write_diagnostic(((str)message).bytes)
    write_diagnostic("\n".bytes)
    finish_trap()

## `trap: file:line:column: message`: a trap naming the statement it stopped at (§11.5).
pub func trap_at(position: c.str, message: c.str) -> never:
    diagnostic_location(position)
    write_diagnostic(((str)message).bytes)
    write_diagnostic("\n".bytes)
    finish_trap()

## Positioned diagnostic with NUL-terminated C strings. Base assertions use
## trap_detail_at so their message spans retain their explicit lengths.
pub func trap_two_at(position: c.str, message: c.str, detail: c.str) -> never:
    diagnostic_location(position)
    write_diagnostic(((str)message).bytes)
    write_diagnostic(": ".bytes)
    write_diagnostic(((str)detail).bytes)
    write_diagnostic("\n".bytes)
    finish_trap()

## Unpositioned diagnostic with NUL-terminated C strings.
pub func trap_two(message: c.str, detail: c.str) -> never:
    begin_trap()
    write_diagnostic("trap: ".bytes)
    write_diagnostic(((str)message).bytes)
    write_diagnostic(": ".bytes)
    write_diagnostic(((str)detail).bytes)
    write_diagnostic("\n".bytes)
    finish_trap()

## Fatal diagnostic for a Base string. Its explicit byte length permits slices,
## empty values and embedded NUL; no byte beyond the view is read.
pub func trap_text_at(position: c.str, message: str) -> never:
    diagnostic_location(position)
    write_diagnostic(message.bytes)
    write_diagnostic("\n".bytes)
    finish_trap()

## `trap(f"...")` streams its message (`stream_put`), so a message longer than a format
## buffer is whole: the location first, then the message to descriptor 2, then `trap_end`.
pub func trap_begin_at(position: c.str):
    diagnostic_location(position)

## The end of a streamed trap message, whose newline the stream wrote: the report, and
## the exit.
pub func trap_end() -> never:
    finish_trap()

## Assertion prefix plus a Base string detail, preserving the detail's length.
pub func trap_detail_at(position: c.str, message: c.str, detail: str) -> never:
    diagnostic_location(position)
    let prefix = (str)message
    write_diagnostic(prefix.bytes)
    write_diagnostic(": ".bytes)
    write_diagnostic(detail.bytes)
    write_diagnostic("\n".bytes)
    finish_trap()

## A trap at a position given as Base text, none when it is empty: how the value
## language's runtime and its interpreter stop.
pub func trap_located(position: str, message: str) -> never:
    begin_trap()
    write_diagnostic("trap: ".bytes)
    if position.length > 0:
        write_diagnostic(position.bytes)
        write_diagnostic(": ".bytes)
    write_diagnostic(message.bytes)
    write_diagnostic("\n".bytes)
    finish_trap()

## `trap: file:line:column: `, or `trap: ` when the position is empty (a C build's code
## before its first statement).
func diagnostic_location(position: c.str):
    begin_trap()
    write_diagnostic("trap: ".bytes)
    let location = (str)position
    if location.length > 0:
        write_diagnostic(location.bytes)
        write_diagnostic(": ".bytes)

## Panic reporting cannot raise another language error. The diagnostic goes to
## stderr and, when crash reports are on, to the report as well.
func write_diagnostic(data: const u8[]):
    write_all(2, data)
    if crash_file >= 0:
        write_all(crash_file, data)

## Retry interruptions and short writes; stop on a terminal write failure or lack of progress.
func write_all(descriptor: i32, data: const u8[]):
    var written: usize = 0
    while written < data.length:
        let remaining = data.length - written
        let count = remaining if remaining < 1073741824 else 1073741824
        let result = write(descriptor, data[written..].data, count)
        if result < 0 and c.errno() == c.interrupted:
            continue
        if result <= 0:
            return
        written += (usize)result

# mark: Crash reports ==========================================================================

extern func posix_open as "open"(path: c.str, flags: i32, ...) -> i32
extern func windows_open as "_open"(path: c.str, flags: i32, ...) -> i32
extern func posix_close as "close"(descriptor: i32) -> i32
extern func windows_close as "_close"(descriptor: i32) -> i32
extern func backtrace(frames: void**, size: i32) -> i32
extern func backtrace_symbols_fd(frames: const void**, size: i32, descriptor: i32)
extern func RtlCaptureStackBackTrace(skip: u32, count: u32, frames: void**, hash: u32*?) -> u16
extern func GetModuleHandleExA(flags: u32, address: const void*, module: void**) -> i32
extern func GetModuleFileNameA(module: void*, name: u8*, size: u32) -> u32
extern func c_quick_exit as "_exit"(code: i32) -> never
extern func dladdr(address: const void*, info: DlInfo*) -> i32
extern func getcontext(context: void*) -> i32
extern func RtlLookupFunctionEntry(pc: u64, image_base: u64*, history: void*?) -> void*?
extern func RtlVirtualUnwind(kind: u32, image_base: u64, pc: u64, entry: void*, context: void*, handler_data: void**, establisher: u64*, pointers: void*?) -> void*?

## `Dl_info`: the module and nearest symbol `dladdr` finds for an address.
extern struct DlInfo:
    file: c.str?
    base: usize
    symbol: c.str?
    start: usize

## Where a crash report goes, NUL-terminated, and what it starts with; empty when
## reports are off. `std.crash` fills them; a trap or fatal signal writes them.
var crash_path: u8[1024]
var crash_header: u8[1024]
var crash_header_length: usize = 0
var crash_file: i32 = -1
## Set while a report walks frame pointers: a fault then is the walk's own, at a
## frame it could not read, and the report ends there.
var crash_walking: bool = false
## Where `getcontext` puts the registers of a trap on Linux: more than any
## `ucontext_t` needs, as words so it is aligned.
var crash_registers: usize[1024]
## A Windows fault's CONTEXT, copied so it can be unwound in place: 1232 bytes
## that must start on 16, with room to move them there.
var crash_windows_context: u8[1280]
## The interrupted context of the fatal signal being reported, when there is one.
var crash_context: const void*? = none
## Whether this process has written a report: a later trap, one in a crash handler,
## is added to it rather than replacing it.
var crash_reported: bool = false
## What runs once a report is written, before the process ends (`set_crash_handler`).
var crash_handler: (func(i32) -> unit)? = none

## Turn crash reports on: a trap from now on also writes `header` and the trap
## to the file at `path` (created then, replaced if present), with a native
## stack where the platform gives one. Paths or headers too long are cut.
pub func set_crash_report(path: str, header: str):
    let length = path.length if path.length < crash_path.length - 1 else crash_path.length - 1
    for index in 0..<length:
        crash_path[index] = path.bytes[index]
    crash_path[length] = 0
    let header_length = header.length if header.length < crash_header.length else crash_header.length
    for index in 0..<header_length:
        crash_header[index] = header.bytes[index]
    crash_header_length = header_length

## Whether crash reports are on.
pub func crash_reports_enabled() -> bool:
    return crash_path[0] != 0

## Run `handler` once a crash report is written, before the process ends: with 0 after
## a trap, on the thread that trapped, where the program may still do ordinary work;
## with the signal's number after a fatal signal, inside the signal handler, where only
## async-signal-safe calls are allowed. The process ends when the handler returns. A
## trap inside the handler is added to the report and runs the handler again.
pub func set_crash_handler(handler: (func(i32) -> unit)?):
    crash_handler = handler

## Open the report, if reports are on and it is not open yet, and write its header.
## The start of every trap and fatal signal: the running test, if any, named as failed
## (§16.5), then the crash report opened.
func begin_trap():
    if test_running.length > 0:
        write_all(1, "FAIL  ".bytes)
        write_all(1, test_running.bytes)
        write_all(1, "\n".bytes)
    begin_crash_report()

## The end of a trap or fatal signal inside a test: the test counted as failed and the
## tally of the tests run so far printed, since the run ends here (§16.5).
func end_trapped_test():
    if test_running.length == 0:
        return
    test_running = ""
    tests_failed += 1
    _ = test_summary()

func begin_crash_report():
    if crash_file >= 0 or crash_path[0] == 0:
        return
    let path = (c.str)&crash_path[0]
    # write, create, and truncate the first time; append after
    if platform.windows:
        crash_file = windows_open(path, 1 | 256 | (8 if crash_reported else 512) | 32768, 420)
    elif platform.macos:
        crash_file = posix_open(path, 1 | 512 | (8 if crash_reported else 1024), 420)
    else:
        crash_file = posix_open(path, 1 | 64 | (1024 if crash_reported else 512), 420)
    if crash_file < 0:
        return
    if crash_reported:
        write_all(crash_file, "\n(and while the program handled that crash)\n".bytes)
    else:
        write_all(crash_file, crash_header[..<crash_header_length])
    crash_reported = true

## Finish a trap: the stack into the report, close it, the crash handler, and exit.
func finish_trap() -> never:
    end_trapped_test()
    finish_crash_report(trap_registers())
    if let handler = crash_handler:
        handler(0)
    c_exit(1)

## Where a fault left the program: its instruction, its frame pointer and, on
## arm64, its link register; zeros where they are not known.
pub struct FaultRegisters:
    ## The faulting instruction.
    pub var pc: usize = 0
    ## The frame pointer at the fault: the start of the frame chain.
    pub var fp: usize = 0
    ## The link register (arm64): the caller of a function that made no frame.
    pub var lr: usize = 0

## Write the stack into the report and close it: walked from `at` when it has a
## frame pointer, else as the platform's own backtrace gives it.
func finish_crash_report(at: FaultRegisters):
    if crash_file < 0:
        return
    write_all(crash_file, "\nstack:\n".bytes)
    var unwound = false
    if platform.windows:
        if let context = crash_context:
            write_windows_unwound(crash_file, context)
            unwound = true
    if unwound:
        close_crash_report()
        return
    if at.fp != 0:
        write_walked_stack(crash_file, at)
    elif platform.posix:
        # Pointer-sized slots: the addresses backtrace fills in.
        var frames: usize[64]
        let depth = backtrace((void**)&frames[0], 64)
        if depth > 0:
            backtrace_symbols_fd((const void**)&frames[0], depth, crash_file)
    elif platform.windows:
        write_windows_stack(crash_file)
    close_crash_report()

func close_crash_report():
    if platform.windows:
        _ = windows_close(crash_file)
    else:
        _ = posix_close(crash_file)
    crash_file = -1

## A trap's own registers on Linux, where `backtrace` needs unwind tables the
## native backend leaves out of release builds; zeros elsewhere (macOS's
## backtrace follows frame pointers, Windows' the SEH tables).
func trap_registers() -> FaultRegisters:
    if platform.linux:
        if getcontext((void*)&crash_registers[0]) != 0:
            return FaultRegisters()
        return context_registers((const void*)&crash_registers[0])
    else:
        return FaultRegisters()

# mark: Walking frame pointers =================================================================

## The registers in a signal's `ucontext_t` (or `getcontext`'s), or in a Windows
## `CONTEXT` record. Offsets are each platform's C layout.
func context_registers(context: const void*) -> FaultRegisters:
    let base = (const u8*)context
    if platform.windows:
        return FaultRegisters(pc = word_at(base, 248), fp = word_at(base, 160))
    elif platform.linux and platform.x86_64:
        # uc_mcontext.gregs at 40: RIP is register 16, RBP 10.
        return FaultRegisters(pc = word_at(base, 168), fp = word_at(base, 120))
    elif platform.macos:
        # uc_mcontext is a pointer at 48, to the exception state (16 bytes) and the thread state.
        let machine = (const u8*)(const void*)word_at(base, 48)
        if platform.arm64:
            return FaultRegisters(pc = word_at(machine, 272), fp = word_at(machine, 248), lr = word_at(machine, 256))
        else:
            return FaultRegisters(pc = word_at(machine, 144), fp = word_at(machine, 64))
    else:
        return FaultRegisters()

func word_at(base: const u8*, offset: usize) -> usize:
    return ((const usize*)(const void*)(base + offset))[0]

## Every frame from `at`: the faulting instruction, the link register on arm64
## (a leaf keeps its caller there), then each saved return address up the
## chain of frame records, which the native backend keeps in every function.
## A record that does not climb the stack ends the walk; one that cannot be
## read faults, and `report_fatal_signal_in` ends the report there.
func write_walked_stack(file: i32, at: FaultRegisters):
    var frames: usize[64] = ---
    var depth: usize = 0
    if at.pc != 0:
        frames[0] = at.pc
        depth = 1
    # The link register is the caller only when the faulting function made no
    # frame of its own; otherwise it is a stale return inside it. Marked so.
    var link: usize = 64
    if at.lr != 0 and at.lr != at.pc:
        link = depth
        frames[depth] = at.lr
        depth += 1
    var frame = at.fp
    crash_walking = true
    while depth < 64 and frame != 0 and frame % 8 == 0:
        let record = (const usize*)(const void*)frame
        let caller = record[1]
        let next = record[0]
        if caller == 0:
            break
        if depth == 0 or caller != frames[depth - 1]:
            frames[depth] = caller
            depth += 1
        if next <= frame or next - frame > 16777216:
            break
        frame = next
    crash_walking = false
    for index in 0..<depth:
        write_frame(file, index, frames[index], index == link)

## Windows: unwind a copy of the fault's CONTEXT a frame at a time through the
## SEH tables the native backend emits (its frame pointer sits below each
## frame's locals, so there are no frame records to follow). A function with no
## table entry is a leaf, whose return address is at the stack pointer.
func write_windows_unwound(file: i32, context: const void*):
    if platform.windows:
        let start = (usize)(const void*)&crash_windows_context[0]
        let copy = &crash_windows_context[(16 - start % 16) % 16]
        _ = memcpy(copy, context, 1232)
        var frames: usize[64] = ---
        var depth: usize = 0
        crash_walking = true
        while depth < 64:
            let pc = word_at(copy, 248)
            let sp = word_at(copy, 152)
            if pc == 0:
                break
            frames[depth] = pc
            depth += 1
            var base: u64 = 0
            if let entry = RtlLookupFunctionEntry((u64)pc, &base, none):
                var data: void* = ---
                var establisher: u64 = 0
                _ = RtlVirtualUnwind(0, base, (u64)pc, entry, (void*)copy, &data, &establisher, none)
            else:
                put_word(copy, 248, ((const usize*)(const void*)sp)[0])
                put_word(copy, 152, sp + 8)
            if word_at(copy, 152) <= sp:
                break
        crash_walking = false
        for index in 0..<depth:
            write_frame(file, index, frames[index], false)

func put_word(base: u8*, offset: usize, value: usize):
    ((usize*)(void*)(base + offset))[0] = value

## One frame's line: its number, address, module and offset in it (for
## addr2line or atos), and the nearest symbol where the platform names one.
func write_frame(file: i32, index: usize, address: usize, link: bool):
    var line: u8[640] = ---
    var used: usize = 0
    line[0] = '#'
    used = put_decimal(line, 1, index)
    line[used] = ' '
    if link:
        used = put_text(line, used + 1, "lr")
        line[used] = ' '
    used = put_hex(line, used + 1, address)
    line[used] = ' '
    used += 1
    if platform.windows:
        used = put_windows_module(line, used, address)
    elif platform.posix:
        var info: DlInfo = ---
        info.file = none
        info.symbol = none
        if dladdr((const void*)address, &info) != 0:
            if let file_name = info.file:
                used = put_base_name(line, used, (str)file_name)
            line[used] = '+'
            used = put_hex(line, used + 1, address - info.base)
            if let symbol = info.symbol:
                line[used] = ' '
                used = put_text(line, used + 1, (str)symbol)
                line[used] = '+'
                used = put_hex(line, used + 1, address - info.start)
        else:
            line[used] = '?'
            used += 1
    line[used] = '\n'
    write_all(file, (const u8[])line[..<used + 1])

## The module holding `address` on Windows, as `name+0xoffset`, into `line` at `used`.
func put_windows_module(line: u8[], used: usize, address: usize) -> usize:
    if platform.windows:
        var module: void* = ---
        var name: u8[260] = ---
        # 4: from an address; 2: without changing the module's reference count
        if GetModuleHandleExA(6, (const void*)address, (void**)&module) == 0:
            line[used] = '?'
            return used + 1
        let length = GetModuleFileNameA(module, &name[0], 260)
        let at = put_base_name(line, used, (str)name[..<length])
        line[at] = '+'
        return put_hex(line, at + 1, address - (usize)module)
    else:
        return used

## The last component of `path` into `line` at `used`, cut to fit.
func put_base_name(line: u8[], used: usize, path: str) -> usize:
    var start: usize = 0
    for index in 0..<path.length:
        if path.bytes[index] == '/' or path.bytes[index] == '\\':
            start = index + 1
    return put_text(line, used, (str)path.bytes[start..])

## `text` into `line` at `used`, leaving room for what follows it.
func put_text(line: u8[], used: usize, text: str) -> usize:
    var at = used
    for byte in text.bytes:
        if at + 40 >= line.length:
            break
        line[at] = byte
        at += 1
    return at

## `value` in decimal into `line` at `used`; the new length.
func put_decimal(line: u8[], used: usize, value: usize) -> usize:
    var digits: u8[24] = ---
    var count: usize = 0
    var rest = value
    while true:
        digits[count] = (u8)('0' + (u8)(rest % 10))
        count += 1
        rest = rest // 10
        if rest == 0:
            break
    var at = used
    while count > 0:
        count -= 1
        line[at] = digits[count]
        at += 1
    return at

## The native stack on Windows, a frame a line as `module+0xoffset`, which a debugger or
## addr2line resolves against the build. Nothing here allocates.
func write_windows_stack(file: i32):
    # One branch on the platform around everything, which the C backend folds away
    # elsewhere: the Windows symbols then appear in no other platform's build.
    if platform.windows:
        write_all(file, "(the reporter's frames and Windows' exception dispatch come first; the fault is the\n first program frame after ntdll.dll. Offsets are from each module's load address;\n add the image base, 0x140000000 by default for a 64-bit program, for addr2line.)\n".bytes)
        var frames: usize[64]
        let depth = (usize)RtlCaptureStackBackTrace(0, 64, (void**)&frames[0], none)
        for index in 0..<depth:
            let address = frames[index]
            var line: u8[400] = ---
            var used: usize = 0
            var module: void* = ---
            var base: usize = 0
            var name: u8[260] = ---
            var length: u32 = 0
            # 4: from an address; 2: without changing the module's reference count
            if GetModuleHandleExA(6, (const void*)address, (void**)&module) != 0:
                base = (usize)module
                length = GetModuleFileNameA(module, &name[0], 260)
            var start: u32 = 0
            for at in 0..<length:
                if name[at] == '\\' or name[at] == '/': start = at + 1
            for at in start..<length:
                if used < 300:
                    line[used] = name[at]
                    used += 1
            if length == 0:
                line[used] = '?'
                used += 1
            line[used] = '+'
            used += 1
            used = put_hex(line, used, address - base)
            line[used] = '\n'
            used += 1
            write_all(file, (const u8[])line[..<used])

## `value` as `0x` and lowercase hex digits into `line` at `used`; the new length.
func put_hex(line: u8[], used: usize, value: usize) -> usize:
    var at = used
    line[at] = '0'
    line[at + 1] = 'x'
    at += 2
    var shift: usize = 60
    var started = false
    while true:
        let digit = (value >> shift) & 15
        if digit != 0 or started or shift == 0:
            started = true
            line[at] = "0123456789abcdef".bytes[digit]
            at += 1
        if shift == 0:
            break
        shift -= 4
    return at

## A fatal signal: report it as a trap would, then end with the signal's exit
## status. Only async-signal-safe calls are made from here on.
pub func report_fatal_signal(name: str, number: i32) -> never:
    report_fatal_signal_in(name, number, none)

## A fatal signal whose handler has the interrupted context (a POSIX
## `ucontext_t`, or a Windows `CONTEXT`): the stack is walked from where the
## fault happened rather than from the handler. A fault while the stack is
## walked ends the report at the frame that could not be read.
pub func report_fatal_signal_in(name: str, number: i32, context: const void*?) -> never:
    if crash_walking:
        crash_walking = false
        if crash_file >= 0:
            write_all(crash_file, "(the walk stopped at a frame it could not read)\n".bytes)
            close_crash_report()
        c_quick_exit(128 + number)
    begin_trap()
    write_diagnostic("trap: fatal signal ".bytes)
    write_diagnostic(name.bytes)
    write_diagnostic("\n".bytes)
    end_trapped_test()
    crash_context = context
    if let interrupted = context:
        finish_crash_report(context_registers(interrupted))
    else:
        finish_crash_report(FaultRegisters())
    if let handler = crash_handler:
        handler(number)
    c_quick_exit(128 + number)

## The buffer `format` and f"..." fill: the bytes, their capacity, and the count used.
pub struct FormatBuffer:
    ## The buffer's bytes.
    pub var data: u8*
    ## The buffer's capacity in bytes.
    pub var capacity: usize
    ## The number of bytes used.
    pub var used: usize
    ## What text past the capacity does: `format_fixed`, it is cut; `format_grows`, the
    ## text moves to the heap and goes on there; `format_grown`, it is on the heap.
    pub var growth: usize = 0

## A buffer of the caller's, as `format` fills: text past its capacity is cut.
pub let format_fixed: usize = 0
## A buffer the compiler made for a formatted argument (§5.5): it starts on the stack, moves
## to the heap when the text outgrows it, and is released once the call it feeds returns.
pub let format_grows: usize = 1
## A growing buffer whose text is on the heap, which `format_release` frees.
pub let format_grown: usize = 2

## Append `count` bytes; 1 when they do not fit: the bytes that fit are kept, and the buffer
## is then over capacity, which `format` reports and `format_finish` marks. A growing
## buffer makes room instead, and fails only when the heap has none.
pub func format_put(b: FormatBuffer*, text: const void*?, count: usize) -> i32:
    if b.used > b.capacity:
        return 1
    if count > b.capacity - b.used and not (b.growth != format_fixed and format_grow(b, b.used + count)):
        if let source = text:
            if b.capacity > b.used:
                _ = memcpy(&b.data[b.used], source, b.capacity - b.used)
        b.used = b.capacity +% 1
        return 1
    if let source = text:
        if count > 0:
            _ = memcpy(&b.data[b.used], source, count)
    b.used += count
    return 0

## Make room in a growing buffer for `need` bytes and the NUL `format_finish` puts after
## them, at least doubling it; false when the heap has no room.
func format_grow(b: FormatBuffer*, need: usize) -> bool:
    var size = b.capacity * 2
    if size <= need:
        size = need + 1
    if b.growth == format_grown:
        let moved = realloc(b.data, size) else return false
        b.data = (u8*)moved
    else:
        let fresh = malloc(size) else return false
        _ = memcpy(fresh, b.data, b.used)
        b.data = (u8*)fresh
        b.growth = format_grown
    b.capacity = size
    return true

## Free what a growing buffer took from the heap; its text is gone with it.
pub func format_release(b: FormatBuffer*):
    if b.growth == format_grown:
        c_free(b.data)
        b.growth = format_grows
        b.capacity = 0
        b.used = 0

## Append the decimal `value` to `b`; the bytes written.
pub func format_u64(b: FormatBuffer*, value: u64) -> i32:
    var digits: u8[24] = ---
    var n: usize = 0
    var v = value
    if v == 0:
        digits[23] = 48
        n = 1
    while v != 0:
        n += 1
        digits[24 - n] = (u8)(48 + v % 10)
        v = v // 10
    return format_put(b, &digits[24 - n], n)

## Append the decimal `value` to `b`; the bytes written.
pub func format_i64(b: FormatBuffer*, value: i64) -> i32:
    if value < 0:
        let minus = "-"
        if format_put(b, minus.bytes.data, 1) != 0:
            return 1
        return format_u64(b, 0 -% (u64)value)
    return format_u64(b, (u64)value)

## A float field (base.md §14): the shortest decimal that reads back as `value`, a `.0`
## after digits with no point (float_text.display_f64); both backends call this.
pub func format_f64(b: FormatBuffer*, value: f64) -> i32:
    var text: u8[40] = ---
    let n = float_text.display_f64(value, text[0..])
    return format_put(b, &text[0], n)

## format_f64 for an f32 (or an f16, widened): the f32's own shortest digits.
pub func format_f32(b: FormatBuffer*, value: f32) -> i32:
    var text: u8[40] = ---
    let n = float_text.display_f32(value, text[0..])
    return format_put(b, &text[0], n)

## Append `true` or `false` to `b`; the bytes written.
pub func format_bool(b: FormatBuffer*, value: bool) -> i32:
    let word = "true" if value else "false"
    return format_put(b, word.bytes.data, word.length)

## A `char` displays as itself, in UTF-8 (§14.4).
pub func format_char(b: FormatBuffer*, value: char) -> i32:
    let cp = u32(value)
    var out: u8[4]
    var n: usize = 0
    if cp < 0x80:
        out[0] = u8(cp)
        n = 1
    elif cp < 0x800:
        out[0] = u8(0xC0 | (cp >> 6))
        out[1] = u8(0x80 | (cp & 0x3F))
        n = 2
    elif cp < 0x10000:
        out[0] = u8(0xE0 | (cp >> 12))
        out[1] = u8(0x80 | ((cp >> 6) & 0x3F))
        out[2] = u8(0x80 | (cp & 0x3F))
        n = 3
    else:
        out[0] = u8(0xF0 | (cp >> 18))
        out[1] = u8(0x80 | ((cp >> 12) & 0x3F))
        out[2] = u8(0x80 | ((cp >> 6) & 0x3F))
        out[3] = u8(0x80 | (cp & 0x3F))
        n = 4
    return format_put(b, (const void*)&out, n)

## The text so far, NUL-terminated when there is room. Text over capacity is cut at a
## character boundary and ends in `...`, so a long f"..." is never silently empty.
pub func format_finish(b: FormatBuffer*) -> str:
    if b.used < b.capacity:
        b.data[b.used] = 0
    if b.used > b.capacity:
        if b.capacity < 3:
            return ""
        var end = b.capacity - 3
        while end > 0 and (b.data[end] & 0xC0) == 0x80:
            end -= 1
        b.data[end] = 46
        b.data[end + 1] = 46
        b.data[end + 2] = 46
        return (str)u8[](b.data, end + 3)
    return (str)u8[](b.data, b.used)

## The startup shim's pieces: the argument vector as `str[]` (checked) or `c.str[]`.
pub func arguments(count: i32, vector: c.str*) -> str[]:
    let raw = raw_arguments(count, vector)
    let n = raw.length
    let block = malloc((n if n > 0 else 1) * memory.size_of(str)) else trap("memory.exhausted")
    let items = (str*)block
    var i: usize = 0
    while i < n:
        let text = (str)raw[i]
        if not utf8_ok(text.bytes.data, text.length):
            trap("invalid_utf8")
        items[i] = text
        i += 1
    return str[](items, n)

## The process's arguments as a span of C strings.
pub func raw_arguments(count: i32, vector: c.str*) -> c.str[]:
    if platform.windows:
        return windows_arguments()
    return c.str[](vector, (usize)count)

extern func GetCommandLineW() -> u16*
extern func CommandLineToArgvW(command: u16*, count: i32*) -> u16**?
extern func LocalFree(block: void*) -> void*?
extern func atexit(callback: func() -> unit) -> i32
var windows_argument_vector: c.str[]

func free_windows_arguments():
    for text in windows_argument_vector:
        c_free((void*)text)
    c_free((void*)windows_argument_vector.data)

## The wide command line preserves names the Windows ANSI code page cannot encode.
func windows_arguments() -> c.str[]:
    if platform.windows:
        if windows_argument_vector.length > 0:
            return windows_argument_vector
        var count: i32 = 0
        let wide = CommandLineToArgvW(GetCommandLineW(), &count) else trap("could not read the Windows command line")
        defer _ = LocalFree((void*)wide)
        let block = malloc((usize)count * memory.size_of(c.str)) else trap("memory.exhausted")
        let items = (c.str*)block
        for index in 0..<(usize)count:
            let size = WideCharToMultiByte(65001, 128, wide[index], -1, none, 0, none, none)
            if size <= 0: trap("the command line contains invalid UTF-16")
            let text = malloc((usize)size) else trap("memory.exhausted")
            if WideCharToMultiByte(65001, 128, wide[index], -1, (u8*)text, size, none, none) != size:
                trap("could not encode the command line as UTF-8")
            items[index] = (c.str)text
        windows_argument_vector = c.str[](items, (usize)count)
        if atexit(free_windows_arguments) != 0:
            trap("could not register command line cleanup")
        return windows_argument_vector
    return c.str[]((c.str*)0, 0)

## The error of the fallible call that failed last on this thread, as the native backends
## pass it: a failing function leaves its error here and returns its flag set, and `try`
## passes the flag up with the error left where it is (§11.2's representation).
pub local var failure: Error

# mark: Messages in flight ==================================================================
#
# `error(code, message)` copies a message that is not a literal here, so the message stays
# readable after the cleanup the failure runs has freed what it was made from (§11.3). The
# room is a stack: a handler that finishes gives back its error's message and everything
# raised after it (`message_handled`), and a failure that leaves a handler takes the place of
# the handled message (`message_raised`'s `replaces`). A message that does not fit above the
# top starts the room again at its beginning, so the room never grows and never allocates.

## The room for the messages of the errors in flight on this thread, and its first free byte.
local var raised_room: u8[16384]
local var raised_top: usize = 0

## The longest message the room keeps: a longer one is cut at a character and ends in `…`.
let raised_most: usize = 4096

## Where `text` starts in this thread's room, or `none` when it lies elsewhere. Only its
## start is read: a message written here lies here whole, and the length an error passes in
## carries its `called_at` above 32 bits (§11.3).
func in_room(text: str) -> usize?:
    let base = (usize)&raised_room[0]
    let at = (usize)text.bytes.data
    if at < base or at > base + raised_room.length:
        return none
    return at - base

## The message of an error being raised, copied into this thread's room: a copy that lives
## until the handler that catches the error finishes (§11.3). `replaces` is the message of the
## error a handler is passing on a failure from, or empty: its place is reused when it is in
## the room, the new message copied before the old one is given up, so a new message made
## from the old one reads it whole.
pub func message_raised(message: str, replaces: str) -> str:
    var length = message.length
    var cut = false
    if length > raised_most:
        length = raised_most - 3
        while length > 0 and (message.bytes[length] & 0xC0) == 0x80:
            length -= 1
        cut = true
    let total = length + (3 if cut else 0)
    var at = raised_top
    if let start = in_room(replaces):
        if start <= raised_top and start + total <= raised_room.length:
            at = start
    if at + total > raised_room.length:
        at = 0
    let room = u8[](&raised_room[at], total)
    if length > 0:
        _ = memmove(room.data, message.bytes.data, length)
    if cut:
        room[length] = 0xE2
        room[length + 1] = 0x80
        room[length + 2] = 0xA6
    raised_top = at + total
    return (str)room

## A handler finished with the error whose message is `message`: its place in the room and
## everything raised after it are free again. A message elsewhere, a literal, frees nothing.
pub func message_handled(message: str):
    if let start = in_room(message):
        if start < raised_top:
            raised_top = start

# mark: Where errors were raised ============================================================
#
# An error keeps where it was raised (§11.3), the position text of the statement a trap there
# would name, in the word after its code: the text's distance from `origin_base`, a byte of
# this program's own data, so the `Error` stays three words and a `T!` result does not grow.
# The texts and the byte are in one image, well within 2 GiB of each other; 0 is no position.
# `called_at`, the first call into another package the error came out of, is kept the same
# way in the word above the message's length, which is 32 bits: a new message clears it.

## The byte an error's `at` is counted from: generated code subtracts its address from the
## position text's.
pub var origin_base: u8 = 0

## `failure.at`: the position text `raised` bytes from `origin_base`, `file:line:column`, or
## empty when it is 0.
pub func origin(raised: i32) -> str:
    if raised == 0:
        return ""
    let text = (u8*)(usize)((isize)(usize)&origin_base + (isize)raised)
    return (str)(c.str)text

## `failure.called_at`: the position text `crossed` bytes from `origin_base`, or `at` (from
## `raised`) when the error came out of no call into another package (`crossed` is 0).
pub func called(raised: i32, crossed: i32) -> str:
    return origin(crossed if crossed != 0 else raised)

## A failed `main`: its error on stderr, `error: file:line:column: message (code n)`, the
## place being where the error was raised, `at`, then `  called at file:line:column` when it
## came out of a call into another package, `called_at`; exit status 1. The code shown is the
## package's own number, `n` of `ErrorCode.package(n)`; the package identity above it (§11.3)
## tells packages apart and means nothing to a reader.
pub func main_failed(code: i32, message: str, raised: i32, crossed: i32) -> i32:
    var bytes: u8[1024] = ---
    let at = origin(raised)
    let number = (u32)code & 0xFFFF
    let line = strings.format(bytes, f"error: {at}: {message} (code {number})\n" if at.length > 0 else f"error: {message} (code {number})\n") catch:
        return 1
    _ = write(2, line.bytes.data, line.length)
    let call = origin(crossed)
    if call.length > 0 and call != at:
        let second = strings.format(bytes, f"  called at {call}\n") catch:
            return 1
        _ = write(2, second.bytes.data, second.length)
    return 1

## The failure of a test whose `assert` was false (§16.5).
pub let assert_failed: ErrorCode = ErrorCode.package(60)

## Where the `assert` that failed the running test stands, empty while none has, and the
## room its message is written in, which the failure views until the test is reported.
var assert_position: c.str = ""
var assert_message: u8[1024]

## A false `assert` in a test's own body (§16.5): the test fails with `text`, `assert failed:`
## and the condition, and `detail` after it when there is one, and is reported at `position`,
## the assert's.
pub func test_assert(position: c.str, text: c.str, detail: str, detailed: bool) -> !:
    assert_position = position
    let condition = (str)text
    let message = strings.format(assert_message, f"{condition}: {detail}" if detailed else f"{condition}") catch:
        recover condition
    error(assert_failed, message)

## The test the runner is running, empty between tests, and the tally so far: a trap or
## fatal signal in a test names it as failed and prints the tally before the run ends.
var test_running: str = ""
var tests_passed: i32 = 0
var tests_failed: i32 = 0

## The runner starts the test named `name`.
pub func test_start(name: str):
    test_running = name

## The test runner's report line for the test that ran: `ok`, or `FAIL` with the place and
## the message on the next line, the place being the failed `assert`'s or else the test's
## own, `at` (§16.5).
pub func test_report(failed: bool, at: c.str, message: str):
    let place = (str)(assert_position if ((str)assert_position).length > 0 else at)
    assert_position = ""
    test_result(failed, place, message)

## Report the test that ran and count it: `ok    name`, or `FAIL  name` and the indented
## `place: message`. Luce's runners report through here too, so every runner prints alike.
pub func test_result(failed: bool, place: str, message: str):
    let name = test_running
    test_running = ""
    if failed:
        tests_failed += 1
    else:
        tests_passed += 1
    if not failed:
        write_all(1, "ok    ".bytes)
        write_all(1, name.bytes)
        write_all(1, "\n".bytes)
        return
    write_all(1, "FAIL  ".bytes)
    write_all(1, name.bytes)
    write_all(1, "\n      ".bytes)
    write_all(1, place.bytes)
    write_all(1, ": ".bytes)
    write_all(1, message.bytes)
    write_all(1, "\n".bytes)

## Print the tally of the tests run, the failures counted when there are any; the process
## exit status. Formats without the heap or `strings`, since a trap may print it.
pub func test_summary() -> i32:
    var line: u8[128] = ---
    var used = put_decimal(line, 0, (usize)tests_passed)
    used = put_text(line, used, " passed\n")
    if tests_failed > 0:
        used = put_decimal(line, used, (usize)tests_failed)
        used = put_text(line, used, " failed\n")
    write_all(1, line[..<used])
    return 0 if tests_failed == 0 else 1

## `print`: the text and a newline on stdout; `answer()` programs print their number.
pub func print_str(text: str):
    _ = write(1, text.bytes.data, text.length)
    let newline = "\n"
    _ = write(1, newline.bytes.data, 1)

# mark: Streamed text =========================================================================

## `print(f"...")` and `trap(f"...")` fill a format buffer and write it out to `descriptor`
## (1, standard output; 2, the diagnostic) as it fills, so no buffer bounds the text and a
## short line is one write. Append `count` bytes at `data` and leave at least half the
## buffer free, which is room for the fields the compiler displays into it between pieces;
## a field that displays itself longer than that is cut, as `format_finish` marks.
pub func stream_put(b: FormatBuffer*, data: const u8*, count: usize, descriptor: i32):
    if b.used > b.capacity or count > b.capacity - b.used:
        stream_flush(b, descriptor)
    if count >= b.capacity:
        stream_write(descriptor, u8[]((u8*)data, count))
        return
    _ = format_put(b, data, count)
    if b.used > b.capacity // 2:
        stream_flush(b, descriptor)

## Write out the buffer's text and empty it: the end of a streamed text.
pub func stream_flush(b: FormatBuffer*, descriptor: i32):
    if b.used > 0:
        stream_write(descriptor, format_finish(b).bytes)
    b.used = 0

func stream_write(descriptor: i32, data: const u8[]):
    if descriptor == 2:
        write_diagnostic(data)
    else:
        write_all(descriptor, data)

## Print `value` followed by a newline.
pub func print_i64(value: i64):
    var bytes: u8[32] = ---
    let all: u8[] = bytes
    var b = FormatBuffer(data = all.data, capacity = 32, used = 0)
    _ = format_i64(&b, value)
    _ = write(1, all.data, b.used)
    let newline = "\n"
    _ = write(1, newline.bytes.data, 1)

## Ordering of text: bytewise, then by length (§7.4).
pub func str_compare(a: str, b: str) -> i32:
    let n = a.length if a.length < b.length else b.length
    var order: i32 = 0
    if n > 0:
        order = memcmp(a.bytes.data, b.bytes.data, n)
    if order != 0:
        return -1 if order < 0 else 1
    if a.length < b.length:
        return -1
    return 1 if a.length > b.length else 0

## The scalar starting at byte `index` of `count` bytes of valid UTF-8, its width left in
## `width`: what `for character in text` steps by (§5.5).
pub func utf8_scalar(text: const u8*, count: usize, index: usize, width: usize*) -> char:
    let byte = text[index]
    var w: usize = 1
    var cp: u32 = (u32)byte
    if byte >= 240:
        w = 4
        cp = (u32)(byte & 7)
    elif byte >= 224:
        w = 3
        cp = (u32)(byte & 15)
    elif byte >= 192:
        w = 2
        cp = (u32)(byte & 31)
    if index + w > count:
        w = count - index
    var k: usize = 1
    while k < w:
        cp = (cp << 6) | (u32)(text[index + k] & 63)
        k += 1
    *width = w
    return char(cp)

## Whether `count` bytes are well-formed UTF-8: no overlong forms, no surrogates, nothing past U+10FFFF.
pub func utf8_ok(text: const u8*?, count: usize) -> bool:
    let s = text else return count == 0
    var i: usize = 0
    while i < count:
        # eight ASCII bytes at a time: source text is mostly ASCII
        while i + 8 <= count:
            var word: u64 = 0
            _ = memcpy(&word, &s[i], 8)
            if (word & 0x8080808080808080) != 0:
                break
            i += 8
        if i >= count:
            break
        let byte = s[i]
        var w: usize = 1
        var cp: u32 = 0
        if byte < 128:
            cp = (u32)byte
        elif (byte & 224) == 192:
            w = 2
            cp = (u32)(byte & 31)
        elif (byte & 240) == 224:
            w = 3
            cp = (u32)(byte & 15)
        elif (byte & 248) == 240:
            w = 4
            cp = (u32)(byte & 7)
        else:
            return false
        if i + w > count:
            return false
        var k: usize = 1
        while k < w:
            let x = s[i + k]
            if (x & 192) != 128:
                return false
            cp = (cp << 6) | (u32)(x & 63)
            k += 1
        if w == 2 and cp < 128:
            return false
        if w == 3 and cp < 2048:
            return false
        if w == 4 and cp < 65536:
            return false
        if cp >= 55296 and cp <= 57343:
            return false
        if cp > 1114111:
            return false
        i += w
    return true

## `hash`: a per-process seed and a multiplicative mixer (§7.4).
var hash_seed_value: u64
var hash_seeded: bool

## A per-process seed for the collection hashers.
# mark: Hashing ===============================================================================

## The process's per-run hash seed, chosen once from the address space.
pub func hash_seed() -> u64:
    if not hash_seeded:
        hash_seed_value = 11400714819323198485 ^ (u64)(usize)&hash_seed_value
        hash_seeded = true
    return hash_seed_value

## Mix `x` into the running hash `h`.
pub func hash_mix(h: u64, x: u64) -> u64:
    var r = h ^ x
    r = r *% 11400714819323198485
    r = r ^ (r >> 32)
    return r

## Mix `count` bytes at `data` into the running hash `h`.
pub func hash_bytes(h: u64, data: const void*?, count: usize) -> u64:
    var r = h
    if let p = data:
        let bytes = (const u8*)p
        var i: usize = 0
        while i < count:
            r = hash_mix(r, (u64)bytes[i])
            i += 1
    return hash_mix(r, (u64)count)

## Integer conversions between widths: `bits` of `value` as a 64-bit word.
func mask_of(bits: i32) -> u64:
    if bits >= 64:
        return 18446744073709551615
    return (1 << (u64)bits) - 1

func sign_extend(value: i64, bits: i32) -> i64:
    if bits >= 64:
        return value
    let m = mask_of(bits)
    let x = (u64)value & m
    if (x & (1 << (u64)(bits - 1))) != 0:
        return (i64)(x | ~m)
    return (i64)x

func zero_extend(value: u64, bits: i32) -> u64:
    return value & mask_of(bits)

func signed_min(bits: i32) -> i64:
    if bits >= 64:
        return -9223372036854775807 - 1
    return 0 -% (1 << (i64)(bits - 1))

func signed_max(bits: i32) -> i64:
    if bits >= 64:
        return 9223372036854775807
    return (1 << (i64)(bits - 1)) - 1

func fits_signed(value: i64, bits: i32) -> bool:
    return value >= signed_min(bits) and value <= signed_max(bits)

func fits_unsigned(value: u64, bits: i32) -> bool:
    return value <= mask_of(bits)

## The source of an integer conversion as a sign and a magnitude, so a `u64` above
## `i64.max` stays itself.
struct Magnitude:
    var negative: bool
    var bits: u64

func magnitude(value: u64, from_bits: i32, from_signed: i32) -> Magnitude:
    if from_signed != 0:
        let v = sign_extend((i64)value, from_bits)
        return Magnitude(negative = v < 0, bits = (u64)v)
    return Magnitude(negative = false, bits = zero_extend(value, from_bits))

## A checked conversion's result as bits: outside the destination's range traps (§7.5),
## naming the statement at `at`.
func checked_bits(m: Magnitude, to_bits: i32, to_signed: i32, at: c.str) -> u64:
    var bad = false
    if to_signed != 0:
        bad = (i64)m.bits < signed_min(to_bits) if m.negative else m.bits > (u64)signed_max(to_bits)
    else:
        bad = m.negative or not fits_unsigned(m.bits, to_bits)
    if bad:
        trap_at(at, "integer conversion out of range")
    return m.bits

## `T(x)` between integers (`mode` 0, checked) and `(T)x` (`mode` 1, truncating).
pub func conv_s(value: i64, from_bits: i32, from_signed: i32, to_bits: i32, to_signed: i32, mode: i32, at: c.str) -> i64:
    let m = magnitude((u64)value, from_bits, from_signed)
    if mode == 0:
        return (i64)checked_bits(m, to_bits, to_signed, at)
    let bits = m.bits & mask_of(to_bits)
    if to_signed != 0:
        return sign_extend((i64)bits, to_bits)
    return (i64)bits

## Convert an unsigned value between integer widths and signedness; `mode` chooses checked or wrapping.
pub func conv_u(value: u64, from_bits: i32, from_signed: i32, to_bits: i32, to_signed: i32, mode: i32, at: c.str) -> u64:
    let m = magnitude(value, from_bits, from_signed)
    if mode == 0:
        return checked_bits(m, to_bits, to_signed, at)
    return zero_extend(m.bits, to_bits)

## A `char` from an integer's bits: a scalar value, or a trap when checked (`mode` 0).
pub func to_char(value: u64, mode: i32, at: c.str) -> u64:
    let bad = value > 1114111 or (value >= 55296 and value <= 57343)
    if bad and mode == 0:
        trap_at(at, "integer conversion out of range")
    return value & 4294967295

func is_finite(value: f64) -> bool:
    return value - value == 0.0

## `2^(bits-1)` and `2^bits` as floats: exact, where `(f64)signed_max(64)` rounds up to `2^63`.
func float_bound_s(bits: i32) -> f64:
    return (f64)((u64)1 << (u64)(bits - 1))

func float_bound_u(bits: i32) -> f64:
    return float_bound_s(bits) * 2.0

## Float to integer: checked (`mode` 0) or saturating (`mode` 1); the cast inside is the target's own.
pub func f_to_s(value: f64, bits: i32, mode: i32, at: c.str) -> i64:
    let high = float_bound_s(bits)
    let low = 0.0 - high
    if mode == 0:
        if not is_finite(value) or value < low or value >= high:
            trap_at(at, "integer conversion out of range")
        return (i64)value
    if value != value:
        return 0
    if value <= low:
        return signed_min(bits)
    if value >= high:
        return signed_max(bits)
    return (i64)value

## Convert a float to an unsigned integer of `bits`; `mode` checks the range.
pub func f_to_u(value: f64, bits: i32, mode: i32, at: c.str) -> u64:
    let high = float_bound_u(bits)
    if mode == 0:
        if not is_finite(value) or value < 0.0 or value >= high:
            trap_at(at, "integer conversion out of range")
        return (u64)value
    if value != value or value < 0.0:
        return 0
    if value >= high:
        return mask_of(bits)
    return (u64)value

## Saturating arithmetic (`+|`, `-|`, `*|`) on `bits`-wide operands in 64-bit words.
func add_overflows_s(a: i64, b: i64, r: i64) -> bool:
    return ((a ^ r) & (b ^ r)) < 0

func sub_overflows_s(a: i64, b: i64, r: i64) -> bool:
    return ((a ^ b) & (a ^ r)) < 0

func mul_overflows_s(a: i64, b: i64) -> bool:
    if a == 0 or b == 0:
        return false
    if a == -1:
        return b == signed_min(64)
    if b == -1:
        return a == signed_min(64)
    return (a *% b) // b != a

## Saturating signed addition at `bits`.
# mark: Saturating and checked arithmetic =====================================================

## Saturating signed addition of `x` and `y` at `bits` bits.
pub func adds_s(x: i64, y: i64, bits: i32) -> i64:
    let a = sign_extend(x, bits)
    let b = sign_extend(y, bits)
    let r = a +% b
    if add_overflows_s(a, b, r) or not fits_signed(r, bits):
        return signed_min(bits) if a < 0 else signed_max(bits)
    return r

## Saturating unsigned addition at `bits`.
pub func adds_u(x: u64, y: u64, bits: i32) -> u64:
    let a = zero_extend(x, bits)
    let b = zero_extend(y, bits)
    let r = a +% b
    if r < a or not fits_unsigned(r, bits):
        return mask_of(bits)
    return r

## Saturating signed subtraction at `bits`.
pub func subs_s(x: i64, y: i64, bits: i32) -> i64:
    let a = sign_extend(x, bits)
    let b = sign_extend(y, bits)
    let r = a -% b
    if sub_overflows_s(a, b, r) or not fits_signed(r, bits):
        return signed_min(bits) if a < 0 else signed_max(bits)
    return r

## Saturating unsigned subtraction at `bits`.
pub func subs_u(x: u64, y: u64, bits: i32) -> u64:
    let a = zero_extend(x, bits)
    let b = zero_extend(y, bits)
    if a < b:
        return 0
    return a - b

## Saturating signed multiplication at `bits`.
pub func muls_s(x: i64, y: i64, bits: i32) -> i64:
    let a = sign_extend(x, bits)
    let b = sign_extend(y, bits)
    if mul_overflows_s(a, b) or not fits_signed(a *% b, bits):
        return signed_min(bits) if (a < 0) != (b < 0) else signed_max(bits)
    return a *% b

## Saturating unsigned multiplication at `bits`.
pub func muls_u(x: u64, y: u64, bits: i32) -> u64:
    let a = zero_extend(x, bits)
    let b = zero_extend(y, bits)
    if b != 0 and a > mask_of(bits) // b:
        return mask_of(bits)
    return zero_extend(a *% b, bits)

## Checked-to-optional arithmetic (`+?`, `-?`, `*?`): the result through `out`, whether it fit.
pub func qadd_s(x: i64, y: i64, bits: i32, out: i64*) -> bool:
    let a = sign_extend(x, bits)
    let b = sign_extend(y, bits)
    let r = a +% b
    if add_overflows_s(a, b, r) or not fits_signed(r, bits):
        return false
    *out = r
    return true

## Checked unsigned addition through `out`; whether it fit.
pub func qadd_u(x: u64, y: u64, bits: i32, out: u64*) -> bool:
    let a = zero_extend(x, bits)
    let b = zero_extend(y, bits)
    let r = a +% b
    if r < a or not fits_unsigned(r, bits):
        return false
    *out = r
    return true

## Checked signed subtraction through `out`; whether it fit.
pub func qsub_s(x: i64, y: i64, bits: i32, out: i64*) -> bool:
    let a = sign_extend(x, bits)
    let b = sign_extend(y, bits)
    let r = a -% b
    if sub_overflows_s(a, b, r) or not fits_signed(r, bits):
        return false
    *out = r
    return true

## Checked unsigned subtraction through `out`; whether it fit.
pub func qsub_u(x: u64, y: u64, bits: i32, out: u64*) -> bool:
    let a = zero_extend(x, bits)
    let b = zero_extend(y, bits)
    if a < b:
        return false
    *out = a - b
    return true

## Checked signed multiplication through `out`; whether it fit.
pub func qmul_s(x: i64, y: i64, bits: i32, out: i64*) -> bool:
    let a = sign_extend(x, bits)
    let b = sign_extend(y, bits)
    if mul_overflows_s(a, b) or not fits_signed(a *% b, bits):
        return false
    *out = a *% b
    return true

## Checked unsigned multiplication through `out`; whether it fit.
pub func qmul_u(x: u64, y: u64, bits: i32, out: u64*) -> bool:
    let a = zero_extend(x, bits)
    let b = zero_extend(y, bits)
    if b != 0 and a > mask_of(bits) // b:
        return false
    *out = a *% b
    return true

## Terminate the process through the minimal runtime layer.
pub func exit(code: i32) -> never:
    c_exit(code)