Luce / engineering
Learn Luce LuciaOS

Where the library is implemented

Open std.json and you are reading Luce. Follow a file read far enough and you reach Zig plus an explicit host callback. This section maps that boundary file by file.

The rule of thumb

Write policy and portable algorithms in Luce. Use Zig for compilation, memory representation, native resources, and host adaptation. Use LLVM and the platform linker only after Luce’s meaning is fixed.

Four library layers

Language primitivesIndexing, append, length, arithmetic, ARC, and other operations whose representation or trap behavior belongs to the language. Embedded standard modulesOrdinary .luc source imported through std., including pure algorithms and hosted wrappers. Maintained packagestermui and future userland libraries resolved through the ordinary package mechanism. Implementation machineryZig runtime and host services for memory representation, native resources, and platform integration.

The test for where code belongs

Can ordinary Luce express it?Keep the algorithm in a standard module or package so it exercises the language it serves.
Does it need object representation?A minimal runtime primitive may own heap, buffer, UTF-8, or checked-machine behavior.
Does it touch the outside world?Expose a public Luce wrapper over a private, optional host service.
Who needs the API?General bundled APIs belong under std.; independently versioned libraries belong in packages.

Reachability determines shipped code

Standard modules join the ordinary module graph, are type-checked like project code, and produce MIR declarations. Reachability pruning removes functions, constants, builtin operations, and host effects the selected entry never reaches. A large pure module can therefore expose a broad API without forcing every function into every artifact.

Three levels of evidence

  1. Compiler and differential specsImports, types, visibility, specialization, effects, ARC, and results agree on native and oracle paths.
  2. Application-scale testsPackages, the editor, examples, and bundled applications exercise composition across larger programs.
  3. Public documentationThe Luce site compiles examples and audits documented public standard signatures against the embedded source.

When an operation becomes a runtime primitive

Measurements identify algorithms whose cost comes from representation or repeated host crossings. Those operations may receive a runtime primitive while keeping the public Luce wrapper and its behavior tests. The wrapper remains the API, and the primitive handles the narrow work that benefits from runtime access.

standard-library contract embedded Luce source documentation surface audit