Flux — Language & FDK documentation

Flux is a total, causal, deterministic application language for the web platform. A Flux program is not a sequence of instructions — it is a typed dataflow graph: every value is a stream, every stream carries a kind (its dimension, not only its shape), and the engine — not the author — owns evaluation, incrementality, memory and scheduling. Four cooperating planes separate what a program computes (ANALYSIS) from what it shows (CANVAS), how it animates between states (TRANSITION), and how it interacts and persists (APP) — with a one-way firewall between them that makes the core guarantees structural rather than disciplinary.

The language ships with the FDK (Flux Development Kit): the standard prelude and the pillar APIs — compute (dataframes, statistics, domain math), collections, color, text, i18n, units, networking, display, host services, the server plane, and asset/currency identity — all bounded, capability-gated, and specified to the same determinism bar as the core.

One dataflow VM stands behind many kinds of application — a live chart, an interactive interface, an animated scene, a server-checked game — because the four planes span compute → show → animate → interact. Flux is general-purpose; its domain specializations ride on top, and the flagship is financial charting and market analytics, which is why many examples plot prices — though nothing in the model is specific to markets. One line is enough to see the character of the language:

fluxplot rsi(close, input(14))   // osc(0,100) → its own pane, 0–100 scale, 30/70 guides, params UI — all inferred

#Reading paths

• New to Flux — read the book in order: What is Flux → Design pillars → Getting started → The four planes.
• Writing programs — the cookbook, then the FDK reference for the API you need, with the language reference at your elbow.
• Evaluating the guarantees — Guarantees, then Compiler & runtime and Kinds.
• Extending the host (representations, tools, panes) — Host integration.

#The map

#The book

#Language reference

#FDK reference

#Internals

#Guides

#Implementation status

The documentation describes Flux v1 as specified by the sealed design plans (docs/DESIGN-flux-*.md). Status at a glance:

Individual pages do not repeat this table; features the design itself defers are labelled Post-v1, Reserved, or Open decision inline (see the conventions below).

#Conventions used throughout

• Kinds are written in code style: price, level, osc(0,100), signal, vec(κ, N), record{…}.
• Error codes are verbatim and load-bearing: [ErrDim], [ErrCausal], [ErrTotal], [ErrFirewall], [WarnTop]…
• Invariants are numbered I1–I7 (the clock/determinism contract); amendment rules A1–A15 refine the kind system.
• Sample lines carry teaching annotations: plot x // level → centered pane ; rejected forms are marked // ✗ [ErrDim] ….
• Post-v1. / Reserved. / Open decision. label design-deferred material inline.

#See also

• What is Flux — start here if the language is new to you.
• Getting started — the first program, and what it infers for you.
• Kinds — the dimensional type system everything else leans on.
• Guarantees — what is promised, and how each promise is machine-checked.
• FDK overview — the libraries and the capability model.
• Glossary — every term, precisely defined.

What is Flux

Flux is a total, causal, deterministic application language for the web platform. It is a general-purpose language with domain specializations — financial charting and market analytics are the flagship specialization, not the definition. You can write an indicator in one line, an animated scene in five, or a complete interactive application in fifty; all of them are the same kind of object: a pure dataflow graph over typed streams, executed by a host that guarantees — by construction, and verified by machine — that the program terminates, never rewrites its own past, produces the same bytes on every machine, and can touch nothing it was not explicitly granted.

This chapter gives you the shape of the whole language: the one idea underneath it, the four planes a program is made of, what programs look like, where they run, whom they are for, and what Flux deliberately does not do. Everything here is unpacked in later chapters; nothing here requires prior knowledge of Flux or of trading.

#One idea: every value is a stream

A Flux value is not a number sitting in a variable. It is a stream: a value as it evolves along an ordered axis of data units — sensor readings, log entries, game turns, or (in the flagship domain) market bars. close is not "the latest price"; it is the whole history of closing prices, one value per unit, up to now.

Everything follows from taking that seriously:

• A constant is a degenerate stream — the same value at every unit. 2 and close are the same kind of thing, so they combine freely.
• Arithmetic is element-wise. fast - slow subtracts two entire histories, unit by unit — yet the engine evaluates it incrementally, one new value per new unit.
• There is no index and no loop. You never write for i, never manage a buffer, never decide when to recompute. You describe what a value is, not when to update it.

fluxfast = ema(close, 12)          // a stream: the 12-unit exponential average, over all history
slow = ema(close, 26)
plot fast - slow               // element-wise difference — itself a stream

Because streams are values, ordinary functional composition is the whole programming model: functions from streams to streams (def), records of streams (bb.upper), streams of records, streams driving visual properties. There is one algebra, applied everywhere.

#Describe an expression; the engine evaluates

The mental model in one sentence: you describe a pure expression, the engine evaluates it. You never write the loop, the buffer, or the await. The compiler inlines your definitions into a typed incremental DAG (directed acyclic graph) of operations, checks it — kinds, causality, totality, plane boundaries — chooses a native kernel for each node it recognizes, plans its memory statically, and then runs it either per unit (live, one step per new data unit) or in batch (full-history replay). Both runs are the same function and produce the same bytes.

This is why a Flux program has no lifecycle code. There is no "on new bar" callback, no subscription management inside ANALYSIS code, no cache invalidation: the DAG is the dependency graph, and the engine advances it. It is also why the engine can make strong promises — a pure, typed, bounded, acyclic graph is an object you can verify, schedule, parallelize and optimize without changing its meaning.

#Four planes, one one-way firewall

A complete application has parts with very different needs. A computation must be exact and reproducible. An animation must read the clock and may use randomness. A screen transition must be able to interpolate freely without corrupting data. Application state must respond to user events and drive effects. Flux does not average these needs into one compromise; it separates them into four cooperating planes — one language, one expression algebra, four sets of rules:

The planes are joined by a firewall with a single direction: presentation may read analysis; analysis never reads presentation. A CANVAS scene may glow brighter when an ANALYSIS value rises; an ANALYSIS expression that tries to read the mouse, the wall clock or an unseeded random signal is rejected at compile time with [ErrFirewall]. The APP plane reads series through typed subscriptions and can never write into ANALYSIS.

Why this rule exists. The firewall is what lets guarantees and freedom coexist in one program. Your signal remains provably no-repaint — a value, once produced for a step, never changes — even while an animated, randomized effect dances right next to it, because the language makes it impossible for the effect to feed back into the signal. Every value that matters lives on the disciplined side of the wall; everything decorative lives on the free side.

Chapter The four planes covers each plane in depth.

#What a program looks like — three tastes

#An analytic, in one line

fluxplot rsi(close, input(14))     // rsi : osc(0,100) → own pane, 0–100 scale, guides 30/70

That single line is a complete, shippable program. Everything else is inferred from the kind of the expression — the dimensional type that says what the value is physically, not merely how wide it is:

• close has kind price; rsi maps any scalar quantity to osc(0,100) — a bounded, dimensionless oscillator.
• An osc(0,100) shares no scale with price, so it materializes in its own pane rather than on the price chart — with a fixed 0–100 scale.
• The conventional guide lines at 30 and 70 come from the operation's metadata and are drawn automatically.
• input(14) declares a parameter: the editor derives a control for it, the tuned value lives with the chart instance (the source keeps the default), and adjusting it re-runs the graph without recompiling.
• The series is registered — name, render style, semantic class, even its accessibility description — all derived from the kind.

Nothing about placement, scale, reference lines or parameter plumbing is written anywhere, and none of it needs to be. When you do want control, every one of these defaults is overridable in place — see Getting started.

#A scene that moves

fluxcircle { at:(spring(close)); glow: 16; trail: 24 }         // a comet easing toward the price
on every(1 bars) -> spawn ring { r: 6->24; life: 200 bars }

This is the CANVAS plane. Its axiom: every property is a signal. A constant, a data stream, and an animation generator like spring(close) — a signal that continuously eases toward its target — are the same kind of thing and combine with the same algebra. There is no separate animation API to learn: you wire signals into properties, and events (on … ->) spawn or tween primitives. The scene compiles once into a retained structure; the host routes each signal to the cheapest execution path (cached, per-unit, or compositor-driven).

#An application

fluxvariant Msg { Inc | Reset }
app counter {
  init(p) = { n: 0 }
  update(m, msg) = match msg {
    Inc   -> { model: m with { n: m.n + 1 }, cmds: [] }
    Reset -> { model: m with { n: 0 }, cmds: [] }
  }
  view(m) = panel(slot: right.panel) { text("count {m.n}") ; button("+1", Inc) }
  subs(m) = []
}

This is the APP plane: The Elm Architecture (TEA), hardened. A Model (bounded, typed state), a pure and total update that folds messages into new state plus a list of commands — inert effect descriptions the host may execute — a pure view that returns a tree of vetted UI primitives, and declarative subscriptions (subs) through which the ambient world (time, data, user gestures) enters as messages. Because update is a pure fold over a message journal, application state is replayable by construction: the journal is the single source of truth. This app requests no capabilities, so the host will let it do nothing beyond drawing its view and receiving its own messages.

#One arrow, five readings

You have now seen the arrow -> three times, meaning three different things — an event's action, an arm of a match, and (in the next chapter) a lambda. That is deliberate, and it is the one piece of syntax worth learning up front, because Flux has exactly one arrow token and it carries five readings, each selected by its context:

The parser never has to guess: a keyword head claims the arrow, and everywhere else the kind of the position decides. The reward is that you never carry a table of arrow-like symbols in your head — there is one, and you read it from its context.

#Where programs run

A Flux program has two execution vehicles and one meaning. While you edit, an interpreter evaluates the DAG directly — instant feedback, per-node values the debugger can read, live preview on every keystroke. When a program runs for real — or ships to someone else — it is compiled to a WebAssembly module and executed in a sandbox. The two are not "close": they are bit-identical. Invariant I7 requires the interpreter and the compiled module to produce exactly the same bytes on the same inputs, and the toolchain verifies this at every compilation by running both and asserting equality — a divergence blocks the artifact from shipping. The same discipline extends across machines: floating-point evaluation is scalar and unreassociated, and every routine with room for platform variance (transcendental math, decimal arithmetic, Unicode, calendars, random generation, the representation of missing values) is pinned to one shared implementation. What you saw in the editor is what runs, everywhere, to the last bit. The machinery is specified in Compiler and runtime.

#The language of a platform: two trust tiers

Flux is not an embedded extension niche; it is the language the platform itself is written in, and the language its users extend it in. Both audiences share one language and one sandbox, distinguished only by trust — the capabilities granted, never the code:

• Tier A — first-party. The platform's own interface, including its most demanding tools, is written in Flux. Its source stays private and ships as compiled WASM — the strongest possible statement that the language is sufficient for real applications.
• Tier B — authors and users. Anyone can write indicators, representations, drawing tools and applications. A shared or purchased artifact arrives as WASM only, never source: the author's work is protected, and the consumer runs an untrusted binary safely — because scripts are total (they cannot run away), sandboxed (the language has no I/O primitives to abuse), and default-deny: every effect requires a capability, and an artifact carries an inspectable, transitively aggregated manifest of everything it may ask for, visible before installation.

Post-v1. The public sharing and marketplace rollout is deferred; the trust model that makes it safe is v1 and is not weakened anywhere.

#What Flux deliberately does not do (v1)

Honest limits are part of the design. Each of these is a choice with a rationale, not a gap:

• No free-running loops. Flux is total, not Turing-complete — by choice. Windows, folds and loops exist, but every bound is a compile-time constant under a cap. A program that cannot state its bound is rejected with [ErrTotal] at compile time rather than killed by a timeout at runtime. (Open decision. An opt-in unsafe escape for an unbounded loop is discussed in the design and discouraged by default; nothing in the catalogue needs it.) See Design pillars.
• No direct I/O from scripts. The language has no fetch, no DOM, no eval, no file handles. Effects are host-mediated: a script emits inert command data under declared capabilities, and the host executes it. This is what makes running untrusted code a routine act rather than a risk assessment.
• Bar-centric time grain. The ANALYSIS clock advances on closed data units. Tick-level and order-flow granularity are a named post-v1 extension, not an implicit promise.
• External non-price data stays out of ANALYSIS. Network-fed data enters the APP plane through typed subscriptions; it cannot silently become an "indicator". Reserved. The metric kind names the seam through which a causal external data stream could later enter ANALYSIS, deliberately held open and inert in v1.
• No market-wide scan, no portfolio management. Cross-series work over a handful of named instruments is first-class; scanning the whole market, and managing many simultaneous positions, are not v1 concerns. (A bounded screener — a total function mapped over a fixed-capacity universe, with a keyed top-K — is a sealed Post-v1. pillar; it is a bounded map-reduce, never an unbounded scan.)
• No automatic code migration. Flux does not ship a converter from other script ecosystems. Its semantics deliberately exclude patterns some ecosystems permit (retroactive history edits, unbounded loops, ambient I/O), so a faithful automatic translation is impossible for a whole class of programs; the documentation instead teaches the equivalent Flux patterns directly.
• Post-v1. Strategy backtesting harnesses, remote alert delivery, and multi-device sync are designed but deferred; local alerts (alert) are v1.

#How to read this documentation

The book (this section) builds the mental model in order:

1. What is Flux — this chapter.
2. Design pillars — the seven guarantees, why each exists, and what each buys you.
3. Getting started — a guided first session, from one line to a small application.
4. The four planes — ANALYSIS, CANVAS, TRANSITION and APP in depth, including the firewall and live values.

Around the book:

• Reference — the normative language: lexical structure, grammar, kinds, operators, inference, time and state, canvas, transitions, the APP plane.
• FDK — the Flux Development Kit: the stdlib prelude and the pillar APIs (compute, collections, color, text, i18n, units, net, display, host services, server, asset/currency) plus the capability catalogue.
• Internals — how the guarantees are implemented: compiler and runtime, memory model, optimizer, concurrency, packages, host integration.
• Guides — the cookbook, the guarantees page, the editor, the FAQ and the glossary.

If you read only one more page, read Design pillars: every design decision in the language traces back to one of the seven.

#See also

• Design pillars — the seven guarantees behind everything above.
• Getting started — write your first program in the next ten minutes.
• The four planes — the plane model and the firewall, in depth.
• Guarantees — what is promised and how each promise is machine-verified.
• FDK index — the author-facing API surface and the capability model.
• README — the documentation map and implementation status.

Design pillars

Every design decision in Flux traces back to seven pillars. Each pillar is a property the language enforces by construction — not a convention, not a linter rule, not a best practice, but something the compiler proves about every accepted program and, where proof needs help, verifies by machine at every compilation. This chapter states each pillar, explains why it exists, spells out what it buys you concretely, and shows it in a micro-example.

Read this chapter to understand why Flux is shaped the way it is; read Getting started to feel it in practice.

#1. Total, not Turing-complete

The statement. Every Flux program terminates, and its cost per step is known at compile time. There are no unbounded loops, no unbounded recursion, no unbounded collections.

Why. Flux belongs to the synchronous-dataflow family (in the lineage of Lustre and SCADE): languages built for systems where "the program might not finish this step" is not an acceptable outcome. A charting host must advance every active script on every data unit inside a frame budget; a platform that runs other people's code must bound what that code can consume. Turing-completeness would remove exactly these guarantees — the halting problem makes an unbounded script impossible to budget — and buys nothing that real analytical programs need. Totality is a choice, and Flux makes it openly.

What it buys you.

• Guaranteed termination. No script hangs, ever — yours or anyone else's.
• A static budget. Memory and cost-per-unit are computed at compile time; a program that exceeds the budget is rejected before it runs with [ErrTotal], with the offending bound named — never killed mid-run by a timeout.
• Sandbox by construction. A total program with no I/O primitives cannot be weaponized into a resource-exhaustion attack. This is the foundation the trust tiers stand on.
• Verifiability everywhere else. Static checks (kinds, causality, exhaustiveness) are decidable because the language is total and its bounds are constants.

In practice. Iteration exists — bounded, and honest about it:

fluxhi20 = highest(close, 20)                        // windowed reducer — the bound is a constant
w    = window(close, 20)                         // the same 20 values as a vec, for map/fold
hi   = scan(close, (prev) -> math.max(prev, close))   // running state with feedback (see pillar 2)

window with map/fold covers counted loops, scan covers running state, and loop(max, …) covers "iterate until done" with a declared ceiling. Every bound is a compile-time constant under a global cap; a data-dependent length is a kind error, not a runtime surprise.

#2. Causal by construction

The statement. A value produced for a step can never change afterwards. History is immutable — not as a discipline the author maintains, but as a theorem of the language.

Why. In any system that re-evaluates over growing history, the deadliest defect is the value that quietly changes retroactively: an analytic that looked prophetic on history because, at each past step, it had silently read data that did not exist yet. The result is a live/replay divergence that no test catches, because both runs are "correct" — for different definitions of time. Flux removes the defect at the root by making it inexpressible: no construct in the language can read the future.

Three rules produce the theorem:

• Delays are past-only. x[n] reaches n steps back, with n ≥ 0 a constant. A negative delay does not parse into a meaning; it raises [ErrCausal].
• Resampling reads only closed units. x @ "1d" reads the last closed daily unit — never the one still forming, and never a future close. (The forming unit is reachable for display only, through live(), which the firewall keeps out of every analysis.)
• Feedback must pass a unit delay. Any cycle in the graph must cross x[1] (the rule scan obeys internally), so today's output may depend on yesterday's output but never on itself.

By induction over the graph: output[t] = f(inputs[0..t]), mathematically. A past value has nothing left to depend on, so nothing can move it. This property is called no-repaint — a value, once produced for a step, never changes — and it holds for every accepted program, not for a careful subset.

What it buys you.

• Live ≡ historical. The stream you compute live and the stream you replay over history are the same function — the honest backbone of any evaluation.
• Trustable signals. A crossing that fired stays fired. Marks and alerts stand on ground that cannot shift.
• Machine-checkable. Causality is a graph property (no zero-delay cycles), decided at compile time — the same clock-calculus idea proven in synchronous languages.

In practice.

fluxprev  = close[1]                 // yesterday's close — legal, and na on the first bar
gain  = math.max(close - prev, 0)
peek  = close[-1]                // ✗ [ErrCausal] — a negative delay reads the future

The rejection comes with its reason: a value from the future would force your past values to change once reality catches up.

#3. Deterministic to the byte

The statement. The same program on the same data produces the same bytes — between the editing interpreter and the compiled WASM, between two runs, between two machines.

