Morphir v4 Design
This section contains the design documents for Morphir v4, organized into three primary themes.
Themes
IR v4
The intermediate representation format and data model.
Scope: Types, values, modules, packages, distributions, naming conventions, decorations, serialization formats.
Key Documents:
- Naming Conventions - How names are encoded
- Types & Values - Core type system
- Distributions - Library, Specs, Application formats
Document Tree Protocol
The specification for the Document Tree IR layout and the JSON-RPC protocol.
Scope: Document Tree layout, Granular vs Hybrid modules, JSON-RPC 2.0 API.
Key Documents:
- Protocol Design - Core protocol spec
Morphir Daemon
The long-running service for workspace management, builds, and IDE integration.
Scope: Workspace lifecycle, project management, dependency resolution, incremental builds, file watching, package publishing, JSON-RPC protocol.
Key Documents:
- Workspace Lifecycle - Create, open, close
- Dependencies - Resolution and caching
- Configuration - morphir.toml system
Extensions
The MEP architecture for adding frontends, backends, validators, and transforms to Morphir.
Scope: Process and WASM runtimes, typed MEP capabilities, verified installation, and custom code generators.
Key Documents:
- Morphir Extension Protocol - Runtime-neutral lifecycle and operations
- Distribution and acquisition - Index, lock, catalog, and activation
- WASM runtime and Avro backend - Accepted design, not released
- Tasks - Build automation and hooks
Status Tracking
Each design document includes tracking metadata:
| Status | Description |
|---|---|
| Draft | Initial design, under active development |
| Review | Design complete, awaiting review |
| Approved | Ready for implementation |
| POC | Proof of concept exists |
| Partial | Partially implemented |
| Complete | Fully implemented |
Tracking Frontmatter
Documents use this frontmatter format for tracking:
---
title: Document Title
status: draft
tracking:
beads: [morphir-xxx]
github_issues: [123]
github_discussions: [45]
implementation: "pkg/path/to/code"
---
Quick Reference
Active GitHub Issues
| Issue | Theme | Description |
|---|---|---|
| #398 | IR | VFS core types |
| #392 | Daemon | Pipeline core types |
| #399 | Extensions | Task execution engine |
| #401 | Daemon | Caching and incremental builds |
| #400 | Daemon | Analyzer framework |
Active Beads Issues
| Issue | Theme | Description |
|---|---|---|
| morphir-om0 | IR | Core decoration infrastructure |
| morphir-l75 | Daemon | Caching and incremental builds |
| morphir-go-772 | Extensions | Task execution engine |
| morphir-8fx | IR | VFS error types |
| morphir-369 | Daemon | SQLite-backed VFS backend |
Related Discussions
| Discussion | Theme | Topic |
|---|---|---|
| #55 | IR | Distributions, versioning, migrations |
| #88 | Daemon | Package manager |
| #52 | IR | Unique identifiers in IR |
| #53 | IR | Type encoding |
Implementation Priorities
Phase 1: Foundation (Active)
- IR v4 Core - Types, values, naming
- Decorations - Metadata infrastructure
- Pipeline - Build system foundation
Phase 2: Daemon (Planned)
- Workspace - Multi-project support
- Dependencies - Path and repository resolution
- Builds - Incremental compilation
Phase 3: Extensions (not released)
- MEP runtimes - Process and Extism-backed WASM adapters
- Verified distribution - Local index, lock, catalog, and store
- Tasks - Separate automation and hook design