tramaj

Tramaj — Language Reference

2026-10-02T20:43:09Z

Generated from specs/reference.md — the repository is the canonical source, and may be ahead of this page.

Tramaj — Language Reference

This is the reference for the language as implemented. Where the earlier drafts disagree with each other or with this document, this document wins; decisions.md records which reading of those drafts was taken and why, and the drafts themselves are in archive/. node-json.md is normative for the output wire format and is not repeated in full here.

Two implementations are held to this document: tramaj/ (PureScript) and tramaj-hs/ (Haskell). Anything below marked implementation-defined is where they are permitted to differ; everything else they must not.

1. Shape of the language

Tramaj is expression-oriented. There is one expression language, and documents are values: an element or a fragment is an ordinary expression result that can be bound, passed to a lambda, returned from one, or stored in an array.

  surface syntax
        │  parse + desugar
        ▼
    core AST  ──────────────┐
        │  evaluate         │  analyse (no evaluation)
        ▼                   ▼
      Value           imports / action keys / context holes
        │
        └── Node ──► normative JSON ──► host fold (HTML, YAML, HCL, UI, …)

The core AST is deliberately smaller than the surface. Conveniences are lowered into it (§8) rather than given constructors of their own.

2. Core AST

Program
  = DocumentProgram Expr
  | ExpressionProgram Expr

Expr
  = Path         root: String, fields: List<String>
  | FieldAccess  target: Expr, fields: List<String>
  | Call         function: Expr, arguments: List<Expr>
  | Lambda       parameters: List<String>, body: Expr
  | Let          name: String, value: Expr, body: Expr
  | StringLit    String
  | NumberLit    Number
  | BoolLit      Boolean
  | NullLit
  | ArrayLit     elements: List<Expr>
  | ObjectLit    fields: List<(String, Expr)>
  | Element      tag: String, attributes: List<Attribute>,
                 value: Expr, children: List<Expr>
  | Fragment     children: List<Expr>
  | Branch       condition: Expr, then: Expr, else: Expr
  | Map          collection: Expr, function: Expr
  | Filter       collection: Expr, function: Expr
  | Scan         collection: Expr, initial: Expr, function: Expr
  | Fold         collection: Expr, initial: Expr, function: Expr
  | Concat       left: Expr, right: Expr
  | Import       name: String, parameters: List<(String, ParamValue)>
  | AdaptActions target: Expr, adaptation: ActionAdaptation,
                 function: Optional<Expr>

ParamValue
  = PExpr        Expr                 -- any expression, evaluated at the import
  | PFromContext path: List<String>   -- read from the importing program's $ctx

Attribute
  = Attr         name: String, value: Expr
  | ActionAttr   event: String, key: String, payload: Expr

ActionAdaptation
  = Identity
  | Prefix       String

Every static position is a String, not an Expr: an import’s name, an action’s event and key, an adaptation’s prefix, a ctx(...) parameter’s path. That is what makes §9’s analyses possible, and the grammar refuses anything else in those positions — the restriction is enforced at parse time, not checked later at evaluation time.

There is no partial-import constructor, and partiality is not visible in the syntax at all: an import is unsaturated when the library reads a parameter nobody has supplied yet, which is a fact about two programs, not about this one (§7).

3. Values

Value
  = Null | Boolean | Number | String
  | Array   List<Value>
  | Object  Map<String, Value>
  | Node                        -- a document
  | Closure                     -- a lambda, with its captured environment
  | Builtin                     -- a builtin, referenced but not yet called
  | ImportResult                -- {rendered, vals}, once the library has run
  | Import                      -- an import wired up but not yet run

Arrays and objects hold Values, not JSON — so a document can travel inside a structure. That is what makes the JSX-children pattern work without a separate “template value” category.

JSON is required only at the boundaries where a document would be meaningless: an attribute value, an action payload, an element’s value slot, and an expression program’s result. A closure, a builtin, an import result, an import that has not run, or a document reaching one of those positions is an error, not a silent serialization.

4. Node (output)

Node
  = Text      value: Value,  annotations: Annotations
  | Element   tag: String, attributes: List<NodeAttribute>,
              value: Value, children: List<Node>, annotations: Annotations
  | Fragment  children: List<Node>, annotations: Annotations

NodeAttribute
  = Attribute name: String, value: Value
  | Action    event: String, key: String, payload: Value

Annotations = Map<String, JSON>

The text leaf carries a Value, so a scalar child keeps its type: .td($ctx.count) yields the number 3, not "3". How that becomes characters is the host’s decision.
Element carries a value slot alongside its children, for targets that attach a body value to a tagged node. It is null unless set.
attributes is an ordered list, so an element may carry any number of attributes and actions, and duplicate names are preserved, not merged.
Annotations have no core meaning. They are the extension point for types, domains, provenance and host metadata, and every transformation must carry them through unchanged.

Serialization — including the strict decoding rules — is specified in node-json.md.

5. Surface syntax

Three leader characters: . builds a document, $ reads a name, @ defines one.

@count=cardinality($ctx.items)          -- bindings, one per line
@panel=(title, kids) => .section(.h2($title), $kids)

.div(class: "panel",                    -- attribute position first
     action("on-click", "save", {"id": $ctx.id}),
     value($ctx.raw),
     .h1("Title"),                      -- then children
     .( .p("a"), .p("b") ),             -- a fragment: tagless element
     map($ctx.items, (i) => .li($i.name)),
     branch(.p("none"), gt($count, 0), .p("some")))

Form	Meaning
`$name`, `$name.a.b`	read a binding, then static field access
`name(args)`, `$name(args)`	a call; the two spellings are identical
`$lib.vals.fn(1)`	the callee may be a dotted path
`f(x).rendered`	field access on a call's result
`"text"`, "n: `$x`"	string literal, backtick interpolation
`123`, `-1.5`, `1e5`, `1_000_000`	number literal; see Number literals below
`true`, `false`, `null`	keyword literals
`[a, b]`	array literal
`{"k": v}`, `{k: v}`, `{foo}`	object literal; keys may be bare; `{foo}` is shorthand for `{"foo": $foo}`
`(x, y) => expr`	lambda
`({a, b: c}, y) => expr`	lambda with an object pattern parameter; see Binding patterns in §8
`@{a, b: c}=expr`	binding with an object pattern; see §8
`(expr)`	grouping
`-- text`	a comment, to the end of the line
`a <> b`	concat — the only infix operator, left-associative, lowest precedence
`.tag(...)`	element
`.(...)`	fragment
`value(expr)`	element value slot; at most one, attribute position
`action("event", "key", payload)`	action; attribute position, any number
`map/filter(coll, fn)`, `scan/fold(coll, init, fn)`	array primitives
`branch(fallback, p1, v1, …)`	conditional
`import("name", {k: expr, j: ctx(path)})`	import; a parameter may also be left out and supplied later
`adapt-actions(node, prefix("ns:") \\| identity [, fn])`	action adaptation

Names — bindings, path segments, tags, bare keys — start with a letter and may contain letters, digits, _ and internal -. Internal is enforced, not merely advised: a hyphen belongs to the name only when another name character follows it, so a name never ends in one and $x-- note reads as x followed by a comment. Whitespace is insignificant except as a separator, with one exception: a field-access . must directly follow the ) it applies to, so f() on one line and .div(...) on the next are two separate things.

Comments. -- begins a comment that runs to the end of the line. There is no block form and no nesting, so a comment cannot be left unterminated and a second -- inside one is simply more comment. A comment is legal wherever a space is — above the bindings, trailing one, between an element’s arguments, after the root — and is discarded together with the whitespace around it, so it reaches neither the core AST nor §9’s analyses. Inside a string literal -- is ordinary text: a string body is read character by character and never passes through this rule.

Being whitespace, a comment does not join the lines it sits between: f() -- note followed by .div(...) on the next line is two separate things, exactly as the uncommented version is.

Number literals.

number = ["-"] digits ["." digits] [("e" | "E") ["+" | "-"] digits]
digits = digit { ["_"] digit }

The - is part of the literal, not an operator (there is no arithmetic, §11), so it must touch the first digit: - 1 is a parse error, and so is a leading +. --1 is a comment, like any other --.
A _ separates digits for readability and means nothing: 1_000_000 is 1000000. It is allowed only between two digits — 1_, 1__0, 1_.5, 1._5 and 1e_5 are all parse errors — and may appear in the integer, fraction and exponent parts alike (0.000_001, 1e1_0).
Both parts around a . need at least one digit: .5 and 5. are not numbers.
The literal denotes the double nearest to its decimal value (round to nearest, ties to even). A literal too large for a double (1e400) is a parse error rather than an infinity; one too small rounds to zero.
There is no negative zero: a literal that denotes zero is 0 whatever its sign, so -0 and -1e-400 both evaluate to 0.

Attribute position before children. Attributes, action(...) and value(...) must all precede any child; a child first is a parse error.

Static positions reject interpolation. A backtick inside an import name, action event/key, adaptation prefix or object key is a parse error rather than a literal backtick — someone writing import("lib-`$x`") means interpolation, and that position cannot be computed.

A malformed special form is a parse error. Name recognition backtracks; the shape does not. action("on-click", $computed, {}) fails to parse rather than quietly becoming a call to an unbound function named action.

Program kind

A program is bindings followed by a root expression. parseProgram reports DocumentProgram if the root is written as a document (.tag(...) or .(...)) and ExpressionProgram otherwise. That is a syntactic classification; what evaluation actually produces is decided at runtime (§6).

6. Evaluation

Evaluation is eager and deterministic, with exactly one exception (Branch). Aside from binding order, no evaluation order is prescribed.

Bindings. @name=expr lines lower to nested Lets, so a binding may reference $ctx and any earlier binding, never a later one. A binding’s value is inserted only after it is evaluated, which is why there is no recursion: a lambda cannot call itself by its own binding name.

Closures capture the environment where the lambda is evaluated. Builtins are ordinary values in the initial environment, so one can be passed by reference: map($ctx.flags, $not).

Branch evaluates its condition, then only the selected arm. Errors in an unreached arm never surface. This holds in every position — there is no separate eager form. The condition must be a boolean.

Elements evaluate attributes, then the value slot, then children, in source order.

Children coercion is the one rule the document side adds:

child value	contributes
a document	itself, as one child
an array	each element, recursively — this is how `map(...)` repeats children
anything else JSON-able	one text node carrying that value unconverted
a closure / builtin / import result / unrun import	an error

So an array in child position is a sibling sequence, not one value. An array wanted as data belongs in an attribute or the value slot.

Concat (a <> b) is a monoid over three types, with no coercion:

String × String → String      ""   identity
Array  × Array  → Array       []
Object × Object → Object      {}   right-biased on key collision

Mixed types are an error. Object key order is not semantically significant.

str, and string interpolation. "n: `$x`" lowers to Concat over str(...), so str decides what interpolation puts in the output. Its rendering is normative:

value	renders as
string	itself, raw
`null`	`""`
boolean	`true` / `false`
number	exactly as ECMAScript's `Number::toString` — `3`, `1.5`, `0.05`, `100000000000`, `1e+21`, `1e-7`
array / object	compact JSON, keys sorted, numbers by the same rule, strings JSON-quoted

Keys are sorted because key order is not semantically significant, so it must not be observable here either. Both implementations must produce these character for character.

7. Imports

import("deployment", {
  name:     "web",              -- (a) an expression, evaluated here
  replicas: ctx(spec.replicas)  -- (b) this program's $ctx.spec.replicas
})                              -- (c) anything not listed: supplied later

Three ways to supply a parameter, and the third is not writing it down.

(a) Any expression. It is evaluated where the import is written, like every other argument in the language.

(b) ctx(path) reads the importing program’s own context, also where the import is written. It means exactly what $ctx.spec.replicas means, and a path the context lacks is the same PathNotFound — the two forms are interchangeable at runtime and the evaluator makes no distinction between them.

The distinction is entirely static. ctx(path) puts the path in a static position in the AST, where §9’s contextHoles can enumerate it directly; the same read spelled $ctx.spec.replicas is an ordinary path buried in an arbitrary expression, indistinguishable from every other read. Writing ctx(...) is how an author says this is a hole — count it, and it costs the ability to compute the value, which is the point.

(c) A parameter the import does not mention is supplied later, by calling the import with an object of more parameters. Merging is right-biased, like <> on objects, so a later call overrides an earlier value for the same name.

@panel=import("panel", {})
@half=$panel({"name": "web"})
$half({"replicas": 2}).rendered

An import runs when a field is read off it — .rendered or .vals — never where it is written. Everything before that is accumulation, which is what lets one wired-up import serve a whole map, each iteration adding its own parameter:

@row=import("row", {kind: ctx(row-kind)})
.ul(map($ctx.items, (item) => $row({"title": $item.title}).rendered))

A run import exposes .rendered (whatever its root evaluated to — a document or an ordinary value) and .vals (its own top-level bindings). Using the import itself where a value is expected is an error: it has not run, so it has nothing to serialize.

A library is evaluated against its parameters as its own fresh $ctx — a library’s $ctx is its parameter object, which is why a library reads $ctx.title for the parameter title, and why a ctx(...) hole inside a library is a hole in what its importer must pass. Import names are resolved by a host-supplied table; where a library came from is not the language’s business. Re-entering a library already being evaluated is reported as a cycle, not run.

Nothing checks that the parameters are enough before running a library, because nothing in the import knows what enough would be. A library that reads a path nobody supplied fails with its own PathNotFound, wrapped in an InLibrary naming the library that raised it:

import("panel", {"name": "web"}).rendered
  -- InLibrary "panel" (PathNotFound ["ctx", "replicas"])

The static counterpart is §9’s unsuppliedParams, which answers the same question without running anything.

Known limitation: an import or adapt-actions result cannot be called directly — import("x", {...})({...}) is a parse error. Bind it first, as the examples above do. Only field access is available as a postfix on a call.

8. Desugaring

The parser lowers each of these; none has a core constructor.

