The conventions below bind every published package. They are the ones a consumer can rely on; the rest of the repository's rules are about how the code is written and reviewed, and are not restated here.
Zero runtime dependencies
A package ships no npm runtime dependency. Its only dependencies are other
@awacloud/* packages, declared as such. Anything a package needs is
implemented from the specification, or vendored with its licence header
and a provenance record (upstream, version, hash).
ES modules only
Every package is "type": "module": plain JavaScript with JSDoc types, no
compilation step, no CommonJS, no require. The code runs as written, in
Bun and in the browser. A package exposes its entry point and, when a
consumer needs direct files, explicit sub-paths in its exports map;
nothing outside that map is a public surface.
No side effect at import
Importing a module executes nothing: a module file exports factories and
values, and registration is an explicit call (runtime.registerAll(...)).
The one documented exception is the framework's lockdown tier, whose
purpose is a side effect at load and which says so in its manifest.
Browser and Web Worker first
Front packages target the browser and Web Workers, with no Node-only API in their sources. Command-line tools are the exception by nature: they are TypeScript run natively by Bun.
The module pattern
A framework module is a pure factory registered in the runtime and resolved on demand: no state at module scope, no work at import time, its dependencies declared as names. Factories are serialisable, so a module can run in a Web Worker; that is why a factory never captures a variable from the file that defines it — everything arrives through its declared dependencies. The runtime resolves each module once and hands the same instance to every consumer.
Maturity levels
Every package declares a maturity level, from L0 to L4, and a level never goes down:
| Level | What it promises |
|---|---|
| L0 stub | A minimal manifest and an entry point. Nothing else. |
| L1 alpha | A README (title, install, quick start, tests), at least one test, a flat source layout. |
| L2 beta | A documentation index, an integration test tree, an explicit files allowlist, a changelog. |
| L3 stable | A licence file, the extended manifest fields, a full API documentation mirror, verified test coverage. |
| L4 reference | A frozen public API (breaking changes need a deprecation cycle), conformance test vectors where a standard applies, proven in production. |
The level is on each package's Overview page, as a badge.
Licences
The packages ship under two licences: the foundation under Apache-2.0, the product families under AGPL-3.0-only with a commercial licence available. The licence of each package is on its Overview page and in its LICENSE file; the terms and how they apply are explained on the licensing page.