Vocabulary mapping: Ash DSL to Mesh

Vocabulary mapping: Ash DSL to Mesh

Date: 2026-10-04. Status: the mapping covers everything the roadmap touches. The alignment of the contracts (the first part of milestone M1, roadmap, “Vocabulary alignment first”) is done for every row that is on main: rows marked “on main (aligned)” in Section 3 and rows marked “Done” in Section 4 are applied in packages/compiler/src/contracts.ts, with tests. The rows for later milestones are not applied. Two rows are held for the operator (X1, X2, Section 5), and the research lookups are checked and recorded in Section 6.

0. The naming rule

Mesh names are Ash’s names in kebab-case with the trailing ? dropped. belongs_to becomes belongs-to, uuid_primary_key becomes uuid-primary-key, allow_nil? becomes allow-nil, require_atomic? becomes require-atomic. The mapping is mechanical and one-to-one: _ becomes -, a trailing ? is dropped, nothing else changes. A trailing ? is disallowed by ruling, not by MX. The MX maintainers first measured on MX main at 7a404916 that an attribute name takes letters, digits and ._:- and never ? (recorded in rulings of 2026-10-04, section “Lead decisions of the architecture-docs brief”), and later confirmed that the data target could allow it in attribute names; MX still allows it in tag names, as Marko does, and MX decision 144 reserves ?= as a future attribute operator and bans a trailing ? in attribute names on every target. The operator ruled on 2026-10-04 (table “Rulings after the decision review”, row “Trailing ? in attribute names”) that Mesh does not use it, in attribute names or in tag names. Reasons: in TypeScript name? means optional, so allow-nil? reads wrong; it would permanently block a future name?=expr syntax; it diverges from Marko’s translator; and a bare boolean attribute already carries the predicate meaning (public, allow-nil=false). The spelling is unchanged: Ash names in kebab-case with ? dropped. Mesh declares no tag and no attribute whose name ends in ? or contains _; a test asserts it (contracts.test.ts, “no tag name and no attribute name ends in ? or contains _”). _ would be accepted by MX in tag and attribute names; Mesh does not use it. Scope of the rule. It applies to tag names and attribute names only: the vocabulary. Three things are not vocabulary and the rule does not touch them. (1) Attribute values are strings the author writes: insertedAt in create-timestamp="insertedAt" is a value. (2) The names a resource author chooses for attributes, relationships and actions (the fixture’s authorId, commentCount) are values too; they stay as the author writes them. (3) Everything inside an expression is JavaScript, parsed by Babel, and must be valid JavaScript: a call name keeps Ash’s snake_case as an identifier (action_type("read"), before_action(...), set_attribute(...)), because action-type("read") would parse as a subtraction. Ash’s ^actor, ^arg, ^context, ^ref and ^tenant templates have no valid JavaScript spelling; Section 3.9 maps them to the declared parameters of the arrow function.

Decision record. 2026-10-04, recorded in rulings of 2026-10-04, section “Lead decisions of the architecture-docs brief”; a working decision (not an operator ruling); the operator may overrule. Alternative considered: Ash’s exact spelling with _ where MX allows it (belongs_to) and a different spelling only for booleans, which would have renamed every tag on main and left two conventions. Kebab-case matches what is on main, avoids renaming twice, and the operator revisits naming for MX after v1 (ADR-0034). Consequence: names that differ from Ash only by this rule are not deviations and are not listed in Section 4.

1. Introduction

The vocabulary of Mesh is the set of tag and attribute names a resource file may use. A resource file is a .mx file: Marko syntax, parsed by MX, a separate project. Mesh invents tag names, not syntax. For each tag name there is one MX tag contract (CustomTag) that says which attributes, children and parents the tag allows, plus analyze hooks for rules a declaration cannot express. MX is core in Mesh, not an adapter (ADR-0043), so the 26 contracts live in the compiler package, packages/compiler/src/contracts.ts, with tests in packages/compiler/test/. (M0 moved them there. The alignment kept the count at 26: defaults and timestamps left, create-timestamp and update-timestamp arrived. The contracts.ts:N line numbers on this page are those of the file before the alignment, at a3b52f4; rows marked aligned describe the new form in the Mesh name column and the old one in the “On main today” column.) They are the only vocabulary code so far. PR #1 (https://github.com/svallory/mesh/pull/1) added them; PR #2 (https://github.com/svallory/mesh/pull/2) adopted MX’s unknownTags option; PR #4 (https://github.com/svallory/mesh/pull/4) changed one test.

