Decision D025 · accepted
Packages: a data manifest, registries first, a solver, a lockfile, and allowed effects
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-15)
Amended 2026-11-18 by D037: a package may have scripts/ (tasks are programs), and the manifest's :diaspar key names the required toolchain and language version.
Amended 2026-11-18 by design/ffi.md (decided by the FFI agent on the author's delegation): an entry of :native is #{:lib NAME :pkg-config MODULE :search #[DIR …]}, and the manifest's :bind key holds the binding generator's input (diaspar bind); generated bindings are source of the wrapper package, committed and published with it.
The concrete design (proposed, 2026-11-18) is design/packages.md, with its questions for the author in section 16 and the work plan in design/packages-plan.md; its first step is built: :path and :git dependencies, the lockfile, modules across packages, diaspar fetch.
The manifest is Diaspar data
package.dias holds literals only and is never executed, as Zig's build.zig.zon: one language all the way down (D001), readable by external tools with a plain s-expression reader.
;; package.dias
#{:name "someone/geom"
:version "0.3.0"
:exports #["geom" "geom.shapes.*"]
:deps #{"someone/vecmath" #{:version "^1.4" :effects #[]}
"acme/http" #{:version "^2.1" :effects #[:net :fs] :registry "corp"}
"lab/fastmath" #{:git "https://git.example.com/lab/fastmath" :tag "v0.9.1"
:effects #[:unsafe]}}
:dev-deps #{"someone/proptest" #{:version "^0.2"}}
:native #{"sqlite3" #{:pkg-config "sqlite3"}}}
:exports is D011's list.
Where packages come from
- Registries are the primary source. A package is named within a registry; the name carries no hosting domain.
- Names are
owner/name, as Ferron's D62: owners are registry accounts, which limits name squatting and typosquatting. - One default registry; others by name. Additional registries (a company's, a mirror) are configured by name in the user's or the workspace's configuration, and a dependency names one explicitly with
:registry. A dependency without:registryis looked up in the default registry only: packages are never searched across several registries implicitly. This closes dependency confusion (2021), where a public package named like an internal one was picked up from the wrong registry. When two registries hold a package with the same name, the choice is always explicit in the manifest. - Git and paths are a last resort.
:gitwith:tag,:rev, or:branch, and:pathfor local work and workspaces. A published package may depend only on registry packages, as Cargo requires, so a published dependency chain cannot be redirected to someone's repository. - Published versions are immutable; they can be yanked, not replaced.
Versions
- Requirements as
"^1.4","~1.4","=1.4.2"; a tag or a revision for git. - A SAT-style solver: PubGrub, as Dart's pub, uv, and Cargo's new resolver use, because it explains conflicts step by step ("geom needs vecmath ^2 and plot needs vecmath ^1, so geom and plot are incompatible"), which fits D014 diagnostics. Go's minimal version selection was rejected.
- One version of each package per program, as in Python and Dart: modules are named by the package's root (
vecmath.…), so two versions would clash; the solver explains the conflict. A renaming escape hatch may come later.
The lockfile
package.lock.dias records exact versions, sources (registry, or git with a commit), and a content hash of every package. It is committed for applications and libraries alike; --locked fails in CI when it is out of date.
Allowed effects per dependency
Effects are inferred (D005), so the compiler knows whether a dependency's code reaches the network, the file system, other processes, the environment, the clock, randomness, the terminal, or C (Unsafe, D021). A dependency lists what it may do, and the build checks it:
:effectscovers the dependency's whole subtree; a violation is reported with the path and the place in the code.- Effect names follow the standard effects:
:fs,:net,:process,:env,:clock,:random,:term,:unsafe. - Trust on first add:
diaspar addinfers a package's effects and writes them into the manifest; an update that needs new effects fails until they are approved, as new permissions are on a phone. - Macros run at compile time with no effects beyond reading their own sources.
Attacks such as event-stream's (malicious code in a popular npm dependency) become visible at update time. Deno and Java's former SecurityManager check permissions at run time; this check happens at build time.
No build scripts
No executable build scripts, unlike Cargo's build.rs or Python build backends: native dependencies are declared as data (D021), and code generation at compile time is macros with limited effects.
Kinds of dependencies
:deps (ordinary), :dev-deps (only for tests/, benches/, and examples), :native (C libraries).
:native names a C library, not a Diaspar package: it tells the build how to find and link it (:pkg-config, or a library name and search paths), as D021 describes. Usually it appears in a wrapper package, a Diaspar package that binds the library through FFI (possibly generated from its headers); applications depend on the wrapper with :effects #[:unsafe …] and never list the C library themselves:
;; the wrapper's package.dias
#{:name "someone/sqlite"
:native #{"sqlite3" #{:pkg-config "sqlite3"}}}
;; an application's package.dias
#{:deps #{"someone/sqlite" #{:version "^3.0" :effects #[:unsafe :fs]}}}
Building a C library from bundled sources, instead of using the system's, is a later option. Cargo-style optional features are deferred: they complicate resolution and builds.
Scripts and the REPL
A single-file script may declare its dependencies inline, as Python's PEP 723, and the REPL outside a project may add a package without restarting, as Clojure 1.12's add-lib. Inside a project (a directory with package.dias), both are errors with a hint to use diaspar add: a program's dependencies are all declared in its manifest and pinned in its lockfile.
;; script.dias
^{:deps #{"someone/csv" #{:version "^1.2"}}}
(use csv)
Entry points (accepted)
A program's entry point is a function (defn main [args] …). diaspar run FILE args… loads the module and calls its main with the arguments; a package names its programs in the manifest, :bin #{"jt" "jt.main"} (the program name and its module). Top-level code only defines things and does no work at load time, so diaspar test and the REPL can load any module without running a program. main returning normally exits with 0; an unhandled error exits with 1 (D017).
One tool
diaspar does everything: run, test, bench, add, update, build, connect, with no separate package manager.
Workspaces
Several packages in one repository share a lockfile, listed in a root workspace.dias; they see each other's exports only (D011); diaspar test -p server runs one package's tests (D016).