Packages, locks and targets

A package root contains topaz.toml. Package-mode commands load that file from the selected root, which defaults to the current directory. The manifest is read before the package entry source.

Package loading source

[package] declares the package name, version, language mode, and entry path. The entry is relative to the package root. License metadata is optional. Unknown top-level sections and unknown fields in supported sections are rejected.

Manifest sections source · Package fields source

topaz init --root app creates a native package with a complete entry program. It refuses to overwrite an existing manifest or entry. Use that scaffold as the starting point for the configuration below.

Scaffold source

Each dependency declaration uses a table. A version dependency has version and may have hash. A path dependency has path and requires hash. The table chooses exactly one of version and path. A bare version string is rejected when the package manifest is loaded.

Dependency declaration source

Registry dependency compilation requires --locked and matching content under vendor/<name>/<version>. The dependency package name and version must agree with the declaration. A local dependency's manifest name must also agree with its declared name.

Package dependency loading source

[exports].module selects the module a dependency exposes as its root. Without that section, its package entry supplies the root. A dependency name that collides with a root module path is rejected. These configuration relationships do not redefine source import syntax.

topaz.lock records the root package identity and a manifest_hash derived from the manifest text. It also binds declared dependency identities and content hashes. Changing a locked input requires a corresponding lock update.

Lock verification source · Manifest digest source

--locked verifies the existing lock before the applicable package operation continues. Missing, stale, duplicate, or undeclared lock entries are rejected. topaz lock writes the lock for the current manifest. It does not waive a mismatched local dependency hash.

Lock verification also checks declared extern artifacts and replay inputs, plus embedded Lispex source, limits, quotas, and prepared artifacts when present. A matching root manifest hash does not replace those checks.

[build].target selects native, web, or web-worker. An omitted build target selects native. Ordinary package loading requires deterministic builds. The separate usage-profile validation path does not enable an unrestricted nondeterministic build.

Build configuration source

For package builds, an explicit command target takes precedence over the manifest target. Without a command target, build uses the manifest. Entry-file builds use their command target or the native default. Web targets cannot be combined with automatic execution through --run.

Package build selection source

The target describes the resulting artifact. It does not select SELF or the reference compiler. emit has a separate Rust-source target and does not produce a final native or web binary.

[lispex] selects a package-owned evaluator profile and declares at least one [[lispex.rule]]. Each rule has a unique name and distinct project-relative source and limits paths. A package containing this section requires locked compilation.

Lispex configuration source · Locked package requirement

An application identifier and its application_quotas file appear together. The application and evaluator profile must be a supported pair. In the current language mode, application configuration also requires the exact standard-library version for that mode.

Application binding source

The Lispex admission contract defines package admission and component identities. The factory contract defines generated calls from the verified lock. Installed profile availability requires distribution evidence.

Lispex lock verification follows the package admission and generated factory contracts. Changing a locked input requires a matching lock update.

[capabilities.fs] declares project-relative read and write roots. [extern] declares externally implemented modules and their associated inputs. An extern module cannot occupy a root path already used by a local module or dependency.

Capability and export declarations · Extern module collision source

The complete external ABI and host sandbox behavior belong to their own reference contracts. This page records their effect on package identity and lock verification.

Compiler selection

init

lock

build

check