Where the 26 came from. The names were copied from an MX test fixture (packages/targets/data/fixtures/ash-resource/post.mx in the MX repository; MX project notes, getting-started section 1). The Mesh copy is packages/compiler/test/fixtures/post.mx; it has 31 tag occurrences and 25 distinct names. The 26th contract, destroy, was added in round 2 of the review of PR #1. Several rules were inferred by the developer in PR #1 or required in four rounds of review of PR #1. The operator never ruled on them.

The ruling. On 2026-10-04 the operator ruled (rulings of 2026-10-04, table “Rulings after the decision review”, row “Vocabulary”):

Copy Ash’s DSL for now (names and structure). After v1, review it and optimise for what feels natural in MX. Resource files and every example always use MX concise syntax.

It is recorded in ADR-0034 (copy Ash now, optimise after v1) and, for the third sentence, ADR-0041. The consequence stated in ADR-0034: where the contracts or the roadmap deviate from Ash in names, defaults or inferred rules, they are aligned with Ash unless MX cannot express it. Only those exceptions go to the operator. A second reason is used on this page for the exceptions that remain: the deviation conflicts with a decision record (the record is named). After v1 the vocabulary is reviewed for what reads naturally in MX; that is a breaking rename for every resource file, planned separately (ADR-0034, Consequences).

What “copy Ash’s DSL” means here. Ash is the Elixir resource framework Mesh is modelled on. Its DSL is organised in sections (attributes, actions, …), each holding entities (attribute, create, …) that take options. Section 3 maps every Ash section, entity and option that Mesh v1 touches to a Mesh tag or attribute, with its status. Section 4 lists each place where contracts.ts or the roadmap differs from Ash and the alignment that follows. Section 5 holds the two deviations that go to the operator. Section 6 holds the points where Ash’s form is not in the research, so the alignment cannot be written yet. Section 7 shows the fixture after alignment. Appendix A is the vocabulary on main, as it is.

Sources used on this page: Ash features (cited by section), Ash DSL and extensions, research synthesis, roadmap, rulings of 2026-10-04, MX project notes, getting-started, MX project notes, contract-extensions, MX project notes, updates, and the contracts file contracts.ts:N (line N of packages/compiler/src/contracts.ts). Where a detail (a default, an option name) is not in the research, the page says “not in the research” and does not fill it from memory.

2. How to read the mapping

