Install Resolution

Install resolution is the path from "the user typed hivecast install gitea://open-matrix/chat@latest" to "the bytes are on disk and ready to mount." Most of it delegates to the npm protocol — Gitea serves the npm-compatible HTTP API and the resolver is standard npm/pnpm.

This section pins what is Matrix-specific and what is just standard npm semantics.

The v1 install path

hivecast install gitea://open-matrix/chat@latest --home /tmp/matrix-home

The ref decomposes into:

gitea://open-matrix/chat@latest
   │       │           │     │
   │       │           │     └── version specifier (semver range or dist-tag)
   │       │           └──────── package name (bare; the scope is implied by the owner)
   │       └──────────────────── owner / scope (Gitea repo owner)
   └──────────────────────────── registry kind: Matrix-native Gitea

The CLI translates this to the npm-compatible HTTP API at https://registry.hivecast.ai/api/packages/open-matrix/npm/<package> and fetches the tarball. The local seeding path (used during hivecast install of bundled packages) writes directly into <host-home>/packages/{system,global}/node_modules/.

Plain @scope/name refs (without the gitea:// prefix) are also accepted; the configured @<scope>:registry setting in .npmrc selects the registry. For HiveCast deployments, that points at Gitea.

Pages

• Package refs — the syntax of a package reference
• Version ranges — semver ranges in package.json
• Channels — latest/next/beta and dist-tags
• Dependency graph — how peers, transitives, and bundled packages interact
• Lockfiles — pnpm-lock.yaml, integrity pinning, reproducibility

Key principle

Matrix install resolution is npm install resolution. The artifact registry speaks the npm protocol (Gitea provides the npm-compatible API). The lockfile is a normal npm/pnpm lockfile. The dependency resolver is npm/pnpm. There is no Matrix-specific resolver layer.

What Matrix adds:

• Scoped registry routing — @open-matrix:registry=https://registry.hivecast.ai/api/packages/open-matrix/npm/.
• Bundled local-mode store — the seeded <host-home>/packages/{system,global}/node_modules/ that ships with hivecast install.
• Catalog index — the parallel discovery-index.json for Q1 search (capability lookup), separate from the registry's own browse API.

These complement npm; they do not replace it.

Connector ecosystems (target state)

Status: target state — system.npm, system.pypi, system.openapi, system.com, system.win32, system.dotnet connectors. v0.5+/v1+. Each connector wraps a foreign ecosystem's registry and reflects its packages as Matrix actors. The catalog ranks results across native Matrix packages and connector-wrapped packages with the same scoring. See THESIS Part 2 / Tier 3.

Today the connector engines for COM and Win32 exist as standalone C# bridges (projects/matrix-3/com-matrix-bridge/, projects/matrix-3/win32-matrix-bridge/); mcp-hub is wrapped as the system.mcp Matrix package. Wrapping the C# bridges as Matrix packages is ~3-5 days each.

Source: Standard npm protocol everywhere. The Gitea backend serves the npm packages API at /api/packages/<owner>/npm/.