Skip to main content

Morph Packages

Purpose​

morphs/ is the canonical home for Morph packages. A Morph package is the ownership boundary for language features, runtime features, execution formats, build providers, platform providers, backend routes, and tooling commands that belong in package space instead of core source trees.

Pipeline: each package’s morph.toml, feature.toml, block.toml, and plugin/* registration (via the MorphABI in include/morphc/morph/MorphABI.h and generated glue) plug syntax, sema, NIR/MIR phases, LLVM/GPU/shader/NN/REPL backends, runtime symbols, and CLI tooling into the single compiler host in src/. That end-to-end governability is the Morph Framework; end-user docs that only describe syntax are intentionally incomplete without that story—see Docs/learnmorph/23_morph_framework/plugin_governed_pipeline.md.

Non-Negotiable Rules​

  • Feature work must happen in plugin/package space. If this package cannot express a feature, widen the framework or SDK instead. Do not edit Core as a shortcut.
  • A new ternary condition must be implemented by extending an existing package or adding a new package.
  • A new operator or precedence rule must be implemented by extending a package such as Ops or a sibling package.
  • A new type or runtime capability must be implemented in the package that owns that domain.
  • A new build or platform target must be implemented by package-owned build and platform providers.
  • Edit core only to widen generic framework or SDK capability that packages consume.

Standard Package Layout​

  • morph.toml is the canonical package manifest ([package], [tokens], [import.*]/[export.*], [runtime.*], [include] globs for nested manifests, [build] source lists, [diagnostics]).
  • features/ contains package-owned feature folders; each logical feature group often has a feature.toml (built-ins, operations, routes, tooling descriptors—shape varies by domain).
  • blocks/<name>/block.toml declares [forms.*] grammar rules (rule DSL, produces, component_class, source) for statement/expression surfaces; the root morph.toml [include] must list blocks/*/block.toml when the package owns syntax blocks (e.g. Core includes both features/*/feature.toml and blocks/*/block.toml).
  • tests/ is optional and contains package-owned Morph behavior tests.
  • runtime/ contains package-owned runtime code when the package owns runtime behavior.
  • backend/ contains package-owned backend routes when the package owns backend behavior.
  • plugin/ contains package export wiring and generated or package-local entry points.
  • docs/ is optional package-specific documentation.

Decision Tree​

  • Extend an existing package when the requested behavior clearly belongs to that package's ownership boundary.
  • Create a new package when the behavior is a distinct domain, platform, execution format, or provider.
  • Widen the framework or SDK only when no existing package can express the feature through Morph manifests, features, runtime slices, backend routes, or tooling descriptors.
  • Never route around package ownership by patching core as a shortcut.

Package README Template​

Every morphs/<Package>/README.md must use this exact section order:

  1. Purpose
  2. Ownership
  3. Public Features
  4. Directory Layout
  5. How To Extend
  6. What Must Not Be Done In Core
  7. Dependencies
  8. Testing
  9. Examples
  10. Related Packages

No custom top-level sections may be inserted before, between, or after these required sections.

Subdirectory README Template​

If a package contains features/, runtime/, backend/, or plugin/, that subroot must contain a README.md with this exact section order:

  1. Purpose
  2. Contents
  3. Extension Rules
  4. Do Not Edit
  5. Pointers

No custom top-level sections may be inserted before, between, or after these required sections.

Extension Examples​

  • Ternary condition: extend the package that owns expression syntax and lowering, or create a dedicated package. Do not edit core parser code as the feature owner.
  • New operator precedence: extend Ops or another owning package. Do not hardcode precedence directly into core as a feature shortcut.
  • New type: extend Types or a domain package such as Tensor or Graphics.
  • New runtime capability: extend the package that owns that runtime family. Do not patch the generic runtime kernel with domain policy.
  • New build or platform target: extend Build and add or update platform provider packages. Do not add target-specific branches to core.

Validation​

This contract is enforced by scripts/validate_morph_docs.py and by Morph boundary tests. Missing README coverage, wrong section order, or weakened plugin-first wording is a hard failure.