Package mode is a toolchain composition layer around canonical Topaz modules. It selects roots, dependencies, hashes, and offline inputs; it does not add package syntax to the language or weaken module containment, visibility, cycle, and initialization rules.
Contract and components
topaz.toml declares package identity, language lane, entry and dependencies. topaz.lock records a deterministic root manifest hash and dependency content. Local dependencies are content-hashed when added. Registry dependencies are copied into vendor/<name>/<version> and verified. Omitting an entry from check/run/test/emit/build/doc activates package mode.
Workflow
Use init for a non-overwriting current scaffold, add for registry or relative-path dependencies, lock to freeze resolution, and fetch/vendor with an explicit local registry source. Commit the manifest and lockfile; use --locked in reproducible gates. Generated doc output is derived from the checked public export surface.
An editor that starts topaz lsp should send the package directory as initialize.rootUri. With a valid lockfile, diagnostics then resolve local modules and vendored dependencies through the same package graph as topaz check, while open documents override their saved bytes.
Current Topaz includes topaz init --target web-app|http-service, makes [build].target the effective package-build default, and admits strict target-scoped [web] and [service] tables. Web lifecycle v2 uses explicit capabilities; the service table fixes finite listener, request, queue, deadline, log, and shutdown budgets. Unknown keys fail closed, and topaz dev keeps both application targets on loopback.
For an application artifact, declare filesystem roots under [capabilities.fs] and launch the generated product from the directory that contains its runtime data and output trees. Native executables and package-mode Python builds interpret those roots from the launch working directory, so the source package is not needed at runtime. The Python bundle requires Python 3.11 or newer and runs as a direct CLI application, including stdout, stderr, arguments, stdin, and explicit-main exit codes.
Current support
Topaz supports package creation, dependency addition, locking, vendoring, package compilation, module isolation, and offline builds. The public topaz-lang package installs the appropriate Topaz CLI binary for the current platform.
Boundaries and limitations
A package dependency does not grant host capabilities or import foreign-language syntax. Topaz source dependencies use topaz.toml, topaz.lock, and vendored inputs; the npm package is a CLI installer, not the Topaz source-package format. Offline builds require every locked dependency to be available locally.
topaz emit --target python remains an inspection and trace-integration surface. Use package-mode topaz build --target python when you need the physical-filesystem application host.
Command reference
topaz init --root my-app
topaz add utility@1.2.0 --root my-app
topaz lock --root my-app
topaz vendor --root my-app --from ./registry
topaz check --root my-app --locked
topaz build --root my-app --locked --out-dir ./dist/native
topaz build --target python --root my-app --locked --out-dir ./dist/python