Architecture and design docs for zed-pkg, the universal package manager backed by the VCS hosts you already use.
Each doc below answers one of the tracked issues, in order. Where a design is already implemented, the doc links to the code.
| # | Topic | Status |
|---|---|---|
| 1 | CAS + symlinks: dependency fetching decoupled from build | implemented |
| 2 | Global store <-> project bridge under OCI | implemented |
| 3 | Polyglot version strings (git/hg tags, commits) | implemented |
| 4 | Lockfile vs mutable tags/branches | implemented |
| 5 | Source caching vs build caching | implemented |
| 6 | Process-level locking for concurrent CLIs | implemented; blocking OS locks + process regressions |
| 7 | From concept to enterprise-grade | implemented* |
| 8 | Fast Rust CI (<3 min) | implemented |
| 9 | Multi-OS / multi-arch CLI distribution | implemented |
| 10 | End-to-end testing across servers, CLI, and browsers | implemented |
| 11 | Deploying the registry to Kubernetes (GitOps app-of-apps) | implemented |
| 12 | In-cluster e2e (kind + in-memory profile + Argo CD) | implemented |
| 13 | Remote browser-grid e2e (ORES clusters, AWS + Hetzner) | partial |
| 14 | Client-side sync patterns + opto-sync package adoption | package-ready; migration staged |
| 15 | The manifest, where deps go, complementing npm/maven | implemented |
| 16 | zed-pkg-test CI harness (GitHub Actions only) | node + rust proven |
| 17 | Polyglot client libraries: one repo, one package per language | implemented |
| 18 | Native registry fan-out and target-only forge mirrors | direction set |
| 19 | Polyglot publishing: what is actually verified (audit of 18) | verified in CI |
| 20 | Repository synchronization and semantic conflict resolution | operational runbook |
| 21 | Deterministic offline release-plan review in a browser | implemented; three-engine + print/a11y verified |
| 22 | Real flags2env C parser in browser WebAssembly and workers | implemented; three-engine verified |
| 23 | Nix–Zed interoperability through sealed, immutable adapter records | proposal; implementation staged |
| 24 | Recursive dependency graphs, five-worker prefetch, and per-artifact locks | implemented; external E2E certified |
| 25 | Complete one-version solving for overlapping transitive ranges | implemented; independent black-box certification |
| 26 | Pure deterministic Zed → Nix flake-bundle rendering contract | implementation under review |
| 27 | Durable .zpkg.toml creation on first dependency install | implemented; Node + Go/Python/Rust certified on Linux/macOS |
| 28 | Flox, Devbox, mise/asdf, and scratch OCI interoperability | RFC; executable policy validated |
| 29 | Native prerequisites, install hooks, consent boundaries, staging, caching, and Nix purity | manifest contract implemented; installer lifecycle under review |
| 30 | Git submodules vs Zed packages, workspaces, release composition, and deployment boundaries | operational policy; pack guard under review |
| 31 | zed-lock: helper-thread async adapters over kernel-backed cross-process locks | architecture approved; extraction tracked |
| 32 | Organization clients/interfaces/lib/CLI/monorepo package pattern and fleet audit | operational policy; rollout audited |
| 33 | Canonical GitHub organization, Linear project, GitHub Project, and artifact ownership registry | operational policy; Projects permission blocked |
| 34 | Terminal/TTY/shell context, prompt safety, and cross-platform certification | implemented; Linux/macOS/Windows certified |
| 35 | Native registry hosts, wire protocols, and per-ecosystem release-candidate tracks | contract implemented; multi-request publishes outstanding |
Independent executable acceptance contracts that do not consume architecture
numbers are indexed separately. The first is the
zed develop clean-room acceptance contract,
which is already on main and remains deliberately unnumbered.
* Enterprise features are implemented except SSO and per-org storage
quotas, which remain planned. Audit logs shipped (zed org audit,
GET /v1/orgs/{org}/audit); the quota that exists today is the org-claim
squatting limit, which is a different thing. See
doc 7.
A package is <org>/<name> with a .zpkg.toml manifest (TOML only). Its
source of truth is a repo on any git/hg/jj/sapling/fossil/pijul host;
zpkg.tech is the primary artifact host and the forge is the mirror +
provenance anchor. zed publish packs a pruned, deterministic tarball (tests,
CI, .github/, READMEs stripped; licenses kept), verifies a matching VCS tag
at HEAD, and uploads. zed install resolves semver, downloads each artifact
once into a content-addressed store at $HOME/.zed-pkg, verifies its sha256,
and symlinks it into the project's zed_modules/ — pnpm-style.
Organization contribution and review rules are in CONTRIBUTING.md. In particular, a pull request may not be closed as superseded until its successor incorporates and traces at least one substantive item from every predecessor.
This documentation is MIT licensed. See LICENSE. Report suspected security issues using the private-first procedure in SECURITY.md, not a public issue containing exploit details or credentials.