Morphir Extensions
Morphir extensions add frontends, backends, validators, and transforms without putting every provider in the CLI process. This draft describes the current implementation boundary. The accepted WASM runtime and Avro work is implemented for contributor testing, but it has not been released.
The accepted WASM extension runtime and Avro backend proposal controls if this overview or another draft differs from it.
Current contract
Every runtime uses the Morphir Extension Protocol, or MEP. MEP is a JSON-RPC 2.0 lifecycle with initialization, typed capability negotiation, operations, cancellation, and shutdown.
The public runtime names are process and wasm:
| Runtime | Transport and execution | Rights |
|---|---|---|
process | The host starts an executable and exchanges Content-Length framed MEP messages over standard input and output. | The process has the ambient filesystem and network rights of the user who starts Morphir. |
wasm | The host loads a module through the Extism engine and sends the same MEP envelopes through the guest adapter. | The guest has no direct filesystem or network access. It returns artifacts for the host to validate and write. |
Extism is an engine detail. It is not a runtime value or a separate extension protocol. The current guest ABI does not use the WebAssembly Component Model or WIT interfaces.
Capabilities are typed. A backend declares its targets, supported Morphir IR
versions, and whether it implements generation. The generation operation uses
the exact GenerateRequest { ir, options } request. The host reads input files,
validates returned relative artifact paths, and writes output files.
Install an extension
The CLI installs from a named local extension repository. It does not accept a
raw .wasm file, an archive, a URL, or an unregistered directory:
morphir extension repository add <REPOSITORY> --directory <DIRECTORY>
morphir extension install --repository <REPOSITORY> <NAME>
morphir extension list
morphir extension update --repository <REPOSITORY> <NAME>
morphir extension uninstall <NAME>
<NAME> is the stable extension ID. <REPOSITORY> is the stable name recorded
in Morphir Home for <DIRECTORY>. The directory contains JSONL release
histories under extensions/ and artifact bytes below the same controlled root.
Installation defaults to the stable channel. --channel <CHANNEL> selects a
different channel, while --version <VERSION> selects an exact semantic
version. The two selection options are mutually exclusive.
Installation resolves one schema-v2 record, verifies its SHA-256, stores the artifact by content digest, and writes matching catalog and lock state. Normal activation is offline. The host checks the catalog against the lock, rehashes the installed artifact, and compares initialization identity and capabilities with the installed metadata before calling an operation.
The CLI has no --global install mode. Contributors can set MORPHIR_HOME to
an isolated directory when testing installation.
The Avro generation guide has a complete local build, schema-v2 repository, and install example. The generated CLI install reference documents the current arguments and flags.
Use a backend
Once an installed backend advertises a requested target and Morphir IR version, the CLI can select it for generation:
morphir generate --target avro \
--input morphir-ir.json \
--output generated/avro
Backend configuration lives under [codegen.<target>] in morphir.toml.
Repeat --option <KEY=VALUE> for one-command overrides. The host transports
these values without knowing backend-specific option names.
Current design documents
| Document | Status | Purpose |
|---|---|---|
| Morphir Extension Protocol | Draft | MEP envelopes, lifecycle, typed capabilities, operations, artifacts, diagnostics, and conformance |
| Distribution and acquisition | Draft | Index records, verified installation, catalog and lock state, runtime selection, and activation |
| WASM runtime and Avro backend | Accepted, not released | Controlling runtime boundary, Avro behavior, release ownership, and acceptance criteria |
| Generate Apache Avro | Contributor guide | Local installation, options, projections, type mappings, and output files |
The task system draft explores build automation and hooks. Tasks are not a capability in the current MEP extension contract.
Historical Component Model design
An earlier design proposed a typed WIT interface for each Morphir operation and packaged extensions as WebAssembly components. That work contains useful notes about portability, sandboxing, and type boundaries, but it is not the current extension ABI or an installation guide. The archived WASM Components source is kept in Git for that rationale and is excluded from the published site.
Do not copy commands or manifests from historical extension documents into a current setup. Use the protocol, distribution draft, accepted proposal, and Avro guide linked above.