Skip to the content
Diaspar

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 :registry is 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. :git with :tag, :rev, or :branch, and :path for 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:

  • :effects covers 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 add infers 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).