Skip to content

CEP-0003: Package Manager and Manifest Evolution

Draft

Draft proposal for the post-V1 package manager. V1 keeps module.toml local, direct, deterministic, and compiler-semantic only.

Summary

Catalyst should eventually grow a package manager around the V1 module manifest model. The package manager should own fetching, registries, version solving, lockfiles, publishing workflow, optional and conditional dependencies, target-specific dependency mappings, and provider metadata.

V1 module.toml remains intentionally small: name, version, main, local direct dependencies, and a few validated non-semantic metadata fields.

Example

Possible future manifest shape:

[package]
name = "audio-tools"
version = "2.1.0"

[dependencies]
json = { package = "@catalyst/json", version = "^1.4" }
dsp = { path = "../dsp", optional = true }

[target."wasm32-unknown".dependencies]
audio_host = { package = "@vendor/web-audio", version = "0.3" }

V1 keeps manifests local and direct; registry identities, version constraints, optional dependencies, and target-specific mappings belong to this proposal.

Motivation

The V1 resolver needs a deterministic module graph without becoming a package ecosystem. A later package manager can build on the same manifest boundary without making V1 source checking depend on registries, network access, version solving, or publishing policy.

Keeping this as a CEP avoids spreading package-manager semantics through module, namespace, import, and build docs before those policies are designed.

Proposed Direction

The package manager should extend module.toml deliberately rather than silently accepting arbitrary unknown fields. Candidate areas:

  • registry package identity and publishing metadata;
  • lockfiles and reproducible resolution;
  • remote fetching, caching, checksums, and trust policy;
  • version constraints and compatibility policy;
  • dependency update behavior;
  • optional dependencies and feature flags;
  • conditional and target-specific dependency mappings;
  • provider-specific metadata;
  • external package identities such as npm-style @vendor/pkgname mapped to source-facing aliases;
  • alternate toolchain roots and std replacement through build policy rather than dependency alias shadowing.

Source-Facing Alias Rule

Source code should keep resolving dependency roots through ordinary Catalyst identifiers such as module("json"). External package names may contain syntax that is not a Catalyst identifier, but those identities should map to local source-facing aliases in the manifest or lockfile.

V1 Compatibility

V1 manifests reject unknown fields and only resolve direct local dependency roots. This proposal should not weaken that baseline. Package-manager metadata becomes meaningful only once the resolver and tooling that own it exist.