lang::mote

lang/src/mote.mo

Mote manifests, read by the self-hosted compiler.

A mote is Monad's unit of distribution (plans/packaging/ package-system.md): a directory with a mote.toml and a src/ tree. This module answers the two questions module resolution asks -- which mote does this file belong to, and which motes did that mote declare -- so that use can be checked against the manifest rather than against whatever happens to exist on disk.

Built on lang.toml's parser, following lang/src/toml.mo's own pattern: own types, own glue over Toml.parse, no shared serialize/deserialize class machinery.

structMoteManifest#
pub struct MoteManifest {
    name : String,
    /// `[mote] version`, or `""` when the manifest declares none. A git or
    /// registry dependency's `mote.lock` entry needs it (`package-system`
    /// §2b), and the lock is written from the DEPENDENCY's own manifest,
    /// so this has to be readable rather than assumed.
    version : String,
    /// The mote's directory as a `Path`. The working directory is spelled
    /// `.` -- an empty `Path` is never constructed -- and every join from it
    /// goes through `Path.child_under`, which keeps the spellings this walk
    /// has always produced (`src/lib.mo`, never `./src/lib.mo`).
    dir : Path,
    deps : List String,
    /// Where each declared dependency COMES FROM: the parsed source of
    /// every `[dependencies]`/`[dev-dependencies]` entry that names one
    /// (`path`, `git`, or a registry version). An entry naming none -- an
    /// empty table, or `workspace = true` before inheritance resolves it
    /// -- is declared but has no entry here; an entry that is malformed
    /// has its error in `dep_errors` instead.
    deps_full : List (Pair String Dependency),
    /// `(name, message)` for each dependency entry that cannot be read as
    /// a source: `path` and `git` together, more than one of `tag`/
    /// `branch`/`rev`, a git-only key without `git`, or a non-string value.
    /// The parse is pure and stays total, so the error is carried rather
    /// than failing the whole manifest; `validate_module_deps`
    /// (lang/module.mo) reports it when a `use` reaches that dependency.
    dep_errors : List (Pair String String),
    /// Where each declared dependency LIVES: `(name, dir)` pairs, computed
    /// from `deps_full`. A `path` dependency's `dir` is its `path` joined
    /// onto this mote's own `dir`, so it is usable as a path exactly as
    /// stored. Any other source is ABSENT from this list -- a git
    /// dependency until its checkout is resolved, a registry one until a
    /// registry exists -- which resolution reads as "declared, but not
    /// located": the name still satisfies `declares` (so a `use` on it is
    /// legal), it just has no directory to resolve into. There is no
    /// sentinel directory, because an empty `Path` is never constructed.
    ///
    /// Without this, a dependency resolved purely by the NAME convention
    /// (`mote_relative_file`: the mote's directory is its name, at the
    /// working directory), which is only true from a checkout root. This
    /// is what `resolve_module_file` consults on its miss path, and it is
    /// what makes resolution key off the mote root rather than the CWD.
    dep_dirs : List (Pair String Path),
    /// `[features]` entries, in manifest order.
    features : List (Pair String (List String)),
    /// Optional/feature policy for each `[dependencies]`, `[dev-dependencies]`
    /// and `[script-dependencies]` entry, keyed by dependency name.
    dep_policies : List (Pair String DepPolicy),
    /// C libraries this mote links against, from `[link] libs = [...]`.
    /// A LINK-time property of the package, not of any one declaration:
    /// which C functions a module calls is `#[extern "c"]`'s business,
    /// but what the linker is handed is the mote's, the same way Cargo
    /// keeps `-l` flags out of `extern "C"` blocks.
    link_libs : List String,
    /// pkg-config packages that say WHERE `link_libs` live, from
    /// `[link] pkg-config = [...]`. `llvm.link`'s `link_ir` asks
    /// `pkg-config --libs-only-L` for these and passes the `-L` flags
    /// itself, so a mote's link does not depend on the caller's
    /// environment happening to carry the right search path. The names in
    /// `link_libs` still supply the `-l` flags.
    link_pkgs : List String,
    /// Where this mote's library root would be: `[lib] path`, else the
    /// conventional `src/lib.mo`. `none` only for an inline mote, which has
    /// no `src/` tree at all.
    ///
    /// A PATH, not a promise that the file is there: `manifest_of_table` is
    /// pure and cannot probe the filesystem. Whether it exists is
    /// `gate_mote_targets`' question (lang/module.mo).
    lib_path : Option Path,
    /// This mote's runnable scripts, from `[[script]]`. A script is a
    /// single source file built with this mote's dependency closure and run
    /// by name (`monad script <name>` / `monad s <name>`). A virtual
    /// workspace root may declare them too; see `Mote.scripts_at_path`.
    scripts : List ScriptTarget,
    /// This mote's binary targets, from `[[bin]]` (or the legacy singular
    /// `[bin]` spelling, which means the same thing here). Empty only for an
    /// inline mote, whose own file IS its binary.
    ///
    /// A manifest with no bin table at all still gets exactly ONE target --
    /// the conventional `src/main.mo`, named after the mote -- so
    /// `monad build <mote>` works without a manifest edit. Whether that file
    /// exists is what `build_target` checks before building it, which is what
    /// keeps a default from becoming an invention.
    bins : List BinTarget,
    /// `[mote] targets = [...]`: the build PROFILES this mote's side effects
    /// are implemented for (`"web"` for the browser boundary). Informational
    /// only -- availability is enforced per extern/native at codegen
    /// (`validate_native_target_availability`), not per mote, because a
    /// mote's pure parts (an ABI spec, a generator) must stay usable on
    /// every target. Do not confuse it with `Mote.target_roots`, which is
    /// about SOURCE files.
    targets : List String,
    /// Names whose dependency entry said `workspace = true`. Recorded even
    /// after resolution so a driver can explain where an inherited edge came
    /// from; empty for an ordinary manifest.
    inherited : List String,
    /// The workspace root whose `[workspace.dependencies]` resolved
    /// `inherited`, when one was used. `with_locked_dirs` reads that root's
    /// `mote.lock` rather than this mote's own.
    workspace_root : Option Path,
}

