Core Library Guide

lib/core contains the first portable 0x0 library modules. These modules are

ordinary .0x0 source files loaded with ↥; they are not compiler intrinsics.

Every core module must pass the same gates as examples:

• source compiler execution;
• generated stage1.oisa compiler execution;
• generated native C compiler output;
• direct ELF executable output;
• generated ELF compiler OISA equivalence.

Modules

• option.0x0: option-some, option-none, predicates, and fallback access.
• result.0x0: result-ok, result-err, predicates, value fallback, and error

field access.

• map.0x0: text-key association maps built from lists.
• bytes.0x0: byte-list helpers with byte range validation, a

Result-returning safe constructor, and reversible hexadecimal text

conversion.

• json.0x0: pure minimal flat-object JSON field readers returning Option.
• error.0x0: structured error values and conversion to failed Result.
• db.0x0: immutable in-memory table helpers built from maps and options.
• path.0x0: pure relative-path validation and path joining helpers.
• file.0x0: Result-returning safe file read/write wrappers using (cap file).

The JSON helpers are deliberately small. They handle flat object fields and

unescaped string values; they are a seed for the future full JSON package, not a

complete parser.

Source Contract

make core-library-check verifies the source-level contract for every core

module without invoking the compiler. The current checked exports are:

• option.0x0: option-none, option-some, predicates, and fallback access.
• result.0x0: result-ok, result-err, predicates, fallback access, and

error field access.

• map.0x0: map-empty, map-entry, map-put, map-get, map-has?, and

map-remove.

• bytes.0x0: bytes-empty, byte validation, checked/unchecked cons, length,

indexing, sum, and hex text encode/decode helpers.

• json.0x0: json-get-int, json-get-text, json-get-bool, scalar token

validation, and the flat-field scanning helpers they require.

• error.0x0: error-new, field access, text rendering, and Result

conversion.

• db.0x0: db-empty, row construction/update, insert, count, cell lookup,

search, and update helpers.

• path.0x0: path-empty?, absolute/parent checks, safe-relative checks,

joins, contains, starts-with, and ends-with.

• file.0x0: file-read-safe and file-write-safe.

Importing

Example:

(↥ "pkg:core-map")
(↥ "pkg:core-json")

Examples should prefer package imports from the package root. Core modules may

still import sibling core modules by relative path. The compiler loader threads

the transitive import seen set, so shared dependencies such as option.0x0

are loaded once when multiple imported modules depend on them.

Representation

The current representations are intentionally simple and public for v0.1.x:

• Option: (list "some" value) or (list "none").
• Result: (list "ok" value) or (list "err" code message).
• Map entry: (list key value) inside a list of entries.
• Bytes: list of integers where each value must be 0 <= byte <= 255; hex

conversion returns lowercase text and decodes lowercase or uppercase input.

• Error: (list code message).
• DB table: list of map rows; row lookup returns Option.
• Safe paths: non-empty relative paths that do not contain ...

These are source-level conventions, not stable v1.0 ABIs. Future type and module

slices should replace broad Any annotations with parametric contracts once the

language can express them.