Projects

An Atoll project is a source tree rooted by atoll.toml. The required module field gives that tree its canonical import prefix.

module = "workreef.dev/seaport"
name = "Seaport"
version = "0.1.0"

TOML is the supported project format. Historical YAML examples are not part of the current toolchain.

The loader searches upward from the requested path for atoll.toml. module is required. If present, version must be a full semantic version such as 0.1.0; dependency strings are parsed as semantic-version requirements.

Source discovery

The loader recursively collects .at files under the project root. It skips dot-prefixed directories plus target, node_modules, and build. It assigns each file a module from its relative parent directory and sorts files for deterministic project input.

Extra local source roots may be added with:

[libs]
paths = ["lib", "../shared"]

These paths contribute source under the current project’s module root.

Each library path is resolved relative to the project root. Its own relative directories are appended to the same configured module root. Because those files join the same project namespace, duplicate declarations can conflict with files under the main root.

Dependencies

Dependencies are keyed by their module path.

[dependencies]
"workreef.dev/common" = { path = "../common" }
"workreef.dev/http" = {
  git = "https://example.com/http.git",
  rev = "7a6c7f0"
}
"workreef.dev/forms" = "^1.2"

The implementations differ:

A dependency with its own atoll.toml uses its declared module root. A bare local directory uses the dependency key as its root.

Pin git dependencies to an immutable commit for reproducible builds. The CLI uses a content-addressed cache and the system git executable.

Path entries are relative to the owning project’s root unless absolute. Missing directories are load errors. A git dependency must provide both git and rev; no implicit branch or default revision is chosen.

Tools that cannot fetch, such as some editor or test contexts, reject unresolved git dependencies and ask for the CLI project pipeline. Once fetched, a git checkout is walked exactly like a path dependency.

Locking

atoll lock records local and git dependency sources and source-tree hashes in atoll.lock. atoll lock --check verifies the recorded state for CI. Registry resolution is not available yet, so a lockfile is not a general version-solver output.

The lock hash covers the dependency’s .at source tree. atoll build and atoll run can fetch a pinned git dependency without rewriting the lockfile; use the explicit lock command when updating recorded state.

Host access

[host] controls which @host namespaces a project can call:

[host]
allow = [
  "atoll_runtime::files",
  "atoll_runtime::http"
]

The section has three distinct states:

Use an explicit allow-list for deployable applications. Omitting the section is convenient for compatibility but does not express least privilege.

Datasources

Each [datasources.NAME] entry requires schema, engine, and url:

[datasources.PRIMARY]
schema = "seaport"
engine = "PostgreSQL"
url = "${DATABASE_URL}"
readOnly = false
pool = { min = 2, max = 16 }

Recognized engines are PostgreSQL, MySQL, SQLite, Turso, DataFusion, and DuckDB. Names are case-sensitive. The loader validates pool ranges and substitutes ${VAR} references in datasource URLs while parsing the manifest. Missing variables and an empty substituted URL are configuration errors.

Datasource names label configuration entries; query routing is based on the declared logical schema. readOnly = true rejects compiled writes targeting that route.

Other configuration

The manifest also parses:

• [identity], [embed], and [messages] application metadata;
• [dev] development ports and devices;
• package metadata for JVM targets.

These sections configure compilers and runtimes; they do not introduce names into Atoll source.

[messages] requires a non-empty locale list and requires its default locale to appear in that list. Development ports must fit the platform port range. Application metadata being parsed does not imply that every historical framework declaration has been implemented.

Directory checks

atoll check path/to/tree can check a source directory without a manifest. This is useful for fixtures and experiments, but it has no dependencies, datasource routing, or host allow-list. Create atoll.toml when module identity or reproducible project behavior matters.

For a loose directory, the directory name becomes the synthetic root module and the same discovery exclusions apply. A lone .at file can also be compiled as a one-shot target when no containing project exists.

Reproducibility

For CI and releases:

1. choose a stable module path;
2. pin every git dependency to an immutable commit;
3. run atoll lock after intentional dependency changes;
4. run atoll lock --check in verification jobs;
5. declare host namespaces and datasource environment variables explicitly.

Version-string dependencies are not reproducible source inputs until registry fetch and solving exist; prefer path dependencies during local development and pinned git dependencies for shared builds.