What resolution needs from a mote.toml: who this mote is, where it lives, and what it declared. [dependencies] and [dev-dependencies] are merged here -- the distinction is about which TARGETS may use an edge, and this corpus has no lib/test target split to enforce it against yet (init/src/tests.mo is an ordinary module). Merging keeps init pure in its manifest, which is the part that documents intent.

structBinTarget#
pub struct BinTarget {
    /// `[[bin]] path`, or `src/main.mo` when the entry names none, joined
    /// onto the mote's own `dir` the same way `dep_dirs` entries are.
    path : Path,
    /// `[[bin]] name`, or the mote's own name when the entry names none. Not
    /// optional: it is what `monad build <mote>` names the output after, so
    /// the fallback to a source file's own stem is the FILE compile's rule
    /// and no longer this one's.
    name : String,
    /// `[[bin]] features = [...]`: this target's feature selection.
    features : List String,
}

One binary target: what monad build selects between.

Both fields are already resolved -- a declared value or the conventional default, joined onto the mote's own dir -- so a consumer needs no rule of its own. plans/packaging/package-system.md §2a is the spec.

defBinTarget.target_path#
pub def BinTarget.target_path (b : BinTarget) : Path

BinTarget.path, and its name sibling below. Accessors rather than bare field reads because a #[test] def ... : Bool body reading a field directly is the shape test-def-struct-field-access-codegen warns about (the def can be emitted with the FIELD's LLVM type as its return type). A one-line accessor whose return type IS the field's type costs nothing and sidesteps it.

defBinTarget.target_name#
pub def BinTarget.target_name (b : BinTarget) : String
defBinTarget.target_features#
pub def BinTarget.target_features (b : BinTarget) : List String
structScriptTarget#
pub struct ScriptTarget {
    name : String,
    path : Path,
    mote : Option String,
    /// `[[script]] features = [...]`: this script's extra features.
    features : List String
}

One [[script]] entry: a named single-file program built against the manifest's dependency closure. path is joined onto the manifest's directory; mote optionally names the member whose manifest and closure the script uses (recommended at a virtual workspace root).

