Learn | Matterforma

1. What `.matr` Is

.matr is the authoring language for Matter/Forma. You use it to describe a material program: a bounded system with inputs, state, transitions, constraints, and observable outputs. .matr is designed for control. It is intentionally not a general-purpose programming language. You won’t find:

unbounded recursion
implicit concurrency
dynamic memory growth
side-effect driven scripting You will find:
explicit boundaries
explicit constraints
explicit transitions
explicit outputs
profiles that make assumptions visible If you can’t say what your program’s valid input range is, .matr will force you to. If you can’t say how a system should end, .matr will force you to. This is what makes compilation and verification possible.

2. The Mental Model

A .matr program answers the same five questions introduced earlier:

What goes in?
What state is tracked?
How can state change?
What rules must hold?
What comes out? That’s it. Everything in .matr maps to one of those questions.

Inputs answer “what goes in.”
State answers “what is tracked.”
Transitions answer “how it changes.”
Constraints answer “what must hold.”
Outputs answer “what comes out.” Forma compiles this into an artifact (a Molebyte) and verifies it under a profile.

3. The Core Building Blocks

A .matr file is organized into a few blocks. You don’t need to memorize these. You just need to understand what each block is responsible for.

3.1 Module

A module is a named unit of source. It provides:

an identity (name)
a namespace
a version line It is the top-level boundary for compilation.

3.2 Types

Types exist to prevent ambiguity. In .matr, types are bounded. If you declare a numeric type, you also declare its valid range. Example:

Temperature is not “a number.”
It is “a number between 30 and 45.” Types also help Forma understand what comparisons and diffs are valid.

3.3 Constraints

Constraints are the rules that must always hold. They are not comments. They are evaluated during compilation (where possible) and during runs. Constraints can enforce:

valid ranges
invariant relationships
legal transition paths
acceptable output bounds Constraints are how “intent” becomes something testable.

3.4 Intent

An intent is a program definition. It declares:

inputs
state
transitions
outputs
required constraints Intents compile into artifacts.

3.5 Profiles

A profile is the execution envelope. It defines:

tolerances
iteration limits
allowed variance Profiles are not an afterthought. They are how .matr stays honest about assumptions.

4. Writing `.matr` the Right Way

The easiest way to write .matr is to be explicit early.

4.1 Declare the bounds first

Don’t start with clever logic. Start with the boundaries:

input range
state range
output range If you do that first, everything else becomes easier.

A `.matr` program should read like a contract. If something must be true, declare it as a constraint. Avoid “implied” rules.

5. A Worked Example

Below is a simple .matr example. It describes a bounded stability check:

It accepts a bounded numeric input.
It declares what “safe” means.
It emits a stability signal when safe.

module demo.stability
version 1.0.0
// A bounded numeric type.
type Reading = float range [0.0, 100.0]
// The safe operating window for this program.
constraint safe_window(x: Reading) {
  x >= 40.0
  x <= 60.0
}
intent stabilize(input: Reading) {
  require safe_window(input)
  emit signal STABLE
}
profile simulation.strict

Let’s unpack that in plain terms.

Reading is bounded, so the program cannot accept nonsense like infinity.
safe_window defines the rule that must hold.
stabilize declares an intent that requires the rule and emits an observable signal.
profile simulation.strict declares the envelope the artifact will run under. If the input is outside the safe window, the run does not “sort of pass.” It violates a declared constraint. Forma will record that as a classified failure.

6. Minimal Syntax Patterns (Readable Reference)

This is not the full grammar. It is a practical pattern guide.

6.1 Module + version

module name.here
version 1.0.0

6.2 Bounded numeric types

type Temperature = float range [30.0, 45.0]

6.3 Enumerations

type Mode = enum { INIT, ACTIVE, STABLE }

6.4 Constraints

constraint within_bounds(x: Temperature) {
  x >= 36.5
  x <= 37.5
}

6.5 Intents

intent regulate(input: Temperature) {
  require within_bounds(input)
  emit signal STABLE
}

6.6 Profiles

profile simulation.strict

7. What `.matr` Guarantees

A valid .matr program provides Forma with enough structure to do real verification. When compilation succeeds, Forma can guarantee:

Inputs, state, and outputs are bounded.
Transitions are finite and explicit.
Constraints are declared and evaluable.
Outputs are observable and typed.
The resulting artifact can be identity-addressed. What .matr does not guarantee by itself:
That the behavior is valid in all environments.
That a specific substrate implementation exists for every program. Those properties are profile- and platform-dependent. That’s not weakness. That is honesty.

8. How `.matr` Becomes an Artifact

Forma compiles .matr into a Molebyte. Compilation is a transformation from:

human-readable intent to:
machine-verifiable artifact The artifact contains:
structure
constraints
boundaries
profile references
identity The benefit of this approach is simple: You can test a program without trusting the author. You trust the artifact.

9. When to Go Deeper

If you want:

full grammar
full typing rules
full constraint compilation semantics
Molebyte schema details Those can live in invite-only docs without weakening public credibility. Public Learn needs to make the contract clear. The contract is clear here.

The `.matr` Language