Projects Packages and Pinning

A piece needs more than a source file: it needs the library code and language version that give that source its meaning. A project records those choices so opening the piece on another machine can reproduce them.

The project is the unit that travels

resonon.toml marks the project root. Source lives under src/, collected kits under kits/, and installed packages under dependencies/. Resolving from the project means a shell’s working directory or a machine-wide library cannot silently substitute a different module.

A package is reusable project content with src/lib.non as its entry point. A piece imports the package’s exported definitions; its manifest records where to fetch the package. Content with no upstream to fetch, such as a kit from a personal library, belongs in [local] and may need to be collected into the project before sharing.

The manifest and lock file answer different questions

The manifest declares the dependencies you chose, including a tag when you want to pin one. The lock file records the exact commits installed. An untagged dependency’s upstream can move while the locked commit stays fixed, so another installation can reproduce the chosen code instead of silently taking today’s upstream.

Updating is an explicit decision to fetch again and record the result. Keeping resonon.lock with the source makes that decision travel with the piece. The installed dependency is still checked against the lock when imported; a mismatch is reported so local changes do not masquerade as the locked version.

The runtime version is part of the piece

The resonon pin selects a major and minor language version; patches within it are interchangeable. The launcher chooses an installed runtime for that pin. It does not download one implicitly. The editor’s language server also follows the project version, while a live server runs the version it started with.

A project requiring a newer minor than the running server is refused because its source may need syntax or behavior that server lacks. An older project can run on a newer server with a warning, so the change in runtime is visible. Upgrading the manifest is a decision to try the piece under the newer version, not evidence that it has already been checked there.

An unknown manifest key is reported without discarding the valid settings. A typo should be visible without taking down an otherwise usable project; malformed TOML, which cannot be read, stops the command before it proceeds.

resonon.toml and resonon.lock specify the fields. For the actions, see Install a Package and Share a Project.