Lockfiles

Matrix uses standard pnpm/npm lockfiles. The pnpm-lock.yaml at the root of matrix-work-harness is the canonical lockfile for the monorepo build. Consumers' lockfiles are their own.

Where lockfiles live

Lockfile	Owns what
matrix-work-harness/pnpm-lock.yaml	The monorepo build dependency graph (every workspace package and its transitive deps, including third-party).
<host-home>/packages/system/package-lock.json (when npm install runs there)	The Host's system package store.
<host-home>/packages/global/package-lock.json (when npm install runs there)	The Host's global package store.
Consumer's pnpm-lock.yaml / package-lock.json	The consumer's project that depends on @open-matrix/* packages.

These are unrelated to each other. A change in the monorepo's pnpm-lock.yaml does not propagate to consumers; only published tarballs do.

Reproducibility guarantees

pnpm lockfiles record per-dependency:

• Resolved version
• SHA-512 integrity hash of the tarball
• Source URL

Re-installing with pnpm install --frozen-lockfile (CI mode) verifies every hash and refuses to update if any differ. This catches:

• Tarball mutation in the registry (unintentional or hostile).
• Network man-in-the-middle.
• Accidental local edits.

Why this matters for Matrix

The artifact registry is private (Gitea) and currently lacks signing. Lockfile SHA-512 pinning is the strongest available integrity guarantee for pre-launch. A consumer who:

1. Successfully installed @open-matrix/chat@0.2.3 once,
2. Captured the SHA-512 in their lockfile, and
3. Re-installs with --frozen-lockfile,

will detect any subsequent tarball mutation. Without lockfiles, they would silently install whatever the registry currently serves.

Frozen-lockfile in CI

The monorepo CI uses --frozen-lockfile for every install. The scripts/ci/premerge-local.sh gate enforces it. A merge that bumps a dependency without updating the lockfile fails before any test runs.

Consumer guidance

Recommendations for projects that depend on @open-matrix/*:

1. Commit your lockfile (pnpm-lock.yaml or package-lock.json).
2. Use pnpm install --frozen-lockfile (or npm ci) in CI.
3. Review lockfile diffs in pull requests — they're security-relevant.
4. Run pnpm audit or npm audit periodically against the lockfile.

Lockfile versions

The current monorepo uses pnpm-lock.yaml v9.x format (pnpm 9). Any consumer using pnpm 7+ can read it. The format is backward-compatible within major versions.

What lockfiles do NOT carry

• discovery-index.json metadata. The lockfile points at the tarball; the catalog's metadata is separate.
• Mount declarations. The lockfile is install-time; mounts are runtime.
• Transitive Matrix package compatibility (peers, capabilities, etc.). The lockfile records what was resolved, not what is compatible.

See also

• Integrity
• Dependency graph
• Authentication

Source: Standard pnpm/npm. The monorepo's pnpm-lock.yaml is the authoritative example.