Package Registry and Catalog

In docker-for-actors / npm-for-actors terms, the registry is where the bytes live and the catalog is how you find what to install. They are two different surfaces; they answer two different questions; they have two different implementations.

Motivation

A package substrate without a registry is just a pile of source trees nobody else can install. Gitea is the Matrix-native package registry — the place tarballs actually live and the API that hivecast install pulls from — and it speaks the same npm wire shape existing tooling already knows. The catalog is a separate surface that sits on top of registries and ranks live capabilities by stats and trust, so an agent or a human looking for "something that can do X right now" gets a useful answer instead of a directory listing. The two answer different questions: "what has been published?" versus "what can do X right now?" Read these docs if you publish packages, install them, or are building tools that need to discover what is available across native and external sources.

What this is, and why it exists

Matrix is npm-shaped: a package is a tarball with a matrix.json and a package.json. Gitea is the Matrix-native package registry. Gitea serves the npm-compatible HTTP API at /api/packages/<owner>/npm/<package>, which is the same wire shape npm clients already speak. hivecast install gitea://owner/repo@version is the v1 install path; existing npm tooling can publish and consume Matrix packages because Gitea speaks the protocol.

hivecast install gitea://open-matrix/chat@0.2.3
       └── pulls tarball from Gitea (npm-shaped HTTP)
       └── unpacks into <host-home>/packages/global/node_modules/
       └── seeds discovery metadata into local catalog index

Three discovery surfaces sit on top of the registry, answering three different questions (THESIS Part 3):

Question	Surface	Authority
Q1. What can do X? (capability search across tiers and registries)	Catalog	system.catalog (and external connectors as they ship)
Q2. What is in registry X? (browse the underlying registry)	Browse	Gitea HTTP browse, npm HTTP browse, etc.
Q3. What is currently live? (what is mounted in this Space right now)	Live actor registry	system.registry

The four authorities, in one table:

System	Question it answers	Authority surface
Artifact registry (Gitea)	"Where do I download @open-matrix/chat@0.2.3 from?"	Gitea HTTP repository (/api/packages/<scope>/npm/...)
Package catalog	"What can I install? What does this package describe itself as?"	system.packages actor — searches a discovery-index.json next to the artifacts
Live actor registry	"Which mounts are claimed by which providers right now?"	system.registry actor (ServiceRegistryActor) — heartbeat-tracked logical mount claims
System catalog (read projection)	"What is mounted, where, with what ops, in this Host?"	system.catalog actor — read-only join over system.registry, system.runtimes, system.gateway.http, and live $introspect

Catalog (Q1) and Browse (Q2) can both query the same registry; they answer different questions. Mixing them is the most common documentation drift.

Where this fits in the whole

This is substrate plumbing, not a vertical. The registry/catalog surfaces are what every vertical consumes when:

• An agent searches for a tool to satisfy a capability (Catalog).
• A developer browses what packages exist (Browse).
• A dashboard shows what is running on this Device (Live).

Tier 1 (local Host), Tier 2 (hosted Host), and Tier 3 (external connector ecosystems like npm/PyPI/COM) all surface through these same primitives — when a connector ships, the catalog ranks its results next to native Matrix packages.

Five-minute quickstart

# 1. Configure your scope to point at the Matrix-native (Gitea) registry.
#    .npmrc:
#    @open-matrix:registry=https://registry.hivecast.ai/api/packages/open-matrix/npm/

# 2. Install a package. Gitea is the Matrix-native registry.
hivecast install gitea://open-matrix/chat@latest --home /tmp/matrix-home

# 3. Browse the registry directly (Q2 — what's available).
curl -s https://registry.hivecast.ai/api/packages/open-matrix/npm/@open-matrix/chat | jq .versions

# 4. Search the local catalog (Q1 — what can do X).
matrix invoke system.packages registry.search '{"query":"chat"}'

# 5. List what's currently live in the local Space (Q3 — what's running).
matrix invoke system.registry registry.list '{}'

Three different commands for three different questions. They are not interchangeable.

Conceptual map

Question you have	Read
What is a registry vs. a catalog vs. a live actor registry?	Overview
Where do tarballs live, and how is Gitea wired in?	Artifact Registry
What does the catalog know, and how is search ranked?	Package Catalog
How does hivecast install resolve a ref to bytes?	Install Resolution
How do I publish a package, promote a version, revoke one?	Publishing
Schemas, error codes, grammars	Reference

Where this lives in the code

Concern	Path
Live mount claims (system.registry)	projects/matrix-3/packages/system-platform/src/ServiceRegistryActor.ts
Read projection (system.catalog)	projects/matrix-3/packages/system-catalog/src/SystemCatalogActor.ts
Discovery search (system.packages)	projects/matrix-3/packages/system-catalog/src/SystemPackageRegistryActor.ts
Artifact seeding	projects/matrix-3/packages/hivecast/bin/hivecast.mjs (seedBundledHostPackages)
Artifact registry deployment	projects/deploy-cloud/Caddyfile.bare, projects/deploy-cloud/deploy.sh
Discovery metadata contract	WORKSTREAMS/core-and-packaging/MATRIX-DISCOVERY-METADATA-SPEC.md

Sister docs

• docs-package-lifecycle — author → build → test → publish → install → run → operate. The publishing side of this docs package lives there.
• docs-runtime-host — <host-home>/packages/ is the local artifact store the registry installs into.
• docs-gateway — the gateway routes assets; inventory questions go to the bus actors named here, not to HTTP.

Source: All four authorities are in code today. system.registry and system.catalog are mounted by every Host's system runtime (projects/matrix-3/packages/system/matrix.json). system.packages is mounted beside them by the same runtime. The artifact registry is external infra: a Gitea instance behind registry.hivecast.ai for the cloud product, or the bundled package store under <host-home>/packages/{global,system}/ for local installs.