Design principles¶

These principles guide the library's scope, public contracts and implementation. Changing one requires an explicit design decision and updated documentation.

Mojo, as native as possible¶

1. Ordinary Mojo only. The library is used through normal imports, functions, closures, structs, traits and parameters. There is no parser, transpiler, source rewriting, mandatory code generation, FFI or Python runtime.
2. Add the smallest missing piece. When a native capability covers part of a contract, add only the missing adapter or specialization, reuse native control flow, ownership and storage, and state the exact gap it fills.
3. Converge. When Mojo adds an equivalent capability, adopt it and delete the library's version. A library component disappearing because the language caught up is a success. A replacement that changes ownership, errors, ordering or empty-input behavior is published as a named breaking change with a migration, never as a silent cast between representations.
4. Accept native limits. The library does not emulate another language's features where Mojo cannot express them. For example, partial binds a positional prefix of a plain function, and keyword binding is a native closure (see functions).
5. No compiler or standard-library changes. Work that requires modifying Mojo itself is outside the project.

One implementation per concept¶

Each shared concept has one implementation in the lowest layer that can own it. Before adding a mechanism, find its owner and every consumer, including those in other packages. Reuse or generalize that implementation. If two mechanisms serve the same purpose, move their consumers to one implementation and remove the duplicate. The overview lists the owners.

Preserve types, ownership and origins¶

Operations keep the native payload types, typed errors, origins and resource constraints of their inputs. Unsafe lifetime erasure, implicit dynamic boxing, runtime registries, erased callback storage and hidden consumption are not used to make an API more convenient. When sharing code would weaken one of these guarantees, the code stays separate and the reason is written next to it.

Observable behavior is specified¶

For every operation the documentation states evaluation order, laziness, how often each callback runs, short-circuiting, failure behavior, and what is borrowed, copied, moved or destroyed. Ownership and errors gives the shared conventions; each reference chapter states the specifics.

Callbacks are not required to be pure. Internal mutation is allowed when the documented observable behavior is preserved. Algebraic laws hold under stated purity and termination assumptions (see laws).

Measured performance¶

The library makes no general zero-overhead claim. Each performance statement names the operation, the compiler, the optimization level and how it was measured (performance). Compile time is a cost like run time and is measured cold.

Scope¶

The library covers function composition and partial application, sequential folds and lazy iteration, typed results, algebraic and inductive data types with exhaustive pattern matching, functional control flow, and algebraic interfaces with monad transformers. Recursion is over finite acyclic data; general well-founded recursion is outside this contract. The scope also includes documented laws and device-compatible specializations of the non-allocating, non-raising core.

Out of scope for now: automatic currying, persistent collections, optics, memoization, asynchronous effects, implicit parallelism, a distributed runtime, a GPU kernel framework, open-world runtime class matching, regular-expression matching, iterator backtracking, dependent pattern matching, proof checking and automatic termination proofs. Conveniences such as partial_right, curry, juxt and predicate combinators wait until the core callable contracts settle.

Some words have deliberately narrow meanings:

• Partial application binds a positional prefix of a native function. It does not reproduce Python's keyword binding, placeholders, object identity or introspection.
• Generic means one algorithm specialized over compatible types and callables, not an untyped container that holds any runtime type.
• GPU-compatible means a specialization is usable inside a device context. It does not imply implicit data transfer, automatic kernel launch or reordering a sequential fold.

Compiler pin¶

The library is pinned to one exact compiler, Mojo 1.1.0, through Pixi. The supported range grows only after the full verification gates pass on a new compiler. Checking a newer compiler for new features or breakage never silently changes the compiler used to qualify a release. The upgrade procedure is in native Mojo boundaries.