defScriptTarget.script_name#
pub def ScriptTarget.script_name (t : ScriptTarget) : String
defScriptTarget.script_path#
pub def ScriptTarget.script_path (t : ScriptTarget) : Path
defScriptTarget.script_mote#
pub def ScriptTarget.script_mote (t : ScriptTarget) : Option String
defScriptTarget.script_features#
pub def ScriptTarget.script_features (t : ScriptTarget) : List String
typeDependency#
pub type Dependency {
    path (dir : Path),
    git (url : String) (tag : Option String) (branch : Option String) (rev : Option String) (subdir : Option String),
    registry (req : String),
}

Where a declared dependency comes from: the canonical model of plans/packaging/package-system.md §2a, which mote.lock shares.

path's dir is already joined onto the declaring mote's dir, the way dep_dirs entries always were. git's tag, branch and rev are mutually exclusive, and none of them means the remote's HEAD; subdir names the mote's directory inside a checkout that holds several. registry carries its version requirement verbatim -- nothing resolves one yet. workspace = true is never a constructor here: inheritance is resolved before a Dependency exists.

defDependency.to_source#
pub def Dependency.to_source (d : Dependency) : String

A one-line spelling of the source, in the lockfile's source style: path+<dir>, git+<url>?tag=v1&subdir=motes/x, registry+<req>. For display and diagnostics only; nothing parses it back.

defMoteManifest.dependency_of#
pub def MoteManifest.dependency_of (m : MoteManifest) (name : String) : Option Dependency

The dependency named name's parsed source, if its entry named one.

defMoteManifest.dep_errors_for#
pub def MoteManifest.dep_errors_for (m : MoteManifest) (name : String) : List String

The errors recorded against the dependency name; empty when its entry is well-formed or absent.

defMoteManifest.dep_dir_of#
pub def MoteManifest.dep_dir_of (m : MoteManifest) (name : String) : Option Path

The directory a declared dependency lives in, or none when the mote does not declare name or its entry carries no path. A dependency with no path is DECLARED but not LOCATED, which is not an error here: the name-convention cascade above is still allowed to find it.

A mote's OWN name answers with its own dir, the same "a mote may always refer to itself" rule MoteManifest.declares already states -- and here it is load-bearing rather than a convenience: prelude belongs to init (mote_dep_files routes it there, since prelude is the one module whose NAME is not its FILE name), and init is exactly the mote that cannot declare itself as a dependency. Without this arm the prelude of the mote init is unreachable from inside init/ itself, which is why monad check src/list.mo from init/ reported unknown variable '==' in List.get.

The self arm answers even for the mote whose mote.toml sits in the working directory: that is precisely the case it exists for, and the manifest's dir spells that directory ..

defMote.discover_config_target_dir#
pub def Mote.discover_config_target_dir (dir : Path) : IO (Option Path)

Walk up from dir for the monad tool's own config, .monad/config.toml, and answer the [build] target-dir it names, joined onto the config's directory so the value is usable as stored.

A TOOL setting, not a mote's. Where output goes is a property of the tool that writes it, so it is read from the tool's config rather than from the mote.toml of whichever mote is being built -- which also means this walk has no mote boundary to stop at. That is what makes it the right lookup for a script-mode file: monad build examples/hello.mo must land where the rest of the tree does, and examples/ sits under no [mote] for Mote.discover to find.

A config that names no target dir does not stop the walk, so a nested .monad/config.toml inherits from the one above it -- the same rule a manifest used to follow for its workspace.

defMote.target_roots#
pub def Mote.target_roots (m : MoteManifest) (fallback : Path) : List Path

The directories a mote's own declared targets live in: the [lib] root's, then each [[bin]]'s, deduplicated in that order.

This is what a bare monad check/monad test covers, and it covers it because the alternative was the whole subtree. Walking the mote's DIRECTORY swept every *.mo under it, and .mo is also GNU gettext's extension -- so in any project that has run devenv shell (which materializes .devenv/bash-bash/share/locale/*/LC_MESSAGES/bash.mo), monad test reported 85 parse failures beside the 2 real files (plans/implementations/2026-10-04-monad-test-no-path-globs-unrelated- dot-mo-files.md). A declared target is the mote saying where its own sources are; nothing else under the directory is its business.

fallback (the mote's own directory) is the answer for an inline mote, which declares no targets at all. An explicit path argument never reaches here -- monad test . still means that directory, literally.

defMote.native_test_roots#
pub def Mote.native_test_roots (m : MoteManifest) (fallback : Path) : List Path

The subset of target_roots a NATIVE driver may compile. The [lib] root is always included (a web mote's pure test files still run natively); a [[bin]] root is included only when the mote's [mote] targets admit the native profile (absent, or containing "native"). A targets = ["web"] bin is not native-testable -- that is the anidoku gap where monad test compiled a web-only bin for the native driver.

defMote.web_only_bin_file#
pub def Mote.web_only_bin_file (m : MoteManifest) (file : String) : Bool

Whether file is a declared [[bin]] target of a mote whose [mote] targets exclude the native profile. The native test driver must not compile such a file (a web-only bin reaches web_* externs); the root-level filter in native_test_roots cannot exclude it when the bin and the tests share src/, so the walk filters the FILE too.

defMote.dir_above#
pub def Mote.dir_above (dir : Path) : Option Path

The directory one step up in the policy/config walks, which keep going ABOVE the working directory: . ascends to .. and a ..-relative directory keeps appending (raw_parent_dir ".." is ., which would otherwise re-probe the cwd forever). none at the filesystem root.

defMote.manifest_at#
pub def Mote.manifest_at (dir : Path) : IO (Option MoteManifest)

The manifest AT dir, with no walk -- unlike Mote.discover, whose walk is right for a file's own mote and wrong for a DECLARED dependency: [dependencies.x] path names x's directory, so a manifest further up is somebody else's. Resolution needs the dependency's own [lib] path.

defMote.workspace_members#
pub def Mote.workspace_members (dir : Path) : IO (List Path)

Every mote directory belonging to the workspace rooted at dir.

Mirrors the Rust reference's Workspace::resolve_members (rust/core/src/term/mote.rs): each [workspace] members entry is a directory relative to the root, except a trailing /*, which expands ONE level to those children that are themselves motes (a directory containing a mote.toml). IO.list_dir already returns entries sorted, so the expansion needs no sort of its own.

List.empty when dir holds no manifest, or one with no [workspace] members -- a single-mote checkout is not an error, just a workspace of one, and the caller decides what to do about that.

A member that does not exist is DROPPED rather than reported: the Rust reference errors, but this is the test runner's path enumeration, where a stale entry should not stop the other members from being tested. The caller sees a shorter list, and the manifest is checked by the Rust host in CI anyway.

defMote.affine_mode_of_path#
pub def Mote.affine_mode_of_path (file : Path) : IO AffineMode

How a mote enforces the affine-by-default usage rule, from [affine] mode in its nearest mote.toml.

The default -- no manifest, no key, a parse error, or any value other than "warn" -- is affine_error. A typo must never silently weaken enforcement, so only one spelling opts out.

This deliberately does not go through Mote.discover. That walk returns none at a virtual workspace root (a mote.toml with no [mote]; see Mote.discover_go), which is exactly the manifest a file outside every member resolves to -- this repository's examples/, for one. The policy walk stops at the nearest mote.toml whether or not it declares a [mote], so a workspace root can carry the fallback and a member can override it.

defMote.scripts_at_path#
pub def Mote.scripts_at_path (file : Path) : IO (Option (Pair String (List ScriptTarget)))

The nearest manifest and its [[script]] entries, whether or not that manifest declares [mote] (a virtual workspace root may own scripts). Mote.discover cannot answer this: it returns none at a virtual root.

defMote.affine_mode_of_text#
pub def Mote.affine_mode_of_text (text : String) : AffineMode

[affine] mode in a manifest's text. See Mote.affine_mode_of_path for why every non-"warn" answer is the strict default.

defMote.manifest_of_table_in_workspace#
pub def Mote.manifest_of_table_in_workspace
    (dir : Path) (root_dir : Path) (root_table : BTreeMap String Toml.Value)
(table : BTreeMap String Toml.Value) : Option MoteManifest

manifest_of_table with a workspace root in hand: workspace = true entries are replaced by the root's [workspace.dependencies] entry. Kept as a separate entry point so callers with no workspace context keep the pure signature.

defMote.workspace_member_names#
pub def Mote.workspace_member_names (root_dir : Path) : IO (List String)
defMote.workspace_root_of#
pub def Mote.workspace_root_of (dir : Path) (name : String) : IO MoteRootLookup

Walk up from dir for the first manifest with a [workspace] table and decide whether name (the manifest being loaded) belongs to it. root_found gives the root and its parsed table; root_rejected names a root that exists but does not list this package; root_none means there is no root above.

defMote.load_manifest#
pub def Mote.load_manifest (dir : Path) (text : String) : IO (Option MoteManifest)

Read a manifest, resolving workspace = true entries against the workspace root above it. The pure parse_manifest stays available for callers with no filesystem; this is the loader's entry point.

defMote.workspace_member_dirs#
pub def Mote.workspace_member_dirs (dir : Path) : IO (Option (List Path))

The member directories of the workspace rooted at dir, or none when dir has no [workspace] table. Used by monad fetch, which is handed a virtual root and must resolve every member's dependencies.

defMote.manifest_problem#
pub def Mote.manifest_problem (dir : Path) : IO (Option String)

The first unresolved-inheritance problem for the manifest at dir, as a finished diagnostic. none means either there is no such problem or the manifest uses no workspace = true.

defMote.git_checkout_dir#
pub def Mote.git_checkout_dir (home : String) (url : String) (commit : String) : String

<home>/cache/git/checkouts/<sha256 url>/<commit> -- the one definition of where a checkout lands, shared with build::git's writer so a fetch and a resolution cannot disagree.

defMote.with_locked_dirs_at#
pub def Mote.with_locked_dirs_at (home : String) (m : MoteManifest) : IO MoteManifest

with_locked_dirs with the cache root given. The test suite needs it: a fixture fetches into its own directory, and nothing in a test may depend on the process's $MONAD_HOME.

defMote.any_git_dep#
pub def Mote.any_git_dep (deps : List (Pair String Dependency)) : Bool

Whether any declared dependency is a git source -- the gate that keeps the lock read off every ordinary mote's resolution path.

defMote.script_targets_of_text#
pub def Mote.script_targets_of_text (dir : Path) (text : String) : List ScriptTarget

Parse a manifest's text for [[script]] entries. Used at a virtual workspace root, where Mote.discover returns none.

defMote.script_dep_names#
pub def Mote.script_dep_names (root : BTreeMap String Toml.Value) : List String

The dependency names declared by [script-dependencies.<script>]. They are merged into the owning manifest's closure for resolution, so a script can use them like any declared dependency.

defMote.script_dep_entries#
pub def Mote.script_dep_entries (dir : Path) (root : BTreeMap String Toml.Value) :
List (Pair String ManifestDepEntry)
defread_file_or_none#
pub def read_file_or_none (path : Path) : IO (Option String)

A file's contents, or none when it is not there at all (not_found) -- "no ~/.monad/active", "no mote.toml in this directory" are the ordinary states every caller here probes for.

Any OTHER read failure is reported on stderr before it reads as absent: the callers' own types (Option MoteManifest, a member list) have no error channel, and an unreadable manifest must not pass silently for a missing one.

defMote.toolchain_root#
pub def Mote.toolchain_root : IO (Option String)

Where an installed toolchain's mote sources live, if there is one.

$MONAD_ROOT first, honoured VERBATIM and deliberately neither existence- nor shape-checked: an explicit variable is an instruction, and a user who points it somewhere useless should get an ordinary "unknown module" listing the candidate paths rather than a silent fallback to a ~/.monad they may not even have. It is also the one root a test can install with nothing but a shell variable.

Otherwise monadup's install: $MONAD_HOME (default $HOME/.monad), the tag its active file names, and <home>/downloads/<tag> -- which IS existence-checked, because that one is a guess rather than an instruction.

none, never an error: a development checkout has no ~/.monad, and resolution reads "no root" as "no candidates from this tier".