Standard Library, Primitives, and OS

This file is part of the Nocter language specification. The specification entry point is README.md.

OS Error Model

Adopted: Nocter uses a layered OS error model. Target-specific raw errors are converted into common standard-library records, then into the built-in error payload used by T!.

Layering:

std/os              common std plus target-gated internals: Platform, OSErrorKind, OSError, syscall, SyscallResult, Errno, errno mapping
std/error           Error, ErrorCode, and constructors for the built-in error payload
std/io              user-facing I/O APIs
std/process         user-facing process APIs

The compiler must not special-case names such as Error, ErrorCode, OSError, Errno, File, args, env, cwd, exit, or abort. These are ordinary standard-library names. The only compiler-level failure type is lowercase error.

Target Raw Errors

std/os owns the raw macOS syscall result and errno wrapper behind #target("arm64-darwin").

#target("arm64-darwin")
pub(nocter) copy struct SyscallResult {
    pub value: usize
    pub errno: i32
}

#target("arm64-darwin")
pub(nocter) copy struct Errno {
    pub code: i32
}

Rules:

SyscallResult.errno == 0 means success.
SyscallResult.errno != 0 means failure.
SyscallResult.value is syscall-specific.
Errno is a target-specific raw error wrapper.
Errno is not exposed as the common OS error type.
syscall number constants live in target-specific std internals, not in user-facing APIs.
the exact syscall number list is a target implementation detail.

Common OS Error

Common standard library module:

std/os

Initial std-internal surface:

pub(nocter) enum Platform {
    macos
    linux
    windows
}

pub(nocter) enum OSErrorKind {
    interrupted
    would_block
    not_found
    permission_denied
    already_exists
    invalid_input
    broken_pipe
    timed_out
    unsupported
    unknown
}

pub(nocter) copy struct OSError {
    pub platform: Platform
    pub code: i32
    pub kind: OSErrorKind
}

Rules:

OSError is the common OS error record.
OSError.platform records the originating platform.
OSError.code stores the target raw code.
On macOS and Linux, code is an errno value.
On Windows, code will be a Windows raw error code chosen by the Windows target design.
OSError.kind is the portable classification used by higher-level standard-library modules.
OSError, OSErrorKind, and Platform are pub(nocter) implementation details. User-facing APIs expose the built-in error payload instead.
Target-gated Errno declarations in std/os are not exposed as the common OS error type.

Target-specific std internals convert raw target errors into OSError.

SyscallResult -> Errno -> OSError

Common Error Payload

The built-in failure payload is error. The standard library exposes ordinary names and constructors for it.

Initial public surface:

pub type ErrorCode = &str
pub type Error = error

pub func Error.new(code: ErrorCode, message: &str): Error

Initial standard-library implementation boundary:

pub(nocter) primitive new_error(code: &str, message: &str): error

pub func Error.new(code: ErrorCode, message: &str): Error {
    return new_error(code, message)
}

Rules:

error is the compiler built-in payload type.
Error and ErrorCode are ordinary standard-library names.
The compiler does not know the name ErrorCode. ErrorCode is an open string classification alias over &str, and Error.new converts that string slice into the built-in error payload's primitive code representation.
new_error is a pub(nocter) standard-library implementation primitive in std/error; user project modules must call Error.new instead of importing it.
Standard-library codes use dotted names such as "std.io.not_found", "std.mem.out_of_memory", "std.string.capacity_overflow", "std.fmt.unsupported", and "std.process.invalid_encoding". User and package code may use their own prefixes, such as "app.config.missing_key".
Standard-library modules should fail with error, not domain-specific fallible error type parameters.
Domain-specific detail is represented by ErrorCode, message, and, where needed later, additional standard-library helper APIs.

String and Formatting API Boundary

Adopted: the initial owning-string and formatting boundary is split between std/string and std/fmt.

Initial std/string public surface:

pub struct String {
    ...
}

pub func String.empty(): String
pub func String.with_capacity(allocator: &+Allocator, capacity: usize): String!
pub func String.from_str(allocator: &+Allocator, value: &str): String!
pub func String.copy(allocator: &+Allocator, value: &str): String!

