Phero Lang — Verifiable Model-Driven Engineering.
Phero Lang is a multi-target modeling language inspired by Eclipse Xcore.
.mox sources compile to a Core IR (an Ecore-like structural metamodel) that is
serialized as a stable artifact. Code generators for multiple target languages
(Rust, JSON Schema, Cedar, ...) consume only that IR. A complementary
.actor policy dimension compiles to its own artifact and feeds the Cedar
backend. The language reference lives in
docs/LANGUAGE.md; if you are writing a backend that
consumes the IR — in or out of tree — start with
docs/BACKENDS.md. Releases and compatibility promises
are documented in docs/VERSIONING.md and
CHANGELOG.md; the spelling contract for the product and
every identifier that carries its name is
docs/NAMING.md.
CONTRIBUTING.md covers the contribution workflow, and
SECURITY.md covers private vulnerability reports.
.mox source -> lexer/parser -> AST -> resolve & validate -> Core IR (.phero.json)
^ |
| +----------------+--------+-----------+
| v v v
| rust backend json-schema backend cedar backend
| ^
+-- import schema "x.json" .actor policy file -> resolve & check ---+-+
+-- import sigil "x.rosetta" -> ActorModel (.actors.phero.json)
.ddd design file -> resolve & validate
-> DddModel (.ddd.json) --xstate-ir--> machines
.evt contract file -> resolve & validate
-> EventModel (orders.evt.json)
.uc use case file -> resolve & validate (4 import buckets)
-> UseCaseModel (support.uc.json)
.dmn decision file -> resolve & validate (.mox types, markdown tables)
-> DmnModel (kiwisaver.dmn.json) --dsntk--> decision tables
.deploy deployment file -> resolve & validate
-> DeployModel (svc.deploy.json)
.cmmn case file -> resolve & validate
-> CmmnModel (support.cmmn.json)
.ifml flow file -> parse
-> IfmlModel (.ifml.json)
|
cmmn backend (phero-backend-cmmn)
v
cmmn-rs CaseDefinition JSON -- the
cmmn-rs engine executes cases
Front-end, Core IR, wire format, Rust backend, canonical JSON instances,
JSON Schema (wire/api), the Tier-2 expression language, hermetic
vocabularies, the .actor authorization dimension with Cedar policy
generation, the .ddd Sculptor-style design layer over imported domains
(with entity state machines lowered to xstate-ir), the .evt
event-contract surface, the .dmn decision-model surface (the
decision-requirements graph over imported domain types, with external
markdown decision tables validated through the dsntk toolchain and .ddd
service operations declaring the decision services they invoke), the
.deploy deployment-projection surface, the
.uc use-case-pattern surface, the .cmmn case-management surface with
its cmmn-rs lowering backend, the .ifml interaction-flow surface, and
structural import schema / import sigil (Rune DSL) imports —
implemented and CI-enforced. C#/Java backends and filter/query predicates
are future work.
pherolang check model.mox # validate, render diagnostics
pherolang check model/ # batch: every supported surface under a directory
pherolang fmt model/ # format every supported surface under a directory
pherolang fmt --check model/ # gate: exit 1 naming any unformatted file (formatter-golden X.fmt.<ext> outputs are skipped, like check's)
pherolang highlight model.mox --format json # compiler-backed highlight spans (`--format html`; `--surface` for stdin)
pherolang ir model.mox -o model.phero.json
pherolang graph build examples/ -o graph.json # one semantic graph across every surface (`graph` needs a verb: build|query)
pherolang graph query graph.json node Support.RaiseRefund # artifact-only: node/list/affected-by/dependencies + cross-policy analytics
pherolang artifact check model.phero.json # validate any serialized artifact
pherolang gen rust model.mox -o src-gen/
pherolang gen json-schema model.mox --profile wire -o schemas/
pherolang gen cedar model.mox -o policies/ # from inline actors blocks
pherolang gen cedar policy.actor -o policies/ # from a standalone actor file
pherolang ir usecase.uc -o usecase.uc.json # every artifact surface: .ddd/.evt/.dmn/.deploy/.uc/.cmmn
pherolang artifact check usecase.uc.json # lint any serialized artifact, no toolchain needed
pherolang vocab fetch model.mox --provider file:vocab-sources/
pherolang explain E0104 # explain any diagnostic code (--list: the allocation ledger)
pherolang completions bash # shell completion script (zsh, fish, powershell, elvish too)
pherolang man # the man page (roff, to stdout or --out FILE)
pherolang lsp # start the language server (stdio)
There are two supported integration styles; both are consumed in anger by sibling projects today.
Style A — artifacts through the CLI (language-agnostic). Each surface
compiles to a versioned JSON artifact with a stable wire contract (camelCase
keys, a formatVersion gate, additive-only evolution):
pherolang ir model.mox -o model.phero.json (Core IR), policy.actor →
ActorModel, design.ddd → DddModel, flow.ifml → IfmlModel,
contract.evt → EventModel, usecase.uc → UseCaseModel,
svc.deploy → DeployModel, case.cmmn → CmmnModel — and
phero-backend-cmmn lowers a CmmnModel plus its domain model to the
cmmn-rs engine's
CaseDefinition JSON: Phero Lang authors and validates the case, cmmn-rs
executes it.
pherolang artifact check <files> validates any serialized artifact without
the toolchain. Treat the artifact as the interface and any Rust version
becomes an implementation detail.
Style B — library crates pinned by git rev (in-process). Depend on the crates the way sigil embedders do — a git dependency pinned to a revision:
[dependencies]
phero-ir = { git = "https://github.com/yestechgroup/pherolang.git", rev = "<rev>" }
phero-driver = { git = "https://github.com/yestechgroup/pherolang.git", rev = "<rev>" }
phero-expr = { git = "https://github.com/yestechgroup/pherolang.git", rev = "<rev>" }
phero-ifml = { git = "https://github.com/yestechgroup/pherolang.git", rev = "<rev>" }The crates are the compatibility boundary:
| Crate | Role for a consumer |
|---|---|
phero-ir |
The artifacts (Model, ActorModel, ddd::DddModel, ifml::IfmlModel, events::EventModel, deploy::DeployModel, usecases::UseCaseModel, cmmn::CmmnModel) with from_json/to_json and their version gates — the type-level boundary |
phero-driver |
Compilation: one call per surface, rich byte-span diagnostics, ariadne render |
phero-expr |
The neutral expression language (parser, type checker) behind when conditions and expr bodies |
phero-ifml |
The .ifml parser (parse_ifml/parse_ifml_file → IfmlModel) |
Everything else (phero-syntax, the backends, phero-vocab, phero-lsp,
phero-runtime) is implementation detail for the compiler itself.
Entry points per surface — the driver is filesystem-free: sources and any import content arrive as text:
// .mox (multi-package): import content provided by the host
let compilation = phero_driver::compile_files(
&sources, // (path, source) pairs
&imports, // DomainImports: schema JSON + sigil rosetta
);
// .actor — policy artifact + union domain model; imports bundle for the domains
let actor = phero_driver::compile_actors_str("policy.actor", &source, &domains, &imports);
// .ddd — design artifact; the _with_actors variant also validates capabilities
let design = phero_driver::compile_ddd_str_with_actors("design.ddd", &source, &domains, &imports, &actors);
// .evt — event-contract artifact over the imported domains
let events = phero_driver::compile_evt_str("orders.evt", &source, &domains, &imports);
// .deploy — deployment projections over compiled designs + flows
let deploy = phero_driver::compile_deploy_str("svc.deploy", &source, &designs, &flows);
// .uc — use case patterns over all four buckets (domains, designs, actors, events)
let uc = phero_driver::compile_usecase_str("support.uc", &source, &domains, &imports, &designs, &actors, &events);
// .cmmn — case management over the same four buckets
let cmmn = phero_driver::compile_cmmn_str("support.cmmn", &source, &domains, &imports, &designs, &actors, &events);
// .ifml — parses directly, no domain needed
let ifml = phero_ifml::parse_ifml(&source)?;Compilation/ActorCompilation/DddCompilation/EventCompilation/
DeployCompilation/UseCaseCompilation/CmmnCompilation carry every
file's
diagnostics tagged with its path (sigil content errors are tagged with the
rosetta path); phero_driver::render(path, source, &diagnostics) produces
ariadne output, and every diagnostic span is a byte offset into its file.
Hosts read import schema JSON, import sigil rosetta, and imported
domains from disk themselves — relative to the declaring file — and thread
them through one DomainImports bundle on every compile entry point (the
empty DomainImports::default() is the no-import compilation).
Normative contracts: the language in docs/LANGUAGE.md, the design layer in docs/DDD.md, event contracts in docs/EVENTS.md, deployment models in docs/DEPLOY.md, use case patterns in docs/USECASES.md, case management in docs/CMMN.md, interaction flows in docs/IFML.md, expression rules in docs/EXPRESSIONS.md, and the out-of-tree backend contract in docs/BACKENDS.md — the full index is docs/README.md. The canonical examples (examples/README.md) compile one domain — the support desk — through every surface, CI-enforced.
Authorization is a separate dimension from the domain model: actors,
capabilities, grants, obligations, and prohibitions never appear in the
domain IR or its JSON Schemas. They live in .actor files that import the
domain so everything stays type safe:
import "examples/support/support.mox"
actors Support {
actor Customer
actor Agent extends Customer
actor Finance
capability RaiseRefund on Ticket
capability ApproveRefund on Ticket
obligation audit
grant Agent {
permit RaiseRefund when (refundCents > 0 && refundCents <= 5000)
obligation audit
}
grant Finance {
permit ApproveRefund when (refundCents <= 100000)
}
never_both { RaiseRefund, ApproveRefund }
}
(This policy compiles — it is the shape of examples/support/support.actor, and
the fenced blocks in these docs are compiled by CI.)
- `when` conditions are **fully type-checked** against the imported classes
(a typo'd feature is a compile error, not a silent Cedar mismatch).
- Policy checks run over the **union** of an `.actor` file's blocks and any
inline `actors` blocks in the imported domain models: separation of duty
(`never_both`), inheritance cycles, and self-narrowing are caught across
files.
- `pherolang gen cedar` emits a Cedar policy set plus a Cedar entity schema;
generated policies are validated against the real `cedar-policy` crate in
CI (strict mode). Obligations become Cedar annotations; `never_both`
groups become review evidence comments.
- Inline `actors` blocks in `.mox` files remain legal for small policies;
both surfaces feed the same `ActorModel` artifact.
## Language server
`pherolang lsp` speaks LSP 3.x over stdio (tower-lsp). Any LSP client works;
capabilities:
- **Diagnostics** — full-document compile on open/change, incremental
(salsa); the flagship diagnostic carries a machine-readable code with
structured data
- **Quick fix** — on `feature 'x' has class type 'C'`: two actions inserting
`contains` or `refers` before the type
- **Go to definition** — type references, `extends`, and **opposite
mentions** (jumping from `opposite library` to `Book.library`, as in
Xcore's F3)
- **Hover** — feature/class/enum/datatype/vocabulary summaries rendered from
the AST
- **Document symbols**, **completion** (keywords, types in scope), and
**rename** (bidirectionally consistent: renaming a feature rewrites the
opposite mentions on the other side)
Example client config (VS Code `settings.json`):
```json
{
"mox.server.path": "/path/to/pherolang",
"mox.server.args": ["lsp"],
"mox.server.languages": ["mox"]
}
Well-known external vocabularies are declared in the model, vendored once, pinned by digest, and materialized identically by every backend:
vocabulary Currency from "iso:4217" {
version "2024-01-01"
key alpha3
facet String symbol
facet int minorUnits
}
pherolang vocab fetchis the ONLY command that fetches: it writesvocab/<source>@<version>.jsonand pinssha256digests inmodel.lock.- Compilation is hermetic: it reads only the vendored snapshot and verifies the lockfile digest; a missing or tampered snapshot is a diagnostic, never a network call.
- Backends materialize the vocabulary as a closed enum over its keys with
facet accessors (Rust), an
enumof keys (JSON Schema), and key strings in canonical instance JSON ("currency": "USD").
Model instances exchange through a cross-language JSON contract:
{
"$type": "phero.instance",
"formatVersion": 2,
"model": "nz.example.library",
"objects": [
{
"$type": "Library",
"$id": "library/0",
"name": "Default Name",
"books": [
{
"$type": "Book",
"$id": "book/0",
"title": "Dune",
"authors": [ { "$ref": "writer/0" } ]
}
]
},
{ "$type": "Writer", "$id": "writer/0", "name": "Frank", "books": [ { "$ref": "book/0" } ] }
]
}- Contained objects serialize inline under their containment feature; container back-references are omitted (derived from nesting, reconstructed on load — serializing them would recurse forever).
- Cross references are links:
{"$ref": "<id>"}. - Object ids are
<singular>/<n>in per-class insertion order. - Enums serialize the declared literal name; datatypes their inner string; optional attributes are omitted when unset; derived features are never serialized.
- Loading is strict: unknown features, serialized containers, duplicate ids, and unresolved refs are errors.
tests/conformance/ holds the flagship model plus its golden artifacts (Core
IR JSON and canonical instance JSON). Every backend must round-trip them.
Regenerate goldens with PHERO_UPDATE_FIXTURES=1 cargo test --workspace.
When running tests locally, prefer the wrappers: scripts/dev-test.sh [args]
runs cargo test with the CI env (debuginfo=0, no incremental compilation,
TMPDIR=target/tmp, --jobs 2), and scripts/ci-local.sh runs the full gate
sequence. A bare cargo test --workspace leaves the default debuginfo=2 on,
and cargo never collects old hashes under target/debug/build/<pkg>/<hash>/out/
— repeated builds can fill the disk, which surfaces as
ld terminated with signal 7 [Bus error] during doctest linking. Reclaim with
rm -rf target/debug/build/phero-* (workspace crates only); the full rationale
is the AGENTS.md operational bullet (issue #261).