Design an ecosystem-wide Morphir model package system

> *This was generated by AI during triage.*

Status: Approved architecture; Stage 0 specification and implementation remain open.
Design date: 2026-09-05; MCK, upstream IR, and staged resolution alignment: 2026-09-16.
Beads: `morphir-uhk3`; alignment `morphir-uhk3.4`; binding compromise `morphir-uhk3.5`; landing `morphir-uhk3.6`.

# Design an ecosystem-wide Morphir model package system

## Canonical specification

The full design now lives in the repository knowledge base. It exceeds GitHub's issue-body size limit, so this issue tracks the approved architecture and delivery rather than duplicating the full specification.

- [Canonical design on main](https://github.com/finos/morphir/blob/main/kb/bundles/morphir/morphir-package-system/package-system-design.md)
- [Exact MCK and staged-resolution revision](https://github.com/finos/morphir/blob/807b1bf76c5df4a1821373d0e8ab8d5fce2337c1/kb/bundles/morphir/morphir-package-system/package-system-design.md)
- [Landing PR #814](https://github.com/finos/morphir/pull/814)
- [MCK overview](https://github.com/finos/morphir/blob/807b1bf76c5df4a1821373d0e8ab8d5fce2337c1/spec/mck/README.md)

The canonical design includes the research, invariants, schemas to define, trust model, migration policy, alternatives, and open specification decisions. Merging the documentation PR does not complete this issue or implement the resolver.

## Purpose and artifact boundaries

Morphir needs an IR-first package system independent of Elm or any other source-language package manager. The same model must be publishable and consumable across Morphir implementations, local and distributed registries, offline environments, and enterprise repositories.

Model packages, executable extensions, and installable tools remain distinct artifact domains. They may reuse acquisition, caching, integrity, signing, and transport components where the semantics fit. They do not share manifests, dependency semantics, or lifecycles merely for reuse.

## Approved architecture

- Published model packages are IR-first. A Library release has a normative Library distribution and derived Specs; a Contract release has normative Specs. Executable providers remain separate.
- An immutable `PackageReleaseId` is an authority-bearing `PackagePath` plus exact SemVer. No Go-style major-version path suffix is required. Source location, channel, PURL, and content digest have separate roles.
- Core IR definitions and references remain package-release-version-free. IR `PackageName`, such as `morphir/SDK`, is explicitly associated with packaging identity, not confused with an authority-bearing path such as `finos.org/morphir/sdk`.
- Human authoring configuration, published release manifests, and exact locks are separate documents. Distribution payloads, logical package bundles, and transport encodings are also distinct.
- Public exports default from logical, package-relative Module names, with explicit export-map customization. Canonical qualification uses `package:module` and `package:module#local-name`.
- Locks record a complete dependency graph, source provenance, and integrity. Unpublished snapshots have explicit identities and cannot impersonate immutable published releases.
- Registries can use local directories, static Git or HTTPS, OCI, or hosted services. Authority delegation, release signing, safe materialization, and rollback/revocation policy remain part of the design. Acquisition never executes package-controlled hooks.
- Linked Application distributions preserve portable model meaning and exact dependency context. Target-specific executable-provider bindings remain separate.

## Approved resolution and delivery compromise

Common use cases have one implicit binding per dependency IR `PackageName` in each consuming package. Authors do not need explicit aliases for ordinary dependencies. Packaging selects exact releases; distribution binding context makes references unambiguous.

Resolution establishes bindings, applies version and capability constraints, and searches for a valid complete graph. It prefers eligible release reuse and higher stable releases according to a deterministic policy. It must reconsider earlier choices when transitive dependencies conflict; a locally highest candidate is not necessarily a valid global solution.

Ordinary builds validate and replay the exact lock without version selection. Initial resolution and updates are explicit operations. Stage 0 must fix grouping, preference ordering, tie-breaks, partial-update behavior, and structured diagnostics with MCK cases.

Separate consumers can select incompatible releases once graph-aware distributions are supported. One consumer deliberately using multiple releases of the same IR package needs explicit dependency distinctions. The resolver cannot infer different intended targets from identical references in the same binding context.

Exact advanced reference encoding, package-instance rules, and the supported IR format release are Stage 3 prerequisites. They do not block Stage 1's single-binding packaging workflow. Baseline readers report unsupported graph capabilities rather than guessing or silently renaming packages.

## Morphir Compatibility Kit

Use one compatibility brand: **Morphir Compatibility Kit (MCK)**.

- Existing MCK IR suite: `spec/ir/mck/`.
- Planned MCK package suite: `spec/package/mck/`.
- Shared overview: `spec/mck/README.md`.

Package operations and suite-aware reports require explicit versioned contract evolution. Current protocol/report version 1 is IR-specific and rejects unknown fields or operations. Preserve existing IR support while reusing infrastructure where appropriate.

Compatibility claims identify suite, kit revision, driver and adapter contract, and required capabilities. Every required case must pass. A successful run with skipped required cases is insufficient. Running TypeScript in-process and through an executable adapter tests transport agreement, not two independent implementations.

## Stages and acceptance

| Stage | Deliverable and exit criterion |
| --- | --- |
| 0: Specification foundation | Domain invariants, binding and deterministic-resolution policy, manifest/lock/registry/diagnostic schemas, canonical digests, package-management interfaces, and versioned MCK integration. Two independent implementations pass the initial normalization/digest cases at a pinned kit revision, with no failed or skipped required cases. Advanced IR reference encoding is not a prerequisite. |
| 1: Local Library workflow | Author, compile, snapshot, resolve, lock, pack, publish to a local-directory registry, and consume/verify from another project. Use implicit single bindings within supported payload limits, workspace overrides, and explicit local signing/trust. Required MCK cases reproduce the same content digest across independent implementations. |
| 2: Signed distributed registry | Static Git/HTTPS index, deterministic archives, authority discovery/delegation, signatures, mirrors, offline caches, revocation, and compatibility checks. Independent clients resolve and verify the same signed release through primary and mirror sources. |
| 3: Graph-aware packages | Settle and implement advanced reference encoding, package-instance identity, multi-release coexistence, direct multi-binding, Contract releases, portable Applications, and separate provider bindings. MCK proves the capabilities across independent implementations. |
| 4: Ecosystem adoption | Integrate existing Elm/Scala workflows and other implementations, publish migration guidance, and validate interoperable package consumption. See the canonical design for full scope. |

## Integration baseline

The documented baseline is Morphir `2cd0dcd0e0236a38e577eff90fad67339aa42449`, including PRs #809, #810, #812, and #813, with morphir-typescript pinned at `46197e289b437038427f964cca6f1f54c03044a1`.

Decision 0015's current dependency layout remains `deps//@//...`. Current readers reject populated version slots and duplicate dependency names. The reserved `@` boundary does not itself implement release resolution or multiple-version linking. Future layout changes do not require SemVer in core definitions or FQNames.

Naming-corpus drift now passes with the updated Rust pin. Rust test-coverage verification remains tracked separately in `morphir-klsu`.

## Remaining work

Complete the canonical design's open specification decisions, implement the staged vertical slices, and add the MCK package suite. The documentation landing does not claim a package resolver, graph-aware IR codec, or package-compatible implementation exists today.

Start with kb/bundles/morphir/morphir-package-system/package-system-design.md and spec/mck/README.md, then review the Stage 0 deliverables and existing spec/ir/mck/ suite. The work is complete only when the schemas, resolution policy, package-management interfaces, and versioned MCK integration are defined and two independent implementations pass the required normalization and digest cases without failures or skips.

Written by the indexing model from the issue text.