docs / stdlib / session

Packages

cajeta.session.Packages — install a library into a live session so later cells can import it. Static methods; there is nothing to construct.

Acquisition and binding stay separate, exactly as they are in a compiled project. install puts an archive on the session’s classpath; import names packages from archives already acquired. install never imports anything itself.

// cell 1
import cajeta.session.Packages;
Packages.install("dev.cajeta.ml", "0.10.*");

// cell 2 — the import resolves now, not before
import dev.cajeta.ml.Frame;

A cell cannot import what it installs: the cell is compiled before its code runs, so the import is resolved before the install happens. The unresolved-import diagnostic says so when a cell calls install.

This is an ordinary stdlib API rather than a %-magic, so it behaves identically in every host and is testable like any other call. In a host with no live session — cajeta run, a compiled binary — it throws PackageInstallException rather than silently doing nothing.

Resolution and verification

The constraint resolves against the governing project’s settings.repositories, or the default central repository when no project governs the session. The highest satisfying version from the first repository carrying one wins.

A fetched archive is verified before it is spliced, by the same check cajeta build runs. By default the repository must serve release metadata signed through its root or delegation, and the bytes must hash to the value it names; a mismatch discards the bytes and fails the install, so there is never a half-installed state. A repository that serves no signed metadata (a local or vendored one) is refused unless the governing manifest relaxes that repository with "verification": "checksum" on its settings.repositories entry, which accepts its published sha256 instead. When the repository publishes an ed25519 archive signature it is verified too: against the owning organization’s key document when the signed metadata names one, otherwise against the machine’s trust store (cajeta trust), and never against a key supplied with the artifact. require-signatures is retired: it is still read, has no effect, and logs a warning.

A cached artifact is served without touching the network, and is held to the same verification as a freshly fetched one.

Limits

Installs are additive. A session cannot unload or replace an archive it has already loaded, because JIT’d code from it may be live: changing to a version the loaded one does not satisfy requires a session restart. Installing an archive that declares a class the session already holds is rejected — an install never shadows session state.

Re-installing at a version already loaded and satisfying is a no-op returning the loaded version, so re-running a notebook top to bottom is safe.

Methods

Both return an owned #String, so bind the result with #=:

String version #= Packages.install("dev.cajeta.ml", "0.10.*");

installAndSave is a separate method rather than a flag so that reading the call site tells you whether a file was written.

Failure

Every rejection leaves the kernel serving: the next cell still runs and the session keeps its bindings. Failures arrive as PackageInstallException, a RecoverableException, and can be caught:

try {
    Packages.install("dev.cajeta.ml", "0.10.*");
} catch (PackageInstallException e) {
    // the install was rejected; the session is still usable
}

See also

• PackageInstallException
• 24 — Notebooks — the guide, with the install → import → save walkthrough

Source: docs/stdlib/session/Packages.md · 3 min read · 571 words