Skip to main content

Package Layout

Morph packages use a feature-first layout.

Canonical Shape​

morphs/<Package>/
  morph.toml
  features/
    <feature-or-group>/
      feature.toml
      *.cpp / *.h (implementation next to the manifest)
  blocks/
    <block>/
      block.toml
      Syntax.cpp / Sema.cpp / Lowering.cpp / ...
  runtime/
  backend/
  plugin/

Not every package needs every folder, but this is the canonical mental model. blocks/ is how many packages attach grammar [forms.*] surfaces; the root morph.toml [include] must list blocks/*/block.toml when the package owns those forms (see Core, Flow, Access, GPU, …).

What Each Directory Means​

PathPurpose
morph.tomlCanonical package manifest: [package], [tokens], [include] (globs for nested TOML), [build] (C++ lists), [runtime.*], imports/exports, diagnostics
features/Package-owned feature.toml groups and their sources (built-ins, ops, routes, tooling, …)
blocks/Package-owned block.toml grammar [forms.*] and syntax/sema/lowering C++ for those forms
runtime/Package-owned runtime code
backend/Package-owned backend routes
plugin/Package export wiring (morph library entry / generated glue)

Feature-First, Not Core-First​

A feature should be grouped with the package that owns it.

That means:

  • syntax, sema, lowering, and runtime slices for one feature stay near that feature
  • package runtime code stays under the package
  • backend route ownership stays under the package

Do not spread ownership across random core folders as a shortcut.

Example​

morphs/Test/
  morph.toml
  features/
    Assert/
    api/
    runner/
  plugin/

Test owns test syntax, assertions, and runner logic. That behavior is package-owned, not a special case in core CLI or parser code.

Runtime And Backend Are Also Package Space​

Do not think only features/ is plugin territory.

These are package-owned too:

  • runtime/
  • backend/
  • plugin/

If a feature needs runtime symbols or backend routes, those stay inside the owning package.

Legacy Layouts​

Legacy layouts are not the target model here.

Learn and use:

  • morph.toml
  • feature-first folders
  • package-owned runtime and backend directories

Next Steps​