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 shows exactly where ordinary library code ends and privileged machinery begins.

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 package mechanism rather than compiler embedding. Implementation machineryZig runtime and host services that cannot be expressed as portable library algorithms.

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.

Is it broadly privileged?If not, keep it a package. Standard embedding is not a shortcut around package design.

Importing source is not importing cost

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

Compiler and differential specsImports, types, visibility, specialization, effects, ARC, and results agree on native and oracle paths.
Real userlandPackages, editor, examples, and bundled applications prove composition at program scale.
Public documentationThe Luce site compiles examples and audits documented public standard signatures against the embedded source.

Optimize without duplicating semantics

A slow Luce algorithm is measured before it becomes a primitive. When a primitive is justified, the public wrapper and language-visible behavior remain singular; tests compare the optimized operation against ordinary behavior. Copying an algorithm into the runtime only because Zig is available would create two implementations to keep in step.

standard-library contract embedded Luce source documentation surface audit