vercel-labs--zerolang/native/zero-c/CONTRACTS.md

Native C API Contracts

This file defines the public C API contract vocabulary used by include/zero.h. The macros in include/zero_contracts.h are zero-cost C annotations; the contract is enforced by pnpm run native:contracts.

Pointer Parameters

Every exported pointer parameter in include/zero.h must carry exactly one access effect.

Effect	Contract
Z_IN T *p	Borrowed read-only input. The callee may read *p during the call only. It must not mutate, free, or retain p.
Z_OUT T *p	Caller-owned output storage. The callee initializes or overwrites *p. Ownership of the outer storage stays with the caller.
Z_INOUT T *p	Caller-owned mutable storage. The callee may read and write *p during the call. Ownership stays with the caller.
Z_SINK T *p	Consumed pointer value. The caller must not use the incoming pointer after the call unless the return value gives a replacement.
Z_OPTIONAL	Nullable parameter modifier. It must be paired with one of the access effects above.

Pointer Returns

Every exported function returning a pointer must state ownership.

Return marker	Contract
Z_RET_OWNED T *	Caller owns the returned pointer and releases it with free or the documented type-specific free function.
Z_RET_BORROWED T *	Caller must not free the pointer. The storage is static, table-backed, or owned by a borrowed input.
Z_RET_OPTIONAL	Nullable return modifier. It must be paired with Z_RET_OWNED or Z_RET_BORROWED.

Owned returns are non-null unless marked Z_RET_OPTIONAL. Borrowed returns are valid until the documented table/input lifetime ends and must not be retained past that lifetime.

Function Families

Family	Contract
zbuf_*	zbuf_init initializes caller storage. zbuf_append* mutate initialized buffers. zbuf_free releases owned buffer storage and leaves the buffer empty.
z_checked_*	Allocation helpers return owned non-null storage or terminate the process with the allocation fatal path. z_checked_reallocarray consumes the old pointer and returns the replacement.
z_strdup, z_strndup, path helpers	Return owned heap strings. Optional path lookup helpers return NULL when no path exists.
z_read_file	Returns an owned heap buffer on success; returns NULL and writes ZDiag on I/O failure.
z_write_file, z_write_binary_file	Borrow input buffers for the duration of the call; return false and write ZDiag on I/O failure.
z_free_source, z_free_manifest, z_free_ir_program, z_free_program	Consume owned fields inside caller-owned structs, then leave them reusable or inert. They do not free the outer stack object.
target/backend lookup helpers	Return borrowed table/static strings or borrowed table rows. Optional lookup helpers return NULL for unknown targets or unsupported requests.
emit/build helpers	Borrow the IR/target/toolchain inputs, append or write through caller-owned output buffers, and report failures through ZDiag.

Internal Representation Boundary

Textual names are accepted at parsing, graph, manifest, CLI, and import boundaries. Internal compiler stages should carry typed ids, enums, helper metadata, and graph facts instead of repeatedly branching on strings. When a string comparison remains in IR or backend code, it should be a boundary decode or a temporary step toward a typed table.

Machine Contract

scripts/native-contracts.mts checks include/zero.h for:

• all contract macros exist in include/zero_contracts.h
• every exported pointer parameter has Z_IN, Z_OUT, Z_INOUT, or Z_SINK
• Z_OPTIONAL parameters are paired with an access effect
• every exported pointer return has Z_RET_OWNED or Z_RET_BORROWED
• Z_RET_OPTIONAL returns are paired with return ownership