Creating a package

A package project

A package will be an ordinary AEL project, with main.ael, pack.ael and metadata.ael at its root. What will make it a package is its name in metadata.ael:

metadata {
    schema = 1;
    name = "acme/billing";
    description = "Billing checks shared by Acme's agents";
}

billing/
  main.ael                     # required; never runs as part of the package
  pack.ael                     # the packages this package uses
  metadata.ael                 # name = "acme/billing"
  src/
    check_invoice.reuse.ael    # exported as check_invoice
    audit.hook.ael             # exported as audit
    invoice.node.ael           # exported as invoice
    rules.config.ael           # exported as rules

• The name will follow the package name rules: lower case and slash-separated. Start it with your own organization's name, such as acme/.
• main.ael will stay required and may do nothing. It will be compiled, but it will never run as part of the package and never start when someone installs it.
• How a package will state its version will be confirmed when the format of metadata.ael is final.

Building the file

ael package
ael package ../billing -o dist/acme-billing-0.3.1.zip

ael package will build the project you are in, or the project folder you name; -o will choose where the file is written. Building a package describes the command in full. Before it writes anything, it will check the whole project: the package name, the three root files, the lock files of every scope, source limits, names, visibility, hooks, targets and packages. Every refer … select will have to be used, as in any other build. A missing package name will fail before any file is written.

The same project, built with the same toolchain, will give the same package file, so its fingerprint will change only when its content does.

What goes into the file

• Every component, compiled. Each agent, node, edge, hook, configuration and shared function in the project, including those that nothing else in the project calls. An extension file's helpers will be folded into their component.
• Its public interface. The exports, with their types, effects and capabilities, so projects can check their calls against it without your source.
• References to its own packages. Their exact versions and fingerprints, never copies of them.

Never in the file: your source files, comments, scripts, native code, executables, model weights or any other files. Descriptions and licence notices will travel as data.

Building a package will publish nothing. It will never upload anything, and you will not be able to publish to the official registry, which will never host or list private packages.

Exports

Every public component will be an export: agents, nodes, edges, hooks, configuration, global and reusable functions, and file roles such as routes. A helper fn will never be exported, including the helpers in extension files.

A project will use your exports by name, in its header, and will have to use each one it selects:

refer acme/billing select check_invoice, audit;

A global function in a package will be visible only to a file that selects it: installing a package will never add names to anyone's folders.

You will be able to write a hook either as get.hook.ael, declaring hook get, or as get/main.hook.ael, declaring hook main. Both will export the name get. A package that has both will be refused as ambiguous.

Every package will be written in AEL

Every AEL package, from OpenEng or from you, will be written in AEL and ship as compiled, verified AEL, with no bundled native code and no install scripts. That rule will cover everything a package does:

• no native libraries, embedded interpreters or code in another language, inside the file or shipped beside it;
• no install, build or post-install scripts, and no compiler plug-ins;
• no helper programs that do the package's work outside it.

When a package talks to an outside system, such as a database, a model server, a robot or a quantum computer, it will use that system's own interface, and you will run that system. A package will also be able to start programs you choose, such as your own Python or Java programs, with runtimes you provide; see the Package catalog. The package's own logic will stay in AEL.

For you, this will mean one language to read, whoever wrote a package. The same checks that apply to your code will apply to every package: types, effects, capabilities and limits. Every package will build for your targets the way your own code does, the reference map will see into it, and nothing in it will run when you install it.

Limits

• Every source file of the package will stay within the source limits: at most 5,000 bytes and at most 5,000 lines.
• A package name will be at most 128 characters.
• The planned limits for a package file are 64 MiB in total, at most 4,096 entries, and no single file inside it larger than 16 MiB. A file over these limits will be refused when it is installed.