WebAssembly Extension System — Documentation Index

ARCHIVE — This document is historical reference only. It may contain outdated information. See docs/status.md for current project state.

Date: 2026-02-16 Phase: 3l — Extensibility & Partnerships Status: Research Complete, Implementation Pending

---

Overview

This index provides navigation to all documentation related to Morphee's WebAssembly-based extension system. Research was completed on 2026-02-16; updated 2026-02-20 for iOS JIT restriction and BaseMorphRuntime concept.

Key Decisions:

• Use WebAssembly for third-party backend extensions (JIRA, GitHub, Notion, Slack...)
• Python backend: wasmtime-py (best security, WASI 0.3 async, unchanged)
• Tauri Rust: wasmer 5.0 — unified API across desktop/Android/iOS (iOS JIT prohibition makes wasmtime unsuitable on iOS)
• BaseMorphRuntime abstraction: WasmRuntime (wasmer 5.0), JSRuntime (frontend canvas/UI), PythonRuntime (future)
• WASM extensions declare their BaseInterface contract (actions, events, config_schema) just like Python integrations — the Runtime is an implementation detail

---

Documentation Structure

1. Comprehensive Research (PRIMARY REFERENCE)

File: 2026-02-16-wasm-extension-research.md

Contents:

• Executive summary and key recommendations
• Python runtime comparison (wasmtime-py vs wasmer-python vs wasm3)
• Rust runtime comparison (wasmtime vs wasmer vs wasm3)
• WASI and Component Model deep dive
• Extension security (sandboxing, permissions, resource limits)
• Real-world examples (VS Code, Figma, Shopify, Cloudflare)
• SDK patterns (Rust, TypeScript, Python host)
• Performance characteristics and optimization strategies
• Distribution (OCI registry, versioning, code signing)
• Architecture diagram and recommendations

Read this first for comprehensive understanding.

---

2. Quick Reference (DAILY USE)

File: WASM_QUICK_REFERENCE.md

Contents:

• TL;DR decision matrix
• Installation commands
• Minimal code examples (Python + Rust)
• Performance benchmarks
• Permission model overview
• WIT interface examples
• Extension manifest format
• OCI registry commands
• SDK build process
• Binary optimization steps
• Module caching strategy
• Implementation roadmap (12 weeks)
• Key takeaways (DOs and DON'Ts)

Use this for quick lookups during development.

---

3. Decision Matrix (COMPARISON TABLES)

File: WASM_DECISION_MATRIX.md

Contents:

• Runtime comparison tables (Python, Rust)
• Performance benchmarks (2026 data)
• WASI version comparison
• Security comparison (WASM vs JS vs native)
• Developer experience by language
• Distribution method comparison
• Real-world architecture comparison
• Permission model options
• Binary size optimization pipeline
• Module caching strategies
• Resource limit recommendations
• Code signing requirements
• Async support comparison
• Cost comparison (development, runtime, maintenance)
• Migration path for existing integrations
• Final recommendations (DOs and DON'Ts)
• Key metrics to track

Use this when making technical decisions or comparing options.

---

4. Implementation Roadmap (PROJECT PLAN)

File: WASM_IMPLEMENTATION_NEXT_STEPS.md

Contents:

• Decision summary
• 6-phase implementation roadmap (12 weeks total)
  • Phase 1: Foundation (2 weeks)
  • Phase 2: Security & Permissions (2 weeks)
  • Phase 3: Distribution (1 week)
  • Phase 4: Developer Experience (2 weeks)
  • Phase 5: Built-in Extensions (3 weeks)
  • Phase 6: Marketplace (2 weeks)
• Immediate next steps (this week)
• Success metrics per phase
• Risks and mitigations
• Open questions
• Reference links

Use this for project planning and sprint breakdowns.

---

Document Relationships

WASM Extension System Documentation
│
├── 2026-02-16-wasm-extension-research.md  ← Comprehensive research (read first)
│   ├── Runtime analysis (Python, Rust)
│   ├── Security architecture
│   ├── Real-world examples
│   ├── SDK patterns
│   └── Recommendations
│
├── WASM_QUICK_REFERENCE.md  ← Daily use reference
│   ├── TL;DR summary
│   ├── Code examples
│   ├── Commands
│   └── Key takeaways
│
├── WASM_DECISION_MATRIX.md  ← Comparison tables
│   ├── Runtime comparisons
│   ├── Performance data
│   ├── Architecture options
│   └── Final recommendations
│
└── WASM_IMPLEMENTATION_NEXT_STEPS.md  ← Project plan
    ├── 6-phase roadmap (12 weeks)
    ├── Immediate actions
    ├── Success metrics
    └── Risks/questions

---

Key Documents Outside This Folder

Updated Documents

1. ROADMAP.md — Current Roadmap (Phase 3l archived, now V1.2 WASM Extension layer)
   • Updated to reference WASM (was JavaScript)
   • Links to research documents
   • Architecture overview

Related Documents

2. architecture.md — System Architecture

   • Overall Morphee architecture
   • Integration/Interface system
   • Hybrid Python + Rust design

3. interfaces.md — Interface System

   • BaseInterface contract
   • Permission model (AIAccess, SideEffect)
   • ExecutionContext
   • VaultProvider integration

4. status.md — Project Status

   • Current phase (3e.4 - 3e.5)
   • Next phases (3f, 3g, 3h, ...)
   • Phase 3l status: PLANNED, research complete

---

Quick Navigation by Use Case

"I need to understand WASM for Morphee extensions"

→ Start with 2026-02-16-wasm-extension-research.md (sections 1-4)

"What runtime should I use?"

→ WASM_QUICK_REFERENCE.md (Decision Matrix table) → WASM_DECISION_MATRIX.md (Runtime Comparison sections)

"How do I write an extension?"

→ 2026-02-16-wasm-extension-research.md (Section 6: SDK Patterns) → WASM_QUICK_REFERENCE.md (Minimal Example + SDK Pattern)

"What's the implementation timeline?"

→ WASM_IMPLEMENTATION_NEXT_STEPS.md (Implementation Roadmap)

"How do I secure extensions?"

→ 2026-02-16-wasm-extension-research.md (Section 4: Extension Security) → WASM_DECISION_MATRIX.md (Security Comparison + Permission Model)

"How do I optimize extension performance?"

→ 2026-02-16-wasm-extension-research.md (Section 7: Performance) → WASM_QUICK_REFERENCE.md (Performance Characteristics + Binary Optimization)

"How do I distribute extensions?"

→ 2026-02-16-wasm-extension-research.md (Section 8: Marketplace and Distribution) → WASM_QUICK_REFERENCE.md (Distribution section)

"What are best practices?"

→ WASM_DECISION_MATRIX.md (Final Recommendations: DO/DON'T) → WASM_QUICK_REFERENCE.md (Key Takeaways)

---

Timeline

Date	Event
2026-02-16	Research completed, documentation written
2026-02-17	GitHub issue created for Phase 3l
TBD	Phase 1 kickoff (Foundation, 2 weeks)
TBD	Phase 2 kickoff (Security, 2 weeks)
TBD	Phase 3 kickoff (Distribution, 1 week)
TBD	Phase 4 kickoff (Developer Experience, 2 weeks)
TBD	Phase 5 kickoff (Built-in Extensions, 3 weeks)
TBD	Phase 6 kickoff (Marketplace, 2 weeks)
TBD	Phase 3l complete (12 weeks after Phase 1 start)

---

Key Decisions Made

✅ Python Runtime: wasmtime-py v41+ — unchanged, best security, WASI 0.3 async ✅ Tauri Rust Runtime: wasmer 5.0 — unified API; Cranelift JIT desktop/Android, Wasmi iOS

• Why not wasmtime? iOS App Store §2.5.2 bans JIT — wasmtime JIT is rejected by Apple
• Why wasmer? Single crate, pluggable backends — one API for all platforms
• wasm3 tracked: Future ultra-minimal option (64KB, 65% native, sync-only) ✅ BaseMorphRuntime: WasmRuntime (backend .wasm), JSRuntime (frontend canvas/UI), PythonRuntime (future .py) ✅ Integration Contract: WASM extensions declare describe() + execute() — same as BaseInterface ✅ Interface Standard: WebAssembly Component Model + WASI 0.3 ✅ Security: Capability-based permissions, deny-by-default, resource limits ✅ Distribution: OCI registry (GitHub Container Registry) ✅ Code Signing: Mandatory (RSA-PSS + SHA-256) ✅ Primary SDK: Rust (secondary: AssemblyScript/TypeScript) ✅ Permission Model: Fine-grained (10+ permission types) ✅ Caching Strategy: Serialize compiled modules to disk/memory ✅ Async Support: WASI 0.3 native async (Python asyncio, Rust Tokio) ✅ Binary Optimization: wasm-opt -Oz (60% size reduction)

---

Open Questions (To Be Resolved)

These questions are documented in WASM_IMPLEMENTATION_NEXT_STEPS.md:

• Should we support multiple versions of an extension installed simultaneously?
• How do we handle extension compatibility with Morphee versions?
• Should extensions be able to call other extensions?
• How do we handle extension updates that require re-approval of permissions?
• What's the policy for revoking/banning malicious extensions?
• Should we build a review process for public extensions?
• How do we handle paid extensions?

---

External Resources

Official Documentation

• Wasmtime Documentation
• wasmtime-py GitHub
• WebAssembly Component Model
• WASI Specification
• WIT Reference

Real-World Examples

• VS Code WASM Extensions
• Figma Plugin System
• Shopify Functions
• Cloudflare Workers

Security

• WebAssembly Security
• Wasmtime Security
• WaVe: Verifiable WASM Sandboxing

Performance

• 2026 Runtime Benchmarks
• WASM Performance Patterns
• V8 Code Caching

---

Contributing to This Documentation

When updating WASM extension documentation:

1. Add new insights to the research doc if they're significant
2. Update the quick reference for frequently-used information
3. Update the decision matrix when comparing new options
4. Update the implementation plan for timeline changes
5. Update this index if adding new documents

Maintain consistency: All documents should reference the same version numbers, recommendations, and code examples.

---

Version History

Version	Date	Changes
1.0	2026-02-16	Initial research and documentation
1.1	2026-02-20	iOS JIT restriction → wasmer 5.0 for Tauri. BaseMorphRuntime abstraction (WasmRuntime, JSRuntime, PythonRuntime). wasm3 tracked as future option.

---

Contact

For questions about WASM extension system design:

• GitHub Issues: Tag with wasm, extensibility, phase-3l
• Documentation: See CONTRIBUTING.md
• Architecture Review: Tag @sebastien in issues

---

Last Updated: 2026-02-16 Next Review: Before Phase 1 kickoff