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 that declares one or more async members (interface method, action, or operation) and carries the required @@[async] header attribute. Its public methods are generated as the host language’s asynchronous form (async/await, CompletableFuture, Future, …). An async system is emitted as two classes — a public casing that enforces single-driver entry and a private machine that holds the dispatch core. Declaring an async member without @@[async] is the hard error E720. 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.

casing

The public class framec emits for an async system — the one bearing the user-declared name. Each interface method is a gated wrapper that enforces the single-driver contract (raising E703 on concurrent external entry), then delegates to the private machine and clears the gate on both the success and the error path. Operations and persist save/load pass through without the gate. The casing is the only surface external callers and composition touch. Introduced in RFC-0043. See language reference § Async.

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, which calls the router and the current state’s dispatcher. See runtime walkthrough § Step 1.

dispatcher

(_state_<State> in generated code.) A state’s own event-handling function — one per state — that matches a frame event’s message to that state’s event handler (or does nothing if the state has no handler for it). Selected and called by the router. Not to be confused with dispatch, the runtime act of routing an event: the dispatcher is the per-state function that performs the final match. See runtime walkthrough § Step 2.

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.

framec

The Frame transpiler: the command-line tool that reads a Frame source file, expands its @@system blocks into an idiomatic state-machine implementation in the file’s target language, and passes all native host code through unchanged. framec is the canonical name for the tool in both prose and CLI examples (framec source.fpy -l rust). Its formal project name is the framepiler.

framepiler

The formal project name for framec — the Frame transpiler. The two names refer to the same tool: “framepiler” is the project/repository name, while framec is the binary and the name used throughout the guides. Architecture: framepiler design.

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.

kernel

(__kernel.) The per-system runtime entry point for one dispatch: an interface-method wrapper builds a frame event and hands it to the kernel, which calls the router and then drains any pending transitions. One kernel per system; it holds no state-selection logic itself. See runtime walkthrough § Step 2.

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.

Two other senses of the word appear in the docs: colloquially, machine is Frame’s shorthand for the whole automaton (the systems it generates), and an async system emits a distinct private class — see machine (async system).

machine (async system)

The private class (_<Name>Machine) framec emits for an async system, holding the actual dispatch core — kernel, router, state methods, transition loop, and lifecycle cascades. It is the previous-release single-class emission minus the public name; self-calls and kernel-internal dispatch run against it directly, bypassing the casing’s gate. It is internal: user code must not name _<Name>Machine directly. Distinct from machine (the machine: block of states) and from the colloquial use of machine for the whole automaton. Introduced in RFC-0043.

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.

router

(__router.) The single dispatch primitive: it reads the current state name from the leaf compartment and calls that state’s dispatcher — one if/elif branch per state. Invoked by the kernel. See runtime walkthrough § Step 2.

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 transpilation 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.

transpiler

A source-to-source translator: a tool that reads source in one language and emits source in another, rather than producing machine code or bytecode. framec is a transpiler — it turns Frame @@system blocks into target-language source (Python, Rust, TypeScript, …) that a developer reads, edits, and compiles with that language’s own toolchain. Frame uses transpiler (verb: transpile) throughout the documentation.

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 framec-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 target 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 transpiling 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.