Positional arguments. Ash writes attribute :subject, :string: name and type are positional (Ash features section 12 examples). An MX tag has one default attribute (written attribute="subject", and arriving in the tree as an attribute named value) plus named attributes (MX project notes, getting-started section 1). The rule used here: the first positional becomes the default attribute; a later positional becomes a named attribute carrying the name Ash gives it (type for attribute and argument, keys for identity name, keys, destination for a relationship, relationship_path for an aggregate), and otherwise the name Mesh has now, marked “inferred”. The positional names were checked against Ash’s documentation (Ash 3.34.0, checked 2026-10-04, G9 in Section 6, https://hexdocs.pm/ash/dsl-ash-resource.html): attribute name, type; belongs_to name, destination; has_many name, destination; has_one name, destination; create name (also read, update, destroy); calculate name, type, calculation (the third is optional); count name, relationship_path (the other aggregates add field; custom adds type); identity name, keys; argument name, type; policy condition (optional); validate validation; change change; prepare preparation. The two names that were inferred before the check, relationship_path and the relationship’s destination, are Ash’s own: the relationship’s destination is destination= on belongs-to and has-many. policy and calculate are the two on-main tags whose positional Mesh does not name as Ash does (the policy’s condition arrives as the default attribute value; calculate’s third positional is the child tag value); see D22, D27 and G2, G8.

Concise syntax. Every example is concise syntax, as in the fixture: indentation nests, no angle brackets (ADR-0041).

Names. The rule of Section 0. Ash atoms (:read) become strings ("read"). A bare boolean attribute means true (public); allow-nil=false is the explicit form (contracts.ts:116-122 reads a BooleanLiteral).

Status values. On main (with line); M3, M5, M7, M8 (the milestone the roadmap adds it in); M4 (the expression milestone); M6 (extension host); after v1 (roadmap section 6 or a ruling); not planned (roadmap section 6, “Not planned at all”); out of M8 (named as out of scope of that milestone); not in roadmap (neither scheduled nor excluded).

3. The mapping

The “Contract check” column is machine-readable and is what the acceptance test reads (contracts.test.ts, describe “roadmap M1 acceptance test 7”). Every row whose status says “on main” carries one or more specs separated by ;, or an explicit n/a (reason) when the row is not about a tag or attribute (today only row 110, recorded deviation D37: an expression’s contents are not vocabulary); any other row carries -. The test pins the list of n/a rows, so a row cannot leave the check by being relabelled. A spec is tag: tokens: a plain token is an attribute the contract declares and a clean fixture uses; >name is a child tag the contract declares and a clean fixture nests in that tag; attr=v1,v2 is an attribute that a clean fixture sets to each of those values. A row marked “on main” whose cell does not parse fails the test, and so does a tag, attribute, child or value no clean fixture uses.

The “On main today” column and its line numbers describe the contracts before the alignment (a3b52f4). “On main (aligned)” means the Mesh name column is now what the contracts declare, with a positive and a negative test.

3.1 Resource level

3.2 Attributes

3.3 Relationships

3.4 Actions

3.5 Identities

3.6 Calculations

3.7 Aggregates

3.8 Policies (Ash.Policy.Authorizer, a separate extension)

3.9 Expressions, and the references inside them

Ash writes a translatable expression as expr(...) and refers to the caller and the call with templates (Ash features section 5.5). Inside a resource file an expression is JavaScript, parsed by Babel (MX project notes, getting-started section 1), so it must be valid JavaScript and the naming rule of Section 0 does not apply to it. Mesh’s roadmap starts from an arrow function’s parsed form (roadmap M4): a translatable expression may use only its declared parameters and registered functions, and a free variable is a build error. The registry of functions and operators is Mesh’s own and starts small (roadmap M4: attribute and parameter references, literals, comparison and boolean operators, string length, assignment to an attribute). The exact expression form is designed in M4; this table records what Ash has and which Mesh element corresponds.

That is 110 rows.

4. Deviations

“Now” is what contracts.ts or the roadmap has today. “Alignment” is the change the ruling implies. Exceptions go to Section 5; open research to Section 6.

4.1 Names and structure

4.2 Rules the developer inferred or review required

Each row is a rule in contracts.ts that is not a name. “Ash” is what the research says; many rules are not in the research at all. “Origin” cites PR #1 (https://github.com/svallory/mesh/pull/1), whose description records the developer’s list “Inferred by me” and rounds 1 to 4 of its review; it does not record who proposed each review finding.

4.3 Roadmap text that changes with the alignment

These are edits to roadmap, listed so none is forgotten. The first item was made in the alignment pull request; the others are not made here.

• Done in the alignment pull request: the roadmap’s section 1 item 6 and M1’s “Vocabulary alignment first” bullet now say the alignment is done, and the M1 model bullet quotes the aligned names (seven types, allow-nil, constraints, create-timestamp, update-timestamp, the defaults attribute). The “M1, model” item below is kept as the record of what changed.
• M1, alignment. The alignment is the first part of M1; its acceptance test (“every row marked ‘on main’ has a contract and a fixture that match it”) is checked against Section 3 with the naming rule of Section 0.
• M1, model. Replace “attributes of the six types” with the aligned type list (D8, D9); required becomes allow-nil (D6); timestamps becomes create-timestamp and update-timestamp (D5); “the four action kinds with accept and defaults” becomes defaults as an attribute of actions (D13) with accept on destroy as well (D14); add the primary-key verifier (D31); the not-implemented list uses the aligned names; names an author chooses stay as written (D33); the registry/contract drift test (ADR-0037) covers the new type list.
• M3. “New vocabulary” for pagination becomes the pagination child (D18); sort waits on G1.
• M4. The expression form is designed here: arrow functions with declared parameters stay (D37), built-in calls take Ash’s snake_case names as JavaScript identifiers (D16), the first registry takes Ash’s names (D38); validate in create and read adds positions to classify (D15).
• M5. Hooks are change=before_action(...) and the other three, as JavaScript calls (D35), with read-side hooks as prepare (rows 71-72); prepare and argument named (D19, D20); before_transaction is not scheduled; validation options (D36) if the protocol needs them. require-atomic is already aligned.
• M7. has-one (D11); the generated foreign-key name is settled (D12); aggregate kinds (D29) and relationship-path (D28); the unique-index rule stays (D32).
• M8. forbid-if (D25); policy conditions are check calls (D22, D23); the rule “at least one check of any kind” (D24); if the operator rules against X2, roadmap section 3 (“on by default”) and ADR-0036 change.
• Risk 9 (“New vocabulary arrives in M3, M5, M7 and M8”): the answer to “one way to do each thing” is now: copy Ash.

5. Exceptions for the operator

Two deviations remain after applying the test of the ruling to each. A deviation is an exception only if MX cannot express the Ash form, or if it conflicts with a decision record.

Exceptions removed by the test: names with _ and ? (answered by the MX maintainers and decided in Section 0); enumerated types (D9), hooks (D35) and policy conditions (D22), which MX can express; camelCase (D33), which is not a conflict with any ruling; has_one uniqueness (D32), a recorded deviation in ADR-0045 rather than a vocabulary exception.

6. Ash’s form: the lookups, checked

These were gaps in the research. Each was looked up in Ash’s documentation and source and the answer was then fact-checked. All facts below are Ash 3.34.0, checked 2026-10-04; the documentation is https://hexdocs.pm/ash/ (dsl-ash-resource.html, dsl-ash-policy-authorizer.html, Ash.Query.html, Ash.Changeset.html) and the source is https://github.com/ash-project/ash (main). Only checked facts are recorded; an unchecked sub-claim stays listed as open. “Applied” says whether the fact changed the contracts; vocabulary of a later milestone is recorded and the code is left alone.

The fact-check said the first lookups’ quoted sentences for G1, G2, G3, G5, G6, G7 and G8 were not literal text of Ash’s documentation; none of those sentences is used here.

7. The fixture after alignment

This is post.mx as it is on main after the alignment: packages/compiler/test/fixtures/post.mx, and the identical examples/blog/post.mx. It carries every alignment of Section 4 that is on main and the naming rule of Section 0 (tag names and attribute names only). Expressions keep arrow functions with declared parameters until M4 is designed (D16, D37); the author-chosen names (authorId, insertedAt, commentCount) are values and stay as in the file before the alignment (D33). Concise syntax.

resource="post" table="posts" domain="blog"
  attributes
    uuid-primary-key="id"
    attribute="title" type="string" allow-nil=false public
    attribute="body" type="string" public
    attribute="state" type="atom" constraints={ one_of: ["draft", "published"] } default="draft"
    create-timestamp="insertedAt"
    update-timestamp="updatedAt"

  relationships
    belongs-to="author" destination="user"
    has-many="comments" destination="comment"

  actions defaults=["read", "destroy"]

    create="create" accept=["title", "body"]
      change=({ post, actor }) => { post.authorId = actor.id }

    update="publish"
      change=({ post }) => { post.state = "published" }
      validate=({ post }) => post.title.length > 0 message="title required"

    read="published"
      filter=({ post }) => post.state === "published"
      sort=["-insertedAt"]

  policies
    policy=action_type("read")
      authorize-if=({ post }) => post.state === "published"
      authorize-if=({ post, actor }) => post.authorId === actor.id

    policy=action("publish")
      authorize-if=({ post, actor }) => post.authorId === actor.id

  calculations
    calculate="excerpt" type="string"
      value({ post }) {
        return post.body.slice(0, 200)
      }

  aggregates
    count="commentCount" relationship-path="comments"

One difference from the proposal this section first held. The proposal put require-atomic=false on publish (D21). require-atomic is vocabulary for M5, not on main, so the fixture keeps the pre-alignment form of publish (no such attribute); the contracts reject the attribute until M5 adds it. action_type("read") and action("publish") are Ash’s check calls action_type(:read) and action(:publish). They sit inside an expression, so they are JavaScript identifiers and keep Ash’s snake_case (Section 0). Differences from the file before the alignment (Appendix A): allow-nil, create-timestamp and update-timestamp; type="atom" with constraints; defaults as an attribute of actions; the policy condition as a check call; relationship-path; destination on the two relationship tags.

---

Appendix A. The vocabulary on main, after the alignment

Everything here is read from contracts.ts as it is now (26 tags). Line numbers are not given: the file is the authority, and the tests in packages/compiler/test/contracts.test.ts pin each row. Helpers: str() is a string attribute with literalOnly; strings() is an array of strings, literalOnly; flag() is a boolean, literalOnly; code() is a function attribute, required; name() is the default attribute value, a required literal string. literalOnly means the authored value must be a literal, not an identifier (header comment of the file). It accepts an object or array literal, which is what constraints={ one_of: [...] } relies on. The exceptions to literalOnly are the function attributes and the policy condition, which is a call. closed() makes every contract list its attributes, attributeTags and children explicitly; an empty record means none. Child cardinality: {} is optional and at most once; { repeatable: true } any number; { required: true } exactly once; both flags at least once. Analyze helpers: nonEmpty(...) rejects an empty or whitespace string; nonEmptyList rejects []; listItems/checkItems reject blank or repeated items.

Rules that are not in any tag: exactly one resource per file, and “an empty file” are not in the contracts; MX has no root cardinality, so Mesh’s model stage enforces them (header comment of the file; PR #1 review round 3, item 2, with two tests that pin MX accepting both).

The fixture

The fixture is Section 7: packages/compiler/test/fixtures/post.mx, identical to examples/blog/post.mx. It parses with zero diagnostics. Its first version was a copy of MX’s own fixture; the alignment replaced that form (required, type="enum" values=[...], timestamps, defaults as a child, policy action-type="read", relationship="comments", resource="user" and resource="comment" on the relationship tags).

How the expressions in this file are treated: every expression is converted to one expression tree when it can be (translatable) and is otherwise kept as TypeScript (opaque). filter must be translatable. change, validate and calculations are classified, and the class is recorded in the model; the file’s publish change and validation are both translatable (roadmap M4 and M5; ADR-0010, ADR-0017).

Appendix B. What this page did not verify

• Checked by the alignment (no longer open): an untyped contract attribute keeps literalOnly for an object literal (D9). An identifier is rejected (literal-only-constraints) and an object literal is accepted (every fixture with constraints).
• The two values @mesh/model records where this page was silent are now checked (Section 6, row “model”): uuid-primary-key is allow-nil false and public true; create-timestamp and update-timestamp are allow-nil false and public false. They match what the model records.
• The two sub-claims Section 6 keeps open: how Mesh spells the validation and check builtins (G3), and the {MyModule, :my_func, []} example of G5.
• Where adapters and extensions are enabled for a project in the Ash sense (rows 3 and 5): the roadmap places it in the project configuration, M1 and M6.
• Who proposed each finding in rounds 1 to 4 of the review of PR #1: the PR records what changed, not the author of each finding.