rigid specification

The language reference for rigid v1.8.1. If you are learning the language, start with the tutorial — this page is the normative description.

1. Thesis

Text is authoritative for content. The derived graph is authoritative for identity. Ambiguity is a compile error.

A definition's identity is the SHA-256 of its canonical form, in which bound names are erased and every reference to another definition is that definition's hash. Names are a human-facing metadata layer. The compiler maintains an exact reference graph as a byproduct of compilation — never reconstructed, never approximate — and refuses to let a name silently change meaning.

Design ordering, used to settle every dispute: exactness > interop > ergonomics > expressiveness. Interop is why text, files, Git, and mainstream syntax survive. Exactness is why silent rebinding does not.

2. Lexical structure

Source files are UTF-8 with the extension .rg. One file is one module; the module id is its path relative to the workspace root, with forward slashes. Comments run from // to the end of the line and are preserved by rigid fmt, though they never affect identity.

String literals are double-quoted and support the escapes \n, \t, \r, \e, \", and \\. Integer literals are decimal and 64-bit signed. A digit run continues into a float only when a . is followed by another digit, so 3.14 is a float while x.field is a field access.

Reserved words

Keywords:

fn  let  return  while  if  else  import  from  table  dyn  memo  extern

Builtin names are reserved words too, so they cannot be used as identifiers:

print  input  read_file  write_file      // io
len  push  str  int  float  substr  chars  join // pure
fail  try                                // errors

3. Grammar

Deliberately tiny: definitions, calls, imports, arithmetic, and if-expressions.

module    := item* EOF
item      := import | fndef | tabledef | externdef

import    := "import" "{" ident ("," ident)* "}" "from" STRING ";"
fndef     := "memo"? "fn" ident "(" (ident ("," ident)*)? ")" effects? "{" stmt* "}"
externdef := "extern" "fn" ident "(" (ident ("," ident)*)? ")" effects? "=" STRING ";"
effects   := ("!" capability)+                        -- io fs net env time rand proc
tabledef  := "table" ident "{" (STRING "->" ident ("," STRING "->" ident)* ","?)? "}"

stmt      := "let" ident "=" expr ";"
           | ident "=" expr ";"                       -- assignment, locals only
           | "while" "(" expr ")" "{" stmt* "}"
           | "for" "(" ident "in" expr ")" "{" stmt* "}"
           | ifstmt
           | "return" expr ";"
ifstmt    := "if" "(" expr ")" "{" stmt* "}"          -- else is optional here
             ("else" (ifstmt | "{" stmt* "}"))?
           | expr ";"

expr      := cmp
cmp       := add (("=="|"!="|"<"|">"|"<="|">=") add)*
add       := mul (("+"|"-") mul)*
mul       := unary (("*"|"/"|"%") unary)*
unary     := "-" unary | "&" ident | dyncall | temporal
           | "print" "(" expr ")" | call

dyncall   := "dyn" "{" ident ("," ident)* "}" "(" expr ("," expr)* ")"
temporal  := "@" STRING "(" (expr ("," expr)*)? ")"

call      := ident "(" (expr ("," expr)*)? ")"        -- direct calls only
           | ident "[" expr "]" ("(" args ")")?       -- table dispatch
           | ident
           | primary

primary   := INT | STRING | "(" expr ")"
           | "[" (expr ("," expr)* ","?)? "]"                      -- list
           | "{" (ident ":" expr ("," ident ":" expr)* ","?)? "}"  -- record
           | "if" "(" expr ")" expr "else" expr
           | builtin

postfix   := atom ("." ident | "[" expr "]")*         -- field access, indexing

if appears twice above because it is two constructs. The parser tells them apart by what follows the condition: a { opens a statement block whose else is optional; anything else is the expression form, whose else is mandatory because it must produce a value.

Note what is absent: there is no break, no continue, and no && or ||. Named function definitions may not nest — a fn(x) { … } lambda is lifted out to the top level rather than nested (§20).

4. Values and operators

Six value kinds: Int, Float, Str, List, Record, and Fun (a reference created by &name).

float(e) widens an integer or parses a string; int(e) truncates toward zero. Two integers are never widened silently — that would lose precision above 2⁵³, which is the kind of quiet wrongness this language exists to refuse. Before hashing, -0.0 normalizes to +0.0 and every NaN to one quiet NaN, because content addressing cannot have two keys that compare equal or one that does not equal itself. The JS target maps Int to BigInt and Float to a plain number, because JavaScript's single number type is a float64 — using it for both silently rounded 64-bit integers, so node answered 9007199254740993 + 1 with 9007199254740992.

There is no boolean type: 0 is false and any other integer is true. Records are immutable maps whose identity ignores field order — the canonical form sorts fields by name, so two differently-ordered literals hash identically. Locals are the only mutable storage; definitions are immutable, and assigning to one is E0210.

Scope is flat per function: parameters, then lets, numbered in binding order, innermost match wins. A let inside a loop body keeps one stable slot across iterations, and reading it after a loop that never ran yields 0.

Value domains

rigid has no type system, but the four value kinds are distinguishable and the operators that accept them are not interchangeable. Three things are inferred: a parameter's domain, from uses admitting exactly one (-, *, /, % and ordering are integer-only; .field needs a record; substr/chars need a string; push/join need a list); a local's domain, from its initializer; and a definition's return domain, when every return agrees.

Three things are checked, and only where the domain is known: an argument at a direct call, an operand of an integer-only operator, and the base of a field access (E0212). Everything else infers nothing and reports nothing, so a parameter with no domain-forcing use stays polymorphic and a conflict silences a slot rather than failing it. Domains are inferred, never declared, and never enter canonical form.

Errors as values

fail(v) raises any value. try(e) evaluates e and yields { ok: 1, value: v } or { ok: 0, error: payload }. Every builtin runtime error — division by zero, out-of-bounds index, a failed int() parse, a missing table key, a quarantine violation — is catchable the same way.

Tests

A definition named test_* takes no arguments, must be pure, and passes by returning a nonzero value. Results are cached keyed by the test's content hash; since a hash pins the whole dependency cone, a cache hit is a proof that the rerun would be identical.

5. Effects and capabilities

A definition declares the parts of the outside world it may touch:

!io   !fs   !net   !env   !time   !rand   !proc

Order is free; the set is canonical, and fmt renders it in the order above. !io is rigid's own console and file builtins — print, input, read_file, write_file — and keeps exactly the meaning it has always had. The rest describe the host boundary and are declared on extern.

Capabilities are part of canonical form, so they are part of identity: a definition that gains !net gets a new hash, and an importer's sidecar sees drift. The sidecar also records the capability set at the moment of pinning, which is what lets the drift say which kind it is — W0405 names the widening, and --frozen refuses it. A dependency that starts reaching the network is a build failure, not an audit finding. rigid caps lists the whole set with the externs that supply it, complete by construction rather than by search.

The rule is one line: a definition must declare every capability it can reach. A violation is E0207, naming the capability that is missing. Propagation flows through dispatch tables and dyn sites — a site is !io if any declared target is — so a pure-looking dispatcher over a table containing one effectful handler is rejected. Temporal calls are always !io.

6. Quarantined dynamism

&name creates a first-class reference; creating one is a static edge in the graph. Reference values may be invoked only through a declared quarantine:

dyn { f, g }(callee, args...)

Each target resolves at compile time and is an edge at that site. At runtime the callee must be a member of the declared set, or evaluation stops with an error naming the value and the set. Calling a value outside a dyn block is E0204, and the compiler emits the inferred set as an I0405 hint.

Dispatch tables

A table is the named, data-keyed form of the same idea, and it is a definition: it hashes over its key-sorted entries, appears in deps and rdeps, and rides the sidecar rules when imported. name[key](args...) dispatches through it. The site's static edge is the table; the table's edges are its whole value set, so blast radius and effects flow through in two exact hops.

Keys are ordinary runtime data; the value set is closed. A missing key fails at the boundary and lists the available keys. Targets must be functions — direct calls of a table, dispatch through a non-table, and non-function targets are all E0208.

Argument counts are checked at compile time at every call form: direct calls, every declared dyn target, and every table entry (E0209). Arity is the first type in the language, admitted because it narrows the quarantine — violations that would have been runtime membership failures become compile errors.

7. Canonical form

Resolution precedes hashing. Every name occurrence resolves to exactly one binding:

• Local(slot) — parameters then lets, numbered in binding order per function. A let name is bound after its initializer.
• Def(id) — a top-level definition: same module first, then imports.
• Anything else is E0201 (unresolved) or E0203 (ambiguous — an imported name colliding with a module-local definition, or a duplicate definition).

canon(def) is then a tagged byte string, and hash(def) = SHA-256(canon(def)), computed in dependency post-order so every reference payload is already available.

8. Encoding table

Tags are frozen. Extend only by appending.

9. Invariants

What identity means, stated as guarantees:

• Renaming does not change a hash. This holds for a parameter, a let, a definition, or anything a definition references.
• Changing structure does change a hash. Literals, operators, or the content of anything transitively referenced. A hash pins the exact implementation and its whole dependency cone.
• Whitespace and comments never matter. They do not survive parsing.
• Field order and declaration order never matter. Records sort by field name; module identity sorts member hashes and excludes names.

The corollary that surprises people: names that are data rather than bindings are part of identity. Record field names and table keys are hashed; definition, parameter, and let names are not.

10. Cycles

Direct self-recursion in a singleton component uses SelfRef (0x05). Mutual recursion is legal: the reference graph is condensed into strongly-connected components (Kosaraju) and hashed in dependency order.

For a multi-member component every intra-component reference encodes as CREF (0x0A) plus a u32 ordinal. Member ordering must itself be name-free, so members are first encoded with placeholder ordinals (0xFFFFFFFF) and sorted by those bytes. Component bytes are then 0x21 + u32 count + members in order with real ordinals; component_hash = SHA-256(component bytes); and each member's identity is SHA-256(0x22 + component_hash + u32 ordinal).

11. The binding sidecar

Each module carries <module>.rg.bind.json, a resolution lockfile. It does not pin content — content evolves in text, where it belongs. It pins which definition each imported name means, by hash. It is diffable, mergeable, reviewable, deliberately shaped like Cargo.lock, and deliberately per-module so parallel edits do not collide in one giant file.

{
  "format": "rigid-bind/0",
  "definitions": { "norm": "sha256:…", "fib": "sha256:…" },
  "references": {
    "clamp": { "target": "util.rg#clamp", "hash": "sha256:…" }
  }
}

definitions lists the module's own definitions and is informational: it makes within-module drift visible in ordinary diffs and feeds tooling. references is normative.

The import statement names the target module; the sidecar pins the identity of what the name bound to there. Text can change freely; the sidecar is how the compiler distinguishes a name's meaning moving from its target being edited.

12. Reconciliation rules

For each imported name n pinned as hash h, checked against the target module's current name→hash table:

R2 and R4 are the point of the language. R2 is the silent-rebind refusal: in a name-bound language, re-using a name quietly changes the meaning of every existing reference; here it cannot. R4 is rename detection by identity: the compiler recognises the renamed definition by hash and hands back a mechanical fix. I0406 applies the same recovery to same-module renames.

rigid fix --apply mechanically applies rename_reference fixes — only occurrences the resolver marked broken, so an unrelated local sharing the name is untouched — and iterates until check converges. rebind fixes are never auto-applied: accepting a changed meaning is a decision, so it is its own command. Under --frozen, any required sidecar write is an error, so the build is reproducible or it fails.

13. memo

memo fn f(a, b) { ... }

Results are cached under (definition hash, canonical argument encoding). Sound by construction: purity is required — if the dependency cone reaches !io the compiler emits E0211 — and the hash covers the entire cone, so any change that could alter the result changes the key. Staleness is impossible by construction rather than detected.

The cache persists across processes in .rigid-memo.json at the workspace root. The memo flag is an execution annotation, not meaning: toggling it does not move the definition's hash. dyn inside a memo function is sound, because the declared set is inside the hashed cone. The JS target runs memo functions uncached.

14. Temporal references

On every green check, each definition is written to .rigid-store/ under its hash: the source slice with its own name and every resolved reference rewritten to d_<hash12>, plus an index of dependency hashes. A stored cone is therefore a self-contained module.

@"<hash-prefix>"(args)

This calls that version live: the cone is materialized into a synthetic workspace, checked, and executed against its old meanings. Temporal calls require !io at the caller, because a past version's effects are unknown. The store is content-addressed and immutable — a hash is never rewritten, only added. rigid recall <prefix> [args] is the CLI form. The JS target refuses temporal calls at runtime.

15. Externs

extern fn name(a, b) !io = "host.path";

An extern declares a foreign function as a boundary node in the graph. It has arity (checked at every call form), an effect (propagated exactly), and a content identity over the declaration itself — so a changed host path is W0401 drift like any other meaning change.

The rigid VM refuses extern calls with a directive error; build --target js emits an arity-shaped wrapper over the dotted global path, which must be a valid identifier path (anything else is refused at build time, never emitted as executable text).

Declarations are trusted for arity and effect; values are not. Every extern return is checked at the boundary in emitted code. Integers, strings, and lists or records of the same pass through; booleans coerce to 1/0; non-integer numbers, null, undefined, and host objects are refused with an error naming the extern, so a float cannot enter rigid arithmetic silently. Integer-valued host numbers (for example Math.sqrt(4)) pass, because they are rigid integers.

16. Semantic diff

rigid diff compares two revisions as sets of identities and answers two questions separately, because they have different victims. Meaning: did any definition's hash move? Equal hash sets prove that none did, whatever the text shows. Surface: did any name or module move? Behaviour is intact, but callers outside the workspace refer to definitions by name. A pure refactor is meaning unchanged, surface changed — a pair that is not expressible in a language where a rename is an edit.

Every definition lands in exactly one bucket: renamed, moved, changed, added, or removed. Identity is matched before name, so a name re-used for something new reads as a rename plus an addition — the same event E0202 refuses to let happen silently.

17. Merge

rigid merge merges three revisions by definition rather than by line. Definitions are paired across revisions by identity first and name second: a surviving hash is the same definition whatever it is called, and a surviving name is the same definition whatever it now does.

Name and body then resolve independently. Two sides that renamed differently conflict on the name; two sides that edited differently conflict on the body; one of each does not conflict at all, and both changes survive. That last case is the one a line-based merge reports as a conflict, because it cannot see that the two edits are about different coordinates.

-o DIR writes the merged workspace. Bodies move as text, comments included — text is authoritative for content, so a merge relocates it rather than regenerating it from the graph. References inside a moved body are rewritten to the merged names, skipping string literals. Conflicts are refused rather than marked: nothing is written until they are resolved.

18. Diagnostics

Codes are stable and never renumbered. --json emits an array of {code, severity, file, span, message, data, fixes}, where fixes are typed and mechanically applicable (rename_reference, rebind, quarantine_call, add_dyn_targets). Machine consumers are first-class readers of compiler output.

19. CLI

Every command accepts --root DIR to select the workspace. RIGID_CACHE_DIR relocates the test and memo caches so CI and a working copy can share one — the keys are content hashes, so a result computed anywhere is valid everywhere. RIGID_TIMING=1 reports where check spends its time.