pub func empty(): String
pub func with_capacity(allocator: &+Allocator, capacity: usize): String!
pub func from_str(allocator: &+Allocator, value: &str): String!
pub func view(text: &String): &str
pub func len(text: &String): usize
pub func capacity(text: &String): usize
pub func is_empty(text: &String): bool
pub func reserve(text: &+String, additional: usize): void!
pub func clear(text: &+String): void
pub func bytes(value: &str): &[u8]
pub func push_str(text: &+String, value: &str): void!
pub func capacity_overflow(): error

impl String {
    pub method &self.view(): &str
    pub method &self.len(): usize
    pub method &self.capacity(): usize
    pub method &self.is_empty(): bool
    pub method &self.bytes(): &[u8]
    pub method &+self.reserve(additional: usize): void!
    pub method &+self.clear(): void
    pub method &+self.push_str(value: &str): void!
}

Initial std/fmt public surface:

pub func append_str(out: &+String, value: &str): void!
pub func append_string(out: &+String, value: &String): void!
pub func append_i32(out: &+String, value: i32): void!
pub func append_usize(out: &+String, value: usize): void!
pub func append_bool(out: &+String, value: bool): void!

Rules:

These functions are ordinary standard-library APIs, not compiler built-ins.
Fallible functions fail with the built-in error payload. std/string and std/fmt must not introduce StringError, FormatError, or another domain-specific fallible payload.
std/string.with_capacity and std/string.from_str take an explicit &+Allocator.
The formatting append functions operate on an already-created String; they do not choose an allocator.
Future lowering for string interpolation must be expressed in terms of explicit String construction and std/fmt.append_* calls. It must not silently choose a process-global allocator.
std/fmt is not part of the initial prelude. User code imports it explicitly unless future prelude policy changes.
Module-local helpers such as formatting unsupported errors are not public API unless explicitly listed in this chapter.

Memory and Allocator API

Adopted: v0 exposes a small explicit allocator surface in std/mem.

Initial public surface:

pub copy struct Layout {
    pub size: usize
    pub align: usize
}

pub struct RawBuffer {
    pub(nocter) ptr: *u8
    pub(nocter) len: usize
    pub(nocter) align: usize
}

pub struct Allocator {
    ...
}

pub func page_allocator(): Allocator
pub func alloc(allocator: &+Allocator, size: usize, align: usize): RawBuffer!
pub func free(allocator: &+Allocator, buffer: RawBuffer): void
pub func bytes(buffer: &RawBuffer): &[u8]
pub func bytes_mut(buffer: &+RawBuffer): &+[u8]
pub func prefix(buffer: &RawBuffer, len: usize): &[u8]!
pub func prefix_mut(buffer: &+RawBuffer, len: usize): &+[u8]!
pub func out_of_memory(): error
pub func invalid_argument(): error

impl Allocator {
    pub method &+self.alloc(size: usize, align: usize): RawBuffer!
    pub method &+self.free(buffer: RawBuffer): void
}

impl RawBuffer {
    pub method &self.bytes(): &[u8]
    pub method &+self.bytes_mut(): &+[u8]
    pub method &self.prefix(len: usize): &[u8]!
    pub method &+self.prefix_mut(len: usize): &+[u8]!
}

Rules:

Allocation failure is recoverable and returns the built-in error payload.
The initial allocator is page-backed. General allocator families are deferred.
RawBuffer owns raw byte storage and is not a typed collection.
RawBuffer's representation fields are pub(nocter): trusted std modules may inspect and pass the raw storage boundary onward, but user project modules must obtain views through the public bytes, bytes_mut, prefix, prefix_mut, and method APIs.
User-facing collection APIs should be built on ordinary std types such as Vec<T>, not by exposing unchecked raw buffer mutation.
Target-dependent allocation helpers are std-internal and target-gated.

Vector API

Adopted: std/vec provides the initial owned variable-length collection type. Vec<T> is an ordinary standard-library type, not a compiler built-in.

Initial public surface:

pub struct Vec<T> {
    ...
}