Why. "Roughly equal" is not a property you can build on. Byte-equality is: it makes replay exact, golden tests meaningful, results reproducible across devices, and independent re-execution (for example, a server re-checking a client's run) possible at all. Floating point is deterministic if and only if every source of variance is pinned — so Flux pins all of them, as language policy rather than author burden.

What is pinned.

• Scalar f64, no SIMD in the deterministic domain, no FP reassociation. Vector reordering and re-associated reductions change bits; Flux's deterministic core refuses both, and reduction order is fixed.
• Transcendentals (log, exp, sin, cos, tan, atan, atan2, pow) route through one pinned libm build — never the host engine's Math, which legitimately differs by an ULP between engines.
• Decimal, Unicode, calendar, PRNG. Fixed-point money math, string operations (Unicode scalar units, pinned case tables), calendar arithmetic (pinned time-zone data), and the seeded random generator (a counter-based integer PRNG) are each one shared routine, used identically by the interpreter, the compiled module and any re-executor.
• A canonical na. Missing values compare as absent everywhere, and at every storage or hashing boundary na is forced to a single bit pattern — so two engines never disagree on the bytes of "nothing".

The equivalence is not assumed; it is verified at every compilation by running the interpreter and the compiled module on real data and asserting bit-equality (invariant I7). A divergence blocks the artifact.

What it buys you.

• Replay-exact debugging. Step backwards as reliably as forwards; every value is reproducible on demand.
• Tests that mean something. A golden snapshot either matches exactly or the program changed. There is no tolerance to tune and no flakiness to excuse.
• Cross-machine agreement. Two devices — or a client and a verifying server — compute identical results, which is what makes shared artifacts and independent verification honest.

In practice.

fluxr = math.log(close / close[1])        // ratio in, dimensionless out — via the pinned libm, same bits everywhere
x = rand(42)                     // seeded: deterministic, replayable, admissible in ANALYSIS

Unseeded randomness exists — on the presentation side of the firewall (pillar 5), where determinism is deliberately not promised.

#4. Dimensional kinds

The statement. Every stream carries a kind — a dimensional type that records what the value is physically, not merely that it is a number. The kind system computes the kind of every result and rejects operations with no physical meaning.

Why. In analytical code, the worst bugs are not type errors a conventional checker would catch — everything is a float. They are dimension errors: adding a price to an oscillator, comparing a volume to a ratio, feeding a percentage where a level is expected. All of these are well-typed nonsense in a float-only world. Flux gives data its physics back. The price axis is modeled as an affine space: price is a point, level is a displacement (vector), ratio is a dimensionless scalar; dimensions form an algebra under the operators. The pleasant consequences are theorems, not special cases:

fluxrange = high - low                                //   price − price → level  (point − point = vector)
band  = sma(close, 20) + 2 * stdev(close, 20)     //   price + level → price  (point + vector = point)
rel   = close / open                              //   price ÷ price → ratio  (dimensionless)
bad   = close + rsi(close, 14)                    // ✗ [ErrDim] — point + dimensionless: no affine meaning

What it buys you.

• Nonsense is rejected at compile time, with a dimensional explanation and a suggested fix — not a mystery NaN three steps downstream.
• Presentation is inferred. The kind is rich enough to derive display: a price overlays the price axis; an osc(0,100) gets its own pane, a fixed scale and its guide lines; a signal renders as marks. One line of mathematics materializes as a correctly furnished chart because the kind said everything needed.
• Inference is silent until you are wrong. You annotate nothing; kinds flow bottom-up from sources through operators, every expression gets its most precise kind, and the only time you hear about the system is when it saves you.

Kinds are the keystone the other pillars lean on: the memory planner sizes buffers from kinds, the optimizer's cost model reads them, and the editor's completion filters by them. The full system — sorts, the lattice, coercion, operator algebra — is specified in Kinds.

#5. Planes with a one-way firewall

The statement. Computation and presentation are separate planes, and dependence crosses between them in exactly one direction: presentation may read analysis; analysis may never read presentation. Violations are compile-time errors: [ErrFirewall].

Why. A language that promises determinism and wants delightful, animated, interactive output has a problem: screens, wall clocks, pointers and randomness are exactly the things determinism must exclude. The usual outcomes are grim — either the guarantees quietly erode ("mostly deterministic"), or the output layer is starved into lifelessness. Flux refuses the dilemma structurally. Everything non-deterministic — now(), screen coordinates, hover state, unseeded rand/noise — exists, but only on the presentation side (CANVAS, TRANSITION), where nothing downstream depends on exactness. The ANALYSIS and APP planes stay inside the guarantees. The wall between them is directional and compiler-enforced — see the figure in What is Flux.

What it buys you.

• Guarantees that survive decoration. An animated, randomized effect can sit pixels away from a signal without any possibility of contaminating it. "No-repaint" holds even in programs full of animation, because the dependency cannot be expressed.
• Freedom where it is safe. CANVAS authors get wall-time, easing, springs, noise and interactivity without a determinism tax — the plane is honestly outside the guarantees, and the firewall is what makes that honesty affordable.
• A clean audit surface. Whether a program is replayable is a static fact about which plane its sinks live in, and the compiler tells you.

In practice.

fluxdot { at:(bar.i, close); r: 4 }       // CANVAS reading an ANALYSIS value — the legal direction
x = ema(now(), 20)                    // ✗ [ErrFirewall] — wall-clock time cannot enter ANALYSIS

The same rule gives live(e) — the presentation-side read of the unit still in formation — a safe home: it may flow to display sinks, never into confirmed analysis. Details in The four planes.

#6. Capability security

The statement. Scripts have no ambient authority. Effects are default-deny object-capabilities: a script can affect the world only through capabilities it declared, that the user granted, and that the host mediates.

Why. Flux is the language of a platform where code is shared, sold and run by people who did not write it. That is only tenable if safety is a property of the language and host, not of a review process. Flux gets there in layers: the language has no primitive that does I/O — no fetch, no DOM access, no eval, no file handles — so a script's only channel to the world is data it hands the host. On the APP plane that channel is explicit:

• Commands are inert data. A Cmd carries values — a sound name, a storage key, a score — never a token, URL or handle. The host holds every resource and executes the command only if the corresponding capability was declared and granted. Emitting a command the manifest does not grant is rejected at compile time ([ErrCapDenied]) — it never becomes a runtime event to be caught.
• Capabilities are declarations, not values. They are named namespace:verb entries in the app descriptor — chart:read, storage:own, net:fetch — never first-class objects, so they cannot be re-delegated or amplified from inside a script.
• Manifests aggregate transitively, with zero escalation. An artifact's sealed manifest is the union of capability needs over its whole dependency closure, intersected with the user's grant. A dependency's need surfaces in the top-level manifest before install, and no dependency can ever hold a capability the user did not grant to the whole.

fluxapp quiz {
  capabilities: [ chart:read, sfx, storage:own ]   // everything this app may ever touch
  // ... a Cmd like PlaySfx("ding") is data; the host decides whether it runs
}

What it buys you.

• Untrusted code as a routine. Installing an artifact is informed consent to a short, exact list — not an act of faith in an author.
• No confused deputies. Authority flows only along import edges, capped by the grant; a library cannot launder access through the app that embeds it.
• First-party honesty. The platform's own applications run under the same regime with the same manifests — trust is a grant level, never a code path.

#7. Optimizable by construction

The statement. A Flux program is a pure, typed, total, causal DAG — the form on which classic optimizations are safe by construction. And the optimizer is verified at every compilation, never trusted.

Why. In impure languages, optimizers spend their sophistication proving that a transformation cannot observe an effect — and give up conservatively when they cannot. Flux programs have no effects to observe: any two computations of the same pure subgraph are interchangeable, so sharing, pruning, reordering and specializing need no heroics. The program's small, bounded size adds a second, unusual advantage: whole-graph searches that are infeasible on large programs are affordable here, so the optimizer can aim for optimal rather than "good enough".

The trust model is the distinctive part. The optimizer obeys one law: the optimized program must be bit-identical to the reference semantics — the unoptimized DAG's canonical evaluation (or the native kernel, for built-ins). That law is enforced by translation validation: every compilation runs reference and optimized artifacts on real data and asserts byte-equality. The optimizer may therefore be aggressive precisely because no one has to believe in it — a miscompilation cannot ship, it can only fail loudly at the gate.

What it buys you.

• Free sharing. Common-subexpression elimination is global: write ema(close, 26) in four places within a script and it is computed once. Post-v1. Sharing it across four co-active scripts — one merged graph for the whole chart — is a later optimizer tier.
• Cost you can see. Dead code is eliminated, constants folded, element-wise chains fused; the editor's cost gutter shows the optimized graph, so what you read is what you pay.
• A safe default and a labeled fast lane. The default is bit-exact, always. Post-v1. Relaxed floating-point (reassociation, fused multiply-add) is designed as an explicit, labelled opt-in — never a silent default, and never bit-exact.

In practice.

fluxdef ema0(s, n) = let a = 2/(n+1) in scan(s, (p) -> a*s + (1-a)*p)
def macd0(s)   = let l = ema0(s, 12) - ema0(s, 26) in { macd: l, signal: ema0(l, 9), hist: l - ema0(l, 9) }

plot macd0(close).macd, macd0(close).signal    // two calls, one shared subgraph — CSE, verified bit-exact

The tiers, the cost model and the validation harness are specified in Optimizer.

#How the pillars compose

The pillars are not seven independent features; each one leans on the others, and the guarantee set holds because the loop closes:

• Totality makes verification possible. Every static analysis in the language — kind inference, causality checking, exhaustiveness, the optimizer's validation oracle — terminates because programs are total and their bounds are constants. A language with unbounded programs could promise none of its checks complete.
• Causality makes the graph a DAG, which is what kind inference walks in one pass, the scheduler parallelizes without locks, the debugger checkpoints and replays, and the optimizer reorders safely. One acyclicity theorem, consumed four ways.
• Determinism needs totality and causality — replay is only exact if programs terminate and history is immutable — and needs the firewall, which keeps wall-time and randomness out of the deterministic domain instead of asking authors to be careful.
• Kinds feed everything. Presentation inference (pillar 4), the memory plan that makes budgets static (pillar 1), the firewall's classification of sinks (pillar 5) and the optimizer's cost model (pillar 7) all read the same dimensional facts.
• Capability security stands on totality and purity. Default-deny would be theater if a script could loop forever, reach ambient I/O, or hide effects in evaluation order. Because it can do none of these, the capability manifest really is the complete story of what an artifact can do.
• The optimizer's freedom is determinism's dividend. "Bit-identical to the reference" is only a usable law because a reference answer exists — deterministic, byte-stable, on every machine. In exchange, the optimizer repays the budget that totality promised: the cost the compiler declared is the cost you observe.

Pull any one pillar out and the others weaken; together they close: describe an expression, and the engine can evaluate it — provably terminating, never rewriting history, identical everywhere, disclosing everything it touches, at a cost known in advance.

#See also

• What is Flux — the mental model and the four planes at a glance.
• Getting started — the pillars as you experience them while writing.
• The four planes — the firewall in depth.
• Kinds — the dimensional system behind pillar 4.
• Time and state — delays, clocks, scan and causality behind pillar 2.
• Guarantees — each promise and the machine check that enforces it.

Getting started

This chapter is a guided first session. It starts with the shortest program that does something real, and grows it — parameters, styling, composition, state, multiple clocks, a moving scene, a small application — explaining what the language did for you at each step and, just as importantly, what it refused to do.

Everything here is a complete program. Paste any of it into the editor and it runs.

#One line

fluxplot rsi(close, input(14))

That is a complete, publishable analytic. Nothing was configured, and yet:

• close is a price. rsi is a bounded oscillator family, so the expression has kind osc(0,100).
• Because the kind is a bounded oscillator, it cannot share the price axis — it gets its own pane, with a fixed 0–100 scale and a midline. Because the operation is specifically rsi, its conventional 30/70 guides are drawn too.
• Because you wrote input(14), a parameter control appears, typed and ranged.
• Because the program is causal and total by construction, it is also replayable, bounded, and byte-identical on every engine — which the guarantees panel will tell you without being asked.

Delete input(…) and write plot rsi(close, 14): same analytic, no control. The input wrapper is how a value becomes a knob.

What just happened. You did not choose a pane, a scale, a colour or a reference line. The kind of the expression carried all of it. This is the single biggest ergonomic consequence of a dimensional type system, and it holds for everything you write next.

#Parameters and styling

input accepts a default, an optional range, and optional metadata:

fluxlen  = input(14, 2..200, title: "Length")
src  = input(close, title: "Source")
show = input(true, title: "Show band")

plot rsi(src, len)

The kind of the default decides the widget: a number gives a numeric field (a range makes it a slider), close gives a source picker, true gives a checkbox, a list of strings gives an enumeration.

Presentation defaults are inferred, but intent always wins:

fluxm = macd(close)
plot m.hist { style: histogram, color: if m.hist > 0 then up else down }
plot m.macd, m.signal
plot ema(close, 200) { overlay }        // it is already a price — this is explicit
plot rsi(close, 14) { guides: [20, 80] } // your own reference lines, kind-checked

The style values are a closed set (histogram, columns, stepline, area, circles, cross); a line is the default a level or a price infers. Forcing a level onto the chart with { overlay } gives it its own secondary axis — the compiler knows a shared price scale would flatten it to nothing.

#Composition

def defines a pure function from streams to streams. It is inlined into the graph, so there is no call cost to think about:

fluxdef zscore(x, n = 20) = (x - sma(x, n)) / stdev(x, n)

plot zscore(close)          // (price − price) ÷ level = level ÷ level → ratio
plot zscore(hlc3, 50)       // the same def on another price source — the kinds follow the argument

Any function can be written as a method-style chain — the receiver becomes the first argument — which is how most people end up writing analytics:

fluxsmoothRsi = close.ema(20).rsi(14)     // ≡ rsi(ema(close, 20), 14)

The payoff is not brevity. After you type close., the editor offers only the functions whose first parameter accepts a price — the type system becomes a discovery mechanism.

Several kernels return a record, and you project the field you want:

fluxbb = bollinger(close, 20, 2)
plot bb.upper, bb.middle, bb.lower
fill bb.upper..bb.lower      // a band: both operands are `price`, so the fill is well-formed

fill bb.upper..rsi(close,14) would be ✗ [ErrDim] — you cannot shade the region between a price and a dimensionless oscillator, and the language says so rather than drawing nonsense.

#Signals, marks and alerts

A comparison produces a signal, and a signal is presented as marks — never as a line:

fluxcross = close cross_up ema(close, 50)

mark cross "crossed at {fmt.price(close)}"
alert cross "EMA-50 crossed up"

Strings interpolate, so a label or an alert message can carry live values. cross_up is an infix operator: it is true on the bar where the left side rises through the right side, and its definition — like everything else — reads only closed data.

#State

You never write a loop over bars. When a value depends on its own past, you write a scan: a seed, and a step that receives the previous state.

flux// a running maximum since the start
def runMax(x) = scan(x, (prev) -> math.max(prev, x))

// a trailing stop that only ever ratchets upward while long
def trail(mult) =
  let stop = close - mult * atr(14) in
  scan(stop, (prev) -> math.max(prev, stop))

plot trail(3)               // price − lit × level = price → it overlays

The step function sees prev — the state at the previous bar — and the current bar's values. That is the whole model: state advances one step per bar, through a unit delay, which is precisely why a value once emitted can never be rewritten.

Composite state is a record, and a state machine is a variant plus a match:

fluxvariant Trend { Up | Down }

def step(p, n) = match p.dir {
  Up   -> if close < p.ref - atr(n) then { dir: Trend.Down, ref: close } else p
  Down -> if close > p.ref + atr(n) then { dir: Trend.Up,   ref: close } else p
}

def flip(n) = scan({ dir: Trend.Up, ref: close }, (p) -> step(p, n))

match is the eliminator of a variant, and it must cover every constructor — an uncovered case is [ErrTotalMatch], a compile error, not a runtime surprise.

#More than one clock

The step axis of a series is a value, of kind clock. @ reads an expression on another clock, and it reads only closed units of it:

fluxplot ema(close, 20) @ tf("1h")                 // hourly EMA, shown on whatever chart you are on
color bars: if close > ema(close, 50) @ tf("1d") then up else down

That second line is the confluence idiom: a fast chart, coloured by a slow trend. It is not a special feature — it is the ordinary resample, and it is causal, so what a bar showed yesterday it still shows today.

Price-driven step axes are clocks too (renko(box), pnf(box, rev), range(r)), which is why alternative chart representations are not a separate subsystem: they are a different clock.

#A scene that moves

Presentation lives on its own plane, where every property is a signal — a constant, a data value and an animation are the same kind of thing, so there is no animation API to learn:

fluxcircle {
  at:    (bar.i, spring(close)),   // the position eases toward the data
  r:     6,
  glow:  16,
  trail: 24
}

on close cross_up highest(close, 250)[1] -> burst(40) ring { r: 6 -> 24, life: 2s }

The scene may read analysis values. Analysis may not read the scene — that one-way rule is what keeps the moving parts from ever touching the numbers. Try it and you get [ErrFirewall], with an explanation.

#A small application

The fourth plane adds state that persists between events and decides what is displayed — a model, a pure update, a pure view, and declarative subscriptions. Effects are inert data the host executes; capabilities are default-deny.

fluxvariant Msg { Tick | Reset }

app counter {
  capabilities: [ ]

  init(p)          = { n: 0 }
  update(m, msg)   = match msg {
                       Tick  -> { model: m with { n: m.n + 1 }, cmds: [] }
                       Reset -> { model: m with { n: 0 },       cmds: [] }
                     }
  view(m)          = row {
                       text("count: {m.n}")
                       button("reset", Reset)
                     }
  subs(m)          = [ OnTick(1000, Tick) ]
}

OnTick(1000, Tick) reads as "every second, apply the Tick constructor". A subscription carries the constructor the host will wrap its payload in — that is how an event knows which arm of update it belongs to, without any function value ever entering the language.

update is pure and total: it cannot read the clock, cannot reach the network, and must handle every message. Everything ambient — time, randomness, data, input — arrives as a message, which is exactly why an application can be replayed message by message and why its tests are goldens over pure functions.

#What the editor is doing while you type

Kind-filtered completion after ., a hover card with the signature and a live sparkline of the expression on the current data, diagnostics with quick-fixes, a preview that re-evaluates the typable part of your program on every keystroke (a half-typed name blanks one value, never the screen), and a dataflow view that answers "why is this signal true here?". See the editor.

#See also

• The four planes — the firewall in depth, and what live() is for.
• Kinds — the type system that produced every default above.
• Time and state — delays, windows, scan, clocks, warm-up.
• Inference — the presentation table, the overrides, the error catalogue.
• Cookbook — working recipes across every plane.
• FDK overview — the libraries: compute, collections, text, net, display.

The four planes

A Flux program is not one kind of thing. Computing an indicator, drawing a comet that follows the price, morphing a chart when the asset changes, and running a stateful application in a pane are four different activities with four different clocks and four different sets of rules. Most languages give you one plane and ask you to be careful. Flux gives you four, and makes the boundary between them a property of the type system.

The payoff is a sentence worth reading twice: a value can be animated, random, and frame-dependent, and still be provably incapable of changing a computed number. Not by convention. By construction.

A note on the samples. Flux has no expression-statements, so a bare expression is not a program. The lines marked ✗ on this page are therefore expression fragments: they exist to show what the kind rules refuse, not what the parser accepts. Every unmarked line is a legal statement.

#ANALYSIS — the plane that computes

The analysis plane is the most constrained, and therefore the most trustworthy. Everything in it is a pure function of the past: delays reach backwards only, resampling reads only closed units, feedback must cross a unit delay. What follows is not a promise but a theorem — a value, once produced for a bar, can never change.

fluxplot rsi(close, 14)
plot ema(close, 20) @ tf("1h")            // a coarser clock — still causal
mark close cross_up ema(close, 50)

Analysis reads nothing from the planes above it. There is no symbol for the mouse, for the wall clock, for the current frame, or for whether 3-D mode is on. Not "it is bad practice" — those names do not exist in the analysis namespace.

#CANVAS — the plane that shows

The canvas plane may read analysis. It may not write it.

fluxcircle {
  at:    (bar.i, spring(close)),   // reads analysis; the easing is cosmetic
  glow:  16 + 8 * throb(0.4),      // per-frame, time-only — the compositor owns it
  trail: 24
}

on close cross_up highest(close, 250)[1] -> burst(40) ring { life: 2s }

Every property is a signal — a constant, a data value and an animation are the same kind of thing here, so there is no animation API to learn. And because the compiler knows which signals are time-driven, it routes them to the host compositor: zero JavaScript per frame for the parts that move the most.

#TRANSITION — the plane that interpolates

fluxon switch(asset) -> morph chart over 500ms { ease: inOutCubic ; stagger: 0.3 }
on click        -> focus(view, at: (bar.i, close), zoom: 2.0, over: 600ms)

A transition's settle value — where it lands — is analysis data and lives in the oracle. Its trajectory — how it gets there — is cosmetic and does not. That is why prefers-reduced-motion can jump straight to the end state and change nothing that any verdict depends on.

#APP — the plane that remembers

Post-v1. The APP plane is sealed in design and additive to the core; its rollout follows the v1 language.

The other three planes cannot hold state that persists between events and decides what is displayed. The APP plane adds exactly that, and pays for it with a strict recipe: everything ambient — time, input, randomness, the network, analysis values — arrives as a message, and the message journal is the single source of truth. That is what makes an application replayable, testable without a mock, and re-executable by a server bit-for-bit.

See App plane for the full contract.

#The firewall

One rule holds the whole design together:

Dependency arrows never point toward a weaker guarantee.

Presentation may read analysis. Analysis may never read presentation. The APP plane may read analysis (read-only, through a typed subscription) and may orchestrate presentation (through commands) — but it may never write analysis either.

   APP  (mutable state + effects)          ← the most permissive plane
    │  reads ANALYSIS  (Sub OnSeries)              ✔ read-only
    │  orchestrates CANVAS / TRANSITION  (Cmd)     ✔
    ▼
 CANVAS / TRANSITION  (cosmetic, per frame)       ← reads ANALYSIS ✔
    ▼
 ANALYSIS  (pure, causal, no-repaint)             ← reads nothing above it ✘

What the firewall actually forbids is precise. These are the values that may never flow into analysis:

All four raise [ErrFirewall], at compile time, with an explanation rather than a scolding.

Why this is worth a plane split rather than a lint. A discipline you have to remember is a discipline you will forget at 2 a.m. under a deadline. A firewall enforced by the kind system is one you cannot forget: the name is not in scope, and the compiler will not let the value cross. That is what makes it safe to run a stranger's animated, random, interactive scene right next to the number your decision rests on.

#live() — the one exception, and why it is safe

Traders want to see an indicator update within the forming bar. That reading is genuinely useful and genuinely non-causal, so Flux gives it a name, a plane, and a wall:

fluxplot live(ema(close, 20))          // ✓ display — the forming bar included, per frame
alert live(ema(close, 20)) > 100   // ✗ [ErrFirewall] — a decision may not read a forming value
rsi(live(close), 14) > 70          // ✗ [ErrFirewall] — analysis may not consume one either

live(e) re-evaluates the analysis sub-graph of e including the bar in formation, per frame. Its result may flow only into display sinks (plot, mark, fill, color bars, a scene). Any confirmed sink — an alert, an assertion, a value a calculation consumes — is [ErrFirewall].

Note where live sits, because the two placements are not variations on a theme. It wraps the expression whose sub-graph is to be re-evaluated: live(ema(close, 20)) asks for the average including the forming bar, and lands in a display sink. Pushed inward, onto a kernel's argument — ema(live(close), 20) — it stops being a display request and becomes a forming value handed to a calculation, which is the breach itself. The firewall does not care that a plot is waiting at the far end: the analysis kernel already consumed it.

Three consequences, all of which matter:

• The confirmed series of e stays byte-identical. live() adds a provisional view; it does not modify what was computed.
• live() is excluded from the byte-identity oracle, exactly as the wall clock is — so the guarantee that the two engines agree is untouched.
• A script that uses it is flagged non-replayable in the guarantees panel. You see the trade-off you made.

That is the general shape of every escape hatch in Flux: name it, bound it, wall it, and show the user what it cost.

#Which plane am I on?

You never declare one. The plane is inferred from what you write — that is the point of "write the maths, the machinery follows":

And if you try to mix them in a way the firewall forbids, the compiler tells you which value crossed which line, and what to do instead.

#See also

• App plane — the full application contract.
• Canvas — signals, spaces, events, primitives, the performance model.
• Transitions — morph, replay, focus, and the transition descriptor.
• Time and state — causality, clocks, live() in depth.
• Guarantees — what each plane promises, and how it is verified.
• display — the two strata, and where presentation determinism ends.

Lexical structure

This page defines how a Flux source text becomes a stream of tokens: the source model, comments, the significant newline, the complete token catalogue (identifiers, the numeric family and its glued suffixes, strings and interpolation, capability references, operators and punctuation), and the keyword model — which words are reserved, where, and why most of them are only reserved contextually. Everything downstream — the grammar, kind inference, the editor — consumes exactly the token stream specified here.

Two properties frame the whole chapter. First, the lexer is total: any input text produces a token stream (malformed input surfaces as precise diagnostics, never as a crash). Second, the lexer is linear and incremental: every context-dependent device below (the significant newline, interpolation, capability references, the numeric munch) is bounded by counters the lexer already maintains, so retokenizing after an edit touches only the edited neighborhood — the property that keeps live preview under its frame budget.

#Source model

A Flux program is a Unicode text. The fixed alphabet of the language itself — identifiers, keywords, operators, punctuation — is ASCII; arbitrary text (any Unicode) lives inside string literals and comments. Between tokens, spaces and tabs are insignificant and may appear in any number; newlines are significant (see TERM below).

One rule shapes many diagnostics on this page: Flux has no juxtaposition. Two adjacent primary expressions with no operator between them never form a term:

fluxx = 1.50 d      // ✗ syntax error — NUMBER then IDENT: two adjacent primaries
y = 1.50d       // decimal(2) — the glued suffix makes this ONE token
d = 2           // `d` alone is an ordinary identifier — a licit binding
z = 1.50 * d    // valid — the detached `d` is just a name here

Because adjacency is never meaningful, the lexer can afford glued suffix tokens (1.50d, 4px) without ambiguity: either the suffix touches the number and the pair is one token, or it does not and the program is ill-formed unless an operator intervenes.

A script may span several .flux source files; the package visibility modifier (see grammar — modules) is scoped to exactly that set of files.

#Comments

flux/// z-score of a series over n bars
def zscore(x, n=20) = (x - sma(x, n)) / stdev(x, n)

plot zscore(close, 20) as z   // an ordinary comment

A doc-comment is lexically a comment (the parser skips it) but it is not thrown away: the documentation pipeline collects the /// block preceding a def and publishes it as the definition's hover documentation and doc-as-data entry (see the editor). There are no block comments; a comment always ends at the newline. Comments are transparent to the significant-newline rules below — a line that ends in a trailing // … comment is classified by the last token before the comment, and a comment-only line neither ends nor continues a statement.

#The significant newline (TERM)

Flux has no mandatory statement terminator. A statement ends at the end of its line — the lexer emits a TERM token at the newline — unless the line is visibly unfinished. Semicolons are optional separators (never required); writing several statements on one line with ; is legal but idiomatic Flux is one statement per line.

A newline does not emit TERM (the statement continues) when any of the three clauses holds:

1. (a) Open parenthesis or bracket. The ( / [ nesting depth is greater than zero. Inside parentheses and square brackets, newlines are pure whitespace — which is how a long call wraps across lines. Braces do not reset that depth: a brace body written inside a call is still at depth > 0, so its items need an explicit , or ; separator. At depth zero, a newline separates items, which is why a top-level multi-line record or match needs no commas at all:

   fluxdef f(r) = r.a + r.b
   m = { a: 1                      // depth 0 — the newline separates
         b: 2 }
   n = f({ a: 1 ; b: 2 })          // inside a call — the `;` is REQUIRED
   

2. (b) The line is pending. The last significant token of the line is an operator, an opening delimiter, a separator, or a keyword that grammatically awaits an operand — if, then, else, let, in, not, and, or, as, from, with, over, def, match, variant, record, app, import, type, representation, tool, on, every, when, tween, spawn, burst, emit, rate, set, morph, replay, focus, cross_up, cross_down, pub, private, package, scene. A contextual keyword only counts here in its keyword role: in x = p.on the trailing on is a field name and the statement ends. (One lexical subtlety: a trailing % glued to a digit is a percent literal, not a pending modulo — 50% ends the line.)

3. (c) The next token is a continuator. The first token of the following line can only extend an expression, never begin a new item.

Clause (c) is not an ad-hoc list. Normative definition: a token is a continuator iff it belongs to no FIRST set of any list item — formally, iff it is outside ⋃ FIRST(item) taken over every repeated-list production of the grammar (statements, view children, variant constructors, representation and tool hooks, match arms, record fields, capability references, app members). The set is computed from the grammar, not maintained by hand, which makes the rule machine-checkable and keeps it in lockstep with the grammar forever.

Illustratively, the continuators are the purely infix or postfix tokens — . (member access), .., @, +, *, /, %, <, >, <=, >=, ==, !=, cross_up, cross_down, and, or, ->, with, ?, ??, ?., :, ,, ;, the closers ) ] }, the variant separator | — and the purely medial keywords then, else, in, as, from.