surface	core
`@a=1` `@b=$a` `root`	`Let "a" 1 (Let "b" $a root)`
`"n:` + `$x` + `!"`	`Concat (Concat "n: " (str $x)) "!"`
`"a\nb"`	one `StringLit` with a real newline
`{foo, bar: 1}`	`ObjectLit [("foo", Path foo), ("bar", 1)]`
`branch(f, p1, v1, p2, v2)`	`Branch p1 v1 (Branch p2 v2 f)`
`a <> b <> c`	`Concat (Concat a b) c`
`.div()`	`Element "div" [] NullLit []`
`@{a, b: c}=$x.y`	`Let "a" $x.y.a (Let "c" $x.y.b …)`
`({a}, n) => e`	`Lambda ["#arg0", "n"] (Let "a" $#arg0.a e)`

Escape sequences:

\n  \t  \r  \\  \"  \`  \0  \u{1F600}

\u{...} is braced, so an astral code point needs no surrogate pair.

Binding patterns. An @ binding or a lambda parameter may be an object pattern instead of a name (decisions §17):

pattern ::= name | "{" field { "," field } [","] "}"
field   ::= name | name ":" pattern

{title, kind: k, meta: {owner}} binds title, k (the field kind) and owner, reading each field the way $x.title would: a missing field is PathNotFound, a non-object is TypeMismatch, and extra fields are ignored. A path source is read directly, so @{a} = $ctx.item is @a=$ctx.item.a; any other source (a call, a literal) is evaluated once. A pattern parameter takes one position, so arity is unchanged. Bindings are made left to right.

