Decisions

Decisions

One page per decision, in ADR (architecture decision record) format. A record captures a choice, the options that were considered and why one won, so that a later reader does not have to reconstruct them.

  • Start from the template.
  • Name files NNNN-short-title.md. See Contributing to these docs.
  • Records are never deleted. A reversed decision gets a new record, and the old one is marked Superseded by NNNN.

The records

Every architecture decision for Mesh has one record here, an ADR (architecture decision
record), in the format of the engineering:architecture skill: status, date, deciders,
context, decision, options considered, trade-off analysis, consequences, action items
(ADR-0032).

How to read the status:

  • Accepted: decided. The record quotes the ruling and says who made it. Deciders are named by role: the
    operator is the project owner (Saulo Vallory); the lead is the team lead who
    coordinates the work, and the operator may overrule the lead; the roadmap author wrote
    the roadmap and proposed parts of the design, and the lead or the operator may overrule.
  • Proposed: open. The record gives the options and a recommendation, and says who must
    rule and what the decision blocks.
  • Superseded: reversed by a later record. Kept so that nobody proposes it again without
    knowing it was tried and why it was dropped.

The roadmap (roadmap) says in which milestone each decision
is built; its section 8 maps every ruling to its ADR and milestone. The rulings themselves are
recorded in rulings of 2026-10-04.

Foundations

ADR Decision Status Deciders
0001 Three rings: core, adapters, extensions Accepted operator
0002 Resource files are .mx, read through MX as a static data tree Accepted operator
0043 MX is core, not an adapter; no front-end adapter slot Accepted operator
0003 Generated code carries the behaviour; the run-time library stays thin Accepted operator
0004 Mesh is built regardless; measuring the agent benefit is not a gate Accepted operator
0005 The core’s interface is a function call; transports are optional adapters, none in v1 Accepted operator
0006 The first transport is a CLI Superseded by 005 lead
0007 The scope { actor, context } is a plain argument on every action call Accepted lead
0008 Transports obtain the scope through an actor-resolver adapter Superseded by 007 lead
0009 Where tenancy lives: core or extension Proposed operator
0019 v1 is milestones M0 to M9; what comes after Accepted operator
0033 Core packages are split by when the code runs Accepted roadmap author

Data and expressions

ADR Decision Status Deciders
0010 One expression tree, evaluated in memory and in SQL Accepted operator; roadmap author for how the forms are produced
0011 Translatable expressions run only as SQL Superseded by 010 roadmap author (never accepted)
0012 Expression semantics where SQL and JavaScript differ Proposed operator or lead
0013 Data-layer contract: a mandatory set plus declared capabilities Accepted operator
0014 SQL adapters are built on Drizzle and drizzle-kit Accepted operator’s position, lead’s choice of tool
0015 Mesh prints SQL and diffs schemas itself Superseded by 014 roadmap author (recommendation)
0016 In-memory data for tests is SQLite’s in-memory mode Accepted roadmap author
0017 Updates are atomic by default; changes and validations are classified Accepted operator, lead, roadmap author
0018 A valid but unimplemented tag is a build error Accepted roadmap author
0044 Folding record-reading validations into the atomic statement (after v1) Proposed lead and operator
0045 How has-one is kept to one row Proposed operator

Extensions, policies, workflows, vocabulary

ADR Decision Status Deciders
0020 Extensions contribute to each other only through declared points Accepted operator
0021 Mesh generates one self-contained MX contracts module Accepted lead
0022 Policies: a simple tier, solver-ready, as a first-party extension Accepted operator
0036 Deny by default arrives with the policies extension Accepted lead
0046 What a denied write reports on an atomic action Proposed operator
0023 Workflows and jobs come after v1; the adapter interface stays a design document Accepted operator
0024 The in-process workflow runner is the first adapter Superseded by 023 operator
0034 The resource vocabulary copies Ash’s DSL for v1; optimised for MX after v1 Accepted operator; lead for the spelling
0041 Resource files and examples always use MX concise syntax Accepted operator
0035 What public on an attribute means Proposed operator
0037 Which artefact is the source of truth for the vocabulary Proposed operator or lead

Platform, tooling, process

ADR Decision Status Deciders
0025 Mesh runs on Bun only Accepted operator
0026 Mesh runs on Bun and Node Superseded by 025 operator
0027 No MCP server; the agent surface is a rules file, later a generated CLI Accepted operator
0028 Input validation is Zod behind Standard Schema Accepted lead
0029 Tracing calls the OpenTelemetry API directly Accepted lead
0030 Established tools first, behind Mesh contracts Accepted operator
0031 No CI until the MX packages are published Accepted operator
0032 Docs site in the repo; decisions as ADRs; the repo is the source of truth Accepted operator
0038 Elysia is not core; a candidate HTTP adapter Accepted operator
0039 Run-time errors: embedded positions or source maps Proposed operator or lead
0040 Package scope and command name Proposed operator
0042 Mesh is open source under MIT; the docs are public Accepted operator

Open decisions at a glance

Nine records are Proposed. One blocks v1 work outright: ADR-0012 (expression semantics, before
M4). ADR-0037 (before M1), ADR-0039 (before M5), ADR-0045 (before M7) and ADR-0046 (before M8) have
a working assumption in the roadmap. ADR-0044 is for after v1. ADR-0009, ADR-0035 and ADR-0040 block nothing in v1.

The dated log the records quote: rulings of 2026-10-04.

Previous Plan revision 2 (superseded) Next Template