Namespaces, projects and distribution

AAL supports multi-file, multi-package projects. Dependency aliases form package namespaces; they are not an implemented arbitrary namespace declaration syntax.

Isolate types with the same name

Two dependencies may both export Account. Consumers refer to them as left.Account and right.Account: distinct nominal types that are not interchangeable even with identical fields. Exported Agents are likewise distinguished by agent("left.Worker") and agent("right.Worker").

Unexported declarations are inaccessible through dependencies. Explicitly update the lock after source changes. The compiler neither accesses the network nor silently refreshes dependencies.

Project structure

workspace/
  left/aal.toml
  left/src/main.aal
  right/aal.toml
  right/src/main.aal
  app/aal.toml
  app/aal.lock
  app/src/main.aal

Example application manifest:

schema = 1
name = "example.app"
version = "1.0.0"
entry = "src/main.aal"
sources = ["src"]
exports = ["Main"]

[dependencies.left]
path = "../left"
version = "1.0.0"

[dependencies.right]
path = "../right"
version = "1.0.0"

aalc lock workspace/app
aalc check workspace/app
aalc build workspace/app -o app.aalc

aal.lock records the complete dependency graph and file SHA-256 hashes. Versions must currently be exact major.minor.patch values, without ranges or prereleases. Sources must stay within the declared package closure; symlinks, absolute paths and escaping imports are forbidden.

Python-like publishing and distribution

Step	Current AAL mechanism	Constraint
Declare projects and dependencies	aal.toml, aal.lock	Exact versions; not full pip resolution semantics
Publish source packages	aal-package build / publish	Immutable versions, explicit publisher, digest checks
Install source dependencies	aal-package resolve	Explicit registry and SHA pin; offline compilation
Build executable packages	aal-provider package	Explicit platform; native profile limits Host effects
Distribute executables	Runtime .eap and existing plugin installation	Package integrity is not installation authorization
Upgrade state	State isolated by execution image	Business-state migration is not implemented

aal-package build library --output library.aals
aal-package publish library.aals --registry https://registry.example --publisher publisher-user-id
aal-package resolve consumer
aalc lock consumer
aalc check consumer

registry.example is a placeholder, not a live service. Publishing tokens come from EASYNET_REGISTRY_TOKEN or an explicitly named token environment variable, not command-line arguments. Use a registry you are authorized to access; no public registry service is provided here.

Hand a project to someone else

For source modifications, deliver the source package and locked dependencies. For running public capabilities, build an executable package and install and bind it through Runtime. A descriptor alone describes the interface but contains no executable program.

Native executables target a specific platform. Model and external tool configuration do not automatically travel with source code. Check these runtime dependencies before distributing.

Next steps

Download the account example for a local multi-package build. To connect an existing Python function, read the function guide. For lock, state or type problems, see troubleshooting.