Three tokens are deliberately not continuators even though they can extend an expression, because they can also begin a new item: - (unary minus), [ (a list literal) and ( (a parenthesized form). A leading . is a continuator only when not followed by a digit — .upper continues, but .5 is a number and begins an item. To continue across a line on one of these ambiguous tokens, end the previous line pending (clause b) instead:

fluxu = bollinger(close, 20)
  .upper                      // `.` continues the postfix chain — clause (c)

total = close
  + open -                    // `+` continues (c); trailing `-` leaves the line pending (b)
  low

cond = if close > open
  then 1
  else 0                      // medial keywords are continuators — clause (c)

variant Wide { A | B
  | C }                       // `|` is a continuator inside the declaration

multi = sma(
  close,
  20)                         // clause (a): inside ( ) newlines are whitespace

m = { a: 1 }
updated = m
  with { a: 2 }               // `with` is a continuator — postfix record update

The clause-(b) idiom for the ambiguous heads: a -⏎ b (line ends on the operator), v[⏎ i] (line ends on the opener). Similarly, over is not a continuator — as a contextual keyword it may begin an item (for example as a property key) — so a multi-line morph … over d breaks after over, which is a pending word under clause (b).

Why this rule exists. A terminator-free surface reads like the notation authors actually sketch, but it must never become whitespace guesswork. The three clauses are decidable from at most one token of lookahead and the counters the lexer already carries, so newline classification is O(1) per line, linear over the file, and incremental under edits. And because the continuator set is defined as the complement of the computed item-head set, there is no hand-curated list to drift out of sync when the grammar grows: adding a statement head automatically removes it from the continuators.

#Token catalogue

The complete token inventory. Each class is detailed in the sections that follow.

#Identifiers

IDENT = [A-Za-z_] [A-Za-z0-9_]*

Identifiers are ASCII: a letter or underscore, then letters, digits and underscores. An identifier is a name for a binding, parameter, field, kind, argument label, module or declaration. The lone underscore _ is lexically an ordinary identifier with two blessed roles given to it by the grammar and the elaborator: the wildcard pattern in match arms, and the implicit single-parameter placeholder in expression position (vec.map(_ * 1.1), see operators).

Whether a given identifier is available depends on the keyword model below — most keywords in Flux are contextual, so words like render, view or color remain usable as field names, parameters and kind names.

#Numbers

NUMBER = ( digits "." digits | "." digits | digits ) [ ("e"|"E") ["+"|"-"] digits ]

42, 2.5, .5 and 1.5e3 are all NUMBER tokens. A bare NUMBER has kind lit — the const-folded literal that is dimension-polymorphic (close + 10 is a price; see kinds).

Maximal munch, bounded by the dot rule. The number scanner never consumes a . that is followed by another . or by a non-digit. This single rule makes ranges and member access compose with numbers without separators:

fluxlen   = input(14, 2..200)      // NUMBER RANGE NUMBER — the dot is never eaten before `..`
half  = .5                     // a leading-dot NUMBER
band  = (2.5..3.5)             // NUMBER RANGE NUMBER — a range lives in its own slots
u     = bollinger(close, 20).upper   // `.upper` is member access, not a malformed number
sci   = 1.                  // exponent form
neg   = -0.5                   // unary minus applied to NUMBER (the sign is not part of the token)

#Suffixed literals

Six literal classes carry their unit as a suffix glued to the number (no space); SPAN alone also accepts exactly one space. Each token is typed at the expression position by rule [LitTyped] of the kind system:

fluxb  = 300s + 20ms               // duration arithmetic
c  = 50%                       // ratio
d  = 4px                       // screen-space size (CANVAS styling)
r  = 40/s                      // emission rate
sp = life(200 bars)            // barspan — unifies every(n bars) and life: n bars
a  = 1.50d                     // decimal, scale 2 — exact money arithmetic

The glued-d rule (representative of the whole family). The d suffix must touch the number, and the character after the suffix must not extend an identifier:

fluxa = 1.50d       // DEC(1.50, scale 2) — one token
b = 1.      // DEC — the suffix composes with scientific notation
c = 1.50 d      // ✗ syntax error — NUMBER IDENT, two adjacent primaries (no juxtaposition)
d = 2           // a detached `d` is an ordinary identifier — a licit binding
d2 = 1.50 * d   // valid — 1.50 times the bound `d`

The same boundary check protects every suffix: 2se is not a DUR (the trailing e would extend an identifier, so the lexer yields NUMBER(2) then IDENT(se), which the parser rejects as juxtaposition), and 40/sec is not a RATE (it is 40 / sec, a division by the identifier sec). The DEC scale is the number of written fraction digits: 1.50d is decimal(2), 2d is decimal(0).

Why glued suffixes. Units on literals could have been separate tokens (1.50 d) or constructor calls (dur(300)), but both spellings put a parse between the number and its unit, and the detached word would collide with ordinary identifiers — d, s and bars are all reasonable binding names. Gluing makes the unit part of the token, so the decision is made by the lexer with zero grammar impact: 1.50d can never be misread, d alone is never stolen from the author, and each literal arrives at inference already carrying its kind. The one relaxation — 200 bars with a single space — is accepted because bars is a reserved head there and the span form reads as prose in every(…) and life: positions.

Open decision. The plan keeps SPAN, PX, RATE and the binary % operator in v1 and flags them for final ratification; they are documented here as kept.

#Strings

STRING = '"' frag '"' | "'" frag "'"

Both delimiters are equivalent — Flux has no character type, so the single quote is free to be a string delimiter. A string literal has kind string and must close on the line it opened (a raw newline inside a string is a syntax error). Inside a string, a backslash makes the next character literal: \" inside a "…" string, \{ and \} for literal braces (see interpolation below).

fluxplain  = "no interpolation"
single = 'quote style'
alert close cross_up open "crossed"       // strings feed the text channels (labels, messages)

Strings are values of the categorical kind string — bounded, immutable text for labels, prompts and messages. They are never plotted as a series, and + on two strings concatenates (the one categorical overload of +; see operators).

#String interpolation

A { inside a string opens an interpolation hole holding a full Flux expression. Lexically the literal is split into fragment tokens:

STR_HEAD = '"' frag '{'          (opening fragment — also with ' delimiter)
STR_MID  = '}' frag '{'          (middle fragment)
STR_TAIL = '}' frag '"'          (closing fragment)
interpStr = STR_HEAD expr { STR_MID expr } STR_TAIL

A string containing no unescaped { stays one atomic STRING token. \{ and \} denote literal braces inside a fragment. The interpolation tokenizer matches its closing delimiter to the opening one ("…" or '…'), and the { of a fragment opens a lexer mode that is bounded by the brace counter the lexer already keeps — so holes nest to any depth the program itself can nest, and tokenization stays linear and incremental.

fluxm = { a: 0 }
x = close
mark close > open "close {close} above {str(open)}"
label  = "nested {(m with { a: 1 }).a} brace"    // a full expression, inner braces counted
single = 'quote {x} style'                 // interpolation works in '…' too
lit    = "a literal \{brace\}"             // escaped — no hole opened

An interpolated literal has kind string. Its AST is a concatenation of the fragments with each hole's expression formatted by the canonical formatter for its kind (fmt.* — pinned, identical across every execution target), so a mark or alert label can be dynamic without any formatting boilerplate. See text for the formatting rules.

#Capability references (CAPREF)

CAPREF = IDENT ":" IDENT        (only inside a capability list)

An APP-plane descriptor declares what it may touch as a list of capability references — namespace:verb pairs like chart:read, storage:own, levels:write, or a bare IDENT for single-token capabilities (sfx):

fluxapp structureGame {
  capabilities: [chart:read, storage:own, levels:write, sfx, app:launch]
  // …
}

CAPREF is deliberately not a greedy lexer rule. It is recognized only in one grammatical state — element of a capability list — so its : never competes with the other colons of the language (record fields f: v, properties at: (x, y), when …: children, the ternary's :). Everywhere else, a:b is an identifier, a colon and an identifier with their usual meanings.

Inside that one state the lexer reads the first segment literally, even when it spells a reserved word: app:launch is a legal capability reference although app is a hard keyword everywhere else. The relaxation is scoped to exactly the namespace position of a capability list; it does not extend to any other position in the language.

#Operators and punctuation

Three lexical facts here are load-bearing:

• Maximal munch in the ? family: the lexer tries ??, then ?., then ?. So a??b is a coalescing, a?.b a safe navigation, and a ? b : c a ternary — no spacing tricks needed, exactly as .. wins over ..
• .. and -> are single tokens. Neither is ever two characters glued at parse time, so bb.upper..bb.lower cannot be misread (.. never appears inside an expression's postfix chain) and no second arrow spelling exists anywhere in the language.
• | has no operator role. It appears only between the constructors of a variant declaration (variant Phase { ask | suspense | revealed }). Boolean disjunction is the word or; there is no bitwise-or operator (bitwise operations are the named functions of bits.*). This keeps | collision-free with every expression level.

Why a single arrow token. Arrow-like syntax appears in five places (lambdas, event wiring, tween pairs, match arms, comprehensions), and languages that grow separately spelled arrows for those roles force readers to memorize which arrow belongs where. Flux decrees one symbol: -> is one token and one grammar production, and the five readings are selected by the context — the guarding head (on, match, for … in) or, for the unguarded uses, by kind inference. The lexer's contribution to that decree is minimal and strict: exactly one arrow spelling exists. The full disambiguation story is on the grammar page.

#The keyword model

Flux keeps the hard keyword set as small as the grammar allows, in three tiers plus a deliberate non-tier.

#Tier 0 — hard-reserved everywhere

The core binders, connectors, operators and literals are reserved at every position:

def  let  in  if  then  else  for  match  with  variant  record  app
and  or  not  cross_up  cross_down  true  false  na

plus the two purely medial connectors as and from. These words can never be an identifier — they are binders and separators whose contextual release would buy nothing and cost lookahead. The single scoped exception, described above, is the namespace position of a capability reference, where app:launch reads app literally.

#Tier 1 — contextual heads

Every other keyword of the language is contextual: it is a keyword at its head position (the first token of its production, or a medial connector like over in morph … over d) and an ordinary IDENT in the five binding slots:

The Tier-1 words, by family:

• statement heads (ANALYSIS): plot mark fill alert assert bars input
• CANVAS heads and event verbs: on group repeat spawn burst emit rate tween flash bounce pulse shake set when every hover click drag enter exit move wheel
• CANVAS primitives: dot circle ring rect square triangle poly line path text image svg sparkline backdrop column
• TRANSITION heads and connectors: morph over focus replay scene
• representation heads and hooks: representation transform render reduce liveReduce updateLastUnit persistKey
• drawing-tool heads and hooks: tool barExtent priceExtent
• APP-plane member heads: capabilities init update subs contributes view
• tooling and modules: test import type
• clause connectors reserved contextually at their clause: at (in assert … at), color (in color bars:)

The visibility modifiers pub, private and package form a distinct contextual subclass: they are not production heads but declaration prefixes, decided by one token of lookahead (followed by a declaration head or a binding, they are modifiers; followed by =, :, . or (, they are plain identifiers).

A Tier-1 word is a keyword only where the parser can shift it as one — at its head or medial position. Everywhere else the lexer hands back an ordinary identifier, so def f(render) = render * 2 is legal, and so is the binding render = 3: a bind's left-hand side shifts an identifier, not a head. What you cannot do is use the word where its production expects it and mean something else.

fluxrecord Stop { color: color }               // (a) field name + (d) kind name — both `color`
tool fib(a, b) {
  render: line { x1: a.bar; y1: a.price; x2: b.bar; y2: b.price }
}                                          // `render` is a keyword here — hook-head position
focus(view, over: 600ms)                   // (e) `over` as an argument label

Why contextual reservation. Reserving every head outright would force authors into distorted names — focusRef, bounds, vdot — precisely where focus, rect and dot are the intended vocabulary of the domain. Contextual reservation keeps the readability that keyword-headed statements buy (every statement is committed by its first token) while returning the words to authors in the five slots where no head can ever occur. The two sides are provably disjoint: the binding slots sit in parser states where only an IDENT is expected, so freeing a word there introduces no ambiguity anywhere — a claim the grammar build re-verifies mechanically on every change.

#Reserved ahead of need

Flux reserves a word before shipping its production whenever the word is destined for the surface, so that no existing program can shadow it in the meantime (see additivity). The APP-plane words (app, match, capabilities, init, update, subs, contributes, view, emit, variant) and the module words (import, pub, private, package) were reserved this way from the first version and have since received their productions.

Reserved. test is the current instance: it is reserved in v1 with no production. The test "name" { … } block is a tooling convenience whose production ships later, additively, together with its golden tests.

#Deliberately NOT reserved — built-ins

The built-in value names are ordinary identifiers, not keywords:

close  open  high  low  volume  time  hl2  hlc3  ohlc4
bar  clock  screen  pane  ratio  depth  z  up  down  self  range

A program may bind them — and a style lint immediately flags the shadowing:

fluxclose = 42            // legal — the shadowing lint flags: `close` hides the built-in series
plot close            // now plots 42 at every bar

Why not reserve them. These names are vocabulary, not structure. Reserving open, range or z would poison huge swaths of ordinary naming (every rectangle has a range, every record an open something), for zero parsing benefit — no grammar production is anchored on them. A lint gives the author the warning that matters (accidental shadowing of a data source) while keeping the keyword set minimal, which in turn keeps the additivity story clean: the fewer words the language owns, the fewer future collisions it must manage.

#Lexical errors

Because both lexer and parser are total, malformed input yields diagnostics, never crashes. The characteristic lexical-level rejections:

fluxs = "unterminated          // ✗ syntax error — a string must close on its own line
x = 1.50 d                 // ✗ syntax error — juxtaposition (NUMBER then IDENT)
t =                     // ✗ syntax error — `se` does not complete a duration suffix

Everything else that looks lexical — a < b < c, a stray ->, a { a, b } in expression position — is rejected one stage later, by the grammar; those diagnostics are catalogued on the grammar page.

#See also

• Grammar — the normative grammar these tokens feed; the single arrow; precedence.
• Kinds — the dimensional kinds that typed literals (DUR, PCT, SPAN, DEC…) carry.
• Operators — the dimensional algebra behind + - * / %, the ? family, UFCS.
• Time and state — what the @ clock suffix means and why it is restricted.
• Text — the string kind, formatting (fmt.*) and the interpolation pipeline.
• Getting started — the same tokens met in program order.

Grammar

This page is the normative syntax of Flux: every statement form, the full expression grammar, the single arrow -> and its five contextual readings, the precedence ladder, the disambiguation decisions that keep parsing deterministic, and the six machine-verified formal properties the grammar is frozen against. Tokens (IDENT, NUMBER, STRING, TERM, …) are defined in lexical structure; what programs mean is the business of kinds, inference and time and state.

There is exactly one grammar, and it is stated once: the normative EBNF below is expressed as a Lezer LR grammar — the same artifact drives the compiler, the editor and the documentation tooling, so no second, drifting description of the syntax exists. The grammar build accepting with zero unresolved conflicts is the machine check that the language is unambiguous (see formal properties).

Notation. { x } repeats zero or more times, [ x ] is optional, | separates alternatives, "x" is a literal keyword or punctuation token, and UPPERCASE names are lexical tokens from the token catalogue.

#One grammar, all planes

Flux programs live on four planes — ANALYSIS, CANVAS, TRANSITION and APP — but the syntax is a single grammar. The plane is inferred from the constructs used, never annotated: there is no plane pragma, no file-level mode switch. plot and alert are ANALYSIS sinks; on, the shape primitives and spawn are CANVAS; morph, focus and replay are TRANSITION; an app descriptor is APP. A single file freely mixes them — an indicator and its presentation are one program — and the firewall between planes (presentation may read analysis, never the reverse) is enforced by the dependency analysis on the parsed tree, not by the grammar. See the four planes.

fluxplot close                                   // ANALYSIS — the smallest program
on click -> burst(40) dot { vel: 3 }         // CANVAS — same file, same grammar
morph chart over 600ms                       // TRANSITION

#Programs and statement separation

program  = { TERM } [ stmt { TERMSEP stmt } { TERM } ]
TERMSEP  = ( TERM | ";" ) { TERM | ";" }
sep      = ( TERM | "," | ";" ) { TERM | "," | ";" }

A program is a sequence of statements separated by significant newlines (TERM) and/or optional semicolons; blank lines are free. Inside brace bodies, list items are separated by sep — a newline, comma or semicolon, interchangeably — which is why a multi-line record at the top level needs no trailing commas and a one-line block can use ;. The newline only counts as a separator at parenthesis depth zero: a brace body written inside a call is still inside the call's parentheses, so its items need an explicit , or ;. The complete newline policy (when a newline terminates and when it continues) is specified in lexical structure.

Flux has no expression-statements: a bare expression at statement level is a syntax error, which is what makes newline-terminated statements unambiguous.

fluxrsi(close, 14)        // ✗ syntax error — an expression is not a statement; write `plot rsi(close, 14)`

#Statement forms

stmt = declStmt | plotStmt | markStmt | fillStmt | colorBarsStmt | alertStmt | assertStmt
     | onStmt | groupStmt | repeatStmt | forStmt | uiElement | primStmt | spawnStmt
     | tweenStmt | effectStmt | setStmt | morphStmt | focusStmt | replayStmt
     | appStmt | importStmt

Nearly every statement is committed by its first token — the keyword-head idiom: at statement level, only assertStmt can begin with assert, only variantDecl with variant, and so on. The parser never guesses; each head owns a distinct LR state. The two statements that begin with an IDENT (a binding, a view container) and the one that begins with { (a destructuring binding) are resolved by one token of lookahead, catalogued below.

#Declarations

declStmt = [ visMod ] ( bindStmt | defStmt | typeDecl | variantDecl | recordDecl
                      | reprStmt | toolStmt )
visMod   = "pub" | "private" | "package"
bindStmt = letPat "=" expr
letPat   = recordPat | IDENT
defStmt  = [ DOC ] "def" IDENT "(" [ params ] ")" "=" expr
params   = param { "," param }
param    = IDENT [ "=" literal ]

A binding names a value for the rest of the program; its left-hand side is a single identifier or an irrefutable record pattern that destructures on the spot. Bindings are immutable — there is no assignment statement, and let exists only inside expressions.

fluxn = input(14, 2..200)
{upper, lower} = bollinger(close, 20)        // destructuring bind — no `:` after `{ IDENT`
let n = 20                                   // ✗ syntax error — `let` is expression-only; top-level binds are bare

A function definition binds a name to a parameterized expression. Parameters may carry literal defaults; a /// doc-comment attaches to the definition. Recursion is rejected ([ErrTotalRec]) — totality by construction.

flux/// z-score of a series over n bars
def zscore(x, n=20) = (x - sma(x, n)) / stdev(x, n)
plot zscore(close) as z

The optional visibility modifier scopes a declaration for the module system: pub crosses an import, package spans the source files of one script, private (the default) stays in its file. The modifier is contextual — decided by the token after it — so pub, private and package remain usable as ordinary names in binding slots.

fluxpub def helper(x) = x * 2
private record Internal { a: num }
pub {upper, lower} = bollinger(close, 20)    // a modifier also prefixes a (destructuring) bind

#Named types — variant, record, alias

variantDecl = "variant" IDENT "{" { TERM } ctorDecl { "|" ctorDecl } { sep } "}"
ctorDecl    = IDENT [ "(" [ field { "," field } ] ")" ]
field       = [ IDENT ":" ] kindExpr
recordDecl  = "record" IDENT "{" { TERM } fieldDecl { sep fieldDecl } { sep } "}"
fieldDecl   = IDENT ":" kindExpr [ "=" ( literal | "na" ) ]
typeDecl    = "type" IDENT [ "(" IDENT { "," IDENT } ")" ] "=" kindExpr
kindExpr    = "vec" "(" kindExpr "," constLen ")"
            | "variant" "{" { TERM } ctorDecl { "|" ctorDecl } { sep } "}"
            | "record" "{" { TERM } fieldDecl { sep fieldDecl } { sep } "}"
            | IDENT [ "(" [ argList ] ")" ]
constLen    = NUMBER | IDENT

variant declares a named sum type (constructors separated by |, payloads positional with optional documentary field names); record declares a named product type (every field named and kinded, with optional constant defaults); type declares a transparent alias, possibly parameterized — substitution, not a new type. A kindExpr names a kind of the lattice (price, osc(0,100)), a declared type, a vec(element, constLength), or an inline structural variant{…} / record{…}. Angle brackets are never type delimiters — < and > are exclusively comparison operators — so every parameterized form uses parentheses.

fluxvariant Phase { ask | suspense | revealed }
variant Tool  { Select | Event(kind: num) | At(price) }   // named or anonymous payloads
record Level  { price: price; kind: num = 3; label: string }
record Inline {
  state: variant { Connecting | Ready }                   // inline structural kinds
  slots: vec(Level, 100)
}
type long = decimal(18, 0)
type Series(T) = vec(T, 500)                              // transparent, parameterized alias

The reference graph between named types must be acyclic — record Node { next: Node } is rejected with [ErrTotalType] at name resolution, keeping every type finite.

#ANALYSIS sinks and parameters

plotStmt      = "plot" exprList [ "as" IDENT ] [ block ]
markStmt      = "mark" condExpr [ strLit ] [ block ]
fillStmt      = "fill" addExpr ".." addExpr [ block ]
colorBarsStmt = "color" "bars" ":" condExpr
alertStmt     = "alert" condExpr [ strLit ]
assertStmt    = "assert" condExpr [ strLit ] [ "at" addExpr ]
strLit        = STRING | interpStr
exprList      = expr { "," expr }

The sinks publish analysis values to the host: plot traces series (optionally named with as, optionally styled with a trailing block), mark drops labeled markers on a condition, fill shades between two series, color bars: colors the bars themselves, alert raises a message on a condition, and assert states an invariant that must hold on every bar — or, with at, on one given bar. An assertion whose condition is na (warm-up) passes; it fires only on a definitely-false signal.

fluxbb     = bollinger(close, 20)
equity = cum(close - open)
fill bb.upper..bb.lower
color bars: if close > ema(close, 200)@"1d" then up else down
alert close cross_up open "crossed"
assert rsi(close, 14) <= 100 "rsi bounded"    // na on bars 0–13 — vacuously satisfied
assert equity > 0 "positive" at 500
mark rsi(close, 14) > 70 "overbought" { size: 8 }

A script parameter is the expression form input(…) (a primary, usable anywhere an expression is):

inputExpr    = "input" "(" inputDefault { "," inputArg } ")"
inputDefault = literal | IDENT | listLit
inputArg     = metaArg | inputExtra
metaArg      = IDENT ":" strLit
inputExtra   = addExpr [ ".." addExpr ]

The default must be constant — a literal, a source identifier, or a list of string labels (the enumerated form); its kind fixes the parameter's kind. After the default come an optional range (2..200) or bound and named meta-UI arguments (title:, group:, tooltip:, inline:), distinguished from a range by the IDENT : lookahead:

fluxlen  = input(14, 2..200)
src  = input(close)
name = input("fast", title: "Label", group: "Style")
mode = input(["ema", "sma"], tooltip: "kind")     // enumerated — a variant of the labels
dec  = input(1.50d)                                // decimal parameter

#CANVAS statements

onStmt      = "on" eventExpr ARROW action
eventExpr   = "hover" | "click" | "drag" | "enter" | "exit" | "move" | "wheel"
            | everyExpr | condExpr
everyExpr   = "every" "(" [ "~" ] ( DUR | SPAN | addExpr ) ")"
action      = stmt | block
groupStmt   = "group" [ block ]
repeatStmt  = "repeat" addExpr "as" IDENT [ block ]
forStmt     = "for" IDENT "in" condExpr ARROW uiChild
primStmt    = primitive [ "when" condExpr ]
primitive   = shapePrim [ block ] | contentPrim [ condExpr ] [ block ]
shapePrim   = "dot" | "circle" | "ring" | "rect" | "square" | "triangle" | "poly"
            | "line" | "path" | "backdrop" | "column"
contentPrim = "text" | "image" | "svg" | "sparkline"
spawnStmt   = ( "spawn" | "burst" "(" addExpr ")" | "emit" "rate" "(" addExpr ")" ) primitive
tweenStmt   = "tween" propPath arrowPair [ overClause ]
setStmt     = "set" propPath "=" expr
effectStmt  = ( "flash" | "bounce" | "pulse" | "shake" ) [ postfix ] [ block ]
propPath    = IDENT { "." IDENT }

on wires an event — an interaction verb, a cadence every(…), or any boolean stream — to an action. A primitive draws one element, with a property block and an optional trailing when guard. spawn / burst(n) / emit rate(r) create pooled short-lived elements; tween, set and the effect words animate properties. The semantics of all of these live on the CANVAS page; grammatically they are keyword-headed statements sharing the one block form.

fluxon click -> group { dot { at:(bar.i, close); r: 4 } }
on every(1 bars) -> spawn ring { r: 6->24; life: 200 bars }
on every(~ 500ms) -> pulse                       // `~` — approximate cadence
on close > highest(close, 250)[1] -> burst(40) dot { vel: 3 }
emit rate(norm(volume) * 40) dot { size: 2 }
tween p.r 6->24 over 300ms
circle { at:(spring(close)); trail: 24 } when close > open

View containers and comprehension. A view container is an identifier head (optionally called) followed by a mandatory brace body of children; the comprehension for … in … -> is a statement/child form only — for never begins an expression (pure data mapping is vec.map):

uiElement = IDENT [ callTail ] uiBlock
uiBlock   = "{" { TERM } [ uiChild { sep uiChild } { sep } ] "}"
uiChild   = uiElement | forStmt | whenChild | primStmt | expr
whenChild = "when" condExpr ":" uiChild

fluxslots = window(close, 5)
row { text "a"; text "b" }
panel(slot: side) { col { for s in slots -> renderSlot(s) } }
grid(cols: 2) { when close > open: text "up"; col { text "deep" } }

A childless container (button(reset), panel(slot: x)) is not a uiElement — it is an ordinary call expression of kind ui; the brace body is what makes the container form.

#TRANSITION statements

morphStmt  = "morph" ( "chart" | IDENT ) [ overClause ] [ block ]
overClause = "over" condExpr
focusStmt  = "focus" "(" "view" { "," arg } ")"
replayStmt = "replay" "from" condExpr overClause

fluxanchors = window(close, 10)
morph chart over 600ms
morph pnf { keep: anchors }
focus(view, over: 600ms, pad: 5%)     // `over` here is an argument label, not the clause keyword
replay from close > 100 over 2s

#Representations and drawing tools

reprStmt  = "representation" IDENT "(" [ params ] ")" reprBlock
reprBlock = "{" { TERM } [ reprHook { sep reprHook } { sep } ] "}"
reprHook  = reprKey ":" reprVal
reprKey   = "transform" | "render" | "reduce" | "liveReduce" | "updateLastUnit" | "persistKey"
reprVal   = primStmt | block | expr
toolStmt  = "tool" IDENT "(" [ params ] ")" toolBlock
toolBlock = "{" { TERM } [ toolHook { sep toolHook } { sep } ] "}"
toolHook  = toolKey ":" toolVal
toolKey   = "barExtent" | "priceExtent" | "render"
toolVal   = primStmt | block | expr

Both are keyword-headed declaration forms whose bodies are a closed enumeration of hooks — the script authors the pure functions (geometry, rendering, reduction), the host supplies everything else (placement, hit-testing, persistence; hence hitTest and lod are not keywords and remain free names). See host integration.

fluxrepresentation pnf(box, rev) {
  transform: rebin(close, box, rev)
  render: column { w: 1 }
  reduce: decimate(cols, k)
  liveReduce: mutateHead(cols)
  updateLastUnit: patch(cols)
  persistKey: "pnf-v1"
}

tool fib(a, b) {
  barExtent: (a.bar, b.bar)
  priceExtent: (a.price, b.price)
  render: line { x1: a.bar; y1: a.price; x2: b.bar; y2: b.price }
}

#The APP descriptor

appStmt    = "app" IDENT appBody
appBody    = "{" { TERM } [ appMember { sep appMember } { sep } ] "}"
appMember  = capEntry | memberDef
capEntry   = "capabilities" ":" capList
capList    = "[" { TERM } [ capRef { "," capRef } { sep } ] "]"
capRef     = CAPREF | IDENT
memberDef  = ( "init" | "update" | "view" | "subs" | "contributes" )
             "(" [ params ] ")" "=" memberBody
memberBody = uiElement | expr

An app is a named descriptor with one capabilities: entry and the five fixed members of the TEA harness (TEA — The Elm Architecture). The member heads are keywords, not identifiers — the form is deliberately def-less because these five roles are fixed. memberBody is the one place in the grammar where a statement-level view container is the right-hand side of = (a view returns a view); everywhere else the RHS of = is an expression.

fluxapp structureGame {
  capabilities: [chart:read, storage:own, levels:write, sfx]
  init(p) = {score: 0, phase: ask}
  update(m, msg) = match msg {
    Tick(dt) -> m with {score: m.score + dt}
    _ -> m
  }
  view(m) = panel(slot: side) {
    row { text "score {m.score}"; when m.done: button(reset) }
    for t in TOOLS -> button(t)
  }
  subs(m) = [OnTick(Tick)]
}

The APP plane's semantics — Model, Msg, commands as inert data, subscriptions — are specified on the APP plane page.

#Imports and visibility

importStmt = "import" pkgRef [ "as" IDENT ]
pkgRef     = IDENT "/" IDENT

import author/package binds a package under its name or an as alias; only the package's pub declarations are reachable, as qualified names mod.f. The / of the coordinate is never confused with division — it is only reachable after import IDENT, a state where no expression exists.

fluximport acme/wyckoff as wk
pub def helper(x) = wk.zone(x) * 2

Post-v1. The import mechanism, content-addressed resolution and lockfile semantics are fully specified (packages); the public registry deployment is deferred.

#Expressions

The expression grammar is a strict stratification: each level refers only to the next tighter level, so precedence is built into the shape of the grammar itself (no precedence declarations are needed for the arithmetic chain, and the parse is LR(1) by construction).

expr      = arrowExpr
arrowExpr = condExpr [ ARROW expr ]                (right-assoc; lambda or pair — see below)
condExpr  = ifExpr | letExpr | ternExpr
ifExpr    = "if" expr "then" expr "else" expr      (else mandatory)
letExpr   = "let" letPat "=" expr "in" expr
ternExpr  = coalExpr [ "?" expr ":" expr ]         (≡ if/then/else)
coalExpr  = orExpr [ "??" coalExpr ]               (right-assoc; ≡ nz)
orExpr    = andExpr { "or" andExpr }
andExpr   = notExpr { "and" notExpr }
notExpr   = "not" notExpr | cmpExpr
cmpExpr   = addExpr [ cmpOp addExpr ]              (NON-associative)
addExpr   = mulExpr { addOp mulExpr }
mulExpr   = unary { mulOp unary }
unary     = "-" unary | postfix
postfix   = primary { callTail | indexTail | clockTail | memberTail | safeNavTail | withTail }
primary   = NUMBER | DEC | DUR | PCT | PX | SPAN | RATE | STRING | interpStr | BOOL | "na"
          | IDENT | inputExpr | tweenSig | matchExpr | listLit | recordLit | blockExpr
          | sceneExpr | parenForm
tweenSig  = "tween" "(" arrowPair [ "," argList ] ")"
arrowPair = condExpr ARROW condExpr

#Conditionals: if, let, ternary, coalescing

if always carries an else — there is no dangling-else problem because the incomplete form does not exist. let … in scopes a binding (or an irrefutable destructuring) over one body expression. The ternary is the same tree as if/then/else, and ?? is sugar for nz (replace na by a default):

fluxplot if close > open then 1 else 0
r = let x = close - open in x * x
d = let { upper, lower } = bollinger(close, 20) in upper - lower   // destructuring let
t = close > open ? 1 : 0                     // ≡ if close > open then 1 else 0
z = close[1] ?? 0                            // ≡ nz(close[1], 0)
x = if a then 1                              // ✗ syntax error — else is mandatory

#match

matchExpr = "match" condExpr "{" { TERM } matchArm { sep matchArm } { sep } "}"
matchArm  = pattern ARROW expr
pattern   = "_" | "na" | ctorPat | recordPat | IDENT
ctorPat   = IDENT [ "(" [ IDENT { "," IDENT } ] ")" ]
recordPat = "{" [ IDENT { "," IDENT } ] "}"

match is the eliminator of variant values (and of na), usable in any expression position. The scrutinee is arrow-free (condExpr), so every -> inside the braces belongs to an arm. Patterns are flat in v1: wildcard, na, a constructor with bound payload names, a record destructure, or a binding identifier — no deep nesting. Exhaustiveness is checked statically; a non-exhaustive match is rejected with [ErrTotalMatch].

fluxvariant Phase { ask | suspense | revealed }
variant Tool  { Select | Event(kind: num) | At(price) }
m = { phase: ask }
t = Event(3)
next = match m.phase {
  ask -> suspense
  suspense -> revealed
  _ -> ask
}
which = match t { Event(k) -> k; At(p) -> 0; _ -> na }
q = SaveState.Saved            // a qualified constructor disambiguates cross-variant homonyms

A nullary tag and a binding identifier are the same parse tree (an IDENT pattern); whether ask names a known constructor or binds a fresh variable is resolved semantically, exactly like function resolution — never a parse fork.

#Record, list and block literals; scene

recordLit = "{" { TERM } fieldAssign { sep fieldAssign } { sep } "}"     (≥ 1 field)
fieldAssign = IDENT ":" expr
listLit   = "[" { TERM } [ expr { "," expr } { sep } ] "]"
blockExpr = "{" { TERM } { blockBind sep } expr { TERM } "}"
blockBind = IDENT "=" expr
sceneExpr = "scene" uiBlock
parenForm = "(" [ parenItem { "," parenItem } ] ")"
parenItem = expr [ ".." expr ]

A record literal builds the first record ({a: 1, b: 2}; an empty {} is not a record). A list literal builds a bounded vec ([1, 2, 3], [] — the spine of every APP command list). A block expression sequences immutable bindings before a final expression and desugars into nested let … in — the multi-line body form:

fluxm = {a: 1, b: 2}
xs = [1, 2, 3]
empty = []
v = { x = 1; y = x * 2; y + x }      // blockExpr — desugars to let x = 1 in let y = … in y + x
w = { close }                        // a one-expression block
bad = { a, b }                       // ✗ syntax error — neither a record (no `:`) nor a block (no `=`)

scene { … } packages a multi-element CANVAS scene as a value of kind ui — the only expression form of a scene, which otherwise lives at statement level. It is how a def returns an overlay:

fluxdef overlayOf(d) = scene {
  line { a: d.a; b: d.b }
  for it in items(d) -> dot { at:(it.bar, it.price) }
}

The paren form unifies grouping, coordinates and lambda heads: (x) grouping, (x, y) a coordinate/argument pair (at:(bar.i, close)), (2..200) a range operand, (p) -> … a lambda head.

#The postfix chain

callTail    = "(" [ argList ] ")"
indexTail   = "[" expr "]"
memberTail  = "." IDENT
safeNavTail = "?." IDENT
clockTail   = "@" clockOperand
clockOperand = STRING | IDENT [ callTail ] | "(" expr ")"
withTail    = "with" recordUpdateBody
recordUpdateBody = "{" { TERM } [ fieldAssign { sep fieldAssign } { sep } ] "}"
argList     = arg { "," arg }
arg         = [ IDENT ":" ] expr
arrowPair   = condExpr ARROW condExpr

All six suffixes bind at the same (tightest) level and associate left, in lexical order:

fluxslots = window(close, 20)
bb    = bollinger(close, 20)
m     = { a: 1 }
i     = input(0, 0..19)
chain = bollinger(close, 20).upper[1]@"1d"
//      ((( bollinger(close,20) ).upper )[1] )@"1d"
prev  = close[1]                       // [Delay] — scalar stream, constant index
s     = slots[i]                       // [Index] — vec element, runtime index, out-of-bounds → na
htf   = ema(close, 50)@"1d"            // clock suffix — see time-and-state
safe  = bb?.upper                      // na-propagating navigation
y     = m with {a: 3}                  // functional record update — shape-preserving

The @ operand is deliberately restricted (a string, an identifier or call, or a parenthesized expression) so that x@"1d" + 1 parses as (x@"1d") + 1 with no precedence subtleties. with { … } is a postfix keyword, not a brace-led expression — the update body is only reachable after the word with, which is what keeps it distinct from every other brace.

Arguments may be labeled (focus(view, over: 600ms)); the label is decided by the IDENT : lookahead. Member access doubles as UFCS — close.ema(20).rsi(14) is rsi(ema(close, 20), 14); the . resolves to field, function call or qualified module name at compilation with no grammar impact (see Operators).

#Lambdas

A lambda is an arrow whose left side is a paren form of bare identifiers, in a position that expects a function (the higher-order arguments of fold, map, scan, loop, …):

fluxdef ema0(s, n) = let a = 2/(n+1) in scan(s, (p) -> a*s + (1-a)*p)

r   = window(close / close[1], 20)   // a vector of ratios
sq  = vec.map(r, (x) -> x * x)
inc = vec.map(r, _ + 1)              // placeholder sugar — exactly one `_`, mono-argument

The parens are part of the form — a bare x -> … in a value position is a tween pair, not a lambda (see the next section); the single-argument shorthand is the _ placeholder. A multi-statement body is a block expression: (x) -> { d = x - open; d * d }.

#Blocks and properties

block     = "{" { TERM } [ item { sep item } { sep } ] "}"
item      = propEntry | stmt
propEntry = IDENT [ ":" propValue ]
propValue = arrowPair | addExpr ".." addExpr | condExpr
literal   = NUMBER | DEC | DUR | PCT | PX | SPAN | STRING | BOOL

There is one block form. Its items are properties (key: value, or a bare flag like stagger) and/or statements; which of the two a given head permits (a dot block takes properties, a group block takes statements) is a semantic restriction, not a separate grammar. A property value may be a plain value, a range lo..hi, or a tween pair a->b:

fluxdot { at:(bar.i, close); r: 6->24; glow: 16; span: 2..8; stagger }

#The single arrow

-> is one token and one grammar production — Arrow { lhs, rhs } — with five readings selected entirely by context. There is no second arrow symbol anywhere in the language.

Deterministic by construction, in two steps:

• Guarded arrows never reach the expression grammar. In on EVENT -> ACTION, match e { pattern -> expr } and for x in coll -> child, the operand before the arrow is a condExpr — a stratum that excludes arrowExpr — so the event, scrutinee and collection can never absorb the ->. The arrow is claimed by the head's own production, with zero choice for the parser.
• Unguarded arrows build one tree; the role is decided at inference. a -> b in an expression parses as the single Arrow node whether it will act as a lambda or as a tween pair. Kind inference reads it as a lambda exactly when the left side is a paren form of bare identifiers and the position expects a function; otherwise it is a pair of values (6->24). The same tree also serves the dedicated pair production arrowPair used by tween and property values.

fluxplot -> 3            // ✗ syntax error — an arrow needs a left side; no production begins with ->

Why one arrow. Five separately spelled arrows would demand five tokens, five precedence entries and a reader's mental table mapping spelling to role. One token with head-guarded readings costs the grammar nothing (each guard is an LR state the head already owns), keeps every program visually consistent, and moves the only genuine ambiguity — lambda versus pair — to the kind checker, which must inspect that position anyway. The parser never forks.

#Precedence and associativity

From loosest to tightest; each level is a stratum of the grammar above:

Consequences worth spelling out:

fluxm = -close[1] * 2                 // (-(close[1])) * 2 — unary minus tighter than `*`, postfix tighter still
p = close > open                  // signal
q = volume > sma(volume, 20)      // signal
r = not p and q or p              // ((not p) and q) or p
s = m ?? 0.0                      // m ?? 0.0 — null-coalescing
t = close > open ? high : low     // (close > open) ? high : low
e = macd(close).hist[1]@"1d"    // (((macd(close)).hist)[1])@"1d" — postfix chain, lexical order
bad = a < b < c              // ✗ syntax error — comparisons do not chain (non-associative)

Outside the ladder. Three token families take no precedence level at all. The range .. is non-associative and appears only in its dedicated slots (fills, spans, input ranges, paren items, property values) — never inside the operator cascade, so bb.upper..bb.lower needs no parentheses. The clock suffix @ restricts its right operand to a clockOperand, so x@"1d" + 1 is (x@"1d") + 1 by construction. And : and , are pure separators.

Why stratification instead of precedence annotations. Each stratum refers only to the next tighter one — there is no cross-recursion anywhere in the expression grammar — so the LR automaton is the precedence table. Nothing needs to be declared, so nothing can be declared inconsistently; the non-associative comparison level is a production that does not repeat. The comparison ban on chaining exists because a < b < c has no boolean reading in a dimensional language (the first comparison yields a signal, which is not ordered against c — the grammar rejects the shape before the kind checker would).

Newlines. The statement separator TERM and its continuation rules interact with this ladder (an infix operator at a line start continues the previous line). The policy is lexical and specified in lexical structure.

#Disambiguation catalogue

Every place where two constructs could compete for the same token is closed by one of five devices: a tokenizer rule, the stratification, a guarding head keyword, distinct LR states, or one token of bounded lookahead. The design plan enumerates each potential conflict and its resolution; the grammar build re-proves the absence of conflicts mechanically on every change. The cases a reader actually meets:

The brace. All { readings are separated by where the brace is reached:

Two brace-led forms — and only two — can begin an expression (record literal, block expression), and one token after { IDENT separates them; a bare { a, b } in expression position is neither, and is rejected. Every other brace is reached after a guarding token, in an LR state where no expression can start — so the parser never forks on {.

The bracket. [ at the start of an expression opens a list literal; [ glued after a postfix is an index. The two sit in different automaton states (expecting-a-value versus holding-a-value), so no input reaches both. The single index form then carries two typing roles, chosen by the receiver's kind, not by grammar: on a scalar stream with a constant index it is the causal delay close[1]; on a vec it is element access slots[i] (runtime index, out-of-bounds yields na).

Items after an identifier. Inside a block, the token after a leading IDENT dispatches: : → property, = → binding, { → view container, ( → call (then a following { makes it a container; otherwise it stays a call — same Call tree either way, the container question is semantic), separator/} → bare flag or expression child.

when, twice. when c: child (a conditional view child, with :) versus dot { … } when c (a trailing guard on a primitive, without :) — the colon decides.

Contextual at. In assert cond "msg" at 500, at is a keyword only in that clause position (after the condition and optional message). It never collides with the property key at: of a canvas block, which is an item-level IDENT :.

The capability colon. chart:read is a single CAPREF token recognized only inside a capability list; the [ of capabilities: [ … ] is likewise reached only after capabilities :, never in expression position. No other colon in the language can occur in that state (details).

Contextual color. color is a keyword only as the head of the two-token sequence color bars; followed by anything else it is an ordinary identifier — which is what lets color name both a field and the color kind (record Stop { color: color }).

The ? family. The lexer's maximal munch orders ?? > ?. > ?; the productions then sit at three different strata (coalescing, postfix, ternary). The ternary's : is reachable only after ? expr, an LR state disjoint from every other colon.

Visibility prefixes. pub / private / package are modifiers exactly when followed by a declaration head or a binding; followed by =, :, . or ( they are plain identifiers. Since two adjacent identifiers are never a valid parse, pub def … commits deterministically.

#Formal properties

The grammar is frozen against six criteria, each with a machine verification — designing the bad states out, then checking by machine, rather than being careful:

Three of these verifications deserve a sentence each:

• The build is the ambiguity proof. The normative grammar is expressed once, as a Lezer LR grammar; an LR generator reports every conflict at build time, so "the build is green" is a machine check of non-ambiguity — not a review claim. (An ordered-choice formalism was rejected for exactly this reason: it does not detect ambiguity, it silently hides it.) The same artifact drives the compiler, the editor's syntax services and the documentation tooling, so there is nothing to drift.
• The corpus round-trips. Every example in the corpus is parsed, printed by the canonical formatter, and re-parsed; the two trees must be identical. A grammar bug and a formatter bug break the same gate. (The corpus is also the golden suite, so an example cannot rot without a test going red.)
• The parser is total. Fuzzing asserts that any byte sequence either parses to a unique tree or is rejected with clean diagnostics — never a crash, never a hang. Malformed input is part of the language's domain.

Semantic coherence extends beyond parsing: for every kind, the admissibility of each operator, comparison, fill and plot is enumerated over the finite-by-family kind set, so no kind/construct pair is left without either a meaning or a named error. The verification harness is described in compiler and runtime and the guarantees themselves in guarantees.

#Additivity and versioning

The grammar evolves under a strict additivity policy:

• A valid script stays valid indefinitely. The semantics of an existing construct is never altered; the surface only grows. Every extension must itself prove zero conflicts at the grammar build before it lands — additivity is a build gate, not a promise.
• Language versions are declared, optionally. Each source file may carry a language version marker; a file without one means "current". (An app's data schema — its Msg variant and model — is versioned separately by the app itself; see the APP plane.)
• Keywords are reserved ahead of need. Words destined for future surface are reserved before their productions ship, so no program written today can shadow tomorrow's syntax — test is the standing example (keyword model). Combined with contextual reservation, this makes future growth collision-free by construction.
• The codemod promise. If a deprecation ever became unavoidable, an automatic codemod would rewrite affected sources at load — mechanically, not by asking authors to migrate by hand. Nothing in v1 is deprecated.

Why this rule exists. A total, deterministic language is a promise about the future of a program, not just its present: a script that replays byte-identically today must still parse — and mean the same thing — under every later compiler. Strict additivity is the syntactic half of that promise; the pinned-routine and byte-identity invariants are the semantic half (compiler and runtime).

#See also

• Lexical structure — tokens, the significant newline, the keyword tiers.
• Kinds — the dimensional lattice the parsed tree is checked against.
• Operators — the per-operator dimensional algebra, UFCS, with, the ? family.
• Inference — how kinds (and the lambda-versus-pair arrow) are decided on the tree.
• The CANVAS plane · The APP plane — semantics of the statement families above.
• Guarantees — the trust page: every machine-verified property in one place.

Kinds — the dimensional type system

Every value in Flux carries a kind: a statement of what the value means, not merely how it is stored. close is not "a float" — it is a price, a point on the price axis. close − open is not "another float" — it is a level, a displacement along that axis. rsi(close, 14) is a bounded oscillator, osc(0,100). Because meaning is tracked, the compiler rejects meaningless arithmetic at compile time, reconciles branches and co-plotted series soundly, and infers presentation — pane, scale, guides — from the kind alone. Kinds are the keystone of the language: causality, totality, presentation inference and the optimizer's guarantees all lean on them.

The mechanism is general. The same machinery kinds calendar arithmetic, exact decimal amounts, physical units (meas[u]), user-declared records and variants, and the APP plane's messages and views; market-data kinds are the flagship instantiation and serve as the running illustrations here. This chapter is the normative reference for the kind system itself — its two cooperating systems, its sorts and partial order, join and meet, its orthogonal tags, and named declarations. Per-operator rules live in Operators; the inference algorithm, the error policy in full, and the complete kind → presentation table live in Inference.

#Two systems, one error channel

"Join and meet of binary operations" is a category error, and the kind system is built on refusing it. price − price = level, yet price ⊔ price = price — subtraction and unification answer different questions. Flux therefore separates two systems cleanly:

• (A) The coercion lattice (K, ≤, ⊔, ⊓, ⊤, ⊥). a ≤ b means "a coerces to b without lying about itself". The join ⊔ unifies — the branches of an if, the two arguments of nz, series co-plotted in one pane. The meet ⊓ constrains — the kind a parameter demands, the intersection of oscillator bounds. The lattice answers "is there one kind that covers both?" — nothing more.
• (B) The dimensional operator algebra for + − × ÷ < > == — a rule table that computes the result kind of each operation from the kinds of its operands, in the style of classical dimensional analysis. This is not the join: it can move across the lattice (price − price → level) or refuse outright (price + osc → ⊤).
• A single error channel: ⊤. Every undefined rule in (B) and every incompatibility in (A) produces the same top element ⊤. A ⊤ is a hard error in a demanding position — an operand, a plot target, an argument — and an operand is itself a demanding position, which is why close + rsi(…) fails at the +, whether or not anything downstream reads it. A ⊤ that reaches no demanding position at all is a warning ([WarnTop]), not a failure.

Read the two rules above together and one thing follows that is easy to miss, and worth stating outright, because it is the difference between a type system that is strict and one that is merely loud: a mixture of dimensions never reaches ⊤. Add a price to an oscillator and the algebra has no rule, so you get ⊤ and a hard [ErrDim]. But reconcile a price and an oscillator — take one branch of an if or the other — and the join does not fail. It erases the dimension and lands on quantity: a real kind, a number that remembers it is a number and has forgotten what of. That is a [WarnBranchDim], and the value flows.

The hard channel is for nonsense that is certain; the soft one for a mixture that is merely suspicious. What separates them is not consumption — it is where the ⊤ was born. ⊤ still appears in a reconciliation, and is still hard when it does: an if whose branches cross sorts (a price and a colour) has no common kind at all, and no erasure can save it.

Why this rule exists. If − were modelled as a join, close − open would have kind price ⊔ price = price — a displacement mislabelled as a point, and every downstream rule (price + level → price, overlay placement, axis choice) would silently go wrong. If joins were modelled as algebra, if c then ema12 else ema26 would need an "operator rule" for a question that is really "do these two branches share a kind?". Keeping the two systems separate — and letting them fail into one shared ⊤ — reconciles a total lattice (every pair of kinds has a join) with a system that still rejects nonsense (that join is ⊤ exactly where no honest common kind exists).

fluxfast   = volume > sma(volume, 20)

spread = close - open              // price − price → level   (algebra, system B)
line   = if fast then ema(close, 12) else ema(close, 26)
                                   // price ⊔ price → price   (join, system A)
plot spread, line

// ✗ plot close + rsi(close, 14)   — [ErrDim]: point + dimensionless has no affine meaning

Three failures, and they are not the same failure:

fluxfast = volume > sma(volume, 20)

mix  = if fast then close else rsi(close, 14)   // ⚠ [WarnBranchDim] — no common dimension, so
plot mix                                        //   the join ERASES it: mix : quantity. It flows.

// ✗ plot close + rsi(close, 14)   — [ErrDim]: the ALGEBRA has no rule for point + dimensionless.
//                                   Hard, at the `+`, read or not: an operand is a demanding
//                                   position, and there is nothing suspicious about this — a
//                                   point plus a bare number is not a thing.
// ✗ if fast then close else up    — [ErrDim]: price ⊔ color = ⊤. Crossing SORTS is not a mixture
//                                   the lattice can erase — there is no common kind to land on.

[WarnTop] is the lint that sits on top of the first case: a binding whose dimension was erased and which nobody reads is almost always a mistake in the making, so leave mix unplotted and you get a second warning saying exactly that. Consume it and the [WarnTop] goes away — the [WarnBranchDim] stays, because the erasure is still there.

A ⊤ also propagates as a kind poison without re-diagnosing: one root fault produces one message, and every node it contaminates stays silent (the anti-cascade rule; see Inference for the typable cone that keeps live preview working around it).

#The affine substrate

The asymmetry of the algebra is not a convention — it is geometry. The price axis is a one-dimensional affine space:

• price is a point on that axis,
• level is a vector — a displacement between points,
• ratio is a dimensionless scalar.

Affine geometry then hands the core rules over for free: point − point = vector (price − price → level), point ± vector = point (close + atr(14) → price), point ÷ point = scalar (price ÷ price → ratio), and "point + point" does not exist at all — which is exactly why close + rsi(close, 14) is refused rather than computed.

Above the affine pairs, a dimension is an element of an abelian group of integer exponents over the five generators {P, V, T, I, rad} — price, volume, time, ordinal bar index, angle. Multiplication adds exponent vectors, division subtracts them, so × and ÷ are total on dimensions (price × volume → pv is P·V; pv ÷ volume → price is P¹V¹−V¹). Only +, − and the order comparisons demand equal dimension, because adding metres to kilograms — or points to displacements of a different axis — has no meaning.

fluxgap    = close - close[1]          // level      pt(P) − pt(P) = vec(P)
band   = close + 2 * atr(14)       // price      pt(P) + lit·vec(P) = pt(P)
rel    = close / open              // ratio      P⁰ — dimensionless, centered on 1
flow   = close * volume            // pv         P·V by the group law
speed  = change(close, 5) / (5 bars)  // slope    vec(P) ÷ vec(I) = P·I⁻¹ — price per bar

Three affine pairs live in the antichain, one per axis: price/level on P, time/ duration on T, and barindex/barspan on the ordinal axis I (rule A1 — the x axis is affine too, so barindex − barindex → barspan, and a regression slope is level ÷ barspan → slope = P·I⁻¹, price per bar, deliberately distinct from P·T⁻¹).

#The sorts

The lattice is stratified into sorts: fine structure inside each sort, and across sorts the join is ⊤ and the meet is ⊥. The extrema are shared by all sorts: ⊤ (any — the error channel, hard when demanded) and ⊥ (never — the kind of na, which inhabits every kind: na : ∀κ.κ enters the lattice at ⊥ and subsumes upward to whatever is expected).

#The scalar sort

Everything in the scalar sort sits below quantity, which sits below ⊤.

The dimensionless spine — lit < {ratio, osc(lo,hi), signal, dir, depth} < num:

• lit — a const-folded literal, polymorphic in dimension: lit ≤safe every scalar, dimensioned or not. This is what makes close + 10, close > 30000 and nz(x, 0) legal without ceremony: the literal adopts the kind its context gives it.
• ratio — dimensionless, centered on 1, multiplicative (price ÷ price, band width).
• osc(lo,hi) — dimensionless and bounded, an interval-parameterized family (rsi → osc(0,100), cmo → osc(-100,100), cmf → osc(-1,1)). See the interval sub-lattice below.
• signal — a boolean event, {0,1} (comparisons, cross_up, rising, in_session).
• dir — a direction, {-1, 0, +1} (rule A6): categorical-discrete, the flat sibling of signal (dir < num). It types the direction field of trend structures (superTrend(…).dir), is presented as bar coloring or marks, and is discriminated by comparison (st.dir == 1), never by match and never by <. (There is no unary + in the grammar: the value +1 is written 1.)
• depth — a dimensionless z-intention tagged @z, produced by analysis and consumed by the presentation z channel (projected in 3-D, flattened in 2-D).
• num — dimensionless of unknown role: the least upper bound of the spine. kdj(…).j and calendar accessors land here.

The dimensioned antichain — each element ≤ quantity, each ≥ lit, and all pairwise incomparable: price = pt(P) · level = vec(P) · volume = V (signed values allowed: obv) · pv = P·V (money-flow) · time = pt(T) · duration = vec(T) · barindex = pt(I) · barspan = vec(I) · slope = P·I⁻¹ · angle = rad — plus every composed dimension the group law can produce (P², P²·V⁻¹, …), which are full plottable kinds presented in an auto pane labelled by their exponents, without warning (rule A3).

quantity — the erased dimension, least upper bound of the whole scalar sort. It is what a dimensionally incompatible join produces (see L2 below): still plottable, but suspect, and always flagged. quantity is reserved for genuinely erased or mixed dimensions; a precise composed dimension like P² never degrades to it.

#The categorical sorts — color, clock, string

Categorical kinds are flat (each is one element, joining only with itself) and live outside arithmetic; each is consumed by a dedicated eliminator rather than computed with:

• color — an RGBA style value, consumed by fills, bar coloring and style channels (Color).
• clock — a resampling schedule: an ordinal index with constructors tf("1d"), renko(box), pnf(box, rev), range(r). A clock is a first-class value (you can select one with an if, take one as an input) but it is eliminated only by @ (Time and state); it is never plotted and never compared.
• string — bounded, immutable UTF-8 text (rule A12): labels, prompts, alert messages. string is flat like color and outside numeric arithmetic, with exactly one operator overload: string + string → string is concatenation — the single categorical line of the + rule table. There is no string < string (locale-dependent collation is excluded by determinism), equality is bit-equality, and a string is consumed by text-expecting channels — it is never plotted as a series (Text).

#The structural sorts — vec and record

Structural kinds compose componentwise; mismatched shapes are nonsense and resolve to the extrema.

• vec<κ>[n] — a vector of κ with const-folded capacity n (n ≤ N_max = 10 000). Capacity, not exact count: see below. Introduced by window(e, n), list literals, vec.fill(N, x) and vec.range(N); covariant in κ.

  Notation. vec<κ>[n] is the metalanguage of this documentation. In source, the same kind is written vec(κ, N) — with parentheses, because < and > are exclusively the comparison operators and never type delimiters.

• record{f₁:κ₁, …} — a named product. This sort is load-bearing for the catalogue: a large share of the built-in kernels return records — bollinger → record{upper, middle, lower: price}, macd → record{macd, signal, hist: level}, superTrend → record{st: price, dir: dir}, adx → record{adx, plusDi, minusDi: osc(0,100)}. Projection is e.f; functional update is e with { f: v } (shape-preserving — unlisted fields carry over, unknown fields are [ErrField]).

#The APP-plane sorts — variant and ui

The APP plane adds two sorts by the same construction, directly under ⊤, without reopening the sealed core lattice:

• variant{Tag₁:κ₁ | …} — the tagged sum, categorical dual of record (the product). Its introduction is the constructor injection Tag(e), its eliminator is match (symmetric to projection). Order, join, meet and ⊤-propagation are derived identically to record: label sets are invariant (same labels → refine per payload, covariantly; different label sets → incomparable, join ⊤, meet ⊥). Messages, commands and subscriptions of an app are variants (The APP plane).
• ui — the view-primitive sort: a closed, vetted set of primitives, flat like color, consumed by the host renderer, and never coercible to a scalar (ui ⊔ κ = ⊤, ui ⊓ κ = ⊥ across sorts — a primitive in scalar position is caught immediately).

#No function sort

There is deliberately no arrow kind in the lattice. Lambdas are second-class: a (p⃗) -> body is admitted only where a higher-order kernel expects a function (window/fold/map/scan/loop, vec.where, sortBy, …) and is inlined at that site. A lambda can therefore never be a record field, a vec element, a variant payload or a let-bound value — which is what keeps every value representable as plain data, every buffer bounded, and compiled artifacts free of closures and function pointers. Recursion goes through def (whose call graph must be acyclic — [ErrTotalRec]) or through bounded scan/loop, never through a self-referencing lambda.

#The kind catalogue

One line per kind. The full presentation table (pane/overlay/scale/guides/css class per kind) is normative in Inference; the last column here is the one-line summary.

decimal(scale), period, the asset tag (B,Q[,@v]), meas[u] and metric[id] are orthogonal tags on these kinds, not kinds of their own — see Orthogonal tags below.

#The partial order

The single most consequential decision in the order: dimensions form an antichain, and num is incomparable to every dimension — price ⊀ num. Dimensioned kinds rise to quantity, never to num.

Why this rule exists. If price ≤ num held, then signal ⊔ price = num — a boolean event and a price would silently reconcile into an ordinary plottable number, and the error detection that motivates the whole system would evaporate at exactly the moment it matters (a co-plot or an if mixing incompatible things). By routing all dimensioned kinds to quantity instead, a mixture is never silent: in arithmetic it is refused ([ErrDim]), and in branch reconciliation it compiles to quantity and is flagged ([WarnBranchDim]) — visible, plottable, suspect.

Descending the order gains information, and presentation always reads the lowest kind known — which is why inference synthesizes the minimal (principal) kind and coerces only at consumption sites (see Inference).

#Two tiers of coercion edges

Every edge of the order is strictly rising, and each edge belongs to exactly one of two disjoint tiers:

• ≤safe — silent. ⊥ ≤ κ ≤ ⊤ for every κ; widening osc bounds (osc(0,100) ≤ osc(-100,100)); widening vec capacity (vec<κ>[k] ≤safe vec<κ>[N] for k ≤ N); the spine edges {ratio, osc, signal, dir, depth} ≤ num and num ≤ quantity; and lit ≤ every scalar.
• ≤lossy — compiles, warns, offers a quick-fix. Erasing a dimension (D ≤ quantity for any dimensioned D), and accepting a non-normalized affine combination. Loss of information is legal but never silent.

Antisymmetry survives because both tiers rise strictly and never overlap.

#Literal polymorphism

lit is the ergonomic floor of the scalar sort. A const-folded literal coerces safely into any scalar, so the natural things are legal without ceremony:

fluxhot   = close > 30000              // price vs lit → the lit reads as price → signal
lift  = close + 10                 // lit adopts price → price
safe  = nz(change(close, 1), 0)    // level ⊔ lit = level
shift = rsi(close, 14) - 50        // osc(0,100) − lit → osc(-50,50): interval propagated

The compiler still lints impossible literals against claimed bounds (rsi(close,14) > 150 is [WarnLit]), because a lit adopting a kind does not suspend arithmetic sanity.

#Capacity, not length: vec<κ>[n]

The n in vec<κ>[n] is a const-folded capacity — an upper bound, not an exact count. A shorter vector inhabits a longer one through the ≤safe widening vec<κ>[k] ≤safe vec<κ>[N] (k ≤ N), its tail [k, N) reading na. Memory stays bounded by the declared cap, so totality holds; bounded iteration (map/fold) is na-aware on the capacity, so a widened tail contributes nothing. [ErrLen] fires only when two declared capacities are genuinely incompatible — otherwise the shorter operand widens to the longer. This is also why list literals of different lengths join cleanly: vec<κ>[k] ⊔ vec<κ>[m] = vec<κ>[max(k,m)].

fluxw    = window(close, 20)           // vec<price>[20] — a specific produced length
wide = nz(w, window(close, 50))   // vec<price>[50] — 20 widens into 50, tail na

Non-const or over-cap lengths are [ErrTotal] (n ≤ N_max = 10 000) — the price of "total, bounded memory" is that a capacity is always a compile-time fact.

#Join and meet

#The join catalogue

κ ⊔ κ = κ           ⊥ ⊔ κ = κ           ⊤ ⊔ κ = ⊤           lit ⊔ κ = κ
osc(L,H) ⊔ osc(L',H') = osc(min L L', max H H')          — the envelope
spine siblings → num          (osc ⊔ ratio = num · dir ⊔ signal = num)
D ⊔ D' (D ≠ D') = quantity    D ⊔ num = quantity    signal ⊔ price = quantity
vec<S>[k] ⊔ vec<T>[m] = vec<S ⊔ T>[max(k,m)]
record{f:A} ⊔ record{f:B} = record{f: A ⊔ B}             — differing field sets → ⊤
variant: same label set → per-payload join                — differing label sets → ⊤
across sorts → ⊤

Two placements deserve their reasons:

• signal ⊔ price = quantity, not ⊤ (correction L2). quantity is a common upper bound of both (signal ≤ num ≤ quantity, price ≤ quantity), so ⊤ would not be the least one — and the error policy wants exactly this outcome: mixed-dimension branch reconciliation is a warning ([WarnBranchDim] on a plottable quantity), while mixed dimension in an arithmetic position stays a hard [ErrDim]. The boundary between hard and soft runs between algebra and reconciliation, not through the lattice.
• dir ⊔ signal = num, not quantity. Both are dimensionless spine leaves below num, so num is their least upper bound — exactly as osc ⊔ ratio = num. Promoting to quantity would put a larger element above an existing upper bound and destroy uniqueness of the LUB.

Joins land at ⊤ exactly where genuine nonsense lives: across sorts (price ⊔ color, num ⊔ record{…}), on mismatched structural shapes (field or label sets that differ), and — the one enumerated in-sort exception — on equal dimension with differing representation tags ([ErrRepr], below). Mere dimension mixtures never reach ⊤; they rise to quantity and stay visible.

fluxc = volume > sma(volume, 20)

a = if c then rsi(close, 14) else cmo(close, 14)
        // osc(0,100) ⊔ osc(-100,100) = osc(-100,100) — envelope
b = if c then close else rsi(close, 14)
        // price ⊔ osc = quantity — compiles, [WarnBranchDim], suggest two panes

#The meet catalogue and the lit correction

⊤ ⊓ κ = κ           ⊥ ⊓ κ = ⊥
quantity ⊓ D = D            num ⊓ ratio = ratio            — a constraint refines
osc ⊓ osc = interval intersection      (disjoint → lit, by L1)
incomparable scalars ⊓ = lit                                — correction L1
across sorts → ⊥            (lit does not cross sorts)
variant/record: same shape → per-component meet — differing shapes → ⊥

Correction L1 is load-bearing: the meet of two incomparable scalars — say price ⊓ volume, or dir ⊓ signal — is lit, not ⊥. lit ≤safe both operands, so lit is a common lower bound, and the greatest lower bound must sit at or above every common lower bound; forcing ⊥ would contradict lit ≤ price ∧ lit ≤ volume ⇒ lit ≤ price ⊓ volume and break the absorption law (price ⊓ (price ⊔ level) = price ⊓ quantity = price holds precisely because meets refine rather than annihilate). Within the oscillator family the same correction resolves the empty intersection: two osc kinds with disjoint intervals are incomparable scalars, so their meet is lit — the empty interval ∅ is the bottom only of the interval sub-lattice viewed in isolation, never the global GLB.

#The osc interval lattice

osc(lo,hi) is a family ordered by interval inclusion: osc(L,H) ≤ osc(L',H') ⟺ [L,H] ⊆ [L',H']. Join is the envelope, meet is the intersection, and bounds may be infinite constants: osc(-∞,∞) (rule A4) is the kind of the entire percent-change family (roc, cci, trix, coppock, fisher, kst, chaikinVolatility, volumeOscillator) — dimensionless, centered on 0, additive, which distinguishes it cleanly from ratio (centered on 1, multiplicative) and from num (role unknown).

Bounds are presentation claims, not runtime invariants. The kind osc(0,100) asserts "this is presented on a fixed 0–100 scale with a midline"; only an explicit clamp makes a bound real at runtime, and arithmetic honestly propagates claimed intervals (rsi − 50 → osc(-50,50)). Rule A5 splits the catalogue accordingly: a bound genuinely enforced by the computation (rsi, stochastic, mfi, cmf) yields a fixed [lo,hi] scale; a merely conventional bound (adx, correl, balanceOfPower) is a claim — auto-scale plus indicative guides. A bound that failed to const-fold would fall back to num; no kernel in the catalogue produces one.

#Deep ⊤ propagation

vec<⊤>[n], record{f: ⊤, …} and variant{T: ⊤ | …} all reduce to ⊤. Without this, a buried mismatch — vec<price> ⊔ vec<color> producing vec<⊤> — would slip beneath every κ ≠ ⊤ guard and surface as a runtime mystery instead of a compile-time diagnosis. An error at any depth is an error of the whole value.

#Closure, verified by enumeration

With L1 and L2 in place, every pair of kinds has a unique LUB and a unique GLB. The kind set is finite by structural family: the dimensional core is finite, and every parameterized axis — osc bounds, vec capacity, decimal scale and precision, the representation tags, the asset-tag components and the fx pair annotation — is a const-folded tag whose keys are enumerable at the point of verification. The lattice laws (antisymmetry, absorption, uniqueness of LUB/GLB) are therefore machine-verified by exhaustive enumeration, family by family — not merely argued (Guarantees). Named record/variant declarations preserve this: their reference graph must be acyclic ([ErrTotalType]), so every named kind flattens to a finite-height structure.

#The operator algebra in brief

The full, normative per-operator tables are in Operators. The shape of system B, in one screen — a missing rule means ⊤, hence [ErrDim] when consumed:

• ± (equal dimension; affine): pt(d) − pt(d) → vec(d) · pt(d) ± vec(d) → pt(d) · vec ± vec → vec · ratio ± ratio → ratio · osc ± osc → propagated interval · lit ± x → x · differing dimensions → ⊤. One categorical overload: string + string → string (concatenation), and nothing else touches string.
• Affine combinations ((high + low) / 2): the expression is normalized to Σ λᵢ·ptᵢ with const-folded coefficients; Σλ = 1 → price (a weighted point), Σλ = 0 → level (a pure displacement), anything else → quantity + [WarnAffine]. Multiplying by a lit preserves the role, so sma(close,20) + 2 * stdev(close,20) types as price + level → price. Rule A7 applies this after inlining, so recursive composites type correctly: dema = 2·ema − ema(ema) has Σλ = 1 → price.
• × and ÷ (the group law, rule A2): exponent vectors add and subtract, so both operators are total on dimensions — D × ratio → D, price × volume → pv, price × price → P² (plottable, A3), pv ÷ volume → price, pv ÷ price → volume, level ÷ barspan → slope.
• Order comparisons (< > <= >= cross_*): admitted only on the ordered scalar sort with compatible dimensions (κₐ ⊔ κ_b ∉ {quantity, ⊤}) → signal. price < osc is [ErrDim]; color, clock, string, record, vec, variant, ui are never ordered; dir is categorical-discrete and outside order.
• Equality (== !=): decidable equality → signal — bit-equality for scalars, string, dir, color; deep, na-aware equality for record/vec/variant (mismatched shapes → [ErrDim]); clock and ui are consumed, never compared ([ErrArg]).
• Logic (and or not): signal × signal → signal — there is no arithmetic on signal.

fluxtrend = ema(close, 50)                    // price   ([CallPoly]: α = price)
hits  = count(close cross_up trend, 20)   // osc(0,20) — const-folded n
since = barssince(close cross_up trend)   // barspan — a bar count, not a num
bad   = close < rsi(close, 14)            // ✗ [ErrDim] — price ⊔ osc = quantity

#Orthogonal tags

Beyond its dimension, a kind can carry up to three orthogonal tags, plus one axis that lives only on ratio:

1. a numeric representation tag — f64 (default) or decimal(scale) (rule A11);
2. a time representation tag on the T dimension — machine (default; exact elapsed time — duration) or calendar (period, rule A10);
3. an asset tag — a fixed-arity string-keyed n-uple (B, Q [, @v]) on price-dimension kinds (rule A9);

plus (4) the currency-pair annotation of fx — an axis carried only by ratio, whose top is the bare ratio itself. Since ratio never carries an asset tag, no kind ever carries four tags: a decimal price[BTC,USD] holds three (representation + asset + dimension), and that is the ceiling.

The two axes families obey two different regimes — and the difference is the point:

• Representation tags (1, 2) never coerce silently. On two kinds of equal dimension but differing representation tags, join and meet produce ⊤ — surfacing as [ErrRepr] in a demanding position. The only bridge is an explicit conversion (toDecimal / toFloat; the period constructors for calendar time). This mirrors the arithmetic refusal: you do not add an f64 price to a decimal price, or a machine duration to a calendar period, without saying so.
• The asset tag (3) widens per component. Each component has its own top (⊤base, ⊤quote, ⊤venue); a join widens the component that differs and preserves the one that matches — price[B1,Q] ⊔ price[B2,Q] = price[⊤base, Q] — and never raises [ErrRepr]. Safety comes not from the join but from the tagged ± algebra: +, −, the comparisons and the affine rule all demand component-wise identical tags, and refuse with [ErrDim] otherwise. Widening keeps composition possible (two venues' price[BTC,USD] can form an index); the identity gate still catches every unit bug.

For both regimes, identical tags fall back to the plain dimension rules with the tag preserved through ± × ÷: decimal price − decimal price = decimal level, period + period = period, price[BTC,USD] − price[BTC,USD] = level[BTC,USD].

#Numeric representation — f64 and decimal(scale)

decimal(scale) is exact fixed-point, orthogonal to dimension: a decimal always has a dimension, and the group law is unchanged (money ÷ qty → price with money ≡ pv, qty ≡ volume). The scale rides the kind and the system computes it: ± takes the max of the two scales, × sums them, and ÷ is the one non-closed operation — it requires an explicit target scale and rounding mode. Declared precision picks the narrowest backing (i64/i128/i256); exceeding the declared precision yields a deterministic na plus a diagnostic, never a silent wraparound. Literals are suffixed: 1.50d is decimal(2), 1.5 is f64. Decimal's domain is settled money — order amounts, fills, balances; the analysis kernels remain f64.

fluxexact = toDecimal(close, 2)        // decimal(2) price — explicit entry, rounds
bad   = close + exact              // ✗ [ErrRepr] — f64 price + decimal price
worse = if c then close else exact // ✗ [ErrRepr] — the join refuses the same mixture
fine  = toDecimal(close * volume, 2) + toDecimal(close * volume, 2)  // decimal(2) pv — a money amount adds; same representation, scales combine

#Time representation — machine and calendar

time = pt(T) is an instant (an int64 epoch under the hood); duration = vec(T) is exact elapsed machine time. period is the same vec(T) tagged calendar — a months-and-days quantity that is aware of zones and daylight-saving transitions. Both t + duration and t + period are dimensionally pt(T) + vec(T) → pt(T); the tag is what separates "exactly 24 hours later" from "the same wall-clock time tomorrow", and the two never mix silently:

fluxage    = time - time[20]                 // duration — machine-exact
renew  = time + time.months(1)           // time — calendar arithmetic, DST-aware

// ✗ (time - time[20]) + time.months(1)  — [ErrRepr]: a duration and a period do not add

period values are produced only by the constructors time.years/months/weeks/days(n) (composable: time.months(1) + time.days(10)); calendar accessors (year, dayOfWeek, …) project a time into a declared zone as num, and out-of-range calendar arithmetic yields a deterministic na, never a wraparound. The pinned time-zone database and the shared conversion routine that make this reproducible are specified with the compute pillar (Compute).

#The asset tag — (B, Q [, @v])

A price is never a bare number: it is a rate, quote-per-base. The asset tag makes that identity dimensional, per kind:

The quote rides every dimension containing the P factor (including composed P², slope); dimensionless kinds carry no asset tag at all. The default is mono-asset price[primary, baseccy], byte-identical to a single-series script that never mentions the axis; tags become concrete only where series keys are static literals, and widen to component tops otherwise. The venue component @v is opt-in (default off; absence is the concrete composite level, not ⊤venue).

fluxc      = volume > sma(volume, 20)
btcUsd = series("BTC-USD").close        // price[BTC,USD]
btcEur = series("BTC-EUR").close        // price[BTC,EUR]
ethUsd = series("ETH-USD").close        // price[ETH,USD]

diff   = btcUsd - btcUsd[1]             // level[BTC,USD]
mixA   = btcUsd + ethUsd                // ✗ [ErrDim] — mixing assets
mixQ   = btcUsd + btcEur                // ✗ [ErrDim] — mixing currencies
cmpQ   = btcUsd < btcEur                // ✗ [ErrDim] — comparisons gate on identity too
rel    = btcUsd / ethUsd                // ratio — cross-base relative strength, tag dropped
either = if c then btcUsd else btcEur   // price[BTC,⊤quote] — the join widens, never errors

#fx and money — existing kinds, tagged

Currency conversion needs no new sort. fx[Q1/Q2] is the kind ratio carrying an optional, ordered currency-pair annotation — the fourth tag axis, living only on ratio, top = the bare ratio. money[Q] is an alias for decimal pv[Q]. Zero new sorts, zero new lattice height. An fx arises from a division of same-base, different-quote prices, or from a feed declared as an fx series; conversion is a type-checked unit cancellation:

fluxc         = volume > sma(volume, 20)
btcUsd    = series("BTC-USD").close
btcEur    = series("BTC-EUR").close
eurGbp    = series("EUR-GBP").close      // an fx series, declared as one

usdPerEur = btcUsd / btcEur             // fx[USD/EUR] — same base, quotes differ
inUsd     = btcEur * usdPerEur          // price[BTC,USD] — the shared quote cancels
flipped   = 1 / usdPerEur               // fx[EUR/USD] — the reciprocal edge
avg       = if c then usdPerEur else eurGbp   // ratio — differing pairs join to bare ratio

A pair mismatch in ×/÷ widens to ⊤quote rather than erroring (the × regime never hard-fails); the pair annotation is excluded from the comparison identity gate, so two fx rates always compare as the ratios they are. The complete edge catalogue — derivation, reciprocal, triangular chaining, conversion in both operand orders — is in Asset & currency.

#Unit and metric annotations

Two further tag axes extend the same construction beyond finance, both carried by num alone, both with the bare num as top:

• meas[u] (rule A14) — generalist quantities: a unit annotation whose u is a product of catalogue symbols with integer exponents (meas[m], meas[m·s⁻¹], meas[kg·m·s⁻²]), augmented by an affine point|delta bit for zero-arbitrary scales (a unit.tempC(20) point versus a unit.tempCDelta(5) displacement — the same point/vector discipline as price/level, applied to temperature). ± and comparisons gate on identical units; ×/÷ compose exponent maps with exact pinned conversion factors and cancel fully to ratio; mixed products with the financial dimensioned kinds are an explicit wall ([ErrDim]). The complete algebra, conversion verb and entrance rules live in Units.

fluxwarm = unit.tempC(20) + 5                // a point ± lit → point — the lit reads as a delta
span = unit.tempC(25) - unit.tempC(20)   // point − point → a 5-degree delta

• Reserved. metric[id] (rule A15) — identity annotations for non-price series (macro indices, on-chain metrics, analytics). Same-id ± preserves, differing ids refuse ([ErrDim]-class), metric[A] ÷ metric[B] → ratio, and kind-preserving families carry the annotation through. The axis is deliberately inert in v1 — no non-price series enters the ANALYSIS plane until the amendment is armed; its design is specified with Asset & currency.

#Named records and variants

Structural kinds can be declared and named at program level:

fluxrecord Band { upper: price, middle: price, lower: price }

variant Tool  { Select | Draw | Erase }
variant Save  { Saved | Failed(code: num) }

t = Tool.Select                     // qualified constructor — resolves homonyms
s = Save.Saved                      //   across variants that share a label

A nullary constructor is read as a value of its variant; a payload-carrying constructor is applied like a function, its payload checked against the declared field kinds. The qualified form T.C selects the constructor of the named variant T — resolved at name resolution, before field projection ever applies, so label collisions across variants are a non-problem.

Two disciplines keep named declarations inside the sealed lattice guarantees:

• Records are monomorphic in v1. A def that projects a field requires a concrete record kind known at inference. Post-v1. an open-row extension (row polymorphism) is a named additive extension — never a v1 prerequisite.
• The reference graph must be acyclic. A declared record/variant may reference other named declarations, but any cycle — direct or transitive — is rejected at name resolution with [ErrTotalType], the kind-level twin of the acyclic def call graph ([ErrTotalRec]). Every named kind therefore flattens to a finite-height structure, and the finite-height property that closure and machine verification rest on extends to user declarations unchanged.

fluxrecord Node { next: Node }          // ✗ [ErrTotalType] — cyclic reference, unbounded height

#A worked example: the lattice refuses wrong physics

Point & Figure charting is a stress test the kind system passes without a single new kind — and it shows the dimensional lens doing real work. Every piece kinds naturally: pnf(box, rev) is a clock; the column state is a scan over a plain record; and the box size must be a level, because the geometry says so:

fluxbox    = atr(14)                    // level — a displacement, by construction
anchor = close                      // price — a point
edge   = anchor + 3 * box           // price ✓ — pt(P) + lit·vec(P) = pt(P)

// the column state the frontier belongs to — a plain bounded scan over a record
state  = scan({ dir: 1, extreme: close, count: 0 },
               (p) -> if close > p.extreme + box
                        then { dir: 1, extreme: close, count: p.count + 1 }
                        else p)

Suppose you had declared the box a price. Then anchor + box would be price + price — point + point, no affine meaning — and the compiler answers [ErrDim] on the spot. The lattice does not merely permit the correct model; it refuses the incorrect one. The same lens types the rest of the state: count is a dimensionless box count (num), so count * box is num · vec(P) → level and extreme + count * box lands back on price; and count is deliberately not a barspan — boxes are not bars, and the kinds keep the two countings from ever being confused.

#Errors and na at the kind level

The error policy in full — including causality, totality and firewall diagnostics — is specified in Inference; the kind-level skeleton is:

• Hard ([ErrDim], [ErrRepr], [ErrLen], [ErrField], [ErrArg], [ErrPlot], [ErrTotalType], [ErrTotalMatch]): a load-bearing guarantee is violated or the nonsense is certain — a ⊤/⊥ in a demanding position, a violated side condition, a shape mismatch.
• Warning ([WarnTop], [WarnAffine], [WarnBranchDim], [WarnBoundsØ], [WarnLit]): suspect but possibly intended, or a recoverable information loss — exactly the ≤lossy tier and the dead-⊤ case.

na deserves its kind-level statement: na synthesizes ⊥ and subsumes into every expected kind, so absence is a value of every kind, never a separate shape. Runtime na propagates through arithmetic with the kind preserved, and every comparison touching na is itself na — never true or false. You test absence explicitly:

fluxm   = sma(close, 200)               // price — na during warm-up
odd = m == na                       // legal, but always na — never true
hit = is_na(m)                      // signal — the way to ask
has = is_some(m)                    // signal — its dual

A match on a possibly-na scrutinee must cover it (an na or _ arm), and destructuring an na record yields na in every field — absence composes structurally, with no special cases to memorize.

#See also

• Operators — the full dimensional algebra per operator, UFCS, with.
• Inference — bidirectional kind inference, presentation inference, the error policy, na.
• Time and state — streams, delay, clocks and @, causality.
• Units — the complete meas[u] algebra: conversions, affine scales.
• Asset & currency — the asset tag, fx and money, venues.
• Design pillars — how dimensional joins the other pillars.

Operators and expression semantics

This page is the reference for the operator layer of Flux: what each operator means, which kinds it accepts, what kind it produces, and why each rule is the way it is. It covers the dimensional algebra of + - * /, the two comparison families, logic on signal, the delay x[n], the resample e @ clock, ranges, indexing and projection, UFCS method syntax, record update with with, destructuring, the ? family of sugar, the _ placeholder, and the full precedence table. How kinds are assigned to whole programs — synthesis, checking, principality — is the subject of Inference; the lattice the operators compute over is defined in Kinds.

A note on the samples. Flux has no expression-statements, so a bare expression is not a program. The lines marked ✗ on this page are therefore expression fragments: they exist to show what the kind rules refuse, not what the parser accepts. Every unmarked line is a legal statement.

#One algebra, two systems

Two distinct systems cooperate under every expression, and keeping them apart is what makes the rules below predictable:

• The coercion lattice (A). a ≤ b means "a coerces to b without lying". Its join ⊔ unifies kinds at reconciliation sites — the branches of an if, the two operands of nz, co-plotted series. Its meet ⊓ intersects constraints — the kind a parameter demands, overlapping osc bounds.
• The operator algebra (B). + - * / < > == are governed by a rule table — dimensional analysis in the tradition of unit-of-measure checkers — that computes the result kind of each application. It is not the join: price - price = level, while price ⊔ price = price.

Both systems report failure through a single error channel: any undefined rule of (B) and any incompatibility of (A) produce ⊤. A ⊤ is a hard error only in a demanding position (an operand, a plot target, an argument); a ⊤ bound to an intermediate name that nothing consumes is a warning ([WarnTop]). The policy is detailed in Inference.

The affine substrate. The price axis is a one-dimensional affine space: price is a point on it, level is a vector (a displacement), ratio is a dimensionless scalar centred on 1. Dimension itself is an abelian group of exponents over the generators {P price, V volume, T time, I bar-index, rad angle}: * adds exponents, / subtracts them. Two consequences fall out for free:

• * and / are total on dimensions — there is always a result exponent vector;
• only + and - demand dimensional agreement, because adding a point to a point has no geometric meaning.

Why this rule exists. The affine reading is not decoration; it is what lets the checker say no to close + rsi(close, 14) while accepting close + atr(14) — both are "price plus a number" to an untyped eye, but only one of them names a displacement on the price axis. Every rule below is an instance of this substrate, not a special case.

#Addition and subtraction: + and -

+ and - require operands of the same dimension and then follow the affine rules:

fluxspread   = close - open                  // price − price : level
band     = close + 2 * atr(14)           // price + level : price
centered = rsi(close, 14) - 50           // osc(0,100) − lit : osc(−50,50)
close + rsi(close, 14)                   // ✗ [ErrDim] — point + dimensionless: no affine meaning
obv() + close                            // ✗ [ErrDim] — volume and price do not add

The osc line deserves a note: the bounds of an osc(lo,hi) are a presentation claim, not a runtime invariant (only clamp makes a bound real), and ± propagates the claim by interval arithmetic. Subtracting the midline from an oscillator therefore re-centres its pane: rsi - 50 is drawn in a fixed [-50,50] pane with a midline at 0.

There is no arithmetic on signal — combine signals with and/or/not (see Logic), count them with count(sig, n).

#The one categorical overload: string concatenation

The only operator line outside the dimensional table is concatenation: string + string → string. - * / and every mixed pair involving string remain outside arithmetic and produce [ErrDim].

fluxlabel = "px " + fmt.price(close) + " @ " + fmt.time(time)   // string
"holdings: " + volume                                       // ✗ [ErrDim] — format it: fmt.num(volume)

Interpolation ("px {fmt.price(close)}") desugars to the same concatenation pipeline (fmt.cat), so the two spellings are equivalent; chains of + fuse into a single bounded write at compile time. See text for the string kind's guarantees.

#Affine combinations: the Σλ rule

A weighted sum of points is meaningful exactly when its coefficients say so. On an expression normalised to Σ λᵢ · ptᵢ (coefficients are constant-folded literals, so x * 0.5 and x / 2 are the same λ, and (2*high + low + close) / 4 normalises fine), the checker applies [Affine]:

• Σλ = 1 → the point kind — a barycentre of prices is a price: (high + low) / 2 : price;
• Σλ = 0 → the vector kind — a zero-sum combination is a displacement: high - low : level;
• anything else → quantity + [WarnAffine] — dimension erased, probably a missing divisor. high + low alone (Σλ = 2) draws the warning with a quick-fix: divide by 2 or use the pre-typed source hl2.

Two refinements make this rule cover real indicator algebra:

• A literal coefficient preserves the role: k * stdev(close, 20) is still a level, which is why sma(close, 20) + 2 * stdev(close, 20) types as price + level → price — a volatility band lands on the chart, not in a pane. (The full bottom-up walkthrough of this exact expression, ending in its presentation decision, is drawn in Inference.)
• The rule applies to composites, recursively, after inlining — not only to syntactic OHLC averages. dema = 2*ema(close,20) - ema(ema(close,20),20) has Σλ = 1 and types as price; so does tema. Without recursive application, every multi-ema composite would mistype as level.

The common OHLC barycentres are pre-typed sources (hl2, hlc3, ohlc4 : price), so the 90 % case never even exercises the rule.

Asset tags gate the combination. All the points in one affine combination must carry the same asset tag, component by component, exactly as ± demands (see below):

fluxbtcUsd = series("BTC-USD").close         // price[BTC,USD]
btcEur = series("BTC-EUR").close         // price[BTC,EUR]
mid    = (btcUsd + btcEur) / 2           // ✗ [ErrDim] — quotes differ; convert one leg first

Why this rule exists. Without the tag clause, (btcUsd + btcEur) / 2 would normalise to Σλ = 1 and type-check as a valid price, silently averaging two currencies. The affine rule must not be a back door around the mixing ban.

#Multiplication and division: * and /

* and / are total on dimensions: the result's exponent vector is the sum (respectively difference) of the operands'. The named kinds are the exponent vectors you meet most often; any other combination is still a valid, plottable composed dimension labelled by its exponents (eom : P²·V⁻¹ gets an auto pane — no warning, because a precise composed dimension is not an erased one).

fluxrel   = close / close[1]                     // ratio — centred on 1, own pane
flow  = close * volume                       // pv — money flow, own pane
vwap0 = cum(close * volume) / cum(volume)    // price — back on the chart

Notes on the corners:

• slope is price-per-bar, not price-per-second: the x axis is ordinal, so level ÷ barspan → slope = P·I⁻¹. Dividing a level by a duration would produce P·T⁻¹, a different (and rarely wanted) dimension. lrSlope returns slope for this reason — derived from the group law, not decreed.
• sqrt halves exponents and pow(x, n) scales them, which is how stdev = sqrt(variance) types correctly; transcendentals (log, exp, trigonometry) demand dimensionless input — log(close / close[1]) is fine; the compute pillar makes log(close) an [ErrDim], with a quick-fix to the ratio.
• Open decision. The grammar keeps % at the multiplicative tier; no catalogue kernel uses it and its retention is a named open item of the grammar plan. Its integer semantics on the integer aliases long (≡ decimal(18,0)) and long128 (≡ decimal(38,0)) are pinned (truncation toward zero; the remainder takes the dividend's sign; division by zero and MIN / −1 yield na, never a trap). See compute.

#Asset and currency tags under the operators

Kinds of price dimension carry an asset tag (B, Q[, @v]) — base, quote, optional venue; volume carries the base alone, pv the quote alone. The operators treat the tag with two different regimes, and the split is deliberate:

• ± and comparisons gate on identity — mixing raises [ErrDim];
• *, / and the join widen — a differing component rises to its per-component top (⊤base, ⊤quote), never an error.

fluxbtcUsd = series("BTC-USD").close      // price[BTC,USD] — a quote-tagged close
d = btcUsd - btcUsd[1]     // level[BTC,USD] — tag preserved through ±
btcUsd + ethUsd            // ✗ [ErrDim] — bases differ: adding two assets
btcUsd + btcEur            // ✗ [ErrDim] — quotes differ: adding two currencies
pnlUsd + pnlEur            // ✗ [ErrDim] — pv[USD] + pv[EUR]: convert first

Division derives exchange rates, and multiplication consumes them — the fx role rule:

fluxbtcUsd = series("BTC-USD").close      // price[BTC,USD]
btcEur = series("BTC-EUR").close      // price[BTC,EUR]
ethUsd = series("ETH-USD").close      // price[ETH,USD]
fxUE  = btcUsd / btcEur    // fx[USD/EUR] — same base, quotes differ, concrete keys
cross = btcUsd / ethUsd    // ratio       — cross-base: relative strength, tag dropped
usd   = btcEur * fxUE      // price[BTC,USD] — shared quote cancels: (EUR/BTC)·(USD/EUR)
usd2  = btcEur / (1 / fxUE)          // ÷ fx[EUR/USD] converts the same way

// triangular chaining — both operands are DERIVED; no primitive conjures a rate
btcGbp = series("BTC-GBP").close      // price[BTC,GBP]
gbpEur = btcGbp / btcEur              // fx[GBP/EUR]
usdGbp = fxUE / gbpEur                // fx[USD/EUR] ÷ fx[GBP/EUR] → fx[USD/GBP]

The complete edge list, in one place — the price ÷ price dispatch is a 2×2 on (base equal?, quote equal?):

• price[B,Q] ÷ price[B,Q] → ratio (both equal) · price[B1,Q] ÷ price[B2,Q] → ratio (base differs) · price[B1,Q1] ÷ price[B2,Q2] → ratio (both differ — no clean conversion exists, so the tag is dropped and you get a bare dimensionless number);
• price[B,Q1] ÷ price[B,Q2] → fx[Q1/Q2] — only when both quote keys are concrete statics; if either is ⊤quote, the result drops to plain ratio;
• price[B,Q1] * fx[Q2/Q1] → price[B,Q2] (commutative) and price[B,Q1] / fx[Q1/Q2] → price[B,Q2] — conversion; the shared quote must match string-for-string, otherwise the result widens to price[B,⊤quote] (never [ErrDim]: safety is ±-only);
• level and pv convert by the same two edges;
• 1 / fx[Q1/Q2] → fx[Q2/Q1] — the reciprocal; the numerator must be the literal 1, matched before any coercion. A wrong direction is a distinct tag (fx[USD/EUR] ≠ fx[EUR/USD]), never a coercion;
• fx[A/Q] ÷ fx[B/Q] → fx[A/B] — triangular chaining; fx * fx → num (the pair annotation has no slot on num);
• fx ± fx → ratio — a sum of rates is a magnitude, not a rate, so the pair annotation drops (kernels are different: ema(fxUE) keeps fx[USD/EUR]);
• price[B,Q] * volume[B] → pv[Q] — the base pairs off and is dropped: a money flow is a currency amount, base-agnostic, so pv[USD] of two different assets may be summed — that is portfolio arithmetic, not the asset-mixing bug;
• cross-asset * widens: price[B1,Q1] * price[B2,Q2] → P²[⊤base,⊤quote], never an error.

There is no fxRate(a, b) primitive: an fx value is derived by ÷ or arrives as a series whose producer declares itself an fx feed. The full model — venue metadata, toSource, mixed-currency series — is specified in asset-currency.

#Comparisons: two families, two scopes

A single "the join is defined" test would be the wrong gate: κ ⊔ κ = κ makes every self-join admissible, including kinds with no order and no useful equality. Flux instead scopes each comparison family to the sorts where its meaning is real. Both families return signal.

#Order: < > <= >= cross_up cross_down

Order comparisons are restricted to the scalar sort with a real total order, and the two sides must be dimensionally compatible (κₐ ⊔ κᵦ ∉ {quantity, ⊤}):

• ordered: the numeric spine (ratio, osc(·), signal, num) and the dimensioned antichain (price, level, volume, pv, time, duration, barindex, barspan, slope, angle);
• excluded: color, clock, string, record, vec, variant, ui — [ErrDim] / [ErrArg]. string < string is rejected deliberately: the core has no locale-dependent collation (a determinism exclusion — see text);
• dir is excluded from order: {-1, 0, +1} is categorical-discrete, not a magnitude. Compare it with == only.

fluxbreakout = close > 30000                       // price ⊔ lit = price → signal
overbought = rsi(close, 14) > 70               // osc vs lit → signal
golden = ema(close, 50) cross_up ema(close, 200)  // signal — true on the crossing bar
close > rsi(close, 14)      // ✗ [ErrDim] — price ⊔ osc = quantity: incomparable magnitudes
tf("1d") < tf("4h")         // ✗ [ErrDim] — a clock has no order to compare on
superTrend(10, 3).dir > 0   // ✗ [ErrDim] — dir is categorical: write dir == 1

cross_up / cross_down are infix comparison operators (never prefix calls): a cross_up b is true exactly on the bar where a moves from below-or-equal to above b. They sit at the comparison tier and are non-associative like the rest of it.

Asset tags gate order too: operands must carry identical tags component-by-component — price[BTC,USD] < price[BTC,EUR] is [ErrDim] even though the join of the two sides would widen to a valid price. The fx pair annotation is exempt from the gate (it lives on ratio, outside the asset axis): fxUE < fxGJ → signal compares two rates as plain ratios.

#Equality: == and !=

Equality reaches further than order — onto every sort whose equality is decidable and terminating:

• bit-equality for string, dir, color — and ordinary scalar equality on the spine (close == open);
• deep, decidable, na-aware equality for record, vec, variant — component-by-component; two shapes that differ are [ErrDim];
• excluded: clock and ui are consumed kinds, never compared — [ErrArg];
• scalar operands of differing dimensions or asset tags: [ErrDim], exactly as for order; the fx pair annotation is again exempt.

fluxst = superTrend(10, 3)
mark st.dir == 1                        // dir compares by equality → signal
bb   = bollinger(close, 20)
same = window(close, 4) == window(close, 4)   // deep, na-aware equality on a vec → signal
tf("1d") == tf("1d")                    // ✗ [ErrArg] — clock is consumed, not compared

#Comparisons and na

Any comparison touching na yields na — never true, never false: na == x, na < x, even na == na are all na. Absence is tested explicitly:

fluxhave = is_some(rsi(close, 14))     // signal — presence (not is_na(x))
gap  = is_na(close[1])             // signal — absence (first bar)

Why this rule exists. During warm-up an indicator is na for its first bars. If na > 70 silently evaluated to false, every threshold rule would fire — or refuse to fire — on phantom data, and the bug would be invisible by construction. Forcing na through comparisons makes absence propagate to the signal, where is_na / is_some handle it deliberately. The same discipline runs through the whole language: match must cover na, and window reducers propagate it.

#Logic: and, or, not

The logical operators are defined on signal and only on signal (signal × signal → signal); not is a prefix operator one tier tighter than and.

fluxsetup = close > ema(close, 50) and rsi(close, 14) < 30
flat  = not in_session("09:30-16:00 America/New_York")
close and volume        // ✗ [ErrArg] — `and` demands signals; neither operand is one

There is no short-circuit effect to speak of — expressions are pure — so and/or are plain boolean algebra on the {0,1} carrier, na-aware like everything else.

#Delay: x[n]

x[n] reads the value of the stream x from n bars ago. The index must be a constant-folded natural literal:

fluxmom   = close - close[10]          // level — momentum as a displacement
prevH = macd(close).hist[1]        // projection, then delay — postfix chain
close[-1]                          // ✗ [ErrCausal] — the future is not addressable
close[input(5)]                    // ✗ [ErrTotal] — delay must be a compile-time constant

• n ≥ 0; x[0] is x itself. A negative index is [ErrCausal]: Flux is no-repaint — a value, once produced for a step, never changes — and a read into the future is not a style violation but an unexpressible program.
• A non-constant index is [ErrTotal]: the delay depth sizes a ring buffer, and totality demands that all memory be bounded at compile time.
• On the first n bars, x[n] is na (warm-up), which the comparison rules above then carry safely.

The same bracket syntax on a vec receiver is not a delay but an element read ([Index]): slots[h.slot] takes a runtime ordinal index, and an out-of-bounds read yields na rather than an error — the declared capacity already bounds the cost. The two roles are distinguished by the receiver's kind, never by guesswork; see Indexing and projection.

#Resample: e @ clock

@ is the eliminator of the clock kind: e @ c re-times the stream e onto the clock c and preserves e's kind ([At]). Clocks are first-class values — composable, assignable, acceptable as input — and @ is how they are consumed:

fluxcalm   = atr(14) < atr(50)                 // signal — a quiet-volatility regime
daily  = ema(close @ "1d", 50)             // MTF: a daily EMA under any chart timeframe
bricks = close @ renko(atrBox(14))         // representation change = clock change
c      = if calm then tf("1d") else tf("4h")
trend  = ema(close @ c, 20)                // the clock itself was computed

• The resample is causal: at any bar it sees the in-progress or last closed unit of the coarser clock, never a future close. [ErrCausal] guards the rest.
• Constructors: tf("1d"), renko(box), pnf(box, rev), range(r) — where box is a level (the lattice forces it: a brick boundary is anchor + k·box, and only price + level is a price).
• v1 allows one clock per series: composing two clocks (renko(b) @ "1d") is rejected.
• Grammar note: the right-hand side of @ is a restricted clock operand, so x @ "1d" + 1 parses as (x @ "1d") + 1.

Clocks generalise "timeframe" — the full treatment (warm-up, alignment, live()) is in time-and-state.

#Ranges: a..b

.. builds a range and exists only in range positions — it is not an expression operator, cannot be chained (non-associative), and never collides with . projection or number literals (2..200 lexes as 2 .. 200).

fluxbb = bollinger(close, 20)
fill bb.upper..bb.lower            // band between two price streams
len = input(14, 2..200)            // bounded parameter range

The two ends of a fill must live on the same ordered scalar axis — fill close..rsi(close, 14) is [ErrDim] (see Inference for the admissibility rules).

#Indexing and projection

Projection e.f reads a field of a record ([Proj]). A missing field or a non-record receiver is [ErrField] — with a nearest-name quick-fix:

fluxbb = bollinger(close, 20)          // record{upper, middle, lower : price}
plot bb.upper                      // price
bb.uper                            // ✗ [ErrField] — no such field; did you mean upper?

Indexing v[i] on a vec<κ>[n] receiver reads an element ([Index]). The index may be a runtime ordinal; the declared capacity n keeps the operation total, and out-of-bounds reads yield na — never [ErrTotal], never a trap. This is the substrate of the slotmap idiom (bounded collections with stable handles and na tombstones).

A dotted name can also be a qualified name rather than a projection — T.Ctor selects a constructor of the declared variant T, and mod.f names an entry of an imported module. Both resolve during name resolution, before [Proj] is ever considered. Which brings us to the dot's third meaning:

#UFCS: close.ema(20).rsi(14)

Uniform Function Call Syntax: recv.f(args) is exactly f(recv, args) — the receiver becomes the first argument. It is a semantic desugaring on the already-parsed tree, not a grammar form, and it is what makes left-to-right pipelines read the way the data flows:

fluxsmooth = close.ema(20).rsi(14)                      // ≡ rsi(ema(close, 20), 14)
top5   = vec.topK(window(close, 100), (x) -> x, 5)  // a namespace call — the dot means something else here

The dot has three meanings, decided at compilation with one token of lookahead:

1. recv.f without ( — a record field (bb.upper), rule [Proj];
2. recv.f( where f resolves to a function — a UFCS call, desugared to f(recv, …);
3. mod.f / T.Ctor where the left side names a module or a declared variant — a qualified name, resolved before either of the above.

Tie-break: if recv has a field f and f names a function, recv.f(…) is the UFCS call — a field is never callable, so the other reading could only be an error.

The trap is reading (2) where only (3) applies. UFCS reaches the functions in scope — the prelude — and topK is not one of them: it lives in vec.*. So w.topK(…) is not a UFCS call but a field projection on a vector, which is [ErrField]. Write vec.topK(w, …). The rule of thumb is the one the completion menu already enforces: if the editor does not offer it after the dot, it is not there.

Why this rule exists. UFCS adds zero grammar and zero semantics — the checker verifies recv against the function's first parameter exactly as if you had written the direct call — but it buys discoverability: after close., the editor can propose precisely the functions whose first parameter accepts a price, filtered by kind. One mechanism, readable pipelines, kind-aware completion.

Named arguments compose with it: recv.f(x, mode: fast) binds mode by parameter name and checks it like a positional (see Inference).

#Record update: e with { … }

with produces a record identical to e except for the listed fields. It is shape-preserving ([With]):

• every listed field must already exist — [ErrField] otherwise (no silent field creation);
• each value must coerce to the field's declared kind — [ErrArg] otherwise;
• unlisted fields are carried over unchanged, and the result has exactly e's kind.

fluxvariant Phase { ask | suspense | revealed }
m  = { score: 0, phase: ask }
m2 = m with { score: m.score + 1, phase: revealed }
m with { scrore: 0 }        // ✗ [ErrField] — typo caught, nothing silently added

with is a postfix suffix (same tier as call and projection), so it chains: m with { a: 1 } with { b: 2 }.

Why this rule exists. Functional update without with means rebuilding the whole record by hand — and a forgotten field is silent state loss. Shape preservation turns that class of bug into [ErrField] at compile time.

#Destructuring: let {a, b} = e

A record pattern on the left of a binding extracts fields by name. It is irrefutable — it can never fail at runtime, so it is allowed exactly where no branching is possible:

fluxw = let { upper, lower } = bollinger(close, 20) in upper - lower   // level — `let … in` is an EXPRESSION
{ macd, hist } = macd(close)                                       // a program-level bind destructures too

• a named field that does not exist, or a non-record scrutinee, is [ErrField];
• if the scrutinee is na, every bound field is na — absence flows inward, consistently with the comparison rules;
• variant destructuring is refutable and therefore lives in match, whose exhaustiveness the checker enforces ([ErrTotalMatch]) — a let never branches.

#The ? family: ??, ?., ternary

Three pieces of pure sugar, all desugared to sealed constructs — no new kinds, no new semantics:

fluxm     = macd(close)                       // record{macd, signal, hist}
len   = close[1] ?? close                 // price — first bar handled
hist  = m?.hist ?? 0                      // safe-nav then default
side  = close > open ? 1 : -1             // ternary, right-associative

Because ?? is nz, it follows the join rules: branches of different dimensions widen toward quantity (with a warning), and mixing representation tags (f64 vs decimal) is [ErrRepr] — the sugar cannot do what the desugared form would not.

#The _ placeholder

At the argument site of a higher-order kernel, a single free _ denotes the one parameter of an implicit lambda:

fluxscaled = window(close, 20).map(_ * 1.1)      // ≡ .map((x) -> x * 1.1)
present = vec.where(window(close, 20), (x) -> is_some(x))  // a namespaced HOF — write the lambda
window(close, 20).fold(0, _ + _)   // ✗ — two-parameter position: write (acc, x) -> acc + x

The placeholder is confined to a prelude kernel reached by UFCS, where the receiver fixes the one parameter; a namespaced higher-order call such as vec.where(…) takes an explicit lambda, because _ has no binder to attach to there.

The rule is strictly mono-argument: exactly one _, in a position expecting a one-parameter function. Two or more _, or a two-parameter site like fold, are rejected with a request for an explicit lambda — the sugar never guesses which _ is which. The pattern _ of match arms is a different, position-distinct symbol; the two never collide.

#Precedence and associativity

From loosest to tightest. The normative stratified grammar — including why this table needs no precedence annotations at all — is in grammar.md.

Outside the cascade:

• .. — non-associative, legal only in range positions (fill a..b, input(n, lo..hi));
• @ — its right operand is a restricted clock operand, so x @ "1d" + 1 is (x @ "1d") + 1;
• : and , — separators, never operators.

Each tier refers only to the next tighter one — no cross-recursion — which is what makes the whole cascade unambiguous by construction rather than by side condition.

#See also

• kinds.md — the lattice these operators compute over: sorts, ⊤/⊥, coercion edges, tags.
• inference.md — how kinds are assigned, presentation inference, and the full error catalogue.
• grammar.md — the normative grammar, the single arrow's five readings, disambiguation.
• time-and-state.md — streams, clocks, scan/fold/loop, causality and warm-up in depth.
• asset-currency — the complete asset-tag model: venues, toSource, money.
• compute — math.*/stat.* and the dimensional rules of the numeric library.

Inference — kinds, presentation, and the error policy

Kinds gives the relation: which kinds exist and which judgments hold. This page gives the algorithm: how a kind is actually assigned to every node of a program, how the presentation of a chart — pane, scale, guides, colour, parameter UI — is derived from those kinds rather than configured, and what happens when something does not type.

Three properties make the algorithm worth specifying precisely, rather than leaving it as an implementation detail. It is principal (the kind it synthesizes is the least one the program admits, so there is never a choice to make), it is deterministic (the same source always yields the same kinds, which is what lets two engines emit byte-identical code), and it is total (every editing state, including a half-typed line, gets a kind or a precise error — never a silent failure).

#Two modes

Inference is bidirectional: it reads the same typing rules in two directions.

Synthesis — Γ ⊢ e ⇒ κ — is the default, bottom-up mode. It produces the smallest kind the expression admits. Leaves synthesize their exact kind (close ⇒ price, 14 ⇒ lit, "hi" ⇒ string); introductions synthesize their structure (a record literal, a scene, a constructor); eliminations synthesize by computing — a call, a projection, a match, a delay, a resample, and every arithmetic node, which asks the dimensional algebra for its result kind.

Checking — Γ ⊢ e ⇐ κ — is the top-down mode, and it runs only at sites of consumption, where an expected kind already exists:

That last row is also what disambiguates the arrow: (x) -> x * 1.1 is a lambda exactly when its position expects a function, and a tween pair otherwise. Disambiguation is a consequence of the mode, not a separate rule (see Grammar).

#Subsumption is confined

The coercion rule — "an a may be used where a b is expected if a ≤ b" — fires only at the boundary between the two modes. To check e ⇐ κ: synthesize e ⇒ κ', then demand κ' ≤ κ. Silent if the edge is ≤safe; a warning with a quick-fix if it is ≤lossy; [ErrDim], [ErrArg] or [ErrPlot] — according to the position — if κ' ⊀ κ.

Coercion never fires during synthesis. A node is never spontaneously widened; its synthesized kind stays the lowest one known.

Why confinement is load-bearing. Suppose subsumption were allowed in synthesis. Then x = close - close could synthesize level or, by the lossy erasure edge, quantity. Both are derivable. But plot x reads the presentation registry at the kind: level gives a pane centred on zero, quantity gives a fallback auto pane. One program, two valid outputs, two different compiled artifacts — and the guarantee that the editor's preview matches the shipped module (I7) would be gone. Confinement is what makes "the kind of an expression" a function rather than a choice.

#Principality

With synthesis defined as above, every expression has a principal kind: the unique smallest kind it admits. The proof is a one-line induction — each leaf synthesizes exactly, each node combines its children's minimal kinds with either ⊔ or the dimensional algebra (both of which return a unique result, verified by enumeration), and the only widening rule is excluded from the mode. So the synthesized kind is the least one, and checking ≤ at each consumer is then complete.

The multi-site case. A field initialized to na synthesizes ⊥ at that site — but its kind is not stuck there: the principal kind of a record field is the join over all its construction and assignment sites. In the APP plane, a Model field written picked: na in init and picked: key (a string) in one arm of update has kind string, with na remaining a legal runtime value of that field (⊥ ≤ string). The fixpoint converges in one pass because the kinds being assigned never depend on the record itself. Declaring record Model { … } up front is the same thing written explicitly.

#Termination and determinism

The algorithm is a single bottom-up pass over the topologically sorted graph. It terminates because the lattice is finite by family and of finite height, the graph is acyclic (causality guarantees that), and ⊔, ⊓ and the algebra are all O(1) — there is no fixpoint iteration and no store of unification variables anywhere.

It is also confluent: a node's synthesized kind depends only on the kinds of its inputs, and ⊔ is commutative and associative, so the result is independent of which topological order was chosen. Inference is therefore a deterministic function of the graph — the same program always yields the same kinds, hence the same emitted module. This is one of the foundations of the interpreter ≡ WASM byte-equality (see Compiler and runtime).

#Bounded polymorphism, resolved then forgotten

The catalogue is full of kind-preserving families: ema, sma, sum, highest, change, stat.stdev — each written (src: α ≤ quantity, len: lit) → ρ(α). This is the only polymorphism in v1, and it is deliberately shallow.

At each call site, α is resolved to a closed, monomorphic kind: α := the join of the kinds synthesized for the arguments in α positions; then α ≤ quantity is checked ([ErrArg] otherwise); then the return kind is the family's shape instantiated at that α. For difference families, the shape is the δ derived from the frozen ± algebra: δ(price) = level.

fluxa = ema(close, 20)              // α := price      ⇒ price
b = ema(rsi(close, 14), 9)      // α := osc(0,100) ⇒ osc(0,100)   — smoothing preserves the kind
c = change(close, 5)            // δ(price)        ⇒ level
d = change(rsi(close, 14), 5)   // δ(osc)          ⇒ osc, centred on 0

α is resolved and then forgotten. It is not a unification variable that persists across the program, so two sites can never contradict one another, and the "no general unification" property that keeps inference a single pass survives intact.

#Typing an unfinished program

An editor types a program that is being written, not one that is finished — so the algorithm assigns a kind to every editing state.

An unbound name (you are halfway through typing it) and a syntax hole (a parse error node) both synthesize a kind hole: a contained ⊤ that emits exactly one diagnostic ([ErrUnbound]) and does not poison its siblings.

From that follows the typable cone: the largest sub-graph in which every node, and every transitive input of every node, is free of ⊤ and free of holes. Live preview evaluates exactly that cone and renders the rest as --. A local mistake therefore never blanks the whole preview — a correct program has a cone equal to the whole graph, and a program with one unbound name still previews everything that does not depend on it.

The cone is a strictly editing-time artifact: a ⊤ in a consumed position is still a hard failure to emit code. The byte-identity guarantee is untouched.

#Incremental re-typing

On an edit, only the changed node and its downstream cone of kind consumers are re-synthesized; every other node's kind is memoized under the pinned node identity that the compiler already maintains for hashing and common-subexpression elimination. Because the graph is acyclic and the lattice is monotone and finite, this converges in one downward pass.

Incremental re-typing is observationally equal to a full re-inference — it is the same function, memoized — so it can never disagree with the shipped module. It is what keeps the sub-16 ms editing budget, together with incremental parsing.

#Presentation is inferred, not configured

Here is the payoff of a kind system that tracks meaning. A kind already says what a value is; so it also says how it should be shown. That is why the first program anyone writes is one line long and needs no options:

The compiler derives a registry entry from the kind, and refines it with metadata from the operation itself:

registry := merge( reg(kind), opMeta(expression) )

reg(kind) supplies the defaults; opMeta refines them (an rsi adds its 30/70 guides). The complete default table:

The CSS class is part of the derivation, not a detail of the theme: the host stamps it on the rendered series, so a stylesheet can restyle every oscillator on the chart without any script naming a colour. It is the one place where "the presentation is inferred" reaches all the way out to the page.

Four rules complete the picture:

1. Overlay if and only if the value shares the price axis. Otherwise it gets a pane.
2. Co-plotting joins scales. Two series in one pane take the ⊔ of their bounds; if that join lands on quantity, you get [WarnBranchDim] and a suggestion to split the pane. (A price overlay next to a ratio pane is not a mix — it is two panes, and it warns about nothing.)
3. The final kind decides. level + price → price, so the expression overlays.
4. Reference lines from convention live in opMeta, not in the kind. osc(0,100) gives a midline; that rsi conventionally marks 30 and 70 is a property of rsi.

A record explodes into its fields, each presented at its own kind — which is why plot bollinger(close, 20, 2) yields three price lines plus a band, and plot macd(close) yields a centred pane with a histogram and a signal line, with no code to say so.

#Overrides — intent beats the default

Inference gives the default; the author overrides it in the plot block, and because the system knows the kind, the override is intelligent rather than blind:

fluxm = macd(close)
plot m.macd { overlay }                  // a level FORCED onto the chart → it gets its OWN secondary axis
plot ema(close, 20) { pane }             // a price FORCED into a pane → auto-scaled, fine
plot m.hist { style: histogram, color: if m.hist > 0 then up else down }
plot rsi(close, 14) { guides: [20, 80] } // authored reference lines, kind-checked as level|osc

ich = ichimoku()                          // sourceless: it reads high/low/close itself
plot ich.chikou { offset: -26 }          // a DISPLAY shift: it moves the x position, never the value

Parameter UI is derived the same way: an input(…) synthesizes its kind, and the kind gives the widget (a numeric field with a range, a source picker, a boolean, an enumeration), with title:/group:/tooltip: as optional metadata. An accessibility descriptor is derived from the kind as well, so a plotted series is announced meaningfully without the author writing a label.

#What may be presented at all

Presentation admissibility is a judgment like any other, decided per kind, and enumerated exhaustively:

Note the deliberate asymmetry: dir is not plottable as a line and not orderable, but it is markable and is a legal bar-colouring channel. Its only presentation channels are the two that make sense for a three-valued direction.

Why enumerate instead of arguing. Because the lattice is finite by family, these tables are checked by machine — every kind, and every pair of kinds, is run through every judgment. "No kind is left without a semantics" is not a claim in a document; it is a test that fails when it stops being true.

#The error policy

An error is hard if and only if a load-bearing guarantee is violated — causality, totality, the firewall — or a dimensional impossibility appears in a demanding position. Everything else that is merely suspect is a warning with a quick-fix.

#Hard errors

The APP plane adds [ErrState] for an unbounded Model field, on exactly this pattern; see App plane.

#Warnings

#What an error message is

A diagnostic is human, dimensional, actionable, and linked — never a stack trace:

price + osc — you are adding a price and a 0–100 oscillator.
  close + rsi(close, 14)
          ^^^^^^^^^^^^^^ osc(0,100), a dimensionless bounded value
  A point on the price axis and a dimensionless number have no common meaning.
  Did you mean  close + atr(14)  (a price + a displacement),
  or            close * norm(rsi(close, 14))  (scale the price by a fraction)?
  → kinds: the affine substrate

A refused repaint is explained, not merely forbidden ("this would make a past value change once the bar closes"), because the refusal is the feature.

Anti-cascade. A poisoned node propagates without re-diagnosing: one root fault produces exactly one message, and the nodes downstream of it stay quiet. A single typo does not produce forty errors.

#na at runtime

Kinds are static; na is the runtime story, and the two are designed to agree.

• Every comparison touching na yields na — never true, never false. Absence is tested with is_na(x) and presence with is_some(x), both signal.
• nz(x, d) (and its sugar x ?? d) substitutes a default; max/min absorb na pointwise, while window reducers propagate it (a window containing a hole yields na, matching the native oracle they must stay byte-identical to).
• A match on a possibly-na scrutinee must cover it — an na arm or _.
• Destructuring an na record gives every field na.
• A NaN produced by arithmetic is na — the kind is preserved, and it is displayed as a gap rather than as a failure. Division by zero is not an error; it is an absent value.
• Internally, na is forced to a single canonical bit pattern at every storage, hashing and serialization boundary. Nothing about that is observable in a program — it is what makes two engines agree on the bytes of a value that is not there (Memory model).

#See also

• Kinds — the lattice, the sorts, the tags, the named declarations.
• Operators — the dimensional algebra rule by rule.
• Grammar — how the modes of inference resolve the arrow and the container heads.
• Time and state — causality, warm-up, live() and the firewall in practice.
• The editor — kind-filtered completion, hover cards, the typable cone in live preview.
• Compiler and runtime — why deterministic inference is a prerequisite for byte-identity.

Time and state

This page specifies the temporal model of the ANALYSIS plane: what a stream is, how the past is accessed, why the future cannot be, how bounded state and iteration are written, and how the step axis of a series — its clock — is itself a first-class value. Everything else in Flux leans on the guarantees defined here: causality (a value depends only on the past), no-repaint (a value, once produced for a step, never changes), totality (every construct terminates within a compile-time bound) and byte-identity (the same program produces the same bytes on every engine, warm-up included).

Kinds (price, level, signal, …) are specified in kinds.md; this page uses them freely and annotates examples with them. The presentation-side clocks — frames and events — belong to canvas.md and app-plane.md; here the clock is the data clock, the one analysis values advance on.

#Everything is a stream

A value in the ANALYSIS plane is a stream: a value-over-steps. close is not a number; it is the whole history of closing values, one per step of the chart's clock. A constant is a degenerate stream — the same value at every step. In the charting specialization a step is a bar; nothing in the model depends on that reading.

Arithmetic is element-wise: an expression relates entire streams, and the result is again a stream.

fluxfast   = ema(close, 12)      // price — a stream: one value per step
slow   = ema(close, 26)      // price
spread = fast - slow         // level — element-wise: spread at step t = fast[t] - slow[t]

There are no indices to manage and no loops to write: you state the relation once, and it holds at every step. Under the hood the runtime is incremental — when a new step arrives, each node advances by one, reusing its own bounded state; nothing is recomputed from the beginning. The element-wise reading (whole histories) and the incremental one (one step at a time) describe the same program; the compiler owes you their equivalence.

Why this rule exists. Index-free streams are what make the rest of the page possible. Because a program never names positions, it cannot name a future position; because every operator advances step-by-step with bounded state, totality and memory bounds are properties of the language, not of the author's discipline.

#The delay operator x[n]

The only way to reach into the past is the postfix delay x[n]: the value the stream x had n steps ago.

fluxprev = close[1]              // price — the previous step's close; na on the first step
diff = close - close[1]      // price − price → level : the one-step change
up4  = close > close[4]      // signal — na on the first four steps (comparison propagates na)

Rules:

• n is a const-folded constant, n ≥ 0 — a literal, or a parameter whose bounded range lets the compiler reserve the worst case. Delay is memory; memory is bounded at compile time.
• Before step n, x[n] is na — the past that does not exist yet (see Warm-up and na).
• On a vec, the same postfix [i] is a bounded element read, not a delay; the kind of the operand disambiguates.

A data-dependent delay is rejected: the lag would be unbounded.

fluxk = barssince(close cross_up open)
close[k]                     // ✗ [ErrTotal] — the lag must be a compile-time constant

#There is no negative index

x[-1] — "the next value" — does not exist. Not as a discouraged form, not as a lint that a determined author can silence: there is no such form. The delay index is non-negative by the language definition, and any attempt to write a negative one is rejected.

fluxclose[-1]                    // ✗ [ErrCausal] — the future is not addressable

Why this rule exists. Causality is a compile-time property, not a style rule. In a language where x[-1] parses and merely warns, every guarantee downstream — replayability, alert trustworthiness, byte-identical re-execution — holds only for well-behaved scripts. Flux inverts the burden: the ill-behaved script is inexpressible, so the guarantees hold for every program that compiles.

#Causality is a theorem

Because the past is reachable only through bounded, non-negative delay, and the forming unit of any clock is unreadable (see @ — the clock eliminator), every ANALYSIS program satisfies, by construction:

output[t] = f(inputs[0..t])

The value at step t is a function of the inputs up to and including step t — never of anything later. Two consequences follow.

Every feedback cycle passes a unit delay. A definition may depend on its own previous value (that is what running state is), but never on its own current value — a cycle with no delay has no causal reading and is rejected:

fluxema20 = 0.1 * close + 0.9 * ema20                       // ✗ [ErrCausal] — cycle with no unit delay
ema20 = scan(close, (prev) -> 0.1 * close + 0.9 * prev) // ✓ the delay is built into scan

scan (below) is the sanctioned way to close a feedback loop: the combinator hands you the previous step's output, so the unit delay is part of its meaning rather than something you remember to insert.

No-repaint. Since output[t] depends only on inputs[0..t], and inputs are append-only, a value once produced can never be contradicted by later data. This is the no-repaint guarantee: a value, once produced for a step, never changes. History is immutable — the chart you scroll back to is exactly the chart that was computed live, the alert that fired is exactly the alert a re-execution fires. Repaint is not "detected" or "warned about"; it is absent from the vocabulary. The full family of rejections shares one diagnostic: [ErrCausal] — negative delay, a non-causal resample, a feedback cycle with no unit delay, an unbounded lag.

#Warm-up and na

Most kernels need history before they can answer: a 14-step RSI has nothing honest to say at step 3. Until enough data has arrived, a kernel's output is na — the absent value. This is its natural warm-up, and each kernel inherits exactly the warm-up of its definition; the language imposes no blanket "na until N" policy on top. Byte-identity holds from the very first step: a Flux kernel and the host's native implementation of the same kernel agree on every byte, warm-up included (invariant I6).

na inhabits every kind (na : ∀κ.κ) and propagates through arithmetic with the kind preserved. Its comparison semantics are strict:

• Any comparison involving na — na == x, na < x, even na == na — is na, never true or false. You cannot test absence with ==.
• Absence is tested with is_na(x) → signal; presence with its dual is_some(x) = not is_na(x) → signal.
• match on a value that may be na must cover it (an na arm or _), or the match is rejected as non-exhaustive.
• Destructuring an absent record (let {upper, lower} = bb when bb is na) gives na in every field.

fluxr     = rsi(close, 14)       // osc(0,100) — na on steps 0..13
warm  = is_na(r)             // signal — 1 during warm-up
bad   = r == na              // na, always — never true; use is_na
assert r <= 100              // passes from step 0: na <= 100 is na, and an na verdict is PASS

The assert verdict on na is deliberately pass: an assertion fires only on a signal that is definitively false, so warm-up cannot produce spurious failures. Where absence itself must fail, write assert is_some(r) and r <= 100.

Substitution of a default uses nz(x, d), or its operator form x ?? d (they are the same construct):

fluxo  = nz(obv(), 0)            // volume — 0 is a literal and adopts the slot's kind
f  = close ?? sma(close, 5)  // price — x ?? d ≡ nz(x, d); right-associative

Both operands must agree dimensionally (the result kind is their join); same dimension with different representation tags — f64 against decimal, machine time against calendar time — is [ErrRepr], asking for an explicit conversion.

Absorption vs propagation. Arithmetic propagates na. Three pointwise operators absorb it instead — math.max, math.min, nz — so math.max(x, na) = x: a missing operand does not poison a running extreme. Window reducers do not inherit that absorption: highest(x, 20) over a window containing a hole yields na, exactly as sma, sum and stdev do. The asymmetry is pinned by byte-identity to the host kernels: the window reducers follow the native oracle, and a hand-written fold with max (which skips na by absorption) is a different — legitimate — program, not a faster spelling of highest.

One representation note: na is a single pinned bit pattern at every storage and hashing boundary, so that byte-identity and replay verification hold across engines; the semantics above are unaffected. Details live in internals/compiler-and-runtime.md.

#Windows and bounded iteration

window(x, n) materializes the last n values of a stream as a vector:

fluxw = window(close, 20)        // vec(price, 20) — the last 20 closes, at every step

The capacity n is const-folded — a literal, or an input with a bounded range (the compiler reserves the worst case). A non-constant or oversized capacity is rejected:

fluxlen = barssince(close cross_up open)
window(close, len)           // ✗ [ErrTotal] — capacity must be a compile-time constant

fold and map over a window are the total for-loop: they visit exactly the window's capacity, no more, and they terminate by construction.

fluxw    = window(close, 20)
hi   = w.fold(na, (acc, x) -> math.max(acc, x))   // price — max absorbs na during warm-up
devs = w.map((x) -> x - sma(close, 20))      // vec(level, 20) — element-wise, kind-tracked

#Why there is no filter (and no flatMap)

fluxw.filter((x) -> x > 0)       // ✗ — there is no filter: the result length would depend on data

A filter's output length depends on the data; a flatMap multiplies lengths by a data-dependent factor. Neither has a compile-time capacity, and capacity is what carries the totality and memory guarantees — every collection in Flux is a vec<κ>[n] whose n is a bound the compiler can charge against its budget. Selection therefore never shrinks; it masks:

• vec.where(v, pred) — same length, na where the element fails the predicate;
• vec.mask(v, live) — same length, na where the parallel signal vector is 0.

fluxw     = window(close, 50)                          // vec<price>[50]
above = vec.where(w, (x) -> x > sma(close, 50))    // vec<price>[50] — na holes, no shrinking

Masked vectors compose with na-aware iteration: an na element produces nothing. Folds and reducers see the hole and apply their own na policy; the view/canvas comprehension skips it outright — a masked-out element draws no child:

fluxgroup { for lvl in window(close, 5) -> dot { at:(bar.i, lvl) } }   // na elements: no dot

Why this rule exists. "Bounded memory" is only a theorem if no operation can grow a collection past its declared capacity or make its size a runtime surprise. Masks keep the shape static and move the "how many survived" question into the values (na holes, a count where one is needed) — which is exactly the information a total program can carry.

#Running state: scan

scan(seed, (prev) -> e) is the running accumulator — the language's feedback construct. At the first step, prev is the seed (evaluated at that step); at every later step, prev is the value the scan itself produced at the previous step. The emitted value is the state. The unit delay that causality demands is inside the combinator: prev is always one step old, so a scan can never read its own current output.

The canonical example — an exponential moving average built from first principles:

fluxdef ema0(s, n) =
  let a = 2 / (n + 1) in
  scan(s, (prev) -> a * s + (1 - a) * prev)   // α → α : Σλ=1 affine step, kind-preserving

A running extreme is a one-liner:

fluxpeak = scan(high, (prev) -> math.max(prev, high))  // price — running maximum since the first step

#Composite state: a record seed

State rarely stays scalar. Seed a scan with a record and the whole record is the accumulator; the kind system tracks every field.

fluxdd = scan({ peak: close, draw: 0 }, (prev) ->
  let p = math.max(prev.peak, close) in
  { peak: p, draw: (p - close) / p })         // record{peak: price, draw: ratio}
plot dd.draw                                  // (p − close) : level ; level ÷ price → ratio

A trailing-stop with a flip — the SuperTrend family — is a record of a price and a dir ({-1, 0, +1}, compared with ==, never matched):

fluxdef flip(mult) =
  let band = mult * atr(14) in                // num × level → level
  scan({ stop: close - band, side: 1 }, (prev) ->
    if prev.side == 1 then
      if close < prev.stop then { stop: close + band, side: -1 }
      else { stop: math.max(prev.stop, close - band), side: 1 }     // ratchet: never loosens
    else
      if close > prev.stop then { stop: close - band, side: 1 }
      else { stop: math.min(prev.stop, close + band), side: -1 })

#State machines: a variant seed and match

When state is a mode, seed the scan with a variant and step it with match — the eliminator forces every mode to be handled ([ErrTotalMatch] otherwise), so a state machine cannot silently forget a case:

fluxvariant Phase { Flat | Long(entry: price) }

def step(prev) = match prev {
  Flat    -> if close cross_up ema(close, 50) then Phase.Long(entry: close) else Phase.Flat
  Long(e) -> if (e - close) / e > 0.05 then Phase.Flat else prev
}

pos = scan(Phase.Flat, (prev) -> step(prev))

Look at the exit rule, because the kind system wrote it. The obvious first draft is close < e * 0.95 — and it is rejected: e is a price, an affine point, and scaling a point by a scalar has no meaning (5% of "the 42nd parallel" is not a place). The algebra erases the dimension, and comparing the result back against a price is [ErrDim]. What you actually meant is a displacement measured against the entry — (e - close) / e, a price − price over a price, which is a ratio, and a ratio compares with 0.05 happily. The compiler did not merely refuse the first draft: it named the second.

#Worked sketch: a point-and-figure column

Price-driven representations keep a column state: which way the column runs, its running extreme, how many boxes it has filled. As scan state:

flux// state : record{ dir: dir, extreme: price, count: num }
def pnfCol(box, rev) =                        // box : level (const-folded), rev : num
  scan({ dir: 1, extreme: close, count: 0 }, (prev) ->
    if prev.dir == 1 and close >= prev.extreme + box then
      prev with { extreme: prev.extreme + box, count: prev.count + 1 }
    else if prev.dir == 1 and close <= prev.extreme - rev * box then
      { dir: -1, extreme: prev.extreme - rev * box, count: rev }
    else prev)                                // sketch: up-side only, one box per step

The kinds are the point of the sketch. count is a pure number of boxes — dimensionless — while box : level carries the price dimension. So:

• count * box : level — a number of boxes times a box height is a displacement;
• extreme + count * box : price — anchoring that displacement at the column's extreme gives back a point on the price axis.

Store count : num and the algebra reconstructs every geometric quantity with the right kind; store a price per box and the arithmetic would type as nonsense (price + price has no affine meaning). The production version of this sketch is not a scan at all but a change of clock — pnf(box, rev) in Clocks — yet its internal state types by exactly this reasoning.

#stateful — the low-level escape hatch

stateful(seed, (st, bar) -> e) exposes the engine's recursive primitive directly: you receive the previous state and the current step's raw data, and return the next state. It is the same construct as scan with the sugar removed, for the rare kernel whose step cannot be phrased as an expression over named streams. Prefer scan; reach for stateful when you need the whole bar record at once.

fluxacc = stateful({ n: 0, ups: 0 }, (st, bar) ->        // seed is a RECORD; bar is the whole step
  { n: st.n + 1, ups: st.ups + (if bar.close > bar.open then 1 else 0) })

#loop — bounded iteration within a step

loop(max, init, step) iterates within a single step: max rounds (const-folded), starting from init and applying step to the running value. It is the total replacement for a while: the bound is part of the program, so termination is a fact, not a hope. Root-finders, implied-value solvers and smoothing passes are its natural users.

fluxdef nroot(x) =                                // num → num : Newton, a fixed 24 rounds
  loop(24, x / 2, (g) -> (g + x / g) / 2)

plot nroot(rsi(close, 14))                    // dimensionless in, dimensionless out

Totality comes from max, and from max alone. It is a static ceiling: the compiler budgets the worst case, so the cost of a step is known before the step runs, whatever the data does. In this shipped form the ceiling is also the exact count — loop runs max rounds and takes the last value — which in practice costs nothing here, because Newton doubles its correct digits each round: an f64 root has converged long before round 24, and the remaining rounds are fixed points.

Post-v1. The sealed design carries a fourth argument, an early-exit predicate: loop(max, init, step, until) stops as soon as until holds. That does not weaken totality — the budget is still max, and the compiler still reserves it — it only lets a converged iteration stop paying for rounds it does not need. The shipped signature does not take it yet, so the form above is the one that runs today.

No unbounded loop exists in the v1 surface: there is no token for one, and every practical iterative kernel states its budget. (Open decision. The design discusses an opt-in unsafe escape for an unbounded loop and discourages it by default; nothing in the catalogue needs it.)

#Cumulative and anchored streams

Two combinators cover "since forever" and "since an event":

• cum(x) → α — the expanding sum from the first step (a scan in a coat);
• cumSince(reset, x) → α — the same accumulation, re-initialized at each rising edge of the reset : signal.

fluxtotal = cum(volume)                                        // volume — since the first step
sess  = in_session("09:30-16:00 America/New_York")         // signal — 1 while the session is open
sVol  = cumSince(sess, volume)                             // volume — since the session opened

The anchored VWAP is this idiom applied to a ratio of accumulations — and it types because the dimensional algebra divides the dimensions out:

fluxsess  = in_session("09:30-16:00 America/New_York")                // signal — the anchor
avwap = cumSince(sess, close * volume) / cumSince(sess, volume)   // pv ÷ volume → price
avwap = vwap(anchor: sess)                                        // the packaged overload

Any signal can anchor: a session open, a crossover, a structural break. An input of kind price or time may be placed by click on the chart — the host writes the chosen value back as a pinned input, so the analysis still reads an input, never the pointer, and a "VWAP since the step I clicked" stays fully causal and replayable.

#Clocks: the step axis is a value

Every series advances on a clock, and clock is a first-class kind: an ordinal step index plus a mapping between step indices and time. A clock answers two questions — what is step i's timestamp? and which step contains time t? — and nothing else; position on the axis is always the ordinal index, never wall-time.

Four constructors build clocks:

Time-coarse clocks and price-driven clocks are the same concept: a rule for when a unit closes. This is why alternative chart representations are not renderers bolted onto bar data — a Renko or point-and-figure series is the ordinary series machinery running on a different clock — and why multi-resolution analysis is not a special feature: an expression at another resolution is an expression on another clock, resampled back (next section).

Clocks are ordinary values. They flow through if, through def parameters, through input:

fluxregime = adx(14).adx > 25                     // signal — a trending regime
c      = if regime then tf("1d") else tf("4h") // clock — chosen like any other value

Constructor parameters const-fold: renko(50) (the literal adopts kind level), or a bounded input. A data-dependent box is rejected — a clock is a fixed axis, not a quantity that drifts with the data it is supposed to index.

Functions may consume clocks like any value: barsPerYear(clk) → num derives the periods-per-year of a time clock (for annualization); on an event clock (renko, pnf) the question has no answer and it returns na with a diagnostic.

#@ — the clock eliminator

e @ c evaluates e per unit of the clock c and reads the result back on the current series' steps. It is the eliminator of the clock kind — clocks are outside arithmetic, and @ is the one operation that consumes them. Resampling is kind-preserving (resample : (α, clock) → α) and causal: at any step, e @ c reads the value of e at the last closed unit of c — never the forming one.