These are parse errors: a name bound twice in one pattern, a default ({a = 1}), a rest element ({...r}), an array pattern (@[a, b]), an empty pattern ({}) and an annotation on a pattern (@{a} : T = e). The parser invents hidden names for the lowering (they start with #, which no surface name can); they never appear as a symbol’s "binding" or in a library’s .vals.

Deferred: array patterns, defaults and rest (see decisions §17 for why).

9. Static analysis

All of these answer from the AST alone — no context, no library evaluation, no host code. The three the laws ask for each have a deep variant that follows imports through a library table and cuts cycles.

function	answers
`staticImportNames` / `transitiveImportNames`	which libraries this program depends on
`staticActionKeys` / `deepActionKeys`	which action keys it can emit
`contextHoles` / `deepContextHoles`	which context paths it declares as holes with `ctx(...)`
`contextReads`	every path it reads from its own context, `$ctx.a` and `ctx(a)` alike
`unsuppliedParams`	per import, the paths its library reads that the import does not supply

contextReads of a library is the shape of the parameter object it expects, since a library’s context is its parameters. unsuppliedParams is that set minus what each import supplies — the parameters still to be saturated by a later call (§7), computed without running anything. It attributes a read to a parameter by the read’s first segment, and stops at the library’s own reads rather than following that library’s imports, whose parameters it supplies itself.

staticActionKeys applies adaptation rather than ignoring it, using the same function the evaluator does: adapt-actions(x, prefix("user:")) over {save, delete} yields {user:save, user:delete}. That is the payoff of restricting adaptation to identity-or-prefix.

These are over-approximations: keys under a Branch arm that a given context will never select are still reported, and so is a parameter a library reads only in such an arm. A name that is imported but missing from the table is reported too — an unresolvable dependency is what a caller wants to hear about — though it contributes no unsupplied parameters, since what it needs is unknowable rather than nothing.

10. Actions and adaptation

action("on-click", "deploy", {"deployment": $ctx.name})

The event and key are literals; only the payload is computed. The language assigns meaning to neither — the event vocabulary is the host’s, and what is fixed is the position, not the words allowed in it.

adapt-actions(node, prefix("deployment:"))
adapt-actions(node, identity)
adapt-actions(node, prefix("ns:"), fn)

Prefixes every action key in the subtree, reaching through imported programs and supplied fragments. Adaptations compose the obvious way — a: then b: gives b:a:key — with no “already adapted” state. Applied to an import that has not run, the adaptation is queued and runs on its result.

The optional fn sees each already-prefixed action and may change only its event type and payload; a key it returns is ignored. Letting it win would put the action vocabulary back beyond static reach, which is the whole point of the restriction.

11. Builtins

The vocabulary is fixed, not user-extensible.

builtin	notes
`cardinality(x)`, `count(x)`	array or object size
`str(x)`	§6's rendering; what interpolation uses
`not(b)`
`and(…)`, `or(…)`	variadic, including zero arguments (`and()` is `true`, `or()` is `false`)
`eq(a, b)`	deep equality; no cross-type coercion, so `eq(1, "1")` is `false`
`lt`, `lte`, `gt`, `gte`	numbers only
`has(container, key)`	tolerant: a missing key, out-of-range index or wrong-shaped container answers `false`
`lookup(container, key, fallback)`	dynamic access; the fallback is mandatory, so this never errors
`map`, `filter`, `scan`, `fold`	also core constructors — see below
`concat(…)`	variadic array join; every argument must be an array
`append(arr, item)`	adds one element; an array item is added whole, not spliced

scan is scanl, not scanl1: its output starts with the seed and is one longer than the input. fold takes the same (acc, item) step and returns only the final accumulator.

There is no arithmetic. No +, -, *, and no numeric builtins beyond the comparisons above — a template compares and selects, it does not compute. Numbers reach a program through $ctx, a literal, or a host-supplied library.

map/filter/scan/fold are core constructors rather than builtins because their function argument needs a fresh binding per element. branch is a core constructor because it must leave an arm unevaluated, which no builtin can do.

12. Errors

error	when
`UnboundName`	a name that is not bound and not a builtin
`PathNotFound`	a field the value does not have; carries the path as written
`TypeMismatch`	wrong type, wrong arity, a non-callable callee, a value that cannot cross a JSON boundary
`ConcatMismatch`	`<>` over two different types
`UnknownLibrary`	an import name the host table does not resolve
`ImportCycle`	a library re-entered while already being evaluated
`InLibrary`	wraps whatever an imported library failed with, naming that library; nests through a chain of imports

13. Implementation-defined

Programs must not depend on any of these.

Object key order, in values and in the serialized Node. str is the exception: it sorts, so it is deterministic.
Evaluation order, beyond binding order and Branch’s laziness.
Error message text. The error kinds above are stable; their prose is not.
Number precision. Numbers are doubles. Beyond 2^53 integers are not exact, and str renders whatever double survived.

14. Open

Array patterns, defaults and rest in binding patterns (§8).
Calling a call’s result directly (§7).
Types, domains and constraints. The AST is built to accept them: node annotations are where derived type/domain information goes, and the semantics avoid equating “unknown” with null, so a constraint-aware evaluator can reuse this AST rather than forking the language. The symbolic and constraint half of that is specified in v3-symbols.md and implemented in both hosts; nominal types are specified in v4-types.md — still a draft, not frozen, but implemented in both hosts through roadmap-to-v4 Phase 15 (tooling included: both the CLI and the browser playground surface the "types"/"type-constraints" envelope fields). v4 shipped as a minor bump — type X = ... declarations and @x : T = e annotations both fit inside the existing Let/Emit chain, so Program’s own shape (DocumentProgram | ExpressionProgram) never changed and no host that pattern-matches it is affected (roadmap-to-v4 Phase 15’s version decision).

Tramaj v4 — Types (draft)

2026-10-02T20:43:09Z

Generated from specs/v4-types.md — the repository is the canonical source, and may be ahead of this page.

Tramaj v4 — Types (draft)

Status: draft, not frozen, implemented. Split out of the v3 design so that v3-symbols.md could be frozen without waiting on the type questions. The design itself is still not settled — the gate in roadmap-to-v4’s Part II was crossed by explicit choice (“no host yet, proceed anyway”), not by a host actually hurt by a plain-string has-type argument, so the six items in §11 remain open and this document remains a draft that could still change under real use. What follows §11 is nonetheless implemented, byte-identically, in both hosts (roadmap-to-v4 Phases 8-14): parsing, resolution and canonical identity, type parameters through imports, annotation erasure, !type-constraint, the "types"/"type-constraints" output lists, and the static analyses in §9.

v3 is complete without this document. A constraint argument may be any JSON value, so a v3 program can already say !constraint("has-type", $d, "Deployment") and a host may give that whatever meaning it likes. What v4 adds is everything that string cannot do: resolution, so a name means a declaration rather than itself; parameterisation, so a library can export a type it does not fully know; an algebra, so types can be built rather than only named; and identity, so two spellings of the same type are the same type.

The thesis is unchanged from v3 §0 — Tramaj fixes positions and identity; the host owns vocabulary and meaning. So v4 still contains no typechecker. It resolves references, normalises type expressions, collects declarations and constraints, and refuses to leave a hole unfilled. It checks nothing against anything. The phase order is the point:

parse  ->  analyse  ->  evaluate  ->  someone else checks
           ^ types live entirely here      ^ a-priori accepted, may be rejected

A program that reaches evaluation has a complete, resolved, hole-free set of types. Whether those types are true of the values is a question for a checker that runs on the concrete output, and Tramaj never asks it.

0. Two realms

v3 gave values a leader for “supplied from outside”: ?. Types get their own, %, and the two realms stay separate.

	values	types
leader	`?`	`%`
supplied by	the host, after evaluation	the caller, before evaluation
identity	allocation site + key (v3 §1.4)	the normal form (§3)
may remain open	yes — that is the output	no — unfilled is an error (§4)
constraints	`!constraint(...)`, evaluated	`!type-constraint(...)`, static (§5)
lives until	the host resolves it	erased before evaluation (§7)

The asymmetry in row three is the whole reason they are separate. A symbol is meant to survive into the output — an unresolved symbol is the deliverable. A type is not: it is scaffolding for a checker, and scaffolding with a gap in it is a bug, not a product.

Unifying the two — symbolic types constrained the way symbolic values are, so that a host could choose a type the way it chooses a value — is a research direction, noted in §11 and deliberately not taken here.

1. The algebra

TypeExpr
  = Prim     name: String                              -- string number bool null document
  | Array    element: TypeExpr                         -- [T]
  | Record   fields: Map<String, TypeExpr>             -- { a : T, b : U }
  | Union    arms:   Map<String, Optional<TypeExpr>>   -- | A T | B U | C
  | Ref      library: String, name: String,            -- a declaration, with its
             arguments: Map<String, TypeExpr>          --   type arguments
  | Var      path: List<String>                        -- %ctx.a.b  -- a hole

Six constructors, closed. There is no function type, no type-level abstraction, and no way for a type to depend on a value.

The primitives are exactly the value domain’s own shapes and nothing else. string, number, bool, null and document are what ref §3 already fixes, so Tramaj can be said to know them without learning anything new. Int is deliberately absent: numbers are doubles and their precision past 2^53 is implementation-defined (ref §13), so an integer type is a host-side refinement of number, not a language primitive. Building it in would oblige both implementations to agree on a boundary the value domain does not have.

1.1 Declarations

type Point   = { x : number, y : number }
type Shape   = | Circle { r : number } | Square { s : number }
type UserId  = string
type Message = { to : string, payload : %ctx.payload }

Declarations are nominal. type UserId = string does not make UserId and string the same type; it declares a new one whose definition is string. Newtyping is therefore not a separate feature — it is what a declaration is, and type OrderId = string is a different type from UserId for the reason a Haskeller expects.
Nominal identity is (library, name) plus arguments (§3), where library is the host table key, not the binding. @a=import("foo",{}) and @b=import("foo",{}) give $a.types.Card and $b.types.Card the same identity, because they are the same type. Since import names are table keys, aliasing is impossible.
Records and unions are structural where they appear anonymously, and get nominal identity only by being the definition of a declaration. {x: number} written in two annotations is one type; Point and Vec2 with identical bodies are two.
A union arm may carry a payload or not. | Dev | Staging | Prod is an enum — the case that matters most, because a hole of that type is a variable with a finite domain, which is precisely what a solver can search and a form renderer can render.

1.2 What Tramaj does not say about a union

Nothing about how a value inhabits an arm. Tramaj declares the arms; whether the host reads a "tag" field, a wrapper object, or a discriminating shape is the host’s convention, on the same footing as what an action key means. This is the one place the thesis has real teeth: the language could mandate a discriminator field, but it could not enforce one — the values come from $ctx or from a solver — so mandating it would buy an opinion without the means to back it.

2. Type parameters are import parameters

This is the load-bearing decision. A library is parameterised over types the same way it is parameterised over values: through its context.

-- library "message"
type Envelope = { to : string, payload : %ctx.payload }

%ctx.payload is a type variable: the type named payload in this library’s context. The importer supplies it in the ordinary params record, marked with % because a type is not a value:

@msg = import("message", {payload: %Json})
@m : $msg.types.Envelope = ?("m")

Everything the import machinery already does applies unchanged:

Partial application (ref §7c). @msg = import("message", {}) is a partial import whose Envelope is a partial type. Saturating the import saturates the type. “Three partially-applied arguments for one and two for the other” falls out of a mechanism that already exists, rather than from a type-level arity discipline.
Deferral. import("inner", {payload: %ctx.payload}) forwards this library’s type variable to the inner one — the exact type-level reading of ctx(path), and the answer to §6’s question.
unsuppliedParams (ref §9) already computes what is missing; §9 below adds the type-side split.

So there is no new parameterisation mechanism, no type-level lambda, no arity to check, and no second notion of “partially applied”. There is also, consequently, no higher-kinded anything — a library is not a type, it cannot be passed, and %ctx.f cannot be applied to arguments. Tramaj is about constructing values; this is the ceiling and it is a deliberate one.

Syntactically there is one params record; semantically there are two channels, split statically by the %. An entry written %T is a type argument, and typeParams (§9) — the %ctx.* paths a library’s declarations mention — says which keys those are. It is an error for the same key to be read as both, so the two namespaces do not overlap in practice even though they share a record.

The alternative, a second record on import, was rejected: it would duplicate partial application, deferral and the unsupplied analysis at the type level, and change the arity of the one form every program uses.

3. Identity is a canonical string

Two types are the same type iff their canonical ids are equal — that is, type equality is string equality, and no unifier, subsumption order or occurs-check exists anywhere in the language.

The normal form resolves every Ref to its (library, name) and every argument recursively, sorts record fields, union arms and argument maps by name, and stops at declaration boundaries — a Ref is rendered as its name and arguments, never as its expansion. That last clause is what makes type Tree = | Leaf | Node { l : Tree, r : Tree } terminate: recursion is compared nominally, structure only within a body.

id     ::= prim | "[" id "]" | record | union | ref | var
ref    ::= library ":" name  [ "[" name "=" id ("," name "=" id)* "]" ]
record ::= "{" name ":" id ("," name ":" id)* "}"
union  ::= "|" name [ " " id ] ("|" name [ " " id ])*
var    ::= "%" path

number
[string]
{x:number,y:number}
message:Envelope[payload=json:Value]
list:T[elem=message:Envelope[payload=json:Value]]
message:Envelope[payload=%ctx.p]        -- partial

list:T[elem=number] written in two libraries a thousand lines apart is one string, hence one type. That is the whole of the equality story, and it is why type arguments need no allocation the way symbols do: a symbol’s two instantiations are genuinely two variables, whereas List[Int] and List[Int] are genuinely one type.

Canonicalisation must be injective, for the reason v3 §1.4 gives about allocation keys: distinct types must not collide in one string. Sorting is therefore total and the grammar above is unambiguous.

4. Partial types

A type is partial if its normal form contains a Var. Partial types are entirely legal while they are being built — that is what a parameterised library exports — and are an error in the root program:

PartialType  the root's type <id> still contains the variable <path>

This is the exact type-level analogue of ref §7’s rule that an import may be partial but must be saturated before it runs, and it is reported the same way — statically, by analysis, before anything is evaluated. It is what makes % safe: unlike ?, a % cannot leak into the output, because a program with one left over does not run.

The consequence worth stating: no partial order over types is needed. Two partial types are compared by the same string equality as any others, holes included; nothing ever asks whether one type is more applied than another, because nothing may ship a partial type to a host that would care.

5. Constraints on types

A template may constrain a type it does not define:

type Envelope = { to : string, payload : %ctx.payload }

!type-constraint("has-default", %ctx.payload)
!type-constraint("serializable", %ctx.payload, "json")

!type-constraint is the type realm’s sibling of v3’s !constraint, and it means exactly what that means: this fact is asserted; someone downstream discharges it. Tramaj checks nothing — it does not know what has-default is, any more than it knows what an action key means. It takes a static name and a list of arguments, each of which is a type expression (%-marked, §2) or a literal scalar.

It is variadic and its arity is unbounded, for the reason v3 §2.1 gives: the language fixes no signature because it knows no names, so arity belongs to the host’s vocabulary alongside the name. A zero-argument !type-constraint("closed-world") is legal, and so is an n-ary relation over many types at once — the type-level counterpart of a global constraint:

!type-constraint("disjoint", %ctx.a, %ctx.b, %ctx.c)
!type-constraint("coercible-to", %ctx.payload, %Json, "lossy")

Argument order is significant and preserved, and is part of the canonical rendering the deduplication below compares on.

statement = "@" name "=" expr           -- ref
          | "!" expr                    -- v3 §2.2, a value constraint
          | "!" "type-constraint" "(" ... ")"   -- v4, a type constraint

Instantiation follows substitution. When message is imported with {payload: %Json}, the collected constraint is has-default(json:Value) — the variable is gone, and the host is asked a question about a concrete type. Constraints are deduplicated by their canonical rendering, as v3 §4 deduplicates value constraints and for the same reason.

5.1 One leader, two phases, told apart by the form name

! means emit a fact, and that is true of both forms. What differs is the realm, and the realm is legible in the form name rather than in the leader — which is the same trick ctx(path) plays in ref §7, where a static form sits in the middle of an ordinary expression and is enumerable precisely because the form name is a fixed word.

The consequences are worth stating, because they are not the ones a reader would assume from the leader alone:

A !type-constraint is resolved, not evaluated. Its arguments are type expressions in the static grammar. The analyser collects it by walking the AST; the evaluator never sees one, exactly as it never sees the type in an annotation (§7).
It is a statement, not a declaration. It lives in the statement chain with the bindings and the value constraints, so the declaration block of §1 stays purely declarative. It may be written anywhere a statement may.
Its position affects nothing but source order. Since it is erased before evaluation, it cannot observe or affect a binding, and moving it up or down the statement list changes only where it lands in "type-constraints" before deduplication.
In the core AST it is TypeEmit name: String, arguments: List<TypeExpr | Scalar>, a sibling of v3’s Emit that the evaluator’s statement fold skips.

The one thing this costs is that ! no longer implies “evaluated”. That was never load-bearing — ! implies “this contributes to the output envelope”, which remains exactly true — and the form name is a static position, so a reader and an analyser can both tell which realm a statement is in by looking at one word.

6. Supplying versus asserting

How does a user force a type variable to be replaced rather than symbolically equated? The two operations are already different things, and only one of them is Tramaj’s:

	written	what Tramaj does	when
supply	`import("m", {payload: %Json})`	substitutes; the variable is gone	analysis
forward	`import("m", {payload: %ctx.payload})`	substitutes one variable for another; still a hole	analysis
assert	`!type-constraint("eq", %ctx.payload, %Json)`	collects the fact; the hole remains a hole	never

Substitution is structural and Tramaj performs it. Assertion is a fact and Tramaj only carries it. Tramaj will never solve an assertion into a substitution — that would be a unifier, and a unifier is the beginning of the checker both documents refuse to build. If you want the type replaced, supply it; the PartialType error of §4 is what guarantees you cannot forget to.

The parallel to ctx(path) is exact: forwarding is deferral, supplying is the literal. The syntax already distinguishes them, because %ctx.p and %T are different expressions.

7. Annotations, and how types reach the value realm

@d : Deployment          = ?("d")
@n : string              = $ctx.name
@m : $msg.types.Envelope = ?("m")

@x : T = e is sugar for the binding plus a v3 emission:

@x = e
!constraint("has-type", $x, {"$type": "<canonical id of T>"})

The type is erased at analysis time into the opaque tag v3 §5.3 already reserved. By the time the evaluator runs there is no type left in the program — only an inert object with a "$type" key, which is data like any other. So:

Value gains no constructor. str, map, eq and the whole NotConcrete table of v3 §1.5 are untouched.
A type reference is still not a value, and cannot be computed, branched on, or built at runtime.
The host looks the id up in the "types" table (§8) and has the definition in hand without parsing Tramaj source.

An annotation whose type is partial is the PartialType error of §4 — which is why erasure is safe: nothing ambiguous can be erased.

A has-type on a symbol is the useful case: it tells the host the domain of a hole it is about to fill, which for an enum union is a finite one. A has-type on a concrete value is a claim a checker can verify against the output. Tramaj distinguishes neither; both are emitted the same way.

8. Output

The v3 §5.2 envelope gains two lists, and the value domain gains the second tagged shape v3 reserved.

{
  "format": "tramaj/symbolic/1",
  "kind": "document",
  "root": { "...": "..." },
  "symbols": [
    {"id": "#0:\"m\"", "origin": {"kind": "alloc", "site": 0, "key": "m"}, "binding": "m"}
  ],
  "constraints": [
    {"name": "has-type",
     "arguments": [{"$sym": "#0:\"m\"", "path": []},
                   {"$type": "message:Envelope[payload=json:Value]"}]}
  ],
  "types": [
    {"id": "message:Envelope[payload=json:Value]",
     "definition": {"kind": "record",
                    "fields": [{"name": "payload", "type": {"kind": "ref", "id": "json:Value"}},
                               {"name": "to", "type": {"kind": "prim", "name": "string"}}]}},
    {"id": "json:Value", "definition": {"...": "..."}}
  ],
  "type-constraints": [
    {"name": "has-default", "arguments": [{"$type": "json:Value"}]}
  ]
}

"types" is the transitive closure of every type the program references: a record’s field types, a union’s payloads, and theirs. The closure is what a host actually needs to interpret a has-type; the direct set is merely cheaper to compute. Cycles are cut by the ids, since a Ref is never expanded (§3).
A constraint goes in the list of its subject’s realm. has-type relates a value to a type, so it is a v3 constraint carrying an erased $type argument; has-default relates a type to nothing else, so it is a type constraint. That is the rule, not an accident of which syntax produced it.
Both lists are [] for a program with no types, so a v3 consumer reading a v4 envelope sees nothing new, and the format version does not change.
Concrete mode (v3 §5.1) emits plain JSON as before. Types are erased, so a concrete-mode run of a typed program is byte-identical to the same program with the annotations deleted — which is the honest meaning of erasure.

9. Static analysis

function	answers
`typeDeclarations`	which types a program declares
`typeReferences` / `deepTypeReferences`	which it refers to, normalised
`typeParams`	which `%ctx.*` variables its declarations read — its type-level parameter list
`unsuppliedTypeParams`	per import, the type params its library needs that the import does not supply
`typeConstraints` / `deepTypeConstraints`	which type-level facts it asserts

typeParams is to types what contextReads is to values, and unsuppliedTypeParams is the type half of ref §9’s unsuppliedParams — the same subtraction, over the keys the % marks.

Resolution follows imports through the library table with the same cycle cutting ref §9’s deep analyses use, and no library is evaluated: the table holds parsed programs, so all of this is an AST walk. Unresolvable references are reported rather than passed through, on the same footing as an import name the table does not resolve.

$lib.types.X is not a runtime field read. It is resolved statically, which means lib must be bound directly to an import(...) in the enclosing binding chain; an import reached through a lambda, an array, or a later saturating call cannot be resolved, and that is an analysis error.

10. Errors

error	when
`UnresolvedType`	a name resolves to no declaration and no primitive
`PartialType`	the root ships a type still containing a `%` variable (§4)
`TypeParamCollision`	a params key is read both as `$ctx.k` and as `%ctx.k`
`NotStaticallyResolvable`	`$lib.types.X` where `lib` is not bound directly to an import
`TypeCycle`	a declaration's arguments cycle (a recursive body does not)

All five are analysis errors. No new evaluation error exists, because by evaluation time there are no types.

11. Open

alias X = T, transparent rather than nominal. Nominal is the right default and gives newtyping for free (§1.1); transparency is occasionally what you want for a host schema that is structural. Cheap to add, easy to regret, so: not until something needs it.
Application sugar. list:T[elem=number] is spelled today as an import plus a field read, which is verbose for what a Haskeller writes List Int. A sugar %list.T[elem: number] desugaring to a fresh wiring would be safe — identity is structural, so a sugared and a spelled-out application are the same type — but it is sugar, and should follow a real complaint.
The Program change. Adding a declaration block breaks DocumentProgram Expr | ExpressionProgram Expr and every host that pattern-matches it. This remains the only breaking AST change across v3 and v4, and it is worth confirming exported types are wanted before paying it.
Type-directed projection. With declarations in hand, $d.replicas could carry a resolved field type into the constraint that mentions it. v3 deliberately computes nothing for a projection (v3 §1.6), and moving that into the language is the first step toward the typechecker both documents refuse to build.
Unifying the realms. A symbolic type — a ?-style hole in the type realm, constrained rather than supplied, that a host resolves alongside the symbols — would collapse §0’s table into one mechanism. It also collapses the erasure of §7, since a type that survives to the host cannot be erased before evaluation, and it reopens the question of which realm is resolved first. Research, not v4.
Row polymorphism, for “a record with at least these fields”. This is what !type-constraint is likely to be abused into expressing, and if that abuse becomes common the honest fix is a former, not a constraint name.

Tramaj v3 — Symbolic values and constraints

2026-10-02T20:43:09Z

Generated from specs/v3-symbols.md — the repository is the canonical source, and may be ahead of this page.

Tramaj v3 — Symbolic values and constraints

This document is normative for the symbolic extension. It builds on reference.md, which remains normative for everything else; section numbers written as (ref §n) point there. node-json.md is unchanged and remains normative for the Node encoding, which v3 wraps rather than alters.

Types are not in v3. Nominal types, type declarations, imported type namespaces and typed annotations are drafted separately in v4-types.md. v3 is complete and implementable without them, and §9 says how far it gets on its own.

Status: frozen as a design. Not implemented in either tramaj/ or tramaj-hs/.

0. What v3 adds, and the rule it follows

Three things: an expression ? that introduces a symbol, a statement ! that emits a constraint, and an output mode that carries both.

Everything follows one rule the language already applies to actions and import names:

Tramaj fixes positions and identity. The host owns vocabulary and meaning.

An action’s event and key are static positions; what "on-click" means is the host’s business (ref §10). v3 says the same of symbolic variables and constraints:

the language guarantees	the host decides
a symbolic variable exists, and which one it is	what it stands for
a constraint was emitted, with these arguments	what `"gte"` means, and how to solve it
the set of constraint kinds a program can emit, statically	whether it supports them

Tramaj therefore solves nothing and checks nothing. It evaluates as far as it can and serializes what it could not resolve, so that a host fold may run a solver, render a form, ask a user, or refuse a template whose constraint vocabulary it does not implement.

1. Symbols

1.1 The value

Value
  = ... as in ref §3 ...
  | Symbol  id: SymbolId, path: List<String>

A Symbol with an empty path is an allocation; one with a non-empty path is a projection of an allocation (§1.6). A symbol is opaque to the language: nothing inspects it, and nothing but §1.6’s projection derives a new one from it.

1.2 `?(key)` — allocation

@primary = ?("primary")
@ports   = map($ctx.services, (s) => ?($s.name))

?(expr) allocates. The argument is an ordinary expression, evaluated where it is written, and MUST evaluate to a concrete JSON value; a symbol used as a key is NotConcrete.

There is no keyless form. A symbol always says what distinguishes it from its neighbours, so the question “did this mean one variable or many?” is always answered in the source:

map($ctx.services, (s) => ?($s.name))   -- one symbol per service
map($ctx.services, (s) => ?("port"))    -- one symbol, shared by every service

Both are legal and mean what they say. A constant key is a constant symbol. What v3 refuses is the version where the author writes nothing and the language guesses.

1.3 `?ctx.path` — demand

@replicas = ?ctx.replicas

?ctx.a.b evaluates to $ctx.a.b and declares this is a value I intend to discuss symbolically. The path MUST be rooted at ctx.

At runtime it means exactly what $ctx.a.b means. Whatever the caller supplied — a number, a symbol, an object — is what it produces. The distinction is entirely static, and it is the same trade ctx(path) already makes for import parameters (ref §7): a path in a static position is a demand an analyzer can enumerate, where the same read buried in an arbitrary expression is not.

An unsupplied demand:

in the root program, allocates the symbol # + the path (§1.4). The root’s caller is the host, the host declined to supply, and the root runs once, so it may allocate.
in a library, is PathNotFound, wrapped in InLibrary naming the library — the same error an ordinary unsupplied read already produces (ref §7).

1.4 Identity

Only a root program may allocate. A library MUST NOT, because the root runs exactly once and a library does not.

AllocationInLibrary is raised when a program containing ?(k) is loaded as a library. The check is lexical: it is about where the ? is written, not where it is evaluated, so a closure created in the root and applied inside a library still allocates in the root, which is where its ? is written.

A SymbolId is a string, formed as follows and identical in every conforming implementation:

form	id
`?(k)`, the n-th `?` in the program's source	`#` n `:` canon(k)
`?ctx.a.b`, unsupplied at the root	`#ctx.a.b`

n is assigned by the parser: the ?(k) occurrences of one program are numbered 0, 1, 2, … in source order. It belongs to the core AST for the same reason a binding’s name does — it is the variable’s identity, not source trivia.
canon is compact JSON with object keys sorted, numbers rendered by ref §6’s str rule, and strings JSON-quoted. It agrees with str on arrays and objects and differs at the top level for strings, where str renders raw. The difference is required: canon MUST be injective, and str(3) and str("3") are the same characters.
The two forms cannot collide: an allocation id continues with a digit, a demand id with ctx. A path segment cannot contain . (ref §5), so the demand form is unambiguous.

Identity is a function of the program text and of one value the author chose. It does not depend on evaluation order, so two implementations agree on symbol ids by construction rather than by agreeing on a traversal.

The site is part of the id, as well as the key, so that two independent ?("replicas") in different places are different variables. A key names a distinction, not a variable.

1.5 What may be done with a symbol

Control flow and structure must be concrete. Only data may be symbolic.

A symbol is data. It may be bound, passed to a lambda, returned from one, stored in an array or object, and placed in an attribute, an action payload, an element value slot or a text child. Everything that would require the language to know something about it is an error:

expression	result
`$s`, `[$s]`, `{k: $s}`	fine — a symbol is a value
`.p($s)`, `.div(class: $s)`, `action(e, k, {r: $s})`	fine — §5.2 carries it
`$s.field`	a projection (§1.6) — the one exception
`branch($s, …)`	`NotConcrete` — no arm can be selected
`map($s, f)`, `filter`, `scan`, `fold`	`NotConcrete` — the spine has no length
`eq`, `lt`, `lte`, `gt`, `gte` on anything containing a symbol	`NotConcrete`
`str($s)`, and so any interpolation of one	`NotConcrete` — §1.8
`cardinality($s)`, `has($s, k)`, `lookup($s, k, d)`	`NotConcrete`
`$s <> x`	`NotConcrete`

has and lookup are called out because both are deliberately tolerant today — has answers false for a wrong-shaped container and lookup never errors. Neither may answer about a symbol: a tolerant false would be a lie, and lookup’s fallback would silently discard the symbol.

Consequence worth stating: v3 can constrain the elements of a list whose length is known, and cannot constrain a list whose length is symbolic. That is the ceiling, and it is where a real symbolic evaluator would have to begin. Declining to go there is what keeps map free of any if value is Symbol branch — no evaluator rule in ref §6 changes, and no builtin learns a new case beyond refusing.

1.6 Projection

$s.field reads nothing. It produces a symbol with the same id and the path extended:

Symbol "#0:\"d\"" []            -- $d
Symbol "#0:\"d\"" ["replicas"]  -- $d.replicas
Symbol "#0:\"d\"" ["a","b"]     -- $d.a.b

A projection is never rejected. PathNotFound is for a concrete value that demonstrably lacks a field; a symbol demonstrably lacks nothing, and whether the thing it stands for has that field is a question for whoever owns its meaning.

Projections do not appear in the symbol table (§5.2); they are references to the allocation they project from.

1.7 Symbols in structures

A concrete structure containing symbols is not special. [?("a"), ?("b")] is an ordinary two-element array that happens to hold symbols. The spine is concrete, so everything structural works: cardinality counts, map iterates, a field read returns the symbol it finds, <> merges. Only the operations that inspect a value refuse.

@ports = map($ctx.services, (s) => ?($s.name))
!map($ports, (p) => constraint("gte", $p, 1024))
.ul(map($ports, (p) => .li($p)))

is legal end to end.

A symbol that is itself structured is the ceiling. $d.replicas projects fine; map($d.items, f) is NotConcrete, because the length is unknown. A symbol may have structure as far as its host-side meaning is concerned; the language cannot walk it.

Two cases fall out of the same rule: a symbol cannot be an object key, because keys are static (ref §5) and nothing computes one; and a symbol inside an import’s parameters is an ordinary value being passed, so it crosses the boundary with its identity intact, which is §2.4’s mechanism.

1.8 Symbols in text

str refuses symbols, so "Deploy `$r` replicas" is NotConcrete. The form to write instead:

.p("Deploy ", $r, " replicas")

Three children — two carrying strings, one carrying the symbol. This is what a form renderer needs anyway: it must put an input where the symbol is, and it cannot if the symbol has been flattened into the middle of a string. The concrete case is unaffected: if $r is a number, the same element produces the same three text children.

Reconstructing a string from those pieces, if a downstream consumer wants one, is that consumer’s job. It has them in order and knows what its target does with them, which the language does not.

2. Constraints

2.1 `constraint(...)`

constraint("gte", $d.replicas, 1)

A special form, not a builtin. The name MUST be a string literal with no interpolation, like an action’s event and key (ref §5) — that is what makes §7’s constraintKinds computable. The remaining arguments are ordinary expressions, evaluated where they are written.

Value
  = ...
  | Constraint  name: String, arguments: List<Value>

The form is variadic and its arity is unbounded. constraint(name) with no arguments is legal, and so is any number beyond. The language fixes no signature for any name, because the language knows no names: arity is part of the host’s vocabulary exactly as the name is, and a host that receives a "gte" with four arguments rejects it the same way it rejects a kind it does not implement. Nothing in §7 depends on arity — constraintKinds reports names, not signatures.

This matters for global constraints in the MiniZinc sense, which are the reason to have a constraint list at all rather than a pile of binary comparisons. They are n-ary over whole collections, and they mix collections with scalars:

!constraint("all-different", $replicas)
!constraint("cumulative", $starts, $durations, $demands, $capacity)
!constraint("global-cardinality", $zones, ["a", "b"], [$lo, $hi])

An argument may be an array (§1.7), so a global taking several arrays of symbols is expressible without any special form of its own; combined with unbounded arity, the whole family is reachable. Argument order is significant and preserved — position is how a global distinguishes its starts from its durations — and it is part of the canonical rendering §4 deduplicates on.

An argument may be any JSON value or any symbol. Anything else — a closure, a builtin, a node, an import — is the TypeMismatch the JSON boundary already raises, through the same code path.

Note what this does not do: there is no restricted constraint-expression grammar and no quoting of argument syntax. constraint("gt", $x, $ctx.threshold) stores 10 when the threshold is concrete and stores a symbol when it is symbolic. Quoting the syntax instead would make every constraint produced by a loop identical, since $item.replicas is the same three words on every iteration.

A Constraint is not data. It MUST NOT cross a JSON boundary: not an attribute, a payload, an element value slot, a text child, or an expression program’s root. The only construct that may consume one is !.

2.2 `!` — emission

! is a fourth leader character, joining ., $ and @. A program is a sequence of statements followed by a root expression:

statement = "@" name "=" expr        -- binding, as today
          | "!" expr                 -- emission
program   = statement* expr

! is a statement leader only. It may not appear inside an expression.

@d   = ?("d")
@min = 1

!constraint("gte", $d.replicas, $min)
!constraint("lte", $d.replicas, 10)
!map($ctx.zones, (z) => constraint("allowed-zone", $d.zone, $z))

.Deployment(name: $d.name, replicas: $d.replicas)

!expr evaluates expr and collects from it by exactly the coercion table children already use (ref §6):

value	contributes
a constraint	itself, one
an array	each element, recursively
anything else	`TypeMismatch`

which is why !map(...) reads naturally: an array is a sequence, in the constraint set as much as in a child list.

A statement sees earlier bindings and not later ones, exactly as a binding does.
!branch(c, …) collects only from the selected arm. Branch is lazy in every position (ref §6) and the unselected arm’s constraints do not exist.
A Constraint value never reached by a ! is discarded. That is the honest consequence of constraints being values, and the price of the @cs = map(...) / !$cs split that makes them worth having.

2.3 Constraints from libraries

A library’s emissions are collected into the same flat list as the root’s. A library is where most constraints will be written, since it is the thing that knows what its own parameters mean.

A library runs when a field is read off its import (ref §7), so its constraints are collected at that point, not where the import is written.

2.4 Who supplies a symbol

Nothing bubbles at runtime. A library declares a demand; its caller decides what to put there:

@a = ?("a")
@b = ?("b")
import("deployment", {replicas: $a})      -- this one
import("deployment", {replicas: $a})      -- and this one share a variable
import("deployment", {replicas: $b})      -- this one has its own
import("deployment", {replicas: 3})       -- and this one is concrete

Symbols are ordinary values, so passing one preserves its identity; no mechanism beyond that is required. The demand bubbles statically instead, through deepSymbolDemands (§7), which tells a root author how many symbols to allocate and where to pass them without running anything.

3. Core AST

Expr
  = ... as in ref §2 ...
  | Alloc      site: Int, key: Expr                 -- ?(k)
  | Demand     path: List<String>                   -- ?ctx.a.b
  | Constrain  name: String, arguments: List<Expr>  -- constraint(...)
  | Emit       constraint: Expr, body: Expr         -- !expr

Emit nests into the chain that bindings already lower to, so

@a=1
!c
root

is Let "a" 1 (Emit c root). The “earlier bindings only” rule therefore needs no separate statement machinery, and Program is unchanged from ref §2 — still DocumentProgram Expr | ExpressionProgram Expr.

Emit is representable anywhere an expression is, but the parser produces it only at statement position.

4. Evaluation

Evaluation produces a value and an emission record:

Emissions
  symbols     : List<SymbolEntry>   -- allocations, first-occurrence order, deduplicated by id
  constraints : List<Constraint>    -- emission order, deduplicated

This is a monoidal output, not mutable state: it is deterministic, it is threaded through evaluation rather than written to, and it gives Branch the right behaviour for free.

Evaluation order is prescribed. ref §13 leaves evaluation order implementation-defined beyond binding order and Branch. v3 removes that freedom: every implementation MUST evaluate call arguments, array literal elements, object literal fields and special-form arguments in source order, in addition to the orders ref §6 already fixes for elements.

This is required, not stylistic. laws.md demands that evaluation be deterministic in the result, and in v3 the emission list is part of the result. It costs nothing: no conforming program could depend on the freedom being removed, since ref §13 already forbade depending on it. It also makes error reporting deterministic, which is a free improvement.

Deduplication. Two constraints with the same name and equal arguments are one constraint, kept at the position of the first. Constraints are declarative facts; asserting one twice says nothing more than asserting it once. This also makes it unobservable whether an implementation runs a library once or twice for two field reads on the same import, which ref §7 does not specify.

Allocations are deduplicated by SymbolId the same way, so ?("port") reached from every element of a map produces one symbol table entry.

5. Modes

An interpreter takes a mode. It is a host parameter, not a property of the program: a host declares what it can read, rather than discovering it from whichever template it was handed. Which mode a template needs is a static question — symbolSites and deepSymbolDemands (§7) answer it without running anything.

5.1 Concrete mode

Output is exactly what ref §1 describes: Node JSON for a document program, a plain JSON value for an expression program. Byte for byte, unchanged. An expression program still pipes into jq; a Node-JSON host still receives Node JSON and nothing else.

In concrete mode a symbol cannot exist:

form	concrete mode
`?(key)`	`SymbolsUnavailable`
`?ctx.path`, supplied	the value the caller supplied; no symbol involved
`?ctx.path`, unsupplied at the root	`SymbolsUnavailable` — that is the same minting
`!expr`	evaluated; the constraints are discarded
`{"$sym": …}` arriving in the context	rejected by the decoder (§5.3)

Two of those rows are load-bearing:

A library written against ?ctx.path runs in both modes. Only minting needs symbolic mode; reading a demand the caller satisfied concretely is an ordinary read. That is what makes a constraint-annotated library dual-use rather than symbolic-only, and it is the reason the demand form is what libraries should be written with.
! is allowed and discarded, not refused. A constraint over values the caller supplied concretely is a checkable fact about a document that is otherwise perfectly correct; refusing would make every annotated library unusable in the half of its settings that do not care. The host has said it does not consume constraints, and deepConstraintKinds (§7) is there for the host that would rather refuse the template up front.

So concrete mode is the language of reference.md exactly, plus one rule about ! and two refusals.

5.2 Symbolic mode

{
  "format": "tramaj/symbolic/1",
  "kind": "document",
  "root": { "type": "element", "tag": "Deployment", "...": "..." },
  "symbols": [
    {"id": "#0:\"d\"",
     "origin": {"kind": "alloc", "site": 0, "key": "d"},
     "binding": "d"},
    {"id": "#2:\"web\"",
     "origin": {"kind": "alloc", "site": 2, "key": "web"},
     "binding": null},
    {"id": "#ctx.threshold",
     "origin": {"kind": "demand", "path": ["ctx", "threshold"]},
     "binding": "t"}
  ],
  "constraints": [
    {"name": "gte",
     "arguments": [{"$sym": "#0:\"d\"", "path": ["replicas"]}, 1]},
    {"name": "allowed-zone",
     "arguments": [{"$sym": "#0:\"d\"", "path": ["zone"]}, "eu"]}
  ]
}

"kind" is "document" or "expression". "root" is Node JSON or a plain value accordingly, and is byte-identical to what concrete mode would have produced whenever the program uses no symbols.
Within a mode the shape is stable. "symbols" and "constraints" are [] for a program that uses none, so a template growing its first ? does not change the shape its host decodes. The shape changes when the host changes its mind, never when the template does.
Only allocations appear in "symbols", and every one of them was allocated by the root program, so the table is exactly as long as the author’s declarations.
A symbol the host seeded (§5.4) arrives as a value and is echoed wherever it was used; the language has nothing to add about it, so it is not listed.
"binding" is the name the allocation was bound to, or null. It is provenance for humans. "origin" is the structured form of "id", so a host never has to parse the id.
Every field is REQUIRED. A decoder MUST reject an object missing any of them, and MUST NOT infer one from a default — the discipline node-json.md already sets.

A host fold may then: run a solver over "constraints"; render an input for every symbol reachable in "root"; ask a user and re-run with the answers seeded into the context; or compare constraints[].name against what it implements and fail with an unsupported-kind error before doing anything else.

5.3 Telling a symbol from an object

Value in symbolic mode is JSON extended with one tagged shape, in the style node-json.md already uses to discriminate nodes by "type" and attributes by "kind":

{"$sym": "#0:\"d\"", "path": ["replicas"]}

Both fields are required. The ambiguity to rule out is a template, or a context, carrying a data object whose key is "$sym". Neither can:

Object keys in Tramaj are always static. An object key is a quoted string literal or a bare identifier, and ref §5 forbids interpolation there, so nothing computes one. {"$sym": 1} written in a program is a parse error, in the same family as import("lib-`$x`").
"$sym" and "$type" are reserved in the value domain in both modes, in programs and in contexts alike. A context carrying either key is rejected by the decoder: in symbolic mode unless it is a well-formed symbol reference, and in concrete mode always. One rule, so a program’s legality never depends on how a host runs it and a context does not change meaning when a host changes mode.
Objects are otherwise built only by <>, which merges keys from objects that came from one of those two sources, so the sources are exhaustive.

"$type" is reserved by v3 but unused by it; it is v4’s (v4-types.md). Reserving it now costs two key names and avoids breaking the grammar later.

The cost is those two names. The benefit is that the tag sits where a reader looks for it and plain JSON stays plain: {"replicas": 3} remains {"replicas": 3}, rather than the {"k":"obj","v":{"replicas":{"k":"num","v":3}}} that a fully tagged value domain would cost every attribute of every document.

5.4 Seeding

In symbolic mode the input context accepts the same {"$sym": …} shape the output emits, decoded recursively. A host that already knows about a variable — because a user is filling a form, or because a solver resolved half of them and the template is being re-run — supplies it as an ordinary context value, and ?ctx.path reads it with no allocation. This is what makes the ask-a-user and re-solve loops work without the template changing.

5.5 Profiles

An implementation MAY implement the core profile only — the language of reference.md, concrete output, no symbolic extension — and remain conforming. It MUST reject ? and ! at parse time rather than ignore them, so that a symbolic template fails on it instead of quietly losing its holes and its constraints. §5.3’s reserved-key rule belongs to the core profile too, so that the two grammars agree.

An implementation of the symbolic profile implements both modes.

6. Errors

Three kinds join ref §12’s table.

error	when
`NotConcrete`	a symbolic value where the language requires a concrete one — §1.5's table, and a symbol used as an allocation key
`AllocationInLibrary`	a program containing `?(k)` is loaded as a library (§1.4)
`SymbolsUnavailable`	a symbol would have to be minted in concrete mode (§5.1)

TypeMismatch covers the rest: a constraint value crossing a JSON boundary, and a ! over something that is neither a constraint nor an array of them. An unsupplied ?ctx.path inside a library is the existing PathNotFound, InLibrary-wrapped.

AllocationInLibrary has a static counterpart: a program with a non-empty symbolSites cannot serve as a library, and a host building its library table SHOULD check that up front rather than discover it on whichever path happens to reach the ?.

Error message text remains implementation-defined (ref §13); the kinds are stable.

7. Static analysis

Answered from the AST alone — no context, no library evaluation, no host code — alongside ref §9’s existing entries.

function	answers
`symbolSites`	the `?(k)` allocation sites this program contains
`symbolDemands` / `deepSymbolDemands`	which context paths it declares symbolic with `?ctx.…`
`constraintKinds` / `deepConstraintKinds`	which constraint names it can emit

The deep variants follow imports through the library table with the same traversal and cycle cutting ref §9’s deep analyses already use.

Two of these earn their keep immediately:

deepConstraintKinds lets a host decide whether it supports a template before running it — possible only because a constraint’s name is a static position.
deepSymbolDemands is the counterpart of ref §9’s unsuppliedParams for this feature. Since only the root allocates, knowing which paths the libraries beneath will discuss symbolically is the whole planning problem, and it is answered without running anything.

symbolSites reports sites, not keys, which are computed. The number of symbols is a runtime fact; the number of sites is not, and a site inside a map is exactly where a reader should look to see what distinguishes them.

Like the existing analyses, these over-approximate: a kind emitted only under a Branch arm that no context will select is still reported.

8. Conformance

decode(encode(n)) on the envelope MUST preserve the semantic result, extending node-json.md’s round-trip invariant.
Symbol ids are exact strings. Two conforming implementations MUST produce the same ids, the same symbol table order and the same constraint order for the same program and context — which is what §4’s prescribed evaluation order and §1.4’s structural identity exist to guarantee.
The shared corpus reference.md §14 calls for is where that is proved. The astral-escape divergence recorded in limitations is the precedent for why neither implementation’s own suite would find a disagreement on its own.

Suggested fixture families: allocation identity under map; a constant key under map; demand supplied concretely vs. symbolically vs. not at all; symbols in attributes, payloads, value slots and text children; ! over a single constraint, an array, a nested array, and a branch; constraint deduplication; library-emitted constraints; concrete mode refusing a mint and discarding an emission; every row of §1.5’s table.

9. Not in v3

left out	where it went
nominal types, declarations, `.types`, typed annotations	`v4-types.md`
any solver, domain or propagation	the host's, per §0
a keyless `?`	§1.2 — a symbol always says what distinguishes it
allocation inside libraries, and any call-frame identity scheme	§1.4 — the root allocates, so identity is a site and a key
symbolic strings, symbolic control flow	§1.5, §1.8
an envelope around concrete output	§5.1 — an expression program's result must still pipe into `jq`
inferring the mode from the program	§5 — a template growing its first `?` would silently change the shape its host decodes

v3 can still express typing informally, because a constraint argument may be any JSON value: !constraint("has-type", $d, "Deployment") is an ordinary constraint carrying a string, and a host may give it whatever meaning it likes. What v4 adds is nominal identity, library-exported declarations and a namespace, so that two libraries’ Card are distinguishable and a type reference is resolved rather than spelled.

Recorded as considered and declined, to be revisited only if practice asks:

A key on the demand form, ?ctx.threshold($s.name). Seeding (§5.4) covers the case a host drives and ?(key) the case a template drives; this is worth it only if something needs both at once.
A label field on the symbol table entry. !constraint("label", $x, "Replicas") already says it, and says it in the host’s vocabulary rather than the language’s.
Symbolic strings. §1.8 has the cost: the value domain would gain terms, not just variables.

Tramaj — Normative Node JSON representation

2026-10-02T20:43:09Z

Generated from specs/node-json.md — the repository is the canonical source, and may be ahead of this page.

Tramaj — Normative Node JSON representation

The evaluated Node AST is the portable interchange boundary between Tramaj implementations and their hosts. This document defines its normative JSON representation.

An implementation MAY use any internal representation of nodes, but a conforming implementation MUST be able to produce and consume the representation below without loss: decode(encode(n)) MUST yield a node equal to n.

Object key ordering is not semantically significant and MUST NOT be relied upon.

Node AST

Annotations = Map<String, JSON>

Node
  = Text
      value: Value
      annotations: Annotations

  | Element
      tag: String
      attributes: List<NodeAttribute>
      value: Value
      children: List<Node>
      annotations: Annotations

  | Fragment
      children: List<Node>
      annotations: Annotations

NodeAttribute
  = Attribute
      name: String
      value: Value

  | Action
      event: String
      key: String
      payload: Value

Value is the ordinary JSON value domain — null, boolean, number, string, array, object. It is not a Node: a document tree never nests through an attribute value, an element value slot, or an action payload.

Text carries a Value, not a String, so scalars survive evaluation without implicit conversion: .p($ctx.count) with count = 3 produces a text node whose value is the number 3, not the string "3". A host that wants a string renders one; the interchange format does not decide that for it.

Element carries a value slot alongside its children, for hosts whose target format attaches a body value to a tagged node (a scalar leaf in YAML/HCL, a configuration value, an editor model). It defaults to null when a template does not set one.

Fragment is an ordered sequence of siblings introducing no wrapper element. It is a real node in this representation; a host MAY flatten fragments when folding into its own target.

JSON encoding

Every object carries a discriminator: "type" for nodes, "kind" for attributes. Every field listed is REQUIRED — including "annotations", which is {} when a node has none, and "value", which is null when an element has no value slot. An encoder MUST emit all of them; a decoder MUST reject an object missing any.

Text

{"type": "text", "value": 3, "annotations": {}}

{"type": "text", "value": "hello", "annotations": {}}

Element

{
  "type": "element",
  "tag": "button",
  "attributes": [
    {"kind": "attribute", "name": "class", "value": "primary"},
    {"kind": "action", "event": "on-click", "key": "deploy",
     "payload": {"deployment": "web"}}
  ],
  "value": null,
  "children": [
    {"type": "text", "value": "Deploy", "annotations": {}}
  ],
  "annotations": {}
}

attributes is an ordered list, not a map: an element may carry any number of attributes and any number of actions, and their source order is preserved. Ordinary attributes and actions share one list because both are attribute-position constructs; a host reading only one kind filters on "kind".

An attribute name may repeat. The representation does not deduplicate; a host decides what a repeated name means for its target.

Fragment

{
  "type": "fragment",
  "children": [
    {"type": "text", "value": "one", "annotations": {}},
    {"type": "text", "value": "two", "annotations": {}}
  ],
  "annotations": {}
}

Annotations

annotations is a JSON object mapping annotation keys to arbitrary JSON.

The core language assigns no meaning to any key or value. Annotations are the extension point for types, domains and constraints, provenance, host metadata, and optimization hints.

Unknown annotations MUST NOT affect core semantics, and implementations MUST preserve them across every node-to-node transformation they perform — adapt-actions in particular copies a node’s annotations through unchanged.

Decoding

A decoder MUST reject:

an object with no "type", or a "type" outside {text, element, fragment};
an attribute with no "kind", or a "kind" outside {attribute, action};
any object missing a field required for its discriminator;
a non-string tag, name, event, or key;
a non-array attributes or children, or a non-object annotations.

A decoder MUST NOT infer a missing field from a default. Defaults are an encoder’s job; on the wire the representation is explicit, so that a missing field is a bug rather than a silent null.

tramaj compared to other tools

2026-10-02T01:00:00Z

tramaj compared to other tools

tramaj sits between three families of tools: string template engines, JSX-style embedded document syntaxes, and configuration languages. This page says where it overlaps with each, where it differs, and when another tool is the better choice. For the argument behind the design, see What sets tramaj apart; for the guarantees, see Properties.

At a glance

String templates (Jinja, Handlebars, Liquid, Go templates): output is text; inputs are discovered by running or grepping; untrusted source depends on the sandbox.
JSX and similar: output is an element tree; the expression language is the full host language; the program’s interface is whatever the host’s type checker knows.
Configuration languages (Jsonnet, Dhall, CUE, Nickel): output is data; the language is small, functional and restricted; the interface is types or schemas.
tramaj: output is a document tree; the language is small, functional and shared by several runtimes; inputs are declared as literal ctx(path) holes; imports, context reads and action keys are recoverable by walking the AST.

Against string template engines

Jinja, Handlebars, Liquid, Mustache and Go’s text/template render text. The template is a string with holes, and the output is a string. That is simple and works everywhere, but a few things follow:

Escaping is a concern of the author. A tree-valued output makes well-formed markup the default instead of a discipline.
Composition goes through includes, partials, or blocks, which are usually resolved by name at render time. In tramaj an import is a value you can bind, partially apply and pass around.
What a template reads is discoverable only by running it or by grepping. tramaj ctx(...) reads are literal paths, so a host can list them without evaluating anything.

Choose a string engine when you produce plain text (emails, config files, code) and want the most familiar syntax and the biggest ecosystem of filters and editors.

Against JSX and embedded document syntaxes

JSX, and its cousins in other languages, make documents values inside a full programming language. tramaj shares that central idea. The difference is the host: with JSX you get all of JavaScript, its tooling and its libraries, and you also get a program that can do anything. tramaj keeps its own small language so the same template runs the same on every runtime and a tool can reason about it before it runs.

Choose JSX when you are already in a JavaScript application, want the component ecosystem, and trust the code that you compile. Choose tramaj when templates are data that travel across languages, or when the source is written by a model or a user you do not fully trust.

Against configuration languages

Jsonnet, Dhall, Nickel and CUE are the closest relatives in spirit: small, functional, importable, restricted on purpose. They produce data, though, and tramaj produces documents. Dhall brings a real type system and CUE brings constraint unification; tramaj does not try to compete with either. What tramaj adds is document composition, deferred and partially applied imports, and a statically recoverable vocabulary of actions that a document may attach to a node.

Choose a configuration language when the output is configuration and you want strong typing, schema validation or constraint solving. Choose tramaj when the output is a rendered document with interactive actions.

Against template layers on top of configuration

Helm charts and similar tools put a text templating layer on top of YAML. That mixes two syntaxes, so indentation and quoting become template concerns. tramaj builds the tree directly, so there is no text stage where structure can break.

Where tramaj is not the right tool

You only need text output and your team already knows a string engine.
You want arbitrary computation, I/O or a large standard library inside the template. tramaj is intentionally small and deterministic.
You need a rich type system or schema language over the data. Pair tramaj with one rather than expecting it in the template language.
You need an established ecosystem of editor plugins, linters and third-party filters. tramaj is young.

See Use cases for where the trade-offs pay off, and Reference for the language itself.

Integrating tramaj into a host

2026-09-25T12:00:00Z

Integrating tramaj into a host

Every integration has the same two moving parts, regardless of language:

Evaluate — parse a template and run it against a JSON context to get a Node: the normative, host-agnostic document tree (node-json.md).
Fold — walk that Node and turn it into whatever your host actually renders: real DOM, a UI framework’s virtual tree, another markup language, a config file.

Nothing about Node or the evaluator knows about HTML, a browser, or any particular UI framework (see Properties) — the fold is always something you write for your host, even where this repository already ships one for you. Which of the six paths below applies depends only on what language your host is written in.

The implementations and how they relate: one specification and corpus, five independently written ports, and the folds and CLIs layered on top of two of them.

Host language	Get the `Node`	Write the fold
PureScript	depend on `tramaj-purs` directly	reuse `tramaj-halogen`, or write your own
Haskell	depend on `tramaj-hs` directly	write your own — none shipped yet
Rust	depend on `tramaj-rs` directly, or shell out to `tramaj-cli-rs`	write your own — none shipped yet
JavaScript / TypeScript	depend on `tramaj-js` directly, or shell out to `tramaj-cli`	reuse `tramaj-react`, or write your own
Python	depend on `tramaj-py` directly, or shell out to `python -m tramaj`	write your own — none shipped yet
anything else	shell out to `tramaj-cli` or `tramaj-cli-rs`, or reimplement the evaluator	write your own, over the JSON

PureScript — import as a library, fold with `tramaj-halogen`

tramaj-purs, tramaj-halogen, tramaj-cli, and playground are members of one Spago workspace rooted at this repository. A new PureScript package placed as a subdirectory of the workspace, with tramaj-purs (and tramaj-halogen if you’re rendering through Halogen) listed in its spago.yaml dependencies, is picked up by Spago’s workspace discovery with no registry publishing step needed.

The core API:

-- Tramaj.Parser
parseProgram :: String -> Either ParseError Program

-- Tramaj.Eval
runProgram :: Mode -> LibraryTable -> Json -> Program -> Either EvalError Json

Mode is Concrete or Symbolic (v3-symbols.md); LibraryTable supplies whatever the template’s import(...) calls need. runProgram gives you the evaluated document as JSON directly, already encoded per node-json.md. If you need the Node value itself rather than its JSON encoding — to fold it without a round-trip through JSON — evalProgramWithEmissions is the lower-level entry point that stops one step earlier.

If your host renders through Halogen, don’t write a fold at all — tramaj-halogen already has one:

-- Tramaj.Halogen
foldToHalogen
  :: forall action slots m
   . (String -> String -> Json -> Maybe action)
  -> Node
  -> Array (ComponentHTML action slots m)

The first argument is a dispatch function: event type, action key, and JSON payload in, an optional host action out. A read-only host supplies \_ _ _ -> Nothing. The result is an Array, not a single element, because a fragment contributes several siblings with no wrapper element. Call validateAttrNames on the Node first — attribute names aren’t validated by the fold itself.

playground/src/Playground/Main.purs is the canonical worked example of the whole pipeline — Tramaj.Parser → Tramaj.Eval → Tramaj.Halogen.foldToHalogen — including dispatchAction, which turns action(...) clicks into real Halogen actions for an interactive host (a read-only host just passes const Nothing instead).

Haskell — the library exists, the fold doesn’t yet

tramaj-hs is an independent Haskell port, built on megaparsec and aeson, that targets the same grammar as the PureScript tramaj-purs and shares its conformance corpus. It’s a normal Cabal library exposing Tramaj.Ast, Tramaj.Parser, Tramaj.Eval, Tramaj.Node, Tramaj.Analysis, and Tramaj.Types — so a Haskell host can depend on it directly (as a source-repository-package or path dependency; it isn’t published to Hackage), the same way a PureScript host depends on tramaj-purs.

What it does not have yet is a tramaj-halogen equivalent — no fold to Lucid, Blaze, or any other Haskell HTML/UI library ships in this repository. A Haskell host gets the parser, the evaluator, and the Node JSON encoding (kept in lockstep with the PureScript Tramaj.Node); writing the fold to your actual rendering library is on you. The shape to follow is tramaj-halogen’s: case on Text/Element/Fragment, recurse into children, and decide what an action(...) payload means in your host.

Rust — the library exists, plus its own CLI

tramaj-rs is an independent, hand-written Rust port of the same grammar and evaluation semantics as the PureScript tramaj-purs and Haskell tramaj-hs, held to the same shared conformance corpus (corpus/cases/ — full parity, including v3-symbols.md’s symbols/constraints and v4-types.md’s nominal types, not just the core language). It’s a normal Cargo library crate — tramaj_rs::{ast, parser, eval, node, analysis, types} — depended on as a path or git dependency (not published to crates.io yet), the same way a PureScript host depends on tramaj-purs or a Haskell host depends on tramaj-hs:

// tramaj_rs::parser
pub fn parse_program(src: &str) -> Result<Program, ParseError>;

// tramaj_rs::eval
pub fn run_program(
    mode: Mode,
    libs: &LibraryTable,
    ctx: &serde_json::Value,
    program: &Program,
) -> Result<serde_json::Value, EvalError>;

run_program gives you the evaluated result as JSON directly, already encoded per node-json.md when the program produces a document, or the concrete/symbolic envelope from v3-symbols.md §5 otherwise — the same shape runProgram returns on the PureScript and Haskell sides. As with Haskell, there’s no tramaj-halogen equivalent shipped yet: a Rust host gets the parser, evaluator, Node JSON codec, and static analysis, and writes its own fold following the same shape (case on Text/Element/Fragment, recurse into children, decide what an action(...) payload means in your host).

Unlike the Haskell port, Rust also has a tramaj-cli equivalent — tramaj-cli-rs — mirroring tramaj-cli’s command surface field-for-field: the same evaluate/analyze <imports|actions|holes|unsupplied|constraints|symbols|types|card|all> subcommands, the same --lib name=path/--mode concrete|symbolic flags, and the same JSON output shapes. If you’d rather shell out than link a Rust library into your host — including from a non-Rust host — tramaj-cli-rs is a drop-in alternative to tramaj-cli with no Node.js runtime required.

JavaScript / TypeScript — import as a library, fold with `tramaj-react`

tramaj-js is an independent, hand-written TypeScript port of the same grammar and evaluation semantics as the PureScript tramaj-purs, Haskell tramaj-hs, and Rust tramaj-rs, held to the same shared conformance corpus (corpus/cases/ — full parity, including v3-symbols.md’s symbols/constraints and v4-types.md’s nominal types, not just the core language). It’s a normal npm package with no React or DOM dependency — a plain Node or browser host can depend on it the same way a PureScript host depends on tramaj-purs:

// parseProgram, tryParseProgram
function parseProgram(src: string): Program; // throws ParseError

// runProgram
function runProgram(
  mode: Mode,
  libs: LibraryTable,
  ctx: Json,
  program: Program,
): Json; // throws EvalError

Mode is "concrete" or "symbolic" (v3-symbols.md); runProgram gives you the evaluated result as JSON directly, already encoded per node-json.md when the program produces a document, or the concrete/symbolic envelope from v3-symbols.md §5 otherwise — the same shape runProgram returns on the PureScript, Haskell, and Rust sides. evalProgram is the lower-level entry point if you want the Node value itself rather than its JSON encoding, to fold it without a round-trip through JSON.

If your host renders through React, don’t write a fold at all — tramaj-react already has one, the same shape as tramaj-halogen’s:

type Dispatch = (
  event: string,
  key: string,
  payload: Json,
) => MouseEventHandler<Element> | undefined | null;

function foldToReact(dispatch: Dispatch, node: Node): ReactNode[];

dispatch decides which action(...) entries become a real event handler — it inspects the event type itself (foldToReact doesn’t), and returns undefined/null for ones it wants to ignore. Every action a dispatch call accepts is wired to onClick. The result is an array, not a single element, because a fragment contributes several siblings with no wrapper — splice it into your own container, <>{foldToReact(dispatch, node)}</>. Call validateAttrNames on the Node first, same caveat as tramaj-halogen: attribute names aren’t validated by the fold itself.

If you’d rather not add a JS dependency at all — or your host isn’t Node — tramaj-cli (or tramaj-cli-rs) as a subprocess is still the same option open to any other language; see Getting started for the exact CLI invocations, and Any other language below for the general shape of folding its JSON output by hand.

Python — import as a library, standard library only

tramaj-py is an independent, hand-written Python port of the same grammar and evaluation semantics as the other four implementations, held to the same shared conformance corpus (corpus/cases/ — full parity, including v3-symbols.md’s symbols/constraints and v4-types.md’s nominal types). It needs nothing outside the standard library (Python 3.9+), so it drops into a data pipeline, a notebook or a backend service without a Node or PureScript toolchain as a runtime dependency. It’s a normal package — tramaj with ast, parser, evaluator, node, analysis, typesys and jsonval modules, laid out one-to-one like tramaj-js — installed from the repository’s tramaj-py/ directory (not published to PyPI yet):

from tramaj import parse_program, run_program

program = parse_program('.p($ctx.name)')          # raises ParseError
run_program("concrete", {}, {"name": "web"}, program)  # raises EvalError

run_program gives you the evaluated result as plain Python JSON values (dict/list/str/numbers/bool/None), already encoded per node-json.md when the program produces a document, or the concrete/symbolic envelope from v3-symbols.md §5 otherwise — the same shape runProgram returns on every other side. A library table is a dict from import name to parsed program; the mode is "concrete" or "symbolic". eval_program is the lower-level entry point if you want the Node value itself rather than its JSON encoding. Numbers keep the language’s double semantics: an exact integer comes back as an int, and str renders as ECMAScript’s Number::toString does, so interpolated text matches the other implementations byte-for-byte.

As with Haskell and Rust, no fold is shipped: a Python host writes its own following the same shape (case on text/element/fragment, recurse into children, decide what an action(...) payload means in your host). Python also has its own tramaj-cli equivalent, python -m tramaj, mirroring tramaj-cli-rs’s evaluate/analyze subcommands, flags and JSON output shapes, so a non-Python host with a Python interpreter around can shell out to it instead of to Node.

Any other language

For a host in a language with no PureScript, Haskell, Rust, JavaScript, or Python interop story — Go, Java, whatever — there are two options:

(a) Full reimplementation. Port the parser and evaluator to your language, the way tramaj-hs ports the PureScript original. Worth it only if you need to evaluate templates natively (e.g. embedding evaluation in a process that can’t shell out, or needs it to run in-process for performance). reference.md is the full grammar and evaluation semantics to implement against, and the conformance corpus (corpus/cases/ in the repository — template + context + expected output triples) is what the five existing implementations are held to; a new implementation should be checked against the same corpus.

(b) Partial implementation, starting from tramaj-cli’s output. For most hosts this is the pragmatic choice: don’t reimplement the parser or evaluator at all. Shell out to tramaj-cli:

tramaj-cli template.tramaj context.json

which prints the evaluated Node as JSON on stdout, exactly per node-json.md. Your host only needs to write the fold — parse that JSON, case on whether each node is text, an element, or a fragment, recurse into children, and decide what each element’s action(...) entries mean in your host — the same shape as tramaj-halogen’s fold, just written against decoded JSON instead of a native Node value. tramaj-cli’s analyze subcommands (imports/actions/holes/unsupplied/constraints/symbols/types) are available the same way, without a context file, if your host wants the static-analysis facts from Properties rather than a rendered document.

This is also the fastest way to prototype an integration in any language before deciding whether a full reimplementation is ever worth it.

See the Roadmap for what a new implementation needs to cover and where to start if you want to build one; Rust, JavaScript and Python each have one now (tramaj-rs, tramaj-js and tramaj-py, above).

Roadmap

2026-09-25T12:00:00Z

Roadmap

No package in this repository has had a stable release yet, and the language itself is still settling — see the repository README for where the language grammar stands. This page is about something narrower: which implementations of tramaj exist, and which are wanted next.

Where things stand today

Five independent implementations target the same grammar and are checked against a shared, language-neutral conformance corpus — template/context/expected-output triples that both must reproduce byte-for-byte, per case, in both concrete and symbolic evaluation modes. That’s a deliberately strong bar: a case belongs in the corpus only if independently written implementations can run it identically.

Implementation	Language	Status
`tramaj`	PureScript	reference implementation, checked against the corpus; `tramaj-halogen` folds to Halogen, `tramaj-cli` is its CLI
`tramaj-hs`	Haskell	independent port, checked against the same corpus
`tramaj-rs`	Rust	independent port, checked against the same corpus; `tramaj-cli-rs` is its CLI
`tramaj-js`	JavaScript / TypeScript	independent port, checked against the same corpus; `tramaj-react` folds to React
`tramaj-py`	Python	independent port on the standard library alone, checked against the same corpus; `python -m tramaj` is its CLI

None is published to a package registry yet (see the README’s “Publishing” section) — all are used today as workspace, source or git dependencies. Each has its own changelog page and Atom feed. See Integrating tramaj for what’s actually usable from each right now, including the fold each one does or doesn’t ship.

The native-implementation wish list is done

Earlier versions of this page asked for native JavaScript, Python and Rust implementations, so that hosts in those ecosystems would get what PureScript and Haskell hosts already had: an in-process parser and evaluator, with no subprocess and no JSON round-trip just to get a Node. All three exist now — tramaj-js, tramaj-py and tramaj-rs — and each passes the full corpus in both modes, v3 and v4 extensions included.

Desired next: folds, and releases

Folds. Only PureScript (tramaj-halogen) and JavaScript (tramaj-react) ship a fold to a rendering target. A DOM fold for JS, a fold to a common Python templating output, and a fold for at least one Haskell or Rust UI or markup library are the obvious next pieces.
Registry releases. The crates.io, npm and PyPI packages are ready to publish but not published; the PureScript registry and Hackage are deliberately deferred until the API has settled. Releases happen when there are major changes, and each package’s version tracks the language version it implements in its major digit.

This is a wish list, not a schedule: there’s no committed timeline or assigned owner for any of it.

What “done” looks like for a new implementation

tramaj-hs, tramaj-rs, tramaj-js and tramaj-py are the templates to follow, since they were added after the language had settled on a normative spec and output format (tramaj-py is the smallest: one module per concern, standard library only). A new implementation is considered on par with the existing ones once it:

implements the grammar and evaluation rules in reference.md, including the static restrictions that make imports, action keys, and ctx(...) paths analyzable without evaluation (see Properties);
encodes and decodes the Node AST exactly per node-json.md, including the round-trip guarantee (decode(encode(n)) == n);
passes every case in the conformance corpus, in both concrete and symbolic mode, byte-for-byte against expected.json;
optionally, but ideally: a fold analogous to tramaj-halogen’s foldToHalogen for at least one popular rendering target in that ecosystem (e.g. a DOM fold for JS, a common Python templating output for Python).

The v3 (?/!, v3-symbols.md) and v4 (%, v4-types.md) extensions are both shipped and part of the same conformance bar — a new implementation isn’t considered complete while targeting only the v2 core.

Contributing an implementation

If you’re taking on one of these, the corpus is the fastest way to find out what you got wrong: it’s meant to be run against a from-scratch implementation just as it’s run against the five that exist, and a case that byte-for-byte matches all of them today is a strong signal your evaluation semantics agree with theirs. Open an issue on the repository before investing heavily in one — coordinating on which language is being worked on avoids duplicate effort.

Changelog: tramaj-halogen

2026-09-25T08:00:00Z

Changelog: tramaj-halogen

Release history of tramaj-halogen, the Halogen host: folds an evaluated Node into Halogen.HTML. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #purescript #tramaj-halogen

`tramaj-halogen` (none)unreleased

Consumed as a git dependency; no registry release yet.

added `Tramaj.Halogen.foldToHalogen`, wiring each `action(...)` to the host's own Action type.

Changelog: tramaj-purs

2026-09-25T08:00:00Z

Changelog: tramaj-purs

Release history of tramaj-purs, the reference PureScript implementation: parser, evaluator, Node codec and analyses. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #purescript #tramaj-purs

`tramaj-purs` (none)unreleased

Consumed as a git dependency; no registry release yet.

added Reference implementation of the language: parser, evaluator (concrete and symbolic modes), normative Node JSON codec and static analyses.
added Conformance corpus under `corpus/cases`, shared with every other implementation.
added Object destructuring patterns in `@` bindings and lambda parameters (decisions section 17): a parser lowering to plain `Let`/`Lambda`, checked by shared corpus cases 100-118.

Changelog: tramaj-hs

2026-09-25T08:00:00Z

Changelog: tramaj-hs

Release history of tramaj-hs, the Haskell implementation, also the engine behind Kitchen-Sink’s templating sections. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #haskell #tramaj-hs

`tramaj-hs` 0.3.0.0date not recorded

Implements v2 of the language: a rewrite of the semantic core, not an extension of it.

changed Documents are expressions: `Element` and `Fragment` are ordinary `Expr` constructors; the separate template-phase AST and `JsonProgram` are gone.
added `Tramaj.Node`, the normative interchange format, with an encoder and a strict decoder.
added `Tramaj.Analysis`: static import names, action keys, context holes, context reads and unsupplied params, with deep variants.
changed Imports take their parameters three ways (expression, `ctx(path)`, or later call); `partial-import` is gone.
changed `a <> b` concatenation, lazy `branch`, `adapt-actions`, `.(a, b)` fragments, string escapes, object shorthand, builtins as values.
fixed Malformed `action(...)`/`value(...)` in an element argument no longer backtracks into a meaningless `Call`; a backtick in a static string position is reported.

`tramaj-hs` 0.2.0.0date not recorded

Adds a JSON-producing mode for hosts that want the data half of the language on its own.

added `Tramaj.Ast.JsonProgram`, `Tramaj.Parser.parseJsonProgram` and `Tramaj.Eval.evalJsonProgram`.

`tramaj-hs` 0.1.0.0date not recorded

Initial release, extracted from the repository it was written in.

added Ports the PureScript package's `Tramaj.Ast` / `Tramaj.Parser` / `Tramaj.Eval` to megaparsec + aeson.

Changelog: tramaj-rs

2026-09-25T08:00:00Z

Changelog: tramaj-rs

Release history of tramaj-rs, the Rust implementation of the parser, evaluator and analyses. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #rust #tramaj-rs

`tramaj-rs` 0.1.0unreleased

Hand-written port kept in agreement with the other implementations through the shared conformance corpus.

added Parser, AST, evaluator and static analyses, plus a program-card analysis.
added Serde-based Node JSON codec.
added Object destructuring patterns in `@` bindings and lambda parameters (decisions section 17): a parser lowering to plain `Let`/`Lambda`, checked by shared corpus cases 100-118.

Changelog: tramaj-py

2026-09-25T08:00:00Z

Changelog: tramaj-py

Release history of tramaj-py, the Python implementation, standard library only. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #python #tramaj-py

`tramaj-py` 0.1.0unreleased

Python port: parser, evaluator (concrete and symbolic modes), Node JSON codec, static analyses and a python -m tramaj CLI. Standard library only, Python 3.9+.

added Hand-written port checked against `corpus/cases` by `tests/test_corpus.py`: every case passes in both modes.
added Object destructuring patterns in `@` bindings and lambda parameters (decisions section 17): a parser lowering to plain `Let`/`Lambda`, checked by shared corpus cases 100-118.

Changelog: tramaj-react

2026-09-25T08:00:00Z

Changelog: tramaj-react

Release history of tramaj-react, the React host: folds a tramaj-js Node into React elements. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #javascript #tramaj-react

`tramaj-react` 0.1.0unreleased

The React counterpart of tramaj-halogen, and the only package here that depends on react.

added `foldToReact` and `validateAttrNames`.

Changelog: tramaj-js

2026-09-25T08:00:00Z

Changelog: tramaj-js

Release history of tramaj-js, the TypeScript implementation for Node.js and browsers. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #javascript #tramaj-js

`tramaj-js` 0.1.0unreleased

TypeScript port: parser, evaluator (concrete and symbolic modes), Node JSON codec and static analyses.

added Hand-written port checked against `corpus/cases` by `test/corpus.test.ts`.
added Object destructuring patterns in `@` bindings and lambda parameters (decisions section 17): a parser lowering to plain `Let`/`Lambda`, checked by shared corpus cases 100-118.

Changelog: tramaj-cli

2026-09-25T08:00:00Z

Changelog: tramaj-cli

Release history of tramaj-cli, the Node.js command-line interface built on the PureScript package. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #purescript #tramaj-cli

`tramaj-cli` (none)unreleased

Bundled with spago; no registry release yet.

added Template file + JSON context file to evaluated Node JSON on stdout, with `--lib name=file` libraries and `--watch`.
added `analyze imports|actions|holes|unsupplied|constraints` subcommands over the static analyses.

Changelog: tramaj-cli-rs

2026-09-25T08:00:00Z

Changelog: tramaj-cli-rs

Release history of tramaj-cli-rs, the standalone Rust command-line interface over tramaj-rs. Releases happen when there are major changes rather than on a schedule; each entry below is one version. Every implementation has its own page like this one, and each page is tagged so the site builds one Atom feed per implementation: #changelog #rust #tramaj-cli-rs

`tramaj-cli-rs` 0.1.0unreleased

Rust port of tramaj-cli's Main.purs over the tramaj-rs crate.

added Template + JSON context evaluation and the `analyze` subcommands, as a single static binary.

What sets tramaj apart

2026-09-11T01:00:00Z

What sets tramaj apart

Plenty of languages already do pieces of what tramaj does. JSX makes documents a value inside an expression language. Dhall and Nickel are typed, functional, importable configuration languages. Jsonnet generates structured data from a small functional core. CUE builds a schema out of constraints. Starlark restricts a language deliberately so tooling can reason about it. None of that is new by itself.

What’s distinctive about tramaj is a specific combination: a document is an ordinary value in a small functional language, and the language is restricted in exactly the places needed to make a program’s external interface — what it imports, what context it reads, what actions it can emit — recoverable by walking the AST, without evaluating it. Most template systems optimize for how easily they generate output. tramaj optimizes for how much a host can know about a program before it runs.

A document is just a value

There’s one expression grammar. A document (an Element or Fragment) is a Value, exactly like a string or a number — it can be bound, passed to a lambda, returned from a function, collected by map, or handed to import. There’s no separate template phase sitting on top of a host language, the way JSX sits on top of JavaScript.

@row = import("row", {kind: ctx(row-kind)})
.ul(
  map($ctx.items, (item) => $row({"title": $item.title}).rendered))

The array map returns is already a sequence of document children — “build a document” and “compute a value” are the same activity. See Reference for the full grammar.

`ctx(...)` is a declared hole, not just a read

$ctx.title and ctx(title) are equivalent at runtime. They are not equivalent to static analysis. $ctx.title is a dynamic read that could, in principle, be buried behind arbitrary computation. ctx(title) is a literal path in the syntax — the author is declaring, in a form a tool can see without running anything, “this is a hole the caller is expected to fill.”

That costs something: a ctx(...) path can’t be computed. It has to be written down. tramaj takes that trade deliberately, because it’s what turns “what does this template depend on” into a question a static pass can answer over an unmodified module — not just the top-level program, but a library sitting behind an import.

Imports accumulate parameters before they run

@panel = import("panel", {})
@half = $panel({"name": "web"})
$half({"replicas": 2}).rendered

An import isn’t “load this module” — it’s a partially applied program. Each call supplies more parameters; nothing executes until .rendered or .vals is actually read. That gives a wired-once, specialized-per-item pattern for free:

@row = import("row", {kind: ctx(row-kind)})
map($ctx.items, (item) => $row({"title": $item.title}).rendered)

Because contextReads and unsuppliedParams are static analyses (see Properties), a host can diff what a library expects against what an import supplies — title supplied, description and id still open — without running the library. That’s close to an implicit interface for modules, without introducing a conventional module type system.

Actions are a statically discoverable vocabulary, not an escape hatch

action("on-click", "deploy", {"id": $ctx.id}) attaches an opaque, structured action to a node. The event and the key are literal strings; only the payload can be computed. adapt-actions(node, prefix("deployment:")) can rewrite a subtree’s action keys under a fixed prefix, and the optional transform hook is allowed to touch the event and payload but never the key.

That restriction exists for one reason: so staticActionKeys(program) stays answerable by walking the AST. A host embedding an untrusted or model-generated template can ask “what could this possibly do to my page or my system” — the full set of action keys it might ever emit — before a single line of it runs. See Use cases for what that buys in practice, and Properties for the determinism and portability guarantees underneath it.

The shape this adds up to

Put the three together and a tramaj program has a discoverable interface even though it’s an executable program:

None of documents-as-values, static analysis, or restricted languages is new on its own — JSX, Dhall, CUE, and Starlark each stake out real territory here, and tramaj doesn’t compete with Dhall’s type system or CUE’s unification. What’s specific to tramaj is treating the combination — document composition + deferred, parameterized imports + a statically recoverable dependency and action vocabulary — as the actual point, instead of a byproduct of “yet another way to generate markup.” That’s why Properties calls out cheap static analysis as an invariant, not a feature: it’s the thing the rest of the design exists to protect.

tramaj for coding agents

2026-09-10T01:00:00Z

tramaj for coding agents

tramaj was designed to be as easy for a model to emit correctly as for a person to write by hand — a small builtin set, one expression grammar, and no template/expression phase split to keep track of. This page is a dense cheatsheet plus a fetch strategy for getting the full grammar when the summary below isn’t enough.

Fetch the canonical source first

Don’t rely on prose alone for anything you’re about to emit — pull the normative text:

Every page on this site is also served as plain text at /text/<page-name>.cmark.text (e.g. /text/reference-language.cmark.text) — no HTML to strip.
The specs themselves are the ultimate source of truth, on GitHub: reference.md, node-json.md, v3-symbols.md, v4-types.md.
corpus/cases/ in the repository is a conformance corpus: each case is a template.tramaj + ctx.json + expected.json triple (plus optional libs/*.tramaj) that both implementations must satisfy — treat these as runnable, ground-truth examples rather than prose.
See also llms.txt for a short machine-readable index of the above (Kitchen-Sink serves arbitrary .txt files under /raw/, so this isn’t at the conventional /llms.txt root path).

Leaders — what each sigil means

Leader	Meaning
`.`	document: `.tag(...)` element, or `.(...)` fragment
`$`	read a binding or path
`@`	define a binding (`@name=expr`)
`!`	emit a constraint, statement position (`!constraint(name, ...)`)
`?`	symbolic allocation/demand, v3 (`?(key)`)
`%`	type hole, v4
`--`	line comment, to end of line

Shape of a program

@n=cardinality($ctx.items)
.p("there are `$n` item(s)")

An optional block of @name=expr bindings, evaluated once each in order, followed by one root expression. Backtick-quoted `$expr` interpolates into a string; a bare $path can be a child directly. a <> b concatenates strings, arrays, and objects.

Documents are ordinary values

There is no separate “template value” type — an element or fragment can be bound, passed to a function, and returned from one:

@kids=.(.p("one"), .p("two"))
@panel=(title, children) => .section(.h2($title), $children)

.main($panel("Deployment", $kids))

Actions are opaque to the language

action("on-click", "select", {"id": $i.id}) attaches structured data to an element. The language does not interpret it — a host decides what the key means. Action keys and adaptation prefixes must be literal strings, never computed, which is what keeps “what actions can this template emit” statically answerable.

Imports

import(...) pulls in another program as a library. Parameters can arrive as an expression, as a ctx(path) hole (a static marker that the importing program’s own context gets read at that point), or be omitted and supplied later by calling the import. Imports are lazy — nothing runs until .rendered or .vals is read on the result.

v3 — symbols and constraints (frozen, implemented)

?(key) allocates an opaque symbol; only the root program may do this (libraries raise AllocationInLibrary). !constraint(name, ...) emits a constraint. Running in Symbolic mode (a host choice, not something the template declares) wraps the result in a tramaj/symbolic/1 envelope of root value, symbols, and constraints instead of a finished document — use this when the actual values should come from a solver rather than be supplied up front. Full grammar: v3-symbols.md.

v4 — types (draft, implemented)

@x : T = e desugars to @x=e plus a has-type constraint carrying T’s canonical id. Types are resolved and erased before evaluation — tramaj fixes type identity (canonical ids, string equality), a separate host checker decides whether values actually satisfy it. Type parameters thread through imports. Full grammar: v4-types.md.

Static analyses available without evaluating

Because imports, action keys, adaptation prefixes, and ctx(...) paths are all literal strings in the syntax, these can all be answered by walking the AST — no context, no evaluation:

what a program imports, and with what parameters
what actions it can possibly emit
what context paths it reads (ctx(...) holes)
which import parameters are still unsupplied
(v3/v4) what constraints and symbols/types it introduces

tramaj-cli’s analyze subcommand exposes these directly — see Getting started for exact invocations. If you’re generating a template and want to self-check it before handing it to a host, running analyze on it is cheaper and more reliable than re-deriving these properties by re-reading your own output.

Common pitfalls

Don’t compute an import name, action key, or ctx(...) path from an expression — these must be literal strings; the grammar doesn’t allow otherwise.
Bindings are visible only after their declaration, in order — not mutually recursive.
A library (something loaded via import) may not call ?(key) — only the root program may allocate symbols.
Evaluation order is unconstrained outside of binding precedence: don’t write templates that rely on side-effect ordering, because there isn’t one — evaluation is meant to be referentially transparent.

tramaj playground

2026-09-10T01:00:00Z

This is the same playground built from the tramaj repository’s PureScript sources, published here as a static bundle so it can be tried without a local build. It parses and evaluates tramaj templates in the browser — nothing is sent to a server. Tabs act as importable libraries for each other; toggle “Symbolic mode” to see the v3 envelope instead of a finished document.

See Getting started for running the same language from the command line, or Use cases for where it fits.

If the embedded frame does not load, open the playground directly.

Getting started with tramaj

2026-09-10T01:00:00Z

Getting started with tramaj

This is a practical walkthrough. For the language’s core ideas, see the overview on the home page; for the full grammar, see the Reference.

A template can be run in four places, and each section below covers one:

The fastest way in: the playground

Before installing anything, try the playground — it runs entirely in the browser, needs no setup, and shows the same panels described below (evaluated AST, rendered HTML, action log).

Installing the toolchain

tramaj’s PureScript packages are one Spago workspace. You need purs and spago on your PATH:

npm install -g purescript spago

Anything that bundles a browser or Node bundle — the playground and the CLI — also needs esbuild, which is a devDependency of the repo root:

git clone https://github.com/lucasdicioccio/tramaj.git
cd tramaj
npm install
export PATH="$PWD/node_modules/.bin:$PATH"

Writing a first template

Create hello.tramaj:

@n=cardinality($ctx.items)
.p("there are `$n` item(s)")

and a context to evaluate it against, hello.json:

{"items": ["a", "b", "c"]}

Running it

spago run -p tramaj-cli --args "hello.tramaj hello.json"

This prints the evaluated Node AST as JSON — a p element wrapping the text there are 3 item(s). See node-json.md for what that JSON shape means, or fold it into real HTML by rendering it through a host like tramaj-halogen.

Splitting a template into libraries

A template can import(...) another template as a library. Pass each one with --lib name=path:

spago run -p tramaj-cli --args "--lib greeter=greeter.tramaj hello.tramaj hello.json"

Repeat --lib for as many libraries as the template’s imports need.

Inspecting a template without running it

Because imports, action keys, and context reads are all static positions (see Properties), the CLI can answer questions about a template without a context file at all:

node tramaj-cli/dist/tramaj-cli.js analyze imports hello.tramaj
node tramaj-cli/dist/tramaj-cli.js analyze actions hello.tramaj
node tramaj-cli/dist/tramaj-cli.js analyze holes hello.tramaj
node tramaj-cli/dist/tramaj-cli.js analyze unsupplied hello.tramaj
node tramaj-cli/dist/tramaj-cli.js analyze all hello.tramaj

(These need a bundled CLI first: spago bundle -p tramaj-cli --platform node --outfile dist/tramaj-cli.js, run from tramaj-cli/.)

Embedding in a real host

Running templates from the command line is one thing; wiring them into an actual application is another — see Integrating tramaj for the four paths (PureScript, Haskell, JavaScript, or any other language) and what each one actually looks like.

Where to go next

Use cases for where this fits alongside other templating approaches.
Reference for the full grammar, builtins, and the v3/v4 extensions.
Integrating tramaj for embedding it in a host application.
For coding agents if you’re setting an LLM loose on tramaj templates rather than writing them by hand.

Reference

2026-09-10T01:00:00Z

Reference

These pages are generated straight from the specs in the tramaj repository — the repository is always the canonical source, and may be ahead of what’s published here.

How the documents relate: the language reference is the base, the Node JSON format encodes what it evaluates to, and v3 and v4 each extend it.

Language reference — core AST, values, evaluation rules, surface syntax and its desugarings, imports, actions, builtins, and what’s implementation-defined. Start here.
Node JSON representation — the normative wire format for the evaluated Node AST.
v3 — Symbolic values and constraints — ?(key) allocation, !constraint(name, ...), and the Symbolic evaluation mode.
v4 — Types — the nominal type algebra, type parameters through imports, and typed annotations.

Two more documents exist only in the repository, not mirrored here since they’re development history rather than language reference:

laws.md — the design invariants, rewritten in prose on the Properties page.
decisions.md — the resolved-conflicts log: which reading won wherever the design drafts disagreed, and why.

Earlier, superseded design drafts live under specs/archive/, kept for the reasoning in them rather than as current documentation.

Properties of tramaj

2026-09-10T01:00:00Z

Properties of tramaj

tramaj is small on purpose. A handful of invariants are what make that smallness pay off — they’re what let a host embed the language without trusting it, and what let an LLM emit templates without a feedback loop to check them against.

Small core

The whole language is one expression grammar: bindings, HAML-like elements, jq-flavoured paths and calls, and a deliberately tiny builtin set. There is no separate template phase and no macro system — an element or a fragment is an ordinary value, so composing documents is just composing expressions. Nothing about the identity of the language depends on HTML, a browser, or any particular UI framework: the core (tramaj/) has no DOM dependency at all, and folding a Node into Halogen HTML, JSON, or anything else is entirely the host’s decision.

Portable at the boundary

Evaluation produces a generic Node AST with a normative JSON encoding (node-json.md): scalars stay scalars, and an element may carry many opaque, structured actions rather than being tied to one host’s event model. That boundary is what lets five independent implementations — PureScript, Haskell, Rust, TypeScript and Python — target the same grammar and share a conformance corpus, and it’s what lets a host system receive a rendered document as data rather than as a blob of host-specific markup.

Cheap to analyze statically

Import names, action keys, action-adaptation prefixes, and ctx(path) reads are all literal strings in the syntax — never the result of evaluating an expression. That’s a deliberate restriction, not an oversight: it means a tool can answer “what does this program import,” “what actions can it emit,” “what context does it read,” and “which import parameters are still unsupplied” by walking the AST, with no evaluation step and no need to run untrusted input to find out what it does.

Deterministic

Templates are referentially transparent — the same bindings evaluated against the same context values always produce the same result. Evaluation order is unconstrained outside of binding precedence, so a host is free to parallelize or reorder work, but never free to change the answer. This is what makes a rendered document reproducible, cacheable, and safe to diff.

Where the properties sit

Determinism lives in the evaluator, portability in the Node JSON boundary after it, and everything host-specific (rendering, what an action key does) after that boundary, in code the host owns.

What this buys you in practice

Put together, these properties mean a host can accept a tramaj template from an untrusted or automated source — a CMS, a design tool, an LLM — and know, without running it, what it can possibly do to the page or app it’s embedded in. See Use cases for what that looks like in practice, or the Reference for the full specification these properties are drawn from.

What tramaj is for

2026-09-10T01:00:00Z

What tramaj is for

tramaj is a small functional language for composing values and documents. A program evaluates against a JSON-like context and produces either an ordinary value or a generic document tree — the host decides what to do with it. That shape shows up in a few recurring situations.

Turning JSON into markup, safely

The original motivation: templates that are comfortable to write by hand and easy for an LLM to emit. A jq-flavoured expression half handles the data, a HAML-like block syntax handles structure, and the builtin set stays small enough that neither a person nor a model has to hold much in their head to use it correctly. This site itself is one instance of that — static site pre-processing, the way Kitchen-Sink itself does it.

Templating a real UI, not just markup

tramaj-halogen folds an evaluated Node into Halogen.HTML, wiring each action(...) in the template to the host’s own Action type. Because actions are opaque structured data rather than host-specific event handlers, a template can describe what should happen (“on-click, select, id: 42”) without knowing how the host will react to it — the same template could drive a different UI framework by pairing it with a different fold.

Documents an LLM can emit and a host can trust

Because imports, action keys, and context reads are all static positions — literal strings, never computed — a host can run the static analyses in Tramaj.Analysis over a model-generated template before evaluating it: what does it import, what actions can it possibly emit, what context does it read, which import parameters are still unsupplied. That turns “an LLM wrote this template” from a trust problem into an inspectable one. See Properties for why this holds.

Constraint-driven generation

v3 adds symbolic values (?(key)) and constraints (!constraint(name, ...)). Running evaluation in Symbolic mode produces an envelope of root value, symbols, and constraints instead of a finished document — useful when the actual values should come from a solver, a form the user hasn’t filled in yet, or a search process, rather than being supplied up front. See v3-symbols.md.

Typed template contracts

v4 adds a nominal type algebra on top of that: type declarations, type parameters threaded through imports, and @x : T = e annotations that are resolved and erased before evaluation. tramaj fixes what a type is (identity is structural string equality over canonical ids); a separate host checker decides whether the values flowing through a template actually satisfy it. That’s useful wherever a template is a contract between two teams or two systems — e.g. a component library whose consumers should be checked against its declared shape. See v4-types.md.

Try it

The playground runs all of the above in the browser — tabs-as-importable-libraries, live AST/render panels, an action log, and a symbolic-mode toggle — with nothing sent to a server.

tramaj

Tramaj — Language Reference

Tramaj — Language Reference

1. Shape of the language

2. Core AST

3. Values

4. Node (output)

5. Surface syntax

Program kind

6. Evaluation

7. Imports

8. Desugaring

9. Static analysis

10. Actions and adaptation

11. Builtins

12. Errors

13. Implementation-defined

14. Open

Tramaj v4 — Types (draft)

Tramaj v4 — Types (draft)

0. Two realms

1. The algebra

1.1 Declarations

1.2 What Tramaj does not say about a union

2. Type parameters are import parameters

2.1 The two channels share one record

3. Identity is a canonical string

4. Partial types

5. Constraints on types

5.1 One leader, two phases, told apart by the form name

6. Supplying versus asserting

7. Annotations, and how types reach the value realm

8. Output

9. Static analysis

10. Errors

11. Open

Tramaj v3 — Symbolic values and constraints

Tramaj v3 — Symbolic values and constraints

0. What v3 adds, and the rule it follows

1. Symbols

1.1 The value

1.2 ?(key) — allocation

1.3 ?ctx.path — demand

1.4 Identity

1.5 What may be done with a symbol

1.6 Projection

1.7 Symbols in structures

1.8 Symbols in text

2. Constraints

2.1 constraint(...)

2.2 ! — emission

2.3 Constraints from libraries

2.4 Who supplies a symbol

3. Core AST

4. Evaluation

5. Modes

5.1 Concrete mode

5.2 Symbolic mode

5.3 Telling a symbol from an object

5.4 Seeding

5.5 Profiles

6. Errors

7. Static analysis

8. Conformance

9. Not in v3

Tramaj — Normative Node JSON representation

Tramaj — Normative Node JSON representation

Node AST

JSON encoding

Text

Element

Fragment

Annotations

Decoding

tramaj compared to other tools

tramaj compared to other tools

At a glance

Against string template engines

Against JSX and embedded document syntaxes

Against configuration languages

1.2 `?(key)` — allocation

1.3 `?ctx.path` — demand

2.1 `constraint(...)`

2.2 `!` — emission

PureScript — import as a library, fold with `tramaj-halogen`

JavaScript / TypeScript — import as a library, fold with `tramaj-react`

`tramaj-halogen` (none)unreleased

`tramaj-purs` (none)unreleased

`tramaj-hs` 0.3.0.0date not recorded

`tramaj-hs` 0.2.0.0date not recorded

`tramaj-hs` 0.1.0.0date not recorded

`tramaj-rs` 0.1.0unreleased

`tramaj-py` 0.1.0unreleased

`tramaj-react` 0.1.0unreleased

`tramaj-js` 0.1.0unreleased

`tramaj-cli` (none)unreleased

`tramaj-cli-rs` 0.1.0unreleased

`ctx(...)` is a declared hole, not just a read