Skip to content
yestechgroupPublic

About

Phero Lang — Verifiable Model-Driven Engineering

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Phero Lang

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

Status

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.

Usage

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)

Consuming Phero Lang from other projects

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.

Actor policies (.actor)

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"]
}

Vocabularies

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 fetch is the ONLY command that fetches: it writes vocab/<source>@<version>.json and pins sha256 digests in model.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 enum of keys (JSON Schema), and key strings in canonical instance JSON ("currency": "USD").

The canonical instance format

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.

Conformance

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).

About

Phero Lang — Verifiable Model-Driven Engineering

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages