Frame Glossary

Plain-English definitions of the terms used across the Frame documentation — the language reference, the runtime walkthrough, the cookbook, the per-language guides, and the RFCs. When one of those documents uses a term defined here, it links to the term’s entry on first use rather than redefining it.

Each entry gives a one- or two-sentence definition and a cross-reference to the section that specifies it normatively. The language reference is the source of truth for syntax and semantics; the runtime walkthrough is the source of truth for runtime behavior; an RFC is the source of truth for a feature the language reference has not yet absorbed.

Word-named terms are listed alphabetically. Symbol-named terms (those starting with @, $, or other punctuation) are collected in Symbols at the end.

action

A private helper procedure declared in a system’s actions: block. Actions can read domain variables and the system / self / return accessors but cannot fire transitions or push / pop the state stack. See language reference § Actions Section.

async system

A system whose interface methods are generated as the host language’s asynchronous form (async/await, CompletableFuture, Future, …) while its internal dispatch stays synchronous. Enabled by an async modifier on interface methods. See language reference § Async.

backbone

The top-level coordinating system of a parser written in Frame: its states correspond to the grammar’s major nonterminals (a section, a state, a handler), and it drives the parse forward, handing focused sub-problems to oracles. Named for being the structural spine the specialists attach to. framec’s own parser is organized this way — one SystemBackbone system whose flat self-looping states cover the entire token-level outer grammar. See RFC-0039.

compartment

The runtime object holding everything specific to one occupancy of a state: the state’s identity, its state variables, and the state-args / enter-args / exit-args passed when it was entered. A new compartment is created on every transition; the state stack is a stack of compartments. See language reference § Compartment.

composed system

(Also: nested system.) A system that holds another @@system instance as a domain field, e.g. domain: inner = @@Inner(...). The parent’s factory constructs the child by calling the child’s factory; the parent’s restore reconstructs the child by allocating it with no-initialization and recursively loading. See RFC-0015.

construction

Creating a fully-initialized system instance: allocate the object, then run the start state’s $Start(...) body and its $> enter handler. The user-facing entry point for construction is the factory. Contrast no-initialization. See RFC-0015.

dispatch

The runtime act of routing an incoming frame event to the event handler for the current state — walking up the HSM parent chain if the current state forwards. Performed by the per-system kernel function. See runtime walkthrough § Step 1.

domain

A system’s persistent, instance-level data, declared in the domain: block. Each entry is a domain variable (also domain field) with an initializer expression. Domain variables live for the lifetime of the system instance — unlike state variables, they are not reset by transitions. See language reference § Domain Section.

domain-param

A system parameter with no sigil, supplying the initial value of a domain variable of the same name. See language reference § Domain params.

enter-args

The arguments passed to a state’s $> enter handler when that state is entered, carried on the new compartment. Declared on the state via $>(name: type); supplied at the transition or instantiation site with the $>(...) sigil. See language reference § Enter Handler.

enter-param

A system parameter tagged with $> that flows into the start state’s enter-args. See language reference § Enter params.

event handler

(Also: handler.) The block a state runs in response to a named event — an interface method call, an $> enter, an <$ exit, or a forwarded event. See language reference § Event Handlers.

exit-args

The arguments passed to a state’s <$ exit handler when that state is left. See language reference § Exit Handler.

factory

The auto-generated construction entry point for a system: it allocates the instance, routes the system parameters into the right channels (domain initializers / state-args / enter-args), runs the start state’s $Start(...) body and $> handler, and returns the initialized instance. Named with @@[create(<name>)]; its per-backend call shape is specified by RFC-0017. See RFC-0015.

forward

(Also: event forwarding.) A handler that re-dispatches the current event to its parent state, written => $^. The basis of hierarchical state machines. See language reference § Forward to Parent.

frame context

(FrameContext.) The per-call runtime object carrying the in-flight event, the return-value slot, the @@:params view, and the dispatch-scoped @@:data store. A stack of frame contexts (the context stack) exists so a self-call nests cleanly. See language reference § System Context.

frame event

(FrameEvent.) The runtime object representing one dispatched event: its name and its positional parameters. See runtime walkthrough § Step 1.

hierarchical state machine (HSM)

A state machine in which a state may declare a parent state and forward (=> $^) unhandled events up the chain. Frame supports a parent chain up to three levels deep. See language reference § Hierarchical State Machines.

interface

A system’s public API, declared in the interface: block: the named methods callers may invoke. Each interface call is dispatched to the current state. See language reference § Interface Section.

load

The deserialization half of the persist contract: an instance method that takes a serialized blob and overwrites the instance’s domain and compartment state without running any construction code. Named with @@[load(<name>)]. The clean restore pattern allocates a target with no-initialization (@@!Foo()) and then calls load. See RFC-0015 and language reference § Persistence.

machine

A system’s state machine, declared in the machine: block: its states, their handlers, and the transitions between them. See language reference § Machine Section.

no-initialization

Allocating a system instance without running any construction code — no $Start(...) body, no $> handler. The Frame source expression is the @@!Foo() sigil (always zero-argument). Used with @@[load] to restore a persisted instance: allocate with no-initialization, then deserialize. What @@!Foo() becomes in each target language is specified by RFC-0017; the design is in RFC-0015. (Earlier drafts called this “blank allocation”; the current name is “no-initialization”.)

Oceans Model

Frame’s principle that anything in a source file outside an @@system block — imports, package declarations, free functions, helper classes, comments — is emitted into the generated target file verbatim, in position. framec does not parse or rewrite this pass-through text; it knows only that the text is not Frame. The name evokes “islands of Frame in an ocean of native host code.” See framepiler design § Segmenter.

Calibration. The Oceans Model is a pragmatic decomposition — the transpiler touches @@system blocks and passes through everything else verbatim. It is architectural humility, not a theoretical breakthrough. Avoid framing it as a paradigm shift in writing or in conversation. The open question of whether it can be elevated to a calculus (with a preservation theorem and pre-backend normalization passes) is captured in RFC-0026 as an exploration thread, not a commitment.

operation

A non-handler method declared in a system’s operations: block. Unlike interface methods, operations are not dispatched to a state — they run directly. Non-static operations may read domain variables and @@:return. See language reference § Operations Section.

oracle

A small, focused machine that a backbone consults to answer one bounded question or parse one sub-structure (e.g. “capture this balanced expression”); it returns a result and the backbone transitions on it without needing to know how it was reached. The name is borrowed from the computer-science oracle machine — a sub-machine treated as a black box. Concretely, an oracle is another Frame system (or scanner) the backbone calls, as framec’s parser does with the dogfooded attribute / expression scanners. See RFC-0039.

parameterized system

A system whose header declares system parameters — state-args, enter-args, and/or domain args — that the factory requires at construction time. See language reference § System Parameters.

persist contract

The set of rules and generated code that makes a system serializable: @@[persist(<type>)] names the host-language type of the serialized blob (see the @@[persist(<type>)] entry), @@[save(<name>)] and @@[load(<name>)] name the two operations, and framec generates both bodies. Load bypasses construction. Domain fields tagged @@[no_persist] are excluded from the blob. See language reference § Persistence, RFC-0012, and RFC-0015.

push / pop

State-stack operations. push$ (often push$ -> $State) saves the current compartment on the state stack and transitions to a new one; -> pop$ discards the current compartment and resumes the one on top of the stack. The mechanism behind modal sub-flows. See language reference § Stack Push and § Stack Pop.

restore

Reconstructing a system instance from a serialized blob: allocate the instance with no-initialization, then call load. For a composed system, the same pattern recurses into nested @@system domain fields. See RFC-0015.

save

The serialization half of the persist contract: an instance method that returns a blob containing the system’s domain fields, compartment, and state stack (and any nested @@system domain fields). Named with @@[save(<name>)]. See language reference § Persistence.

start state

The first state declared in a system’s machine: block — the state the system occupies immediately after construction. Its $Start(name: type) header receives the state-args; its $> enter handler receives the enter-args. See language reference § System Parameters.

state

A named node in a system’s machine. The system is always “in” exactly one state; an event handler in that state runs when a matching event is dispatched. See language reference § State Declaration.

state-args

The arguments bound to a state’s $Start(...)-style parameters when that state is entered, carried on the new compartment. Declared on the state; supplied at the transition or instantiation site with the $(...) sigil. See language reference § State params.

state-param

A system parameter tagged with $(...) that flows into the start state’s state-args. See language reference § State params.

state stack

The stack of compartments maintained by push$ / pop$. The current state is the compartment on top; pushing saves it and starts a new one; popping discards the current one and resumes the saved one. See language reference § State Stack = Compartment Stack.

state variable

A variable scoped to a single state (declared inside the state), reset to its initializer each time the state is entered. Distinct from a domain variable, which persists for the instance’s lifetime. Accessed with $.name. See language reference § State Variables.

system

A Frame state machine as a unit: the @@system declaration with its interface:, machine:, actions:, operations:, and domain: blocks. The compilation target. See language reference § System Declaration.

system context

The runtime façade through which a handler reads call-scoped information: @@:return, @@:params, @@:event, @@:data, @@:system.state, and @@:self. Backed by the frame context stack. See language reference § System Context.

system parameter

A parameter declared in a system’s header. Frame distinguishes three groups by sigil: $(...) → state-param, $>(...) → enter-param, bare → domain-param. The factory routes each group to the appropriate channel. See language reference § System Parameters.

transition

Moving the system from one state to another, written -> $Target (optionally with $(...) / $>(...) argument groups). A transition runs the old state’s <$ exit handler, creates a fresh compartment for the target, and runs the target’s $> enter handler. See language reference § Transition.

Symbols

`@@`

The system context token. On its own it introduces a context accessor (@@:return, @@:params.x, @@:event, @@:data.k, @@:system.state, @@:self.method(...)); as a prefix it tags compiler-recognized constructs (@@system, @@[...] attributes, @@SystemName(...) instantiation, @@!Foo()). See language reference § System Context — @@.

`@@system`

Declares a Frame system. See language reference § System Declaration.

`@@[...]` (attribute syntax)

An @@[name(args)] annotation attached to a declaration (file, system, or domain field). See language reference § @@[target(...)] and RFC-0013.

`@@[target(...)]`

File-level attribute selecting the code-generation backend. See language reference § @@[target(...)].

`@@[main]`

System-level attribute marking the module’s primary system (the one a caller instantiates as the module’s entry point). See RFC-0014.

`@@[persist(<type>)]`

System-level attribute marking a system serializable. <type> is the host-language type of the serialized blob — the return type of the generated save method and the parameter type of the generated load method. It is not a fixed set: you write your language’s string-or-byte-buffer type (bytes in Python, String in Rust/Java/Kotlin/Swift/Dart/PHP, string in C#/Go/JS/TS, char* in C, std::string in C++, PackedByteArray or String in GDScript, binary in Erlang). framec emits it verbatim into the save/load signatures and does not interpret it; the per-backend serialization library (serde, Jackson, nlohmann/json, pickle, cJSON, …) does the actual encoding. So <type> is “what the blob looks like to your code”, not “what format is inside it”. Companion attributes: @@[save(<name>)] / @@[load(<name>)] name the methods (next entry); @@[no_persist] excludes a domain field. See persist contract, language reference § @@[persist], RFC-0012, and RFC-0016 (the proposed system-level inclusion list).

`@@[save(<name>)]` / `@@[load(<name>)]`

System-level attributes naming the generated save and load operations. See RFC-0015.

`@@[create(<name>)]`

System-level attribute naming the generated factory. See RFC-0015.

`@@[no_persist]`

Domain-field attribute excluding the field from the serialized blob; after restore the field holds its domain: default (typically null for a resource handle, which the user reattaches explicitly). Applies only to domain: fields — not state variables or the rest of the compartment bookkeeping, which is always persisted. Specified in RFC-0016.1; see also persist contract.

`@@import`

Module-level analysis directive naming a Frame source file — @@import "./other.frm". It tells framec where a referenced system’s source lives so framec can read it while compiling the current file: to check this file’s use of that system (argument arity/types, existence) and to resolve cross-file facts code generation needs (notably a composed child’s save / load method names). It is not a code-generation directive — framec emits no import line and no target code for an imported system; native host imports remain Oceans Model pass-through. Removed by RFC-0024 (which deleted the original analysis-and-emission directive); re-introduced in analysis-only form by RFC-0040.

`@@SystemName(args)`

Instantiation expression: construct a system instance by calling its factory. See language reference § System Instantiation; the per-backend call shape is in RFC-0017.

`@@!Foo()`

No-initialization allocation expression: produce an instance of Foo without running any construction code. Always zero-argument. Used with @@[load] for restore. See RFC-0015 (design) and RFC-0017 (what it becomes in each target language).

`$>` (enter handler)

A state’s enter handler: the block run when the state is entered. Receives enter-args. Since RFC-0019, $> is an ordinary leaf-dispatched event — only the current state’s $> runs on entry. Ancestor $> handlers run only if the leaf explicitly forwards via => $^ (placement in the handler body controls order). See language reference § Enter Handler and RFC-0019.

`<$` (exit handler)

A state’s exit handler: the block run when the state is left. Receives exit-args. Since RFC-0019, <$ is an ordinary leaf-dispatched event — only the current state’s <$ runs on exit. Ancestor <$ handlers run only if the leaf explicitly forwards via => $^ (placement in the handler body controls order). See language reference § Exit Handler and RFC-0019.

`$Start(...)`

A start state’s parameter header, receiving the state-args that flow from $(...)-tagged system parameters.

`@@:self.method(args)` (self-call)

Invoke one of this system’s own interface methods through the dispatcher (so it re-enters cleanly, with the automatic transition guard). See language reference § Self Interface Call and RFC-0006.

`@@:return`

The current call’s return-value slot: @@:return = expr sets it, @@:return reads it. Shorthand @@:(expr) sets it and is the common form in handlers. See language reference § System Context — @@.

`@@:system.state`

The name of the current state at runtime. See language reference § Current State.

How to use this glossary

Documents (language reference, runtime walkthrough, cookbook, per-language guides, RFCs) use these terms without re-defining them, and link to the term’s entry on first use.
New terms get an entry here before or with the RFC or feature that introduces them — never after.
When a term’s canonical name changes, update the entry and leave a parenthetical note about the old name (see no-initialization for an example), so a reader who encounters the old name in history can find the current one.