pub func Vec.empty<T>(): Vec<T>
pub func Vec.with_capacity<T>(allocator: &+Allocator, requested_capacity: usize): Vec<T>!
pub func Vec.from_slice<T>(allocator: &+Allocator, values: &[T]): Vec<T>!

pub func empty<T>(): Vec<T>
pub func with_capacity<T>(allocator: &+Allocator, requested_capacity: usize): Vec<T>!
pub func from_slice<T>(allocator: &+Allocator, values: &[T]): Vec<T>!
pub func len<T>(values: &Vec<T>): usize
pub func capacity<T>(values: &Vec<T>): usize
pub func is_empty<T>(values: &Vec<T>): bool
pub func view<T>(values: &Vec<T>): &[T]
pub func view_mut<T>(values: &+Vec<T>): &+[T]
pub func reserve<T>(values: &+Vec<T>, additional: usize): void!
pub func clear<T>(values: &+Vec<T>): void
pub func push<T>(values: &+Vec<T>, value: T): void!
pub func capacity_overflow(): error

impl<T> Vec<T> {
    pub method &self.len(): usize
    pub method &self.capacity(): usize
    pub method &self.is_empty(): bool
    pub method &self.view(): &[T]
    pub method &+self.view_mut(): &+[T]
    pub method &+self.reserve(additional: usize): void!
    pub method &+self.clear(): void
    pub method &+self.push(value: T): void!

    drop &+self {
        ...
    }
}

Rules:

Vec<T> is not exported by std/prelude; user code imports std/vec.Vec explicitly.
The v0 runtime surface is narrow. Scalar, &str, and explicitly promoted copy-aggregate element storage paths are supported by the current implementation.
Non-copy aggregate element storage, per-element drop glue, insertion/removal APIs, and iterator helpers are deferred.
check may accept Vec<T> APIs outside the runtime-supported element subset when they typecheck. build and run must reject unsupported Vec<T> element storage paths during v0 buildability validation.
clear resets length. Element drop behavior is deferred until per-element drop glue is designed.
view and view_mut expose slices over initialized elements only.

I/O API

Adopted: std/io provides the initial user-facing file and text output API. The compiler must not special-case File, stdout, stderr, or print.

Initial public surface:

pub struct File {
    ...
}

pub func open(path: &str): File!
pub func File.open(path: &str): File!
pub func read(file: &+File, buffer: &+[u8]): usize!
pub func write(file: &+File, bytes: &[u8]): void!
pub func write_text(file: &+File, text: &str): void!

impl File {
    pub method &+self.read(buffer: &+[u8]): usize!
    pub method &+self.write(bytes: &[u8]): void!
    pub method &+self.write_text(text: &str): void!

    drop &+self {
        ...
    }
}

pub func stdout(): File
pub func stderr(): File
pub func print(text: &str): void!

Rules:

File is a move-only standard-library type with private representation.
open, read, write, and write_text are ordinary free-function wrappers around the associated function or methods.
File.open(path) opens an existing file for reading in v0.
File creation, append, truncate, read-write modes, and open options are deferred.
File.open(path) maps path-related OS errors into "std.io.not_found", "std.io.permission_denied", or "std.io.invalid_path" when the target can classify them.
read(buffer) reads into a writable byte view and returns the number of bytes read.
read(buffer) returning 0 means end of file for regular files.
read(buffer) may return fewer bytes than buffer.len() without treating that as an error.
write(bytes) writes all bytes in the view or fails.
Target implementations handle partial OS writes inside write(bytes).
write_text(text) writes the UTF-8 bytes of &str without encoding conversion.
print(text) writes text to stdout() and does not append a newline.
stdout() and stderr() return File values representing the process standard streams.
File internally distinguishes owned handles from borrowed process standard streams.
Dropping a File returned by File.open(path) closes the owned handle.
Dropping a File returned by stdout() or stderr() must not close the process standard stream.
The File drop member cannot fail. Close errors are ignored in v0 unless a future explicit close API is adopted.
Unexpected OS errors are converted to "std.os.unexpected_os_error" with a message that preserves useful target context.

Physical placement:

std/io is the user-facing module path and owns File plus the public I/O API.
Target-dependent raw file-descriptor helpers live in std/io as pub(nocter) implementation details.
Target-dependent helper functions and primitive declarations use #target("...").
Raw helper names such as write_text_raw are not user-facing API.
Common I/O API names should remain stable across targets.

Conversion flow:

std/os.syscall3
    -> SyscallResult
    -> Errno
    -> std/os.OSError
    -> error

Not adopted in v0:

buffered I/O
async I/O
seek
directory traversal
path object
encoding conversion
automatic newline printing
compiler magic for print
println as a compiler feature

Process Context

Adopted: command-line arguments and environment access are standard-library APIs in std/process, not entry function parameters.

Initial public surface:

pub func args(): Vec<&str>!
pub func env(name: &str): &str?!
pub func cwd(allocator: &+Allocator): String!
pub func exit(code: i32): never
pub func abort(): never

V0 distribution status:

exit(code) and abort() are runtime-shipped.
cwd(allocator) is runtime-shipped on arm64-darwin through the standard-library syscall boundary and returns caller-owned String storage.
args() is runtime-shipped on arm64-darwin and returns an owned Vec<&str> whose string views point into process context storage.
env(name) reserves the future &str?! API shape, but useful runtime behavior is check-only until nested fallible/optional return lowering and process context runtime are promoted. It must not silently succeed with none before environment access is implemented.
During the check-only period, check accepts calls to env(name) for source-level validation, while build and run reject them during v0 buildability validation.

Rules:

Entry function type parameters and value parameters, such as func main<T>(): i32! and func main(args: Vec<&str>): i32!, are not part of v0.
The compiler must not special-case a function named args, env, cwd, exit, or abort.
The generated low-level entry code may receive platform process entry information such as argc, argv, and envp.
That platform information is connected to a std/process process context inside the active target implementation.
User code reads command-line arguments with std/process.args().
User code reads environment values with std/process.env(name).
args() returns an owned Vec<&str> of borrowed string slices on success.
The first argument follows the host platform convention and represents the executable path or invocation name when the platform provides one.
The env(name) runtime behavior rules below are the contract for the future promoted implementation. During the v0 check-only period, build and run reject env(name) before lowering.
env(name) has type &str?!.
env(name) succeeds with none when the variable is absent.
env(name) succeeds with a present &str when the variable is present and valid UTF-8.
cwd(allocator) returns an owned current-working-directory string or fails with error.
cwd(allocator) fails with "std.process.cwd_failed" if the target cannot retrieve the current working directory.
Process context string storage is valid for the whole program.
Argument and environment views returned by std/process are not owned by the caller and must be treated as borrowed view data.
The caller must not drop process-context storage.
The cwd(allocator) result is owned by the caller and must be dropped normally.
APIs that need owned strings must explicitly copy into an allocator-owned String.
Target implementations must validate argument and environment strings before exposing them as &str.
The v0 arm64-darwin cwd(allocator) implementation treats the path returned by F_GETPATH as platform UTF-8 text; byte-to-UTF-8 validation for targets that expose arbitrary path bytes remains future std work.
args() fails with "std.process.invalid_encoding" if any returned argument cannot be represented as UTF-8.
env(name) fails with "std.process.invalid_encoding" if the matching environment value exists but cannot be represented as UTF-8.
Future target implementations of cwd(allocator) must fail with "std.process.invalid_encoding" if their current-working-directory source can contain non-UTF-8 bytes and validation fails.

Example:

use std/process.args

func main(): i32! {
    let argv = args()?

    if argv.len() < 2 {
        return 1
    }

    return 0
}

Physical placement:

std/process is the user-facing module path.
Process context implementation may call target-gated std internals when it depends on the target process ABI.
Common process API names should remain stable across targets.

Process Termination

std/process's terminating functions are normal standard-library APIs.

pub func exit(code: i32): never
pub func abort(): never

Rules:

exit is not a compiler primitive.
abort is not a compiler primitive.
exit does not return an error.
abort does not return an error.
exit terminates the process with an explicit status code.
abort terminates the process immediately as abnormal termination.
Neither exit nor abort runs caller-scope Nocter cleanup. Code that needs cleanup must do it before calling them.
The target implementation uses the active target's syscall or process termination boundary.
If the platform termination operation unexpectedly returns, the implementation calls trap().
The module path is std/process; target-dependent helper or primitive calls inside it are reached through #target-gated std internals.

Pointer API

Adopted: v0 exposes only a narrow raw-pointer surface.

Initial public surface:

pub primitive addr<T>(pointer: *T): usize
pub primitive from_ref<T>(value: &T): *T
pub primitive from_ref_mut<T>(value: &+T): *T

Rules:

These APIs are ordinary public standard-library primitive declarations under std/ptr.
Pointer dereference and general user memory mutation through raw pointers are deferred.
Raw construction helpers such as from_addr, raw-parts string/slice construction, raw stores, and raw copies are pub(nocter) std-internal APIs.

Not Adopted

std/posix is not part of the initial design. macOS and Linux can share POSIX-like ideas, but Windows does not fit that layer cleanly. Shared concepts should use stable module paths such as std/os, std/io, and std/process. Their target-dependent boundaries should remain in std-internal modules with #target on type, helper, and primitive declarations.

Standard Library and Low-Level Code

The compiler must not special-case names such as print, args, env, cwd, exit, abort, or File.

Standard library functions provide these features.

use std/io.stdout

func main(): i32! {
    var out = stdout()
    out.write_text("Hello\n")?
    return 0
}

The standard library may use typed primitive declarations to connect Nocter code to compiler-provided low-level implementations. Arbitrary inline ARM64 asm is not part of the initial language.

#target("arm64-darwin")
pub(nocter) copy struct SyscallResult {
    pub value: usize
    pub errno: i32
}

#target("arm64-darwin")
pub(nocter) primitive syscall3(
    number: usize,
    a0: usize,
    a1: usize,
    a2: usize,
): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive trap(): never

#target("arm64-darwin")
pub(nocter) primitive unreachable(): never

trap() terminates the current process or thread with a target-defined illegal-instruction, breakpoint, or equivalent non-recoverable stop. It has type never, does not return an error, and does not unwind.

unreachable() is a standard-library marker for paths that should be impossible. Reaching it traps.

Initial policy:

primitive declarations are allowed only inside the active Nocter home std/ directory in the initial design.
A primitive declaration has no function body.
A primitive declaration uses normal Nocter parameter and return types.
Target-independent declarations do not use #target.
Target-dependent type declarations, helper functions, and primitive declarations must be preceded by #target("target-name").
#target applies only to top-level function, primitive, struct, enum, interface, and type-alias declarations in v0.
target is not a reserved keyword; it is treated as the directive name only after #.
Primitive calls follow normal visibility rules. A pub primitive may be called by any module that can import it. A pub(nocter) primitive may be called only inside the active Nocter home.
Primitive calls follow the Nocter ABI after visibility and trusted-boundary restrictions pass.
The compiler validates each primitive declaration against the target-independent core primitive set or the closed primitive set for the active target.
The compiler validates primitives by module path, name, and exact signature.
An ordinary func with the same name as a primitive has no primitive behavior.
Standard-library wrappers should expose user-facing APIs such as exit, write, write_text, alloc, and free.
print, exit, abort, file operations, allocators, String, and Buffer are not primitives in v0.
General user code cannot declare primitives in v0. The long-term default direction is that user project modules do not declare primitives.
General user code can call only the small public primitive APIs intentionally exposed by the standard library, such as safe raw-pointer address conversion. Target syscall primitives are pub(nocter).
Arbitrary inline asm is not part of the initial language.

Trusted Boundary

Adopted: v0 has no unsafe keyword, no unsafe block, and no unsafe func.

Instead, the trusted boundary is the active Nocter home:

~/.nocter/std/

Rules:

User project modules are always safe Nocter code in v0.
unsafe is not a reserved keyword in v0.
trusted is not a reserved keyword in v0.
Modules inside the active Nocter home may contain primitive declarations when those declarations match the closed primitive set.
Modules inside the active Nocter home may call pub(nocter) primitive declarations.
Modules inside the active Nocter home may call restricted low-level APIs such as std/ptr.from_addr.
User project modules must not declare primitives.
User project modules must not call pub(nocter) primitive declarations.
User project modules must not call restricted low-level APIs such as std/ptr.from_addr.
Trusted modules still go through normal parsing, type checking, ownership checking, borrowing rules, and drop checking.
Trusted modules should expose ordinary safe APIs to user code, using types such as File, String, Vec<T>, Allocator, error, &str, &[T], and &+[T]. Std-internal records such as OSError must stay behind pub(nocter) unless the public API contract is explicitly changed.
If trusted standard-library code violates an invariant required by its public safe API, that is a standard-library or compiler bug. It is not an opt-in source-level permission granted to user code.

Initial primitive declaration syntax:

pub primitive name(params): ReturnType
pub(nocter) primitive name(params): ReturnType

#target("arm64-darwin")
pub(nocter) primitive target_dependent_name(params): ReturnType

Initial primitive declaration modules:

~/.nocter/std/error.nct
~/.nocter/std/ptr.nct
~/.nocter/std/string.nct
~/.nocter/std/io.nct
~/.nocter/std/os.nct
~/.nocter/std/process.nct

std/error.nct contains the target-independent built-in error payload construction primitive used by Error.new.

std/ptr.nct contains target-independent core pointer primitive declarations. These are required for raw pointer address conversion, borrow-to-pointer conversion, and std-internal construction and copying of string, byte, and typed views over raw storage.

std/string.nct contains the target-independent bytes_from_str primitive used to expose &str storage as a byte slice inside the standard library.

std/io.nct contains the initial arm64-darwin raw file descriptor primitives used by File.open, File.read, File.write, File.write_text, and print. These declarations are pub(nocter) and are not part of the user-facing I/O API.

std/os.nct contains common OS declarations plus target-specific declarations for arm64-darwin behind #target("arm64-darwin"). Future OS targets should add new #target("...") declarations inside stable std-internal modules instead of changing import resolution.

std/process.nct contains the initial arm64-darwin process termination primitive used by std/process.exit. It is pub(nocter) and is not part of the user-facing process API.

Initial core error primitive set:

pub(nocter) primitive new_error(code: &str, message: &str): error

Initial core pointer primitive set:

pub primitive addr<T>(pointer: *T): usize
pub primitive from_ref<T>(value: &T): *T
pub primitive from_ref_mut<T>(value: &+T): *T
pub(nocter) primitive from_addr<T>(address: usize): *T
pub(nocter) primitive pointee_size<T>(pointer: *T): usize
pub(nocter) primitive copy_str_to_ptr(destination: *u8, offset: usize, text: &str): void
pub(nocter) primitive copy_ptr_to_ptr(destination: *u8, source: *u8, byte_count: usize): void
pub(nocter) primitive store_u8_to_ptr(destination: *u8, offset: usize, value: u8): void
pub(nocter) primitive store_value_to_ptr<T>(destination: *T, offset: usize, value: T): void
pub(nocter) primitive str_from_raw_parts(pointer: *u8, len: usize): &str
pub(nocter) primitive slice_from_raw_parts(pointer: *u8, len: usize): &[u8]
pub(nocter) primitive slice_from_raw_parts_mut(pointer: *u8, len: usize): &+[u8]
pub(nocter) primitive slice_from_raw_parts_value<T>(pointer: *T, len: usize): &[T]
pub(nocter) primitive slice_from_raw_parts_value_mut<T>(pointer: *T, len: usize): &+[T]

from_addr, pointee sizing, raw-storage copy/store helpers, and raw-storage view construction helpers are pub(nocter) and therefore restricted to trusted modules inside the active Nocter home. User project modules must not call them. Calls to from_addr with an address expression statically known to be zero are rejected because v0 raw pointers are non-null.

Initial core string primitive set:

pub(nocter) primitive bytes_from_str(value: &str): &[u8]

bytes_from_str is pub(nocter) and is exposed to user code only through ordinary standard-library wrappers such as std/string.bytes and text.bytes().

Initial arm64-darwin target primitive set v0:

#target("arm64-darwin")
pub(nocter) copy struct SyscallResult {
    pub value: usize
    pub errno: i32
}

#target("arm64-darwin")
pub(nocter) primitive syscall0(number: usize): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive syscall1(number: usize, a0: usize): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive syscall2(number: usize, a0: usize, a1: usize): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive syscall3(number: usize, a0: usize, a1: usize, a2: usize): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive syscall4(number: usize, a0: usize, a1: usize, a2: usize, a3: usize): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive syscall5(number: usize, a0: usize, a1: usize, a2: usize, a3: usize, a4: usize): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive syscall6(number: usize, a0: usize, a1: usize, a2: usize, a3: usize, a4: usize, a5: usize): SyscallResult

#target("arm64-darwin")
pub(nocter) primitive trap(): never

#target("arm64-darwin")
pub(nocter) primitive unreachable(): never

#target("arm64-darwin")
pub(nocter) primitive open_read_raw(path: *u8): i32!

#target("arm64-darwin")
pub(nocter) primitive write_text_raw(fd: i32, text: &str): void!

#target("arm64-darwin")
pub(nocter) primitive write_bytes_raw(fd: i32, bytes: &[u8]): void!

#target("arm64-darwin")
pub(nocter) primitive read_bytes_raw(fd: i32, buffer: &+[u8]): usize!

#target("arm64-darwin")
pub(nocter) primitive close_fd_raw(fd: i32): void

#target("arm64-darwin")
pub(nocter) primitive exit_raw(code: i32): never

SyscallResult.errno == 0 means success. SyscallResult.errno != 0 means the syscall failed with an OS error value. The meaning of value is syscall-specific.

The compiler recognizes these declarations only at their registered module path and target:

std/os
std/io
std/process

An ordinary function named syscall3 elsewhere is not primitive.

syscall0 through syscall6 are a bootstrap boundary for the initial macOS standard library. The std/io.*_raw and std/process.exit_raw primitives are narrow bootstrap boundaries for shipped v0 I/O and process termination before all wrappers can be expressed through the ordinary SyscallResult path. Longer term, target-gated std internals may replace direct syscall exposure and these raw primitives with narrower typed wrappers. Those wrappers are standard-library APIs, not compiler primitives.

Typed Primitive Wrappers

Adopted: typed wrappers over low-level target operations are standard-library APIs, not compiler primitives.

The closed compiler primitive set stays small. For the initial arm64-darwin target, the target primitive boundary is std/os.syscall0 through std/os.syscall6, std/os.trap, std/os.unreachable, the raw std/io file descriptor primitives, and std/process.exit_raw; separately, std/ptr, std/error, and std/string own the target-independent core primitive set.

Std-internal modules may define narrower typed wrappers around those primitives:

pub(nocter) func write_fd(fd: FileDescriptor, bytes: &[u8]): void! {
    ...
}

User-facing modules then expose safe ordinary APIs:

pub method &+self.write(bytes: &[u8]): void! {
    ...
}

Rules:

Adding a file API, process API, allocator API, string API, buffer API, or OS wrapper must not require adding a compiler primitive.
The existing std/io.*_raw and std/process.exit_raw primitives are v0 bootstrap exceptions for shipped I/O and process termination, not a precedent for adding one primitive per standard-library API.
Target-specific syscall numbers, raw OS handles, errno-like values, and calling conventions belong in target-gated std internals, not in the compiler's general language semantics.
The compiler validates the existing primitive declarations by module path, name, and exact signature.
An ordinary wrapper name such as open_file_raw, write_fd_raw, mmap_raw, or exit_process has no compiler-defined behavior.
A future compiler primitive may be added only by an explicit language and backend design update, not as the normal way to grow the standard library.
User project modules remain outside the primitive declaration boundary. If Nocter later adds an explicit trusted or unsafe extension, it should not make arbitrary user-defined primitive declarations the default extension mechanism.

Keyword Ownership

Keyword and lexical rules are specified only in Lexical Grammar. This chapter does not maintain a separate keyword list.

Open Design Questions

No open design questions are currently listed in this chapter.