# Flowscript documentation

# Flowscript documentation

> Learn the language, understand its host contract, and compile and replay programs over your own data.

[Canonical documentation](https://flowscript.ftw.trade/docs)

Flowscript is a language for programs that read time series, calculate signals and describe when to act. The same program and inputs produce the same evaluated values and decisions. The compiler checks types, reads and actions before evaluation; the runtime enforces work and memory limits.

The language is an independent library. You can use its Rust compiler and evaluator or embed `@flowscript/core`, the JavaScript and TypeScript package backed by WebAssembly. Neither requires an ftw.trade account.

## Start here

- [Quickstart](https://flowscript.ftw.trade/docs/quickstart): compile a complete signal program and replay it over a small, explicitly illustrated history.
- [Embedding Flowscript](https://flowscript.ftw.trade/docs/embedding): declare a host, feed its data, handle refusals and save or resume evaluation.
- [Build libraries and tools](https://flowscript.ftw.trade/docs/extending): compose reusable helpers, declare application actions and connect recorded model predictions.
- [Outputs and consumers](https://flowscript.ftw.trade/docs/outputs): turn evaluated metrics, text and action intents into charts, application logs and your own data.
- [Language reference](https://flowscript.ftw.trade/docs/reference): the types, syntax, series, built-in functions, triggers, diagnostics and host contract.

## What belongs to the language

Flowscript provides values and series, expressions, functions, explicit state through `fold`, indicators, metrics and trigger semantics. `na` represents an unknown observation or a value that cannot yet be calculated, including indicator warmup. There are no loops or mutable variables in a program.

A program reaches only the reads and actions its application declares. It cannot open a file, fetch a URL, read a secret or obtain the system clock. The application supplies observations and evaluation timestamps.

Compilation checks whether a program fits that declaration. It does not establish that an external data feed is complete, that a future input is valid, or that an order will settle.

## What the host supplies

The **host** is the application's declaration of available sources, capability manifests, libraries and integrations. A source declaration gives a read its name, type, key shape and intervals. A capability manifest declares actions and their arguments.

`bars.close` is a source name used in the examples. Your host must declare it and provide its samples. Names such as `paper`, `perp` and `aave` describe host capabilities; they are not connections to a broker or protocol built into the language.

A program can publish metrics without declaring any actions. If actions are declared, evaluation can return decisions for an application to inspect. An execution adapter or an explicitly configured paper broker supplies the execution behavior.

## Using Flowscript on ftw.trade

ftw.trade is an application that embeds Flowscript. It provides market data, its module catalog, strategy settings, backtests, accounts, wallets and execution services. Its injected names, saved-strategy workflow and trading permissions belong to that platform's host.

Read [Strategies on ftw.trade](https://docs.ftw.trade/strategies/overview) for that integration. Use these language docs when learning Flowscript itself or embedding it in your own application.

---

# Your first Flowscript program

> Compile a complete program against an explicit host and replay an illustrated price sequence with @flowscript/core.

[Canonical documentation](https://flowscript.ftw.trade/docs/quickstart)

This example calculates two moving averages and a numeric trend signal. It declares one data source and no actions. The twelve input values are an illustrated price path for learning the API, not recorded market data or a backtest result.

## Get the library

There is currently no public package release or public download of `@flowscript/core`. It is not available from the npm registry. Running this example locally requires authorized access to the source repository and a library build.

From the root of an authorized checkout, use the existing build, test and packaging recipe:

```sh
just flowscript-pack
```

The recipe writes `flowscript/npm/flowscript-core-0.1.0.tgz` at the current package version. Install that locally built tarball in your application. It includes the compiled JavaScript and `flowscript.wasm`; it does not publish a release. The [embedding guide](https://flowscript.ftw.trade/docs/embedding) covers prerequisites, installation and the boundary your application owns.

## Compile and replay

Save this complete example as `signal.mjs` in the project where you installed the package, then run `node signal.mjs`.

```js
import { loadFlowscript } from '@flowscript/core';

const flowscript = await loadFlowscript();

const host = {
  sources: [
    {
      name: 'bars.close',
      type: 'number',
      keyed: true,
      intervals: ['1h'],
    },
  ],
  capabilities: [],
};

const source = `flowscript "0.3";
uses { bars: "^1" }
const close = bars.close("DEMO-USD", "1h");
const fast = ema(close, 3);
const slow = ema(close, 5);
metric("close", close);
metric("fast", fast);
metric("slow", slow);
metric("trend", fast > slow ? 1 : 0);
`;

const compiled = flowscript.compile(source, host);
if (!compiled.ok) {
  throw new Error(compiled.problems.map((p) =>
    `${p.line}:${p.col} ${p.code} ${p.message}`).join('\n'));
}

try {
  const closes = new Float64Array([
    100, 100, 100, 100, 100, 102, 104, 106, 105, 103, 101, 99,
  ]);
  const firstClose = Date.UTC(2026, 0, 1, 1) / 1000;
  const history = {
    len: closes.length,
    series: { 'bars.close': closes },
    time: Float64Array.from(closes, (_, i) => firstClose + i * 3600),
  };

  const replay = flowscript.replay(compiled.program, history);
  if (!replay.ok) throw new Error(replay.error);
  if (replay.unmodelled.length) {
    throw new Error(replay.unmodelled.join('; '));
  }

  const last = history.len - 1;
  console.log({
    close: replay.metrics.close[last],
    fast: replay.metrics.fast[last],
    slow: replay.metrics.slow[last],
    trend: replay.metrics.trend[last],
    decisions: replay.decisions.length,
  });
} finally {
  flowscript.drop(compiled.program);
}
```

## Read the result

- `uses` declares the `bars` module. The host explicitly permits `bars.close` with a key and the `1h` interval.
- `"DEMO-USD"` and `"1h"` are written in the program. It needs no injected `market`, `interval` or account settings.
- Each metric returns one value per input bar. The trend is `1` when the fast average is above the slow average, `0` otherwise, and unknown while its inputs are warming up. Numeric unknown values cross the JavaScript API as `NaN`.
- `history.time` gives each completed bar's evaluation time in whole Unix seconds. The input columns are ordered oldest first and have exactly `len` values.
- The source is read under one key, so the history can use its bare name, `bars.close`. A program reading several keys needs separate `source|key` columns.
- There are zero decisions: this program publishes signals and declares no action capability.

Replace the illustrated input with observations your application owns when evaluating real data. Preserve the source identity, units, ordering and timestamps; an interval declaration does not fetch or construct hourly bars for you.

Next, read [Embedding Flowscript](https://flowscript.ftw.trade/docs/embedding) or the [language reference](https://flowscript.ftw.trade/docs/reference). To use the hosted editor, market data and strategy workflow, see [Strategies on ftw.trade](https://docs.ftw.trade/strategies/overview).

---

# Values, series and na

> Values and series, missing observations, expressions, functions, folds, enums and phases.

[Canonical documentation](https://flowscript.ftw.trade/docs/language)

Flowscript calculates over the inputs its [host declares](https://flowscript.ftw.trade/docs/reference#the-host). A host supplies data, available actions and any names bound to a run. ftw.trade is one such host; these language rules also apply when you embed the compiler yourself.

## Values

| Kind | Example |
|---|---|
| Number | `1`, `0.5`, `1e-3` |
| Condition | `true`, `false` or `na` |
| Text | `"ETH"` |
| Record | `{ usd: 100, side: "long" }` |
| List | `[1, 2, 3]` |

## Everything is a series

Every `const` is a series: one value per bar. `close` is today's close; `close[1]` is the bar before; `close[5]` five bars back. Arithmetic works bar by bar, so `(high + low) / 2` is a series of midpoints.

Durations are seconds: `seconds(30)`, `minutes(15)`, `hours(6)`.

## na: not known yet

`na` means a value isn't known yet: an indicator still warming up, a division by zero, a bar with no data.

- It spreads: `na + 1` is `na`, `na > 3` is `na`, and `!na` is `na`.
- A trigger never fires on `na`.
- Test for it with `isNa(x)`; replace it with `nz(x, 0)`.

So write the condition you mean: `close > ema(close, 200)` is `na` (not false) for the first 200 bars.

## Expressions

- Arithmetic `+ - * / %`, comparisons `< <= > >= == !=` (they don't chain: write `1 < x && x < 3`), logic `&& || !`.
- `c ? a : b`, and `if (c) a else b`.
- Math: `abs`, `min`, `max`, `clamp`, `ln`, `exp`, `sqrt`, `pow`, `floor`, `ceil`, `round`, `sign`.
- Time: `hour`, `minute`, `dayofweek` read a timestamp in UTC, and `nyTime`, `londonTime`, `tokyoTime` and others give a city's clock with daylight saving. `inWeekdaySession(nyTime(t), 930, 1600)` identifies the US stock session. The host declares its timestamp source and bar intervals.

## Functions and folds

```text
fn mid(a: Series<number>, b: Series<number>): Series<number> { return (a + b) / 2; }
const m = mid(high, low);
const doubled = map(xs, (x) => x * 2);
```

There are no loops and no variables to change. State that carries from bar to bar is a `fold`: a seed and a step from the last state and the new value.

```text
const streak = fold(close, 0, (st, c) => isNa(c) ? st : (c > c[1] ? st + 1 : 0));
```

Guard every fold step with `isNa(x) ? st : …`: one missing bar would otherwise turn the state `na` forever.

## Enums and match

```flowscript
uses { bars: "^1" }
enum Regime { hot, quiet, normal }
const close = bars.close("BTC-USD", "1h");
const vol = stddev(change(ln(close)), 24);
const regime = vol > 0.02 ? Regime.hot : (vol < 0.005 ? Regime.quiet : Regime.normal);
metric("size", match (regime) { hot => 0, quiet => 1, _ => 0.5 });
```

A `match` must cover every variant or end in `_`. A swap's `side` and a source's cases are enums too.

## Phases

`phases Trade { phase Flat { … } phase Long { … } }` is a state machine: inside each phase, `when … => Phase` moves to another, at most once a bar. It's the clearest way to write "wait for a setup, then enter, then manage the position".

## Higher timeframes

On a 15-minute run, `bars.close(market, "4h")` is the last closed four-hour bar's close, held until the next one closes. It never repaints. `higher("4h", close, c => ema(c, 20))` runs a calculation on the four-hour bars themselves.

## Libraries

Keep functions you reuse in a library and `import "mylib";` after the `uses` line. Your host provides the library resolver. On ftw.trade, [the module and library guide](https://docs.ftw.trade/flowscript/modules) explains how to save and version them.

## Exact integers

Numbers are 64-bit floats. For token amounts that need every digit, `u256` functions carry exact 256-bit integers, with checked arithmetic and unit conversion. See [exact integers](https://flowscript.ftw.trade/docs/reference#exact-integers) for the versioned conversion rules. An action with an invalid argument is refused by the runtime; the host owns execution and signing.

---

# Indicators and models

> Moving averages, oscillators, windows, sessions, market profile and models over the inputs your host supplies.

[Canonical documentation](https://flowscript.ftw.trade/docs/indicators)

Indicators calculate over series your host supplies. The language does not connect to a venue or choose a data provider; the host declares and records those inputs.

## Moving averages

`sma`, `ema`, `wma`, `rma`, `hma`, `dema`, `tema` take `(src, len)`; `vwma(src, vol, len)` and `vwap(price, vol, len)` weigh by volume.

## Momentum and oscillators

| Function | Gives |
|---|---|
| `rsi(src, len)` | 0 to 100 |
| `stoch(close, high, low, len)` | 0 to 100 |
| `cci(src, len)`, `mfi(src, vol, len)`, `obv(src, vol)` | The classic readings |
| `roc(src, len)`, `momentum(src, len)` | Rate of change (percent) and momentum |
| `macd(src, fast, slow)`, `macdSignal(…, sig)`, `macdHist(…, sig)` | One function per line |

## Volatility and bands

`bbUpper(src, len, mult)` and `bbLower(…)` (the middle is `sma(src, len)`), `stddev`, `zscore`, `wilderAtr(high, low, close, len)` (the ATR charts draw) and `trueRange`.

## Trend

`adx(high, low, close, diLen, adxLen)`, `diPlus`, `diMinus`, `supertrend(high, low, close, factor, len)` with `supertrendDir`, and `sar(high, low, close, start, inc, max)`.

## Windows and levels

`highest`, `lowest`, `rolling_sum`, `cum`, `linreg`, `corr(a, b, len)`, `median`, `percentile`, `barssince(cond)`, `valuewhen(cond, src)`, and `pivothigh` and `pivotlow` (known a few bars late, by design).

## Sessions and VWAP

- `periodVwap(price, volume, t, 86400)` is the day's VWAP from 00:00 UTC; `anchoredVwap` starts from any bar; both have σ bands.
- `inSession`, `inWeekdaySession`, `sessionOpen`, `sessionHigh` and `sessionLow` frame a trading session in any city's time.
- `import "std/vwap";` adds what a VWAP trader reads: where price sits in σ, the week's and month's anchors, whether the day is trending, and a failed push into a band.

## Market profile

`tpo.poc`, `tpo.vah`, `tpo.val`, `tpo.vpoc`, `tpo.poorHigh`, `tpo.singleAbove`, `tpo.nakedPocAbove` and more read the last whole day's (or week's, or the forming session's) time-price profile, the same in a backtest and live.

## Trained models

Models train on the market as the strategy runs, with no look-ahead, and refit on a schedule. The same model is fitted in a backtest and live.

| Model | Answers |
|---|---|
| `ml.linear`, `ml.ridge`, `ml.lasso`, `ml.elasticNet`, `ml.svr` | A forecast of `y` |
| `ml.boost` | Gradient-boosted trees forecasting `y` |
| `ml.logistic`, `ml.boostClassifier` | The chance `y` is above zero |
| `ml.svm` | A signed margin |
| `ml.knn` | The mean `y` of the nearest rows |

Each is written `ml.<kind>(y, [x1, x2, …], window: n, horizon: h, retrain: r)`: it learns `y` `h` bars after the predictors over the last `n` rows, refits every `r` rows, and answers `na` until its first fit.

```flowscript
uses { bars: "^1" }
const close = bars.close("BTC-USD", "1h");
const ret = close[0] / close[1] - 1;
const fwd = close[0] / close[3] - 1;
const f = ml.ridge(fwd, [ret, close / ema(close, 20) - 1, rsi(close, 14)], window: 300, horizon: 3, retrain: 20);
metric("forecast", f);
```

This publishes a forecast without sending an action. Your host can expose actions that use the result. The [ftw.trade strategy starters](https://docs.ftw.trade/strategies/starters) include a trading example with five features.

## Liquidations

Liquidation feeds are host-provided inputs. ftw.trade exposes `liq.*` for supported perp markets; its [source documentation](https://docs.ftw.trade/sources/flowscript-sources) describes coverage. These feeds are part of that platform's binding rather than built into the language.

---

# Language reference

> The compiler-owned reference for syntax, types, hosts, actions, functions, diagnostics and runtime semantics.

[Canonical documentation](https://flowscript.ftw.trade/docs/reference)

Flowscript is a small language for trading strategies and indicators, designed
for AIs to write. A program reads time series (prices, volumes, event tapes),
computes values over them, and fires actions when its conditions turn true. It
is deterministic: the same inputs always produce the same values and the same
actions, which is why a backtest over history and a live run over new bars make
the same decisions.

What makes it suit a model writing strategies is that the language is small and
bounded. A program has no loops and no mutation, so it always terminates. It
reaches only what its host declares. It is checked before it runs, and compiler
errors are located, carry stable codes, and suggest fixes. Because each run
replays exactly, a model can backtest a change and trust the comparison.

Compilation does not promise that external data or execution will always
succeed. A run refuses invalid inputs and damaged checkpoints, and stops when
it exhausts a resource budget. Hosts must surface that refusal and retain the
last successful checkpoint; they must not treat it as a successful bar or
replace it with fabricated values. Missing observations and indicator warmup
use the language's explicit `na` value.

This reference describes the language as `flowscript-core` and `@flowscript/core`
implement it, without ftw. Every program in a `flowscript` block below is
compiled by the library's tests (`src/docs_reference.rs`) against the host in
[The examples' host](#the-examples-host) and replayed over a synthetic history,
so the examples cannot drift from the compiler. The semantics are specified in `FLOWSCRIPT_V2_SPEC.md` at the
repository root; this is the user's view of them.

- [A first program](#a-first-program)
- [Language versions](#language-versions)
- [The host](#the-host)
- [Values and types](#values-and-types)
- [Expressions](#expressions)
- [Functions, lambdas and fold](#functions-lambdas-and-fold)
- [Metrics](#metrics)
- [Triggers](#triggers)
- [Actions and handlers](#actions-and-handlers)
- [Enums and match](#enums-and-match)
- [Phase machines](#phase-machines)
- [Tapes](#tapes)
- [The prelude](#the-prelude)
- [Built-in functions](#built-in-functions)
- [Diagnostics](#diagnostics)
- [What runs where](#what-runs-where)
- [Coming from Pine Script](#coming-from-pine-script)

## A first program

```flowscript
uses { bars: "^1", paper: "^1" }

const close = bars.close("BTC-USD", "1h");
const fast = ema(close, 5);
const slow = ema(close, 20);

metric("fast", fast);
metric("slow", slow);

when (crossover(fast, slow)) { paper.buy({ symbol: "BTC-USD", quote: 100 }); }
when (crossunder(fast, slow)) { paper.sell({ symbol: "BTC-USD" }); }
```

- `uses { … }` names the modules the program calls, with a version range. A
  module is either a source namespace (`bars`) or a capability (`paper`).
- `const` binds a name to a value. Every binding is a series: `close` is the
  close of every hourly bar, and `ema(close, 5)` is a new series computed from
  it, one value per bar.
- `metric(name, value)` publishes a value: a replay returns it for every bar,
  and a live run returns it at each step.
- `when (condition) { … }` fires its actions when the condition turns true.
  `crossover(fast, slow)` is true at the bar `fast` crosses above `slow`.

Comments are `// …` to the end of the line, or `/* … */`.

## Language versions

Flowscript is versioned as `MAJOR.MINOR`, and is at 0.3 before its beta. A
program says which version it is written in on its first line, before `uses`
(comments may come above it):

```flowscript
flowscript "0.3";
uses { bars: "^1", paper: "^1" }

const close = bars.close("BTC-USD", "1h");
when (crossover(ema(close, 5), ema(close, 20))) { paper.buy({ symbol: "BTC-USD", quote: 100 }); }
```

The version is a requirement string, written as a module's is in `uses`:
`"0.1"` and `"^0.1"` mean the same, Cargo's caret. Before 1.0 each minor
version may change what a program means, so a 0.x requirement names its minor
and compiles only as exactly that version; `"0"` alone is refused. From 1.0 on,
`"^1.2"` compiles as the newest 1.x the compiler speaks that is at least 1.2.

- A version the compiler does not speak is refused where it is written
  (`language.version`), with the versions it does speak, never compiled under
  another version's rules. So is a declaration anywhere but the first line, or
  given twice.
- A program that names none compiles as the compiler's newest version.
  Applications that keep programs record the version each was saved as and
  compile it as that version from then on (`Options::language`, or `language`
  in an `@flowscript/core` host); the program's own line wins over the record.
- New 0.3 artifacts always pin the version they compiled as
  (`language_version`), including programs using the default. Historical
  artifacts with no marker retain their historical unsigned policy. A runtime
  refuses an artifact of a version it does not speak. `Program.language` in
  `@flowscript/core` gives the version a program compiled as.
- A trusted host restoring a known historical unversioned artifact may request
  `ArtifactIdentity::LegacyUnversioned` (`artifactIdentity: 'legacy-unversioned'`
  in a JavaScript host) with explicitly selected language `0.1`. Without an own
  source header, this reproduces the omitted marker and original digest while
  reporting effective language `0.1`. An own source header wins with its normal
  pinned identity. Checkpoint hash checks remain strict; new programs leave
  this restoration option unset.
- A library may name its version on its first line too, and is held to it.

| Version | What changed |
|---|---|
| 0.1 | Versions began (D1543). |
| 0.2 | [Arrays](#arrays) (D1544). Their functions (`buffer`, `filter`, `groupBy`, …) are built-in names, so a program's own `fn filter` is refused. A 0.1 program keeps its own function of such a name, and has arrays besides. |
| 0.3 | [Exact integer math](#exact-integers): checked signed long and uint256 arithmetic, full-precision multiply-divide, exact units, and safe numeric input rules. Earlier saved versions keep their own names and unsigned-input policy. |

## The host

The language has no built-in data and no built-in actions. The application
compiling a program declares what it may read and do. That declaration is the
**host**.

- **Sources** are the reads. Each has a `namespace.name`, a type (number, bool,
  text, a tape of events with typed fields, or a record of typed fields read
  one bar at a time, such as a position's `size` and `pnl`), whether it takes a literal key
  as its first argument (a symbol, an address), and which bar intervals it is
  published at. `bars.close("BTC-USD", "1h")` is a keyed number source read at
  `1h`. A key can instead be a typed **identity**: a source declared with
  `identity: 'pool'` (`'token'`, `'market'`, `'venue'`, `'wallet'`) takes
  `pool("base:0x…")` (`wallet("main")`, keyed by the wallet's name) and
  refuses a bare string or another kind of identity (`market.identity`), so a
  pool's bars cannot be read with a token's address. Optional `args` follow
  the key and the interval, each typed (`duration`, `number`, `quantity`,
  `text`): a TWAP's window, `twap(pool("…"), "5m")`. Reading a source the host does not declare is the `stream.unknown`
  error, with the nearest name it does declare; an interval it does not publish
  is refused too.
- **Capabilities** are the actions, declared as YAML manifests: the module's
  name and version, and each action with its typed arguments. A call that does
  not match a manifest (an unknown action, an argument it does not take, or
  one of the wrong kind, such as a number where it takes `Text`) is refused at
  compile time. An action's `required:` lists the arguments it cannot run
  without (`pair|token` for either of two), after its `defaults:`, and its
  `positive:` the amounts that must be above 0 where the source writes them:
  `paper.buy({ symbol: "BTC-USD" })` is `action.required` and `quote: 0` is
  `action.positive`, each at the call. Its `evaluated:` lists the arguments the host reads as values when the action fires (each decision's `values`), not as the source that computes them: an application's own action, such as a source's `emit`, gets what they were at that bar. A manifest's `streams` are the module's reads: the
  first argument's type is the key's identity (`Market`, `Token`, `Pool`,
  `Wallet`, or `Venue` for either a pool or a market), the rest are optional arguments
  (`Duration`, `Bps`, `Number`, `Text`), and `out` is `Series<number>`,
  `Series<bool>`, `Series<text>` or a record, `"Series<{ size: number }>"`.
- **Catalog** rows resolve `series("tenant:me/name@1")` in Rust hosts through
  `Host::with_catalog(json)` or `extend_catalog(json)`. Each reference is
  unique and declares `type: "number"`, `"bool"` or `"string"`; an optional
  `keyed` is `"pool"`, `"token"` or `"market"`. String enum `variants` are
  distinct, nonempty names, using the same word rules as tape/record enums.
  References contain no whitespace/control characters and use a positive
  decimal major within `u32`. Tenant names occupy one path segment;
  platform names may use nested nonempty segments, such as
  `platform/metrics/volume-5m@1`.
  Invalid rows are refused when the host is built, even if no program reads
  them. A misspelled type never becomes a numeric series.
- **Markets** are the names `market("…")` may take, when the application has any.
- **Units** are the numeric reads' scales, `Host::with_stream_units(json)`,
  in the format of ftw's `platform/stream-units.json`. A row's `identity`
  (`pool`, `token`, `market`, `venue`, `wallet`) is what its read is keyed by,
  and makes the row a read the host declares: a number with the row's bar
  `intervals`, a tape when the row lists its `events` (`{ "px": "number" }`),
  otherwise a number taking the row's `args` (`[{ "name": "window", "type":
  "duration" }]`). A record row is not a call, and a read the host already
  declares keeps its declaration. A row naming any other identity is refused
  when the host is built. A bar's
  `forms_from` names the live mark its forming bar is decided on
  (`when (…, intrabar: true)`), and `unformed: true` marks a bar price the
  forming bar does not deliver, which an intrabar condition may not read.
  A tape's row may name a candle read, `"candles": { "read": "dex.candles",
  "price": "price", "volume": "usd" }`: bars of any period built from the
  tape (`Host::with_candles` declares one directly).

In TypeScript the host is a plain object (see `npm/README.md`):

```ts
const host = {
  sources: [{ name: 'bars.close', type: 'number', keyed: true, intervals: ['1h'] }],
  capabilities: [paperManifestYaml],
};
```

In Rust it is `flowscript_core::Host`, built with `Host::empty()`,
`.with_source(Source::number("bars.close").keyed().intervals(["1h"]))` and
`.with_capability(yaml)`.

### The examples' host

Every example in this reference compiles against this host:

| Source | Type | Keyed | Intervals |
|---|---|---|---|
| `bars.open`, `bars.high`, `bars.low`, `bars.close`, `bars.volume`, `bars.time` (each bar's start, unix seconds) | number | yes | `1h`, `1d` |
| `news.sentiment` | text | no | |
| `trades.prints` | tape: `price` number, `size` number, `side` text | yes | |

Two capabilities: `paper` with `buy({ symbol: Text, quote: Number })` and
`sell({ symbol: Text })`, and `alerts` with `send(message: Text)`.

## Values and types

| Type | Written | Notes |
|---|---|---|
| number | `1`, `0.5`, `1_000_000` | 64-bit float |
| bool | `true`, `false` | |
| text | `"BTC-USD"` | `+` concatenates text: `"filled @ " + fill.price`; a number joins with two decimals, more below 1 (`"p" + 1` is `p1.00`) |
| `na` | `na` | "not available": the one option type |
| record | `{ sum: 0, n: 0 }` | field access is typed: `r.sum`; an unknown field is an error |
| list | `[a, b, c]`, `[[a, b], [c, d]]` | a fixed list of numbers or series, a vector; a list of rows is a matrix. `xs[0]` is an item; see [Lists, statistics and linear algebra](#lists-statistics-and-linear-algebra) |
| array | `buffer(e, 100)`, `filter(xs, x => x.usd > 1000)` | items a run gathers, as many as its data makes (at most 10,000): numbers, text, conditions, records or arrays; see [Arrays](#arrays) |
| series | any of the above, over time | what a source returns, and anything computed from one |
| duration | `seconds(30)`, `minutes(5)`, `hours(4)` | |
| basis points | `bps(25)` | 25 basis points, as an action's argument declared in them takes it (`max_slippage: bps(25)`); in arithmetic it is the number 25, so a rate is written `25 / 10000` |

Quantity constructors such as `usdc(25)`, `eth(1)`, `bps(25)` and `pct(5)`
take exactly one argument. Extra arguments are compile errors.

**`na`** is how the language says a value is not known yet: an `ema(close, 20)`
is `na` for its first 19 bars rather than a made-up number. It propagates
through arithmetic and comparisons, and a condition that is `na` is not true.
A condition is true, false or `na`: `close > open` is `na` where either side
is, `!` of `na` is `na`, and `&&` and `||` answer `na` only when the known side
cannot decide (`false && na` is false, `true || na` is true, `true && na` is
`na`). `c ? a : b` and `if` over an `na` condition are `na`, and a `when` does
not fire on one. A chart and a running strategy read conditions the same way.
`isNa(x)` tests for it and `nz(x, 0)` replaces it. A condition or a text names
what replaces it, `nz(cond, false)`, since 0 is neither.
A condition is not a number: functions that take numbers (arithmetic,
`crossover`, the windows such as `median`) refuse one, and `cond ? 1 : 0` is
its number. A duration such as `"1h"` goes only where a clock takes one
(`cooldown`, `resample`); `hours(1)` is that many seconds as a number (D1290).

**Scalars lift over series.** `close * 2`, `close > open` and `abs(change(close))`
apply bar by bar.

## Expressions

- Arithmetic `+ - * / %` on numbers, comparison `< <= > >= == !=`, logic
  `&& || !` on conditions. A condition is not a number: `(a > b) * 2` is an
  error, and `a > b ? 1 : 0` is the number.
- Comparisons do not chain. `1 < x < 3` is an error; write `1 < x && x < 3`.
- A comparison with `na` is `na` at every bar, so `x == na` is an error; test
  with `isNa(x)`.
- Conditional: `cond ? a : b`, or `if (cond) a else b` as an expression. Both
  arms must have the same type.
- History: `close[1]` is the previous bar's close, `close[k]` the value `k` bars
  ago (`na` before there are `k` bars).
- Blocks: `{ let x = …; return …; }` where a function or lambda body is
  expected. A `let` or a lambda's parameter cannot shadow a binding or a
  `const`, and a `fn` cannot take a built-in function's name.

```flowscript
uses { bars: "^1" }
const close = bars.close("BTC-USD", "1h");
const open = bars.open("BTC-USD", "1h");
const body = abs(close - open);
const bias = if (close > open) "up" else (close < open ? "down" : "flat");
metric("body", body);
metric("bias", bias);
metric("gap", (open - close[1]) / close[1]);
```

A `const` is bound once: a second `const` of the same name is an error, not a
replacement.

There are no loops, no recursion and no mutation. That is deliberate: every
program terminates at every bar with bounded memory, which is what makes it
replayable.

## Lexical structure and grammar

**Text.** A program is UTF-8. Outside strings and comments it is ASCII: a
non-ASCII character there is an error naming it, except Unicode spaces, which
separate tokens as ASCII whitespace does. A leading byte-order mark is ignored.
Comments are `// …` to the end of the line and `/* … */`, which does not nest.

**Tokens.**

| Token | Form |
|---|---|
| name | an ASCII letter or `_`, then letters, digits and `_` |
| number | decimal digits with an optional fraction and exponent: `42`, `0.5`, `1_000`, `1.5e3`, `2E-1`. No sign (that is unary `-`), no leading `.`, no hex. A number too large for a 64-bit float, or so small it would read as `0`, is an error, as is a number run into a name (`2px`) |
| string | `"…"`, with the escapes `\"`, `\\`, `\n` and `\t`; any other `\` is an error |
| `true`, `false` | the two conditions |
| operators | `+ - * / % < <= > >= == != && \|\| ! ? : => = . , ; ( ) [ ] { } @` |

**Precedence**, loosest first. Binary operators on one level associate left,
except comparisons, which do not associate at all.

| Level | Operators |
|---|---|
| 1 | `c ? a : b`, `if (c) a else b` and `match (x) { … }` (right-associative: `a ? b : c ? d : e`) |
| 2 | `\|\|` |
| 3 | `&&` |
| 4 | `< <= > >= == !=`, one per expression |
| 5 | `+ -` |
| 6 | `* / %` |
| 7 | unary `-` and `!` |
| 8 | history `x[k]`, field `r.f`, call `f(…)`, parentheses |

So `-x[1]` is `-(x[1])`, `a || b && c` is `a || (b && c)`, and
`x - 1 - 2` is `(x - 1) - 2`.

**Limits.** An expression nests at most 128 levels as written: each
parenthesis, operand, call and record is one, and so is each operator in a
chain (`a + b + c` is two). Once its `const`s are substituted and its library
calls inlined, one binding may lower to 160 levels and 1 MB. A library
call's large argument that its body reads more than once is bound once
rather than copied to every read, so stacked indicators (`sma(stoch(r, r, r,
14), 3)` over an `rsi`, `hma(hma(hma(close, 9), 9), 9)`) grow with their
nesting, not exponentially. A large `const` of any type is bound once in
the binding that reads it, and a small one is copied where it is read. The
largest program in the repository uses about a sixth of the depth and a
fortieth of the size. A program past either limit is refused with
`syntax.depth` or `expr.size` instead of exhausting the memory of whatever
compiles it.

A program's source is at most 1 MB, and a metric's name at most 128
characters. The whole program lowers to at most 4 MB, summed over every
const, metric, condition and argument, keeps at most 4,000,000 samples of
state, and has at most 1,000 metrics, 2,000 triggers (each handler and each
`if` in a body counts as one) and 2,000 actions. Past any of these the
program is refused with `program.size`, as soon as the compiler passes it;
the refusal names the const, metric or trigger that passed the size and the
three that lowered to the most before it. A `const` that lowers to 2,000
bytes or more, whatever its type, is bound once in each binding that reads
it, however many times that binding reads it, so a step that reads a scored
list of pools through two or three consts holds the list once; a smaller
`const` is copied at every read, as it always was. A `const` that reads
another is still held once per binding that reads either, so a program over
many pools keeps the bindings that read its scored list few.

A run is bounded too, in evaluation steps (a node walked, or an element a
window scans), which count the same on every replay of the same bars: a bar
may take 50,000,000 and a replay 4,000,000,000, and a replay returns at most
1,000,000 decisions and orders. Past one the replay stops with an error that
names the bar.

What a program keeps is bounded where it is written: one expression keeps at
most 1,000,000 samples of state (a window's length, a history depth `[n]`, a
warm-up), and a `window` over a tape spans at most `"7d"`, since it keeps every
event in its span. Both are refused with `expr.size`. A text value holds at most
4,096 bytes; joining past that is `na`, so a `fold` that grows its text cannot
grow without end. A NaN or infinity a source feeds is `na`, and so is an answer with no finite
reading, such as `log10(0)` or `asin(2)`.

## Functions, lambdas and fold

`fn` defines a function. Parameters and the result are typed: `number`,
`bool`, `text` or `count`, or a `Series<…>` of the first three. Annotations
check the element kind: a scalar broadcasts as a constant series, so
`ewma(3, 5)` is valid. `count` names a whole number from 1. A call whose argument,
or a body whose result, is a different kind (a number, a condition, text) from
what the annotation names is refused, and so is a name that is not one of these
(`Series<Number>`). A parameter with no annotation takes anything. A function
has one definition, and its parameters have distinct names.

An annotation names exactly one type. After `:`, a type is required:
`x:`, bare `Series`, `Series<>`, `number bool` and `number + text` are
errors, rather than an untyped parameter or an alternative type. `Series`
contains one of `number`, `bool` or `text`; `count` is scalar. The existing
spellings `boolean` and `string` are aliases for `bool` and `text`.

```flowscript
uses { bars: "^1" }
fn spread(a: Series<number>, b: Series<number>): Series<number> {
  return (a - b) / b;
}
const close = bars.close("BTC-USD", "1h");
metric("stretch", spread(close, sma(close, 50)));
```

`fold(series, seed, (acc, x) => next)` is the one stateful loop: it steps once
per bar, from `seed`, with the last result and the new sample. The seed may be
a record, and the accumulator is typed by it. Every indicator in the prelude is
written with it.

```flowscript
uses { bars: "^1" }
const close = bars.close("BTC-USD", "1h");
// Bars since the close last made a new high. A bar with no close leaves
// the state as it was: without the isNa test one missing sample would make
// the state na for the rest of the run.
const since = fold(close, { high: 0, n: 0 },
  (st, x) => isNa(x) ? st
    : (x > st.high ? { high: x, n: 0 } : { high: st.high, n: st.n + 1 }));
metric("bars_since_high", since.n);
```

A lambda is `(a, b) => expr` or `(a, b) => { let …; return …; }`. It captures
the names around it by value.

`@warmup(n)` after a `const`'s expression, or before a `fn`, states a lookback
the compiler cannot derive.
It can only ask for more history, never less.

### Libraries

`import "name";`, after `uses`, gives a program the functions of a library its
host offers (D1214). A library holds `fn` definitions, contract interfaces
and imports of other libraries: no `uses`, metrics or triggers. Its caller
owns the sources, actions and contract instances it may use. The compiler itself
offers the `std/` libraries, such as `std/erc20` (see Contract calls) and `std/vwap` (below). Its functions are checked like the
program's own, where the program calls them, and a problem inside one is named
as an imported function's.

```text
// The library "swing", as the host offers it.
fn mid(a: Series<number>, b: Series<number>): Series<number> {
  return (a + b) / 2;
}
```

```text
uses { bars: "^1" }
import "swing";
const high = bars.high("BTC-USD", "1h");
const low = bars.low("BTC-USD", "1h");
metric("mid", mid(high, low));
```

`import "std/vwap";` is the VWAP trader's library, built on the prelude's
`periodVwap`, `anchoredVwap` and their σ: `weekStarts(t)` and `monthStarts(t)`
(anchors: the first bar of each UTC week from Monday 00:00, and of each
month), `vwapZ(price, vw, dev)` (where price sits in σ), `vwapDrift(vw, dev,
anchor)` (how many σ a bar the VWAP has walked since its anchor: near 0 on a
balanced day), `ridingAbove(close, vw, dev, len)` and `ridingBelow(…)` (the
share of the last `len` closes beyond the 1σ band: a trend, not a fade), and
`failedPushUp(high, open, close, upper, within)` and `failedPushDown(low, open,
close, lower, within)` (a push into a band that turned back within `within`
bars). Its source and tests are `flowscript/std/vwap.flow` and
`vwap.test.yaml`.

```flowscript
uses { bars: "^1" }
import "std/vwap";
const close = bars.close("BTC-USD", "1h");
const high = bars.high("BTC-USD", "1h");
const vol = bars.volume("BTC-USD", "1h");
// Anchored at each new 20-bar high: the average price of everyone who bought since.
const top = high >= highest(high, 20);
const vw = anchoredVwap(close, vol, top);
const dev = anchoredVwapDev(close, vol, top);
metric("z", vwapZ(close, vw, dev));
metric("riding", ridingAbove(close, vw, dev, 12));
```

A host names its libraries when it compiles (`Options.libraries` in Rust,
`Host.libraries` in `@flowscript/core`), so the same source compiles to the
same program wherever it is given the same libraries. A library can compose
another helper with `import "features/base";` before its functions; a strategy
then imports only the entry library. Dependencies resolve by those exact host
names, including `std/` helpers. A host-supplied standard-library source takes
precedence over the compiler's installed copy in compilation and editor tools.
The compiler performs no filesystem, package-registry or network discovery.

The complete dependency closure may contain at most 15 unique libraries, each
subject to the program source-size limit. A shared dependency reached through
several libraries loads once; explicitly importing that same dependency beside
an entry library also loads it once. Listing an import twice in the same file
still refuses. Cycles, unavailable dependencies, malformed libraries and
incompatible library language headers refuse before evaluation, at the
strategy's importing line with the dependency path in the diagnostic. Library
functions share the caller's function namespace: use distinct names when
composing packages. Conflicts between two libraries, the prelude or the
program's own functions refuse.

Hosts can obtain the exact reached source map, including installed standard
libraries, with `resolve_libraries(source, options)` in Rust or
`flowscript.resolveLibraries(source, host)` in `@flowscript/core`. This validates
source syntax and dependency admission without requiring the strategy's data
host or typechecking its function bodies; compile and test it separately.
Persist the returned sources together with the program, then supply that frozen
map to compilation, testing and editors. Changes to a dependency's used code
change the compiled artifact identity and cannot reuse another version's live
checkpoint. On ftw.trade a library is the account's, saved with `save_library`,
and a strategy keeps its complete saved dependency closure until it is saved
again.

## Metrics

`metric(name, value)` publishes one value per bar, and each metric has its own
name. A numeric or boolean metric
comes back as numbers (`true` is 1). A metric that is `na` (still warming up)
reads `NaN`, and a text metric comes back as words (`""` while `na`). A
constant is a metric too, a number or a word the same at every bar.

## Triggers

A trigger is a condition and the actions to fire when it holds.

- **`when (cond) { … }` fires on the rising edge**: the bar the condition turns
  from false to true, once per crossing.
- **`while (cond) { … }` fires at every bar the condition holds** and that
  brought something new the condition reads.

```flowscript
uses { bars: "^1", alerts: "^1" }
const close = bars.close("BTC-USD", "1h");
const volume = bars.volume("BTC-USD", "1h");
when (close > rolling_high(close, 24)[1]) { alerts.send("new 24h high"); }
while (volume > 3 * sma(volume, 48)) { alerts.send("volume still heavy"); }
```

Combinators, all usable inside any condition:

| | |
|---|---|
| `crossover(a, b)`, `crossunder(a, b)` | `a` crosses above, below `b` |
| `rising(cond)`, `falling(cond)` | `cond` turned true, false this bar |
| `changed(x)` | `x` differs from its last value |
| `once(cond)` | true the first bar `cond` holds, never again |
| `sustained(cond, n)` | `cond` has held for `n` bars; a count written in the source is a whole number from 1 |
| `cooldown(d)` | false for `d` after the trigger last fired; `d` is a duration of 0 or more (`hours(6)`, `"6h"`, a `config`), and only in a `when` or `while` condition (FS0541) |
| `hysteresis(x, on, off)` | true once `x` passes `on`, until it falls back past `off` |
| `every("1d")`, `every("1w", at: "Mon 14:00")` | each boundary of chain time |

```flowscript
uses { bars: "^1", alerts: "^1" }
const close = bars.close("BTC-USD", "1h");
when (sustained(close > sma(close, 20), 3) && cooldown(hours(6))) {
  alerts.send("three closes above the 20-bar average");
}
when (every("1w", at: "Mon 14:00") && close < sma(close, 200)) {
  alerts.send("weekly buy window");
}
```

`every` counts chain time from the Unix epoch, from the time a run is given
with each bar (or the bar number when there is none). It fires on the first
bar at or after each boundary, once per boundary.

`every`, `crossover`, `crossunder`, `rising`, `falling`, `changed`, `once`
and `triggered` are impulses: true for exactly the bar they mean. A `when`
whose condition contains one fires at every bar the condition is true, on
consecutive bars too, so `when (every("1d"))` over daily bars fires every
day and `when (changed(regime))` at every change. Everything else is a
level, and a `when` over a level fires once per crossing.

## Actions and handlers

An application with a correlated execution coordinator can choose how it waits:
`async orders.marketBuy({ … })` leaves other strategy decisions running while
this action's site remains pending. `await orders.marketBuy({ … }, timeout:
"30s")` holds strategy decisions until settlement or that chain-time wait
deadline. The trailing timeout is execution metadata, not a venue argument;
write a positive duration literal. Existing unbounded `await` and action
defaults retain their meaning.

An explicitly bounded await may attach `.onTimeout { … }`. This reports
**the wait ending**, not transaction cancellation or a failed trade. The
coordinator keeps its request identity, site exclusivity and unresolved money
reserved. A later `.onFill`/`.onRevert` still belongs to that same request.
Do not fund a replacement order merely because the strategy resumed. Cancelling
an upstream request is a separate supported action and must itself settle.
Task `.onTimeout` retains the task invocation's separate timeout semantics.

The language run folds reads/metrics while the coordinator pauses decisions;
trigger edges and phase transitions remain held. Its snapshot retains the
pause and in-flight observations, not the coordinator's authoritative request
ledger. The application must persist request IDs, deadlines and event cursors,
validate late/duplicate outcomes, then feed execution state and report outcomes.
The legacy uncorrelated connector is not a bounded-wait execution coordinator.

The JavaScript SDK's `requestRun` supplies a durable request journal for trigger
strategies whose managed actions explicitly choose `await` or `async`. It
refuses phase machines, maintainers and instantaneous paper brokers. The
application supplies durable storage, submits requests and reconciles
authoritative venue outcomes; the journal performs no IO. The SDK's legacy
`connect`, Rust `Connectors` and the platform `Host` refuse bounded waits.
Language support alone does not enable a venue or establish live execution.

An action is a call to a capability: `paper.buy({ symbol: "BTC-USD", quote: 100 })`.
Each action expression is an **action site**, named by where it is in the
program (`when1#1:paper.buy`). A decision carries its site, and an outcome
reported for it names the site back.

Handlers attach to an action and run when it ends: `.onFill`, `.onRevert`,
`.onAbort` and `.onStuck`. A handler reads the outcome as `fill.price`,
`fill.amountOut` and `outcome.reason`, and may fire actions of its own, guarded
by `if` if it likes.

```flowscript
uses { bars: "^1", paper: "^1", alerts: "^1" }
const close = bars.close("BTC-USD", "1h");
when (crossover(close, ema(close, 20))) {
  paper.buy({ symbol: "BTC-USD", quote: 100 })
    .onFill {
      if (fill.price > close * 1.01) { paper.sell({ symbol: "BTC-USD" }); }
      alerts.send("bought at " + fill.price);
    }
    .onRevert { alerts.send("buy failed: " + outcome.reason); };
}
```

A bridge transfer takes time to land, so it has one more handler: `.onSent`
runs when the funds leave, reading what is expected to land as
`fill.amountOut`, and `.onFill` runs when they arrive, reading what did.
Between the two the transfer is `inFlight()`. `bridge.inTransit(route)` reads
how much is on its way along a route, and `bridge.held(route)` what the
route's destination account holds, so a strategy's funds are always somewhere
it can read. This example needs a host with a bridge module, such as ftw's, so
it isn't one of the examples run against this reference's host.

```text
uses { bridge: "^1" }
const out = market("relay:usdg-robinhood-to-usdc-hyperliquid");
when (bridge.feeBps(out) < 20 && !inFlight()) {
  bridge.transfer({ market: out, amount: 500 })
    .onSent { notify("on its way: " + fill.amountOut); }
    .onFill { notify("arrived: " + fill.amountOut); };
}
```

An action that signs names its wallet with `from: wallet("main")`, or takes
the strategy's `default_wallet`. `from: pick(group("Group A"))` sends it from
one wallet of a group, chosen each time it fires; `pick` takes groups and
wallets together (`pick(group("A"), wallet("desk"))`). `pick(group("A"), 3)`
sends it from three of them at once, each its own order and nonce, as a
competing fill needs. The host knows each group's wallets, and chooses by a
hash of the action site and the bar, so a replay of the same bars picks the
same wallets. A group the host does not know, or one smaller than the count,
refuses the action when it fires. The choices are literal, so the wallets a
strategy may sign with are read off the program (D1141). This example needs a
host with wallet groups, such as ftw's.

```text
uses { orders: "^1" }
const P = pool("robinhood:0x…");
when (crossover(dex.close(P, "5m"), ema(dex.close(P, "5m"), 20))) {
  orders.marketBuy({ pair: P, quote: usdc(25), from: pick(group("snipers"), 3) });
}
```

An `if` in a `when` or `while` body guards the actions inside it. It is read
at the bar the `when` fires, so `when (a) { if (b) { … } }` acts the bar `a`
turns true, if `b` holds then, and not later when `b` turns true while `a`
still holds (that is `when (a && b)`). The other actions in the body fire
either way, and every action that fires comes out in the order it is
written, guarded or not: an `if (inPosition()) { sell }` written above a buy
is placed before it.

```flowscript
uses { bars: "^1", paper: "^1", alerts: "^1" }
const close = bars.close("BTC-USD", "1h");
const volume = bars.volume("BTC-USD", "1h");
when (crossover(close, ema(close, 20))) {
  alerts.send("crossed up");
  if (volume > sma(volume, 24)) { paper.buy({ symbol: "BTC-USD", quote: 100 }); }
}
```

Who decides the outcome is the application's choice. With a paper broker, a
replay or a run fills each order itself. An application with its own venue
reports each outcome to the run (`run.report` in TypeScript, `Run::report` in
Rust), and the handlers fire at the last bar stepped.

### Contract calls

`uses { v: abi("Name", "0x…", ["sig", …], { Struct: "(…)" }) }` imports exactly
the listed functions of the contract at that address (D550b, D1249, D1250). A program
can call any function of any contract this way. A call is an action:
`v.fn({ param: value, … })`, with each parameter passed by its name in the
signature.

```text
uses {
  bars: "^1",
  v4: abi("Router", "0x…", [
    "swap(PoolKey key, bool zeroForOne, int256 amount, bytes hookData)",
    "swap(PoolKey key, bool zeroForOne, int256 amount) as swapSimple",
  ], { PoolKey: "(address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks)" })
}
const key = { currency0: "0x…", currency1: "0x…", fee: 3000, tickSpacing: 60, hooks: "0x…" };
when (bars.close("ETH-USD", "1h") > 4000) {
  v4.swapSimple({ key: key, zeroForOne: true, amount: 5000, retries: 2, backoff: "3 blocks" });
}
```

| Solidity | Flowscript value |
| --- | --- |
| `uintN`, `intN` | a whole number; sent as exact decimal text, range-checked by the encoder |
| `address`, `bytesN`, `bytes`, `string` | text (`"0x…"` for addresses and bytes) |
| `bool` | a condition |
| a tuple `(T a, U b)` or a named struct | a record with exactly those fields |
| `T[]`, `T[n]` | a list `[…]`, of exactly `n` items for `T[n]` |

- **Structs.** A named struct is declared once in the fourth argument and used
  by name in any signature, nested up to eight deep. A tuple can also be
  written inline: `"f((address to, uint256 v)[] legs)"`.
- **Overloads.** Two functions with one name are told apart by renaming one
  with `as`. The name in the program changes and the selector stays the
  contract's own.
- **Call options.** `from`, `retries`, `backoff` and `value` sit beside the
  arguments, so a parameter cannot use those names.
- **Views.** A signature ending `view returns (T)` is read like a stream, with
  literal arguments, or a `const` holding one:
  `when (vault.pending("0x…") > 1000)`.
- **Checks.** A missing or extra field, a list of the wrong length, and a
  literal of the wrong type are refused when the program compiles. A value
  that does not fit its type, or that is `na` or fractional, refuses the call
  before anything is signed.
- **Interfaces.** `interface ERC20 = abi(["sig", …], { structs });` lists a
  contract's functions without an address, and `uses { usdc: ERC20("0x…") }`
  binds it to one. Two contracts with the same functions are then two
  names, `usdc.balanceOf(…)` and `weth.balanceOf(…)`, with no clash. A
  program declares its own interfaces or imports them from a library.
- **Standard libraries.** `import "std/erc20";` gives the `ERC20` interface
  (transfer, approve, transferFrom, and the balanceOf, allowance,
  totalSupply and decimals views) and `tokenUnits(amount, decimals)`.
  `import "std/erc4626";` gives `ERC4626`: deposit, mint, withdraw and
  redeem, and views for its assets, balances, conversions and previews.
  Their sources and tests are in `flowscript/std/`. The standard's `from`
  parameter is named `owner`, because `from:` is a call option.
- **Events.** The same parser reads event signatures for sources that decode
  logs: `abiEvent("Swap(bytes32 indexed id, int128 amount0, …)")` in
  `@flowscript/core`, and `abiFunction(sig, structs)` for functions.

## Enums and match

`enum` declares a closed set of words. An unknown variant is a compile error
with the nearest one, and `match` must cover every variant or end in `_`.

```flowscript
uses { bars: "^1" }
enum Regime { hot, quiet, normal }
const close = bars.close("BTC-USD", "1h");
const vol = stddev(change(ln(close)), 24);
const regime = vol > 0.02 ? Regime.hot : (vol < 0.005 ? Regime.quiet : Regime.normal);
metric("regime", regime);
metric("size", match (regime) { hot => 0, quiet => 1, _ => 0.5 });
```

## Phase machines

`phases` declares a state machine. Each `phase` holds the triggers that apply
in it, and a `when` inside one names the phase it moves to. A phase's `let`
bindings start over each time the phase is entered, so `cummax(close)` inside
`Long` is the high since this entry, the entry bar's close included; like any
`let`, one cannot take a `const`'s name. A
phase's `entry { … }` block fires when the machine enters it, right after the
transition's own actions.

```flowscript
uses { bars: "^1", paper: "^1", alerts: "^1" }
const close = bars.close("BTC-USD", "1h");
phases Trade {
  phase Flat {
    when (crossover(close, ema(close, 20))) => Long {
      paper.buy({ symbol: "BTC-USD", quote: 100 });
    }
  }
  phase Long {
    entry { alerts.send("long"); }
    let stop = cummax(close) * 0.95;
    when (close < stop) => Flat { paper.sell({ symbol: "BTC-USD" }); }
  }
}
metric("phase", phase("Trade"));
```

A target that does not exist, a `when` in a phase with no target, and a phase
nothing can reach are compile errors. Every trigger decides against the phases
the bar began in, so a machine moves at most once a bar. An `if` inside a
transition's body fires with the move, when its guard holds then; the machine
moves either way. An `if` inside an `entry` block is a compile error
(`phases.guard`): put the guard on the transition that enters the phase, or in
a `when` inside it.

## Risk limits

An `invariants` block bounds the risk a strategy takes. Each line is a
comparison of something measured against a literal limit, and the block ends
with what a breach does:

```flowscript
uses { bars: "^1", paper: "^1" }
const close = bars.close("BTC-USD", "1h");
when (crossover(close, ema(close, 20))) { paper.buy({ symbol: "BTC-USD", quote: 100 }); }
when (crossunder(close, ema(close, 20))) { paper.sell({ symbol: "BTC-USD" }); }
invariants {
  drawdown() <= pct(5);
  dailyLoss() <= 50;
  trades.perDay() <= 4;
  on_breach: pause;
}
```

- `drawdown()` is the percent fallen from the highest the money put to work
  has been worth: the largest cost basis held, plus everything made or lost.
  The book counted at cost is a peak too, so a gap on the bar after a fill is
  drawdown, and fees count.
- `dailyLoss()` is how far profit has fallen since the UTC day began, in
  quote units. Bars with no time are one day.
- `trades.perDay()` counts the orders sent today. A bound reads it as the
  count the next order would make, so `<= 4` admits four and refuses the
  fifth.
- `position(P).size`, `.entryPrice` and `.pnl` read one market's position.

While a bound is breached, or cannot be read, every entry is refused: a buy
is not placed, and the run records why (`invariant (drawdown: 6.2/5,
on_breach pause)`). A sell is never refused, because a cage that froze a
losing position would be the opposite of one. `on_breach: flatten_and_pause`
also sells every open position at the bar a `drawdown()` or `dailyLoss()`
bound breaks, and at each bar after while it stays broken. `alert` refuses
entries the same way and sells nothing.

A replay, a live run and a test enforce the block on their paper book the
way ftw's host does on its own. A replay lists what the cage refused in
`refused`, and a test expects it with `{ paused: paper.buy, at: 15, by:
drawdown }`. A program can read the same measures itself, in a `metric` or a
condition. Without a paper broker there is no book to measure, and
`unmodelled` says the block is not enforced.

## Tapes

A tape is a source of events (trades, prints, messages) that arrive whenever
they happen, not once a bar. `map` picks a field off each event, `resample` or
`window` buckets the events, and a reducer (`sum`, `mean`, `count`, `first`,
`last`, `distinct`) turns each bucket back into one number.

```flowscript
uses { trades: "^1" }
const prints = trades.prints("BTC-USD");
const buys = map(prints, (p) => p.side == "buy" ? p.size : 0);
metric("buy_volume_1h", sum(resample(buys, "1h")));
metric("prints_15m", count(window(prints, "15m")));
```

Using a tape where a bar series is expected is the `cadence.events` error.

A host may declare a tape field as an enum, `{ "case": { "enum": ["call",
"exit", "note"] } }`: the tag of a sum type. Inside a `map` it reads as an
enum, so `match (e.case) { call => e.usd, exit => -e.usd, note => 0 }` must
cover every word or end in `_`, and `e.case == "cal"` is refused with the
nearest word. An event whose tag is not one of the words is refused when it is
fed to the program.

## The prelude

The prelude is Flowscript source (`prelude/standard.flow`), and its doc
comments are the definitions. In brief:

| Function | |
|---|---|
| `sma(src, len)`, `ema(src, len)`, `ewma(src, len)`, `wma(src, len)`, `rma(src, len)` | moving averages (`ema` is SMA-seeded, as charts draw it; `ewma` seeds on the first close) |
| `stddev(src, len)`, `zscore(src, len)` | dispersion over a window |
| `rsi(src, len)` | Wilder's RSI |
| `atr(src, len)`, `trueRange(h, l, c)`, `wilderAtr(h, l, c, len)` | true range and average true range |
| `vwap(price, vol, len)` | volume-weighted average price over a window |
| `anchoredVwap(price, vol, anchor)`, `anchoredVwapDev(price, vol, anchor)` | the VWAP since the last bar `anchor` held, that bar included (a swing low, a news bar, an entry), and its volume-weighted standard deviation: Pine's `ta.vwap(src, anchor)`. `na` until the anchor has held and traded. `import "std/vwap";` adds week and month anchors and the reads a VWAP trader makes (Libraries) |
| `periodVwap(price, vol, t, secs)`, `periodVwapDev(price, vol, t, secs)` | the session VWAP a chart draws, reset on the first bar of each period (`86400`: from 00:00 UTC), and its volume-weighted standard deviation, so `periodVwap(…) ± 2 * periodVwapDev(…)` are its 2σ bands (Pine's `ta.vwap(src, anchor, stdev_mult)`). `na` until the period has traded. See the starter "VWAP rotation: fade failed pushes to the mean" |
| `corr(a, b, len)`, `cov(a, b, len)` | correlation and covariance over a window; given a list, `cov([a, b, c], len)` is the matrix |
| `beta(y, x, len)` | the hedge ratio: the slope of `y`'s least-squares line on `x` over the window, `ols(y, [x], len)[1]` |
| `roc(src, len)`, `momentum(src, len)` | rate of change, and change over `len` bars |
| `cummax(src)`, `cummin(src)` | high and low since the start (or since a phase was entered) |
| `highest(src, len)`, `lowest(src, len)`, `rolling_sum(src, len)` | the high, low and sum of the last `len` bars (Pine's `ta.highest`, `ta.lowest`, `math.sum`) |
| `cum(src)` | the running total since the start |
| `barssince(cond)`, `valuewhen(cond, src)` | bars since `cond` last held, and `src` at that bar (`na` until it first has) |
| `linreg(src, len)` | the least-squares line's value at this bar over the last `len` bars |
| `stoch(c, h, l, len)` | where `c` sits in the last `len` bars' range, 0 to 100 |
| `pivothigh(src, left, right)`, `pivotlow(src, left, right)` | the value `right` bars back when it is the extreme of the `left + right + 1` bars around it, else `na`; known `right` bars late, as Pine's are |
| `macd(src, fast, slow)`, `macdSignal(src, fast, slow, sig)`, `macdHist(…)` | the MACD line, its signal and the histogram between them |
| `bbUpper(src, len, mult)`, `bbLower(src, len, mult)`, `variance(src, len)` | Bollinger bands around `sma(src, len)`, and the window's variance |
| `vwma(src, vol, len)`, `swma(src)` | volume-weighted and four-bar symmetric averages |
| `wpr(h, l, c, len)`, `cmo(src, len)`, `mfi(src, vol, len)`, `obv(src, vol)`, `tsi(src, short, long)` | Williams %R, Chande momentum, money flow, on-balance volume, true strength |
| `diPlus(h, l, c, len)`, `diMinus(h, l, c, len)`, `adx(h, l, c, len, adxLen)` | Wilder's directional movement |
| `supertrend(h, l, c, factor, len)`, `supertrendDir(…)`, `sar(h, l, c, start, inc, max)` | Supertrend's line and direction (−1 up, 1 down), and the parabolic SAR |
| `hour(t)`, `minute(t)`, `dayofweek(t)`, `dayofmonth(t)`, `month(t)`, `year(t)` | a unix-seconds time's calendar in UTC (`dayofweek` is 1 for Sunday to 7 for Saturday, as Pine's); another zone is a shifted time, `hour(t + 3600*9)` |
| `nyTime(t)`, `chicagoTime(t)`, `londonTime(t)`, `frankfurtTime(t)`, `sydneyTime(t)`, `tokyoTime(t)`, `hongKongTime(t)` | the time on that city's wall clock, daylight saving included, for the calendar above: `hour(nyTime(t))` is New York's hour all year |
| `inSession(lt, start, end)`, `inWeekdaySession(lt, start, end)` | whether a wall-clock time is in [start, end), each HHMM, Pine's session `"0930-1600"`; an end before the start runs past midnight; `inWeekdaySession` keeps to Monday to Friday, Pine's `":23456"` |
| `sessionStarts(active)`, `sessionOpen(o, active)`, `sessionHigh(h, active)`, `sessionLow(l, active)` | a session's first bar, and its open, high and low so far (between sessions, the last one's) |
| `nyseClose(t)` | the New York Stock Exchange's close on `t`'s New York date, HHMM: 1600, 1300 on an early close, 0 on a weekend or a holiday (its rules since 1993, Juneteenth from 2022, and the closures it named, such as 9/11 and Hurricane Sandy) |
| `nyseSession(t)`, `nyseTradingDay(t)`, `nyseHoliday(t)`, `nyseEarlyClose(t)`, `nyseMinutesToClose(t)` | whether the exchange is open at `t` (9:30 to its close), opens that day, is shut on a weekday, closes at 13:00; the minutes to its close (`na` outside the session). The overnight hold: buy when `nyseMinutesToClose(t) <= 15`, sell when `sessionStarts(nyseSession(t))` |
| `barIndex(src)` | the bar's index from 0 |
| `hma(src, len)`, `dema(src, len)`, `tema(src, len)` | the Hull, double and triple exponential averages |
| `cci(src, len)`, `cog(src, len)`, `range(src, len)` | the commodity channel index, the centre of gravity, and the window's high less its low |
| `kcUpper(src, h, l, c, len, mult)`, `kcLower(…)`, `kcw(…)`, `bbw(src, len, mult)` | Keltner channels around `ema(src, len)`, and the Keltner and Bollinger widths as a ratio of the basis |
| `cross(a, b)` | `a` crossed `b` either way this bar |
| `pvt(src, vol)`, `accdist(h, l, c, vol)`, `wad(h, l, c)`, `nvi(src, vol)`, `pvi(src, vol)`, `iii(h, l, c, vol)`, `wvad(o, h, l, c, vol)` | price-volume trend, accumulation/distribution, Williams' A/D, the negative and positive volume indexes, intraday intensity, and Williams' variable A/D |

## Built-in functions

| | |
|---|---|
| Math | `abs`, `min(a, b, …)`, `max(a, b, …)` (`na` if any is), `clamp(x, lo, hi)`, `ln`, `log10`, `exp`, `sqrt`, `pow`, `bps` |
| Rounding | `floor`, `ceil`, `round` (halves away from zero, as Pine's), `sign` (1, −1 or 0) |
| Trigonometry | `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, in radians |
| `na` | `na`, `isNa(x)`, `nz(x, default)` |
| Series | `change(x)`, `rolling_high(x, n)`, `rolling_low(x, n)`, `median(x, n)`, `percentile(x, n, q)` |
| Higher timeframe | `sample(cond, inputs, x => body)`: `body` as if the chart had only the bars `cond` holds on, its answer held between them; `inputs` (a series or a record of them) is read on every bar and is all `body` reads. `newPeriod(t, secs)` and `periodEnds(t, secs)` pick a period's first and last bars, and `periodOpen`, `periodHigh`, `periodLow` and `periodVolume(…, t, secs)` gather its bar |
| Window statistics | `skew(x, n)` and `kurtosis(x, n)` (the biased skewness and excess kurtosis, scipy's defaults), `dev(x, n)` (mean absolute deviation), `percentrank(x, n)` (the percent of the `n` bars before this one at or below it), `highestbars(x, n)` and `lowestbars(x, n)` (how many bars back the extreme is, as 0 or less), `alma(x, n, offset, sigma)` (the Arnaud Legoux average); `n`, `offset` and `sigma` are written in the source |
| Time | `seconds`, `minutes`, `hours`, `every`, `daily`, `during` |
| Triggers | `crossover`, `crossunder`, `rising`, `falling`, `changed`, `once`, `sustained`, `cooldown`, `hysteresis` |
| Tapes | `map`, `resample`, `window`, `sum`, `mean`, `count`, `first`, `last`, `distinct` |
| Lists | `median(xs)`, `mean`, `sum`, `min`, `max`, `count`, `stddev`, `variance`, `mad`, `skew`, `kurtosis`, `percentile(xs, q)`, `wmean(xs, ws)`, `dot(a, b)`, `solve(A, b)`, `inv(A)`, `det(A)`, `transpose(A)`, `ols(y, xs, n)`, `cov(xs, n)`, `corr(xs, n)`; see below |
| Arrays | `buffer(x, n)`, `push(xs, x, n)`, `concat`, `size`, `xs[i]`, `slice(xs, start, end?)`, `reverse`, `sort`, `sortBy(xs, f)`, `unique`, `contains`, `indexOf`, `map(xs, f)`, `filter`, `reduce(xs, seed, f)`, `any`, `all`, `find`, `groupBy(xs, f)`, and the list reducers and `first`, `last`, `count`, `distinct`; see [Arrays](#arrays) |
| Market profile | `tpo.poc`, `tpo.vah`, `tpo.val`, `tpo.vpoc`, `tpo.vvah`, `tpo.vval`, `tpo.vpocShift`, `tpo.high`, `tpo.low`, `tpo.ibHigh`, `tpo.ibLow`, `tpo.poorHigh`, `tpo.poorLow`, `tpo.singleAbove`, `tpo.singleBelow`, `tpo.nakedPocAbove`, `tpo.nakedPocBelow`, each `(high, low, close, volume, t, window: n, …)`; see [Market profile](#market-profile) |
| Trained models | `ml.linear`, `ml.ridge`, `ml.lasso`, `ml.elasticNet`, `ml.logistic`, `ml.svm`, `ml.svr`, `ml.knn`, `ml.boost`, `ml.boostClassifier`, each `(y, [x1, x2, …], window: n, …)`; see [Trained models](#trained-models) |
| Exact integers | `u256` and `i64` checked arithmetic, `u256MulDiv`/`u256MulDivUp`, `u256Units`, `u256Format` and safe number conversions; [details](#exact-integers) |

### Lists, statistics and linear algebra

A list, `[a, b, c]`, is a fixed number of numbers or series: three price
feeds, a portfolio's weights, the factors of a hedge. A list of equal-length
lists is a matrix, row by row. A list has the length it was written with, so
every shape is checked when the program compiles, and nothing about it costs
anything at run time that its items do not (D1524).

```flowscript
uses { bars: "^1" }
// The median of three readings, skipping one that has no price this bar.
const feeds = [bars.open("BTC-USD", "1h"), bars.close("BTC-USD", "1h"), bars.high("BTC-USD", "1h")];
metric("mid", median(feeds));
metric("spread", max(feeds) - min(feeds));
// Arithmetic on a list applies to each item.
const scaled = feeds / feeds[1] - 1;
metric("open_vs_close", scaled[0]);
```

Across assets, the same tools hedge and size a book:

```text
uses { bars: "^1" }
const btc = bars.close("BTC-USD", "1h");
const eth = bars.close("ETH-USD", "1h");
const sol = bars.close("SOL-USD", "1h");
const returns = [btc, eth, sol] / [btc[1], eth[1], sol[1]] - 1;

// SOL hedged with BTC and ETH: a rolling least-squares fit over 200 bars,
// [intercept, b_btc, b_eth], and the residual the hedge leaves.
const fit = ols(returns[2], [returns[0], returns[1]], 200);
const residual = returns[2] - dot(fit, [1, returns[0], returns[1]]);
metric("sol_beta_btc", fit[1]);
metric("residual_z", (residual - sma(residual, 50)) / stddev(residual, 50));

// Minimum-variance weights: solve Σ·w = 1, then scale them to sum to 1.
const w = solve(cov(returns, 200), [1, 1, 1]);
const weights = w / sum(w);
metric("w_btc", weights[0]);
```

- **Reducers** take one list and answer one number from its decided items:
  `median`, `mean`, `sum`, `min`, `max`, `count`, `stddev` and `variance`
  (dividing by `n`, as the windowed `stddev` does), `mad` (the median absolute
  deviation), `skew`, `kurtosis` (excess) and `percentile(xs, q)` with `q`
  from 0 to 1. An `na` item is skipped, so a feed that has no price this bar
  does not blank the median of the others; the answer is `na` only when no
  item is decided. The conventions are numpy's and scipy's defaults: an even
  `median` averages the middle two, and `percentile` interpolates between the
  two nearest ranks. (The windowed `median(x, n)` and `percentile(x, n, q)`
  pick the nearest rank, as they always have.)
- **Arithmetic** `+ - * /` and unary `-` apply item by item: two lists of the
  same length pair up, and a number or series on one side applies to every
  item, as numpy broadcasts. A comparison does not take a list: reduce it
  first, `max(xs) > 100`.
- **Items**: `xs[0]` is the first item and `xs[-1]` the last, an index
  written in the source; on a matrix, `A[0]` is the first row. On a list,
  `[k]` is an item, never a bar back: `feeds[1]` is the close, and
  `btc[1]` is BTC an hour ago.
- **Linear algebra** at each bar: `dot(a, b)` is numpy's (a number for two
  vectors, a vector for a matrix and a vector, a matrix for two matrices),
  `wmean(xs, weights)` the weighted mean, `solve(A, b)` the vector `x` with
  `A·x = b`, `inv(A)`, `det(A)` and `transpose(A)`. A singular matrix makes
  `solve` and `inv` `na` rather than an answer made of rounding error.
- **Rolling** over the last `n` bars at which every series is decided:
  `ols(y, xs, n)` is the least-squares fit of `y` on a constant and the list
  `xs`, `[intercept, b1, …]` (Householder QR, so a nearly collinear pair does
  not lose its digits as the normal equations would); `cov(xs, n)` and
  `corr(xs, n)` are the covariance and correlation matrices. Each is `na`
  until its window fills, and `ols` is `na` while a factor does not move.
  OLS normalizes each column and the target by an exact power of two before
  fitting, so very large or small units do not overflow the QR norms or
  turn a varying factor into a constant. Coefficients are returned in the
  original units. A rank-deficient fit, a nonfinite coefficient, or a fit
  whose normalization would lose an input's precision remains `na`.
- A list is not a value to publish: `metric("w", weights)` is an error that
  asks for an item or a reduction. A `fn` takes and returns a list like any
  other value.

Every evaluator answers these with one Rust implementation
(`flowscript/src/stats.rs`), in plain IEEE arithmetic, so a backtest, a live
run and a chart study agree to the bit. Generated list and matrix IR is reserved
against the compiler's existing size and lowering quotas before eager copying;
oversized expansions are located compilation refusals. The live evaluator charges matrix
elimination and rolling regression work before execution against its watermark
evaluation budget, including computations whose result would be unavailable.

### Arrays

An array is a value a run gathers as it goes, as long as its data makes it:
the last hundred trades a source heard, the wallets among them that bought,
the book grouped by pool (D1544). A [list](#lists-statistics-and-linear-algebra)
has the length it was written with and costs nothing at run time; an array
is held by the run, so it can be built from a stream, filtered and sorted.

```flowscript
uses { bars: "^1" }
const close = bars.close("BTC-USD", "1h");
const volume = bars.volume("BTC-USD", "1h");
// The last 48 hourly bars, oldest first, each a record.
const bars48 = buffer({ close: close, volume: volume }, 48);
// The bars that traded more than usual, and the five busiest of them.
const usual = mean(map(bars48, (b) => b.volume));
const busy = filter(bars48, (b) => b.volume > usual * 1.5);
const busiest = slice(sortBy(bars48, (b) => -b.volume), 0, 5);
metric("busy_bars", size(busy));
metric("busiest_close", busiest[0].close);
metric("median_close", median(map(bars48, (b) => b.close)));
// What a fold keeps can be an array too: every close above 100, the newest 20.
const highs = fold(close, [], (xs, c) => c > 100 ? push(xs, c, 20) : xs);
metric("highs", size(highs));
```

- **Building one.** `buffer(x, n)` is the last `n` samples of `x`, oldest
  first: a series, or a record such as a source's `input.event()`. A sample
  that is `na` is not kept, and `buffer` steps when its input ticks, as a
  window does. Inside a `fold`, an array seed (`[]`) holds what the step puts
  in it: `push(xs, x, n)` is `xs` with `x` after its last item, keeping the
  newest `n` (an `na` `x` is not added). `concat(a, b)` is `a`'s items then
  `b`'s. A list written in the source, `[a, b, c]`, is an array wherever a
  function takes one.
- **Reading one.** `size(xs)` is how many items it holds; `xs[i]` is an item,
  from 0, with −1 the last, and `na` past either end (the index may be any
  number the run computes). `first(xs)` and `last(xs)` are the ends.
  `slice(xs, start, end?)` is the items from `start` up to `end`, −1 counting
  from the last, so `slice(xs, -10)` is the last ten. `contains(xs, v)` and
  `indexOf(xs, v)` (`na` when it is not there) look for an item.
- **Functions of its items.** `map(xs, x => …)`, `filter(xs, x => cond)`,
  `reduce(xs, seed, (acc, x) => next)`, `any`, `all`, `find` (the first item
  the condition holds for, or `na`), `sortBy(xs, x => key)` (lowest key first,
  stable, `na` last; `-x.usd` for the largest first) and `groupBy(xs, x =>
  key)`, which is `{ key, items }` for each key in the order it first appears
  (an item whose key is `na` is in none). `sort(xs)` orders numbers or text,
  `reverse(xs)` turns it round, and `unique(xs)` keeps each different item
  once.
- **Reducing one.** An array of numbers takes the list reducers, `sum`,
  `mean`, `median`, `min`, `max`, `stddev`, `variance`, `mad`, `skew`,
  `kurtosis` and `percentile(xs, q)`, skipping `na` items as a list's do;
  the sum of no numbers is 0. `count(xs)` is the items that are not `na`, and
  `distinct(xs)` how many different values it holds. Reduce an array of
  records by mapping it first: `sum(map(xs, x => x.usd))`.
- **A list of markets reads each of them** (D1545). A read keyed by a list
  written in the source, `aerodrome.rewardApr(pools, interval)` with `const
  pools = ["base:a", "base:b"]`, is the list of the reads, one per market in
  the list's order: `apr[1]` is the second's, `max(apr)` the best, and the
  artifact names every series read. The keys are literals, as any read's key
  is; a list of anything else is refused (`identity.key`).
- **`map` over a list runs its function at compile time**, once per item,
  with the item itself bound to the parameter, so, unlike an array's `map`,
  its body may window and read: `map(price, (p, i) => stddev(change(p) /
  p[1], 24))` is a list of one volatility per market, and the second
  parameter is the item's position from 0. The answer is a list, which is an
  array wherever a function takes one: `sortBy(map(pools, (p, i) => ({ pool:
  p, apr: apr[i] })), (s) => -s.apr)` ranks the markets.
- **A function given to an array runs once for each item**, so it keeps no
  state and reads no feed of its own (`array.lambda`): `filter(xs, x => x >
  ema(close, 20))` is refused. What it reads from outside is computed once,
  before it, and the function reads that value, so bind it to a `const` and
  read the const: `const level = ema(close, 20); filter(xs, x => x > level)`.
- An array is not a number: arithmetic and comparisons refuse one, and so
  does `metric`. Publish one of its items or a reduction of it. An action
  argument its capability declares `Json` takes an array, so a source can
  publish one as a field (below).
- **Bounds.** An array holds at most 10,000 items: `buffer` and `push` keep
  at most that many, written in the source, and a `concat` that would hold
  more is `na`. Every item an operator touches, and a sort's `n log n`, is
  charged to the watermark's evaluation budget before the work, and an array
  a run keeps counts toward its retained state. A program that would walk
  or keep more than a run may is stopped with a refusal at that watermark,
  rather than slowing every run beside it.

In a source, each event is one step, so `buffer(input.event(), 200)` is the
last 200 events and every function above works on them. A field declared
`json` publishes an array:

```text
uses { input: "^1", source: "^1" }
const e = input.event();
const recent = buffer(e, 200);
const byPool = groupBy(recent, (s) => s.pool);
const flows = map(byPool, (g) => ({ pool: g.key, usd: sum(map(g.items, (s) => s.usd)) }));
const top = slice(sortBy(flows, (f) => -f.usd), 0, 5);
while (size(recent) == 200) { source.emit({ pool: e.pool, top: top }); }
```

**A tape's array field.** A host may declare a tape's field an array, of
numbers, text, words or records (`{ "array": { "record": { "pool": "text",
"usd": "number" } } }`, as a ftw source declares `[{ pool: "pool", usd:
"number" }]`), and a program reads it as one. `buffer(tape, n)` keeps a
tape's last `n` events across watermarks as an array of records, newest
last, so the newest event's array is `flows[-1].top`; inside a tape's `map`,
an array function over the event's own field (`size(e.top)`) is one value
per event, which its buckets reduce. An array field left out is empty.

```text
const flows = buffer(sources.top_pools(), 10);
const top = size(flows) > 0 ? flows[-1].top : [];
metric("usd", sum(map(top, (f) => f.usd)));
```

**On a chart.** A study may keep an array too, as long as each line it draws
is a number: `metric("up", size(filter(buffer(price, 20), (x) => x > open)))`.
The compiled plan holds no arrays, so such a study is replayed bar by bar by
the same evaluator a strategy runs on, and draws what that run computes.

### Trained models

A strategy can train a regression or a classifier on its own series and use
its prediction at every bar, in a backtest and live alike (D1561). A model
is written `ml.<kind>(y, [x1, x2, …], window: n, …)`: the target `y`, a list
of predictors, and named settings.

```flowscript
uses { bars: "^1", paper: "^1" }
const close = bars.close("BTC-USD", "1h");
const volume = bars.volume("BTC-USD", "1h");
// The return over the last 6 hours: the target, known at each bar.
const ret6 = close / close[6] - 1;
// What the model sees at each bar.
const features = [
  close / close[1] - 1,
  close / ema(close, 24) - 1,
  volume / sma(volume, 24) - 1,
  rsi(close, 14) / 100 - 0.5,
];
// Learn the next 6 hours' return from the last 500 hours, refitted every
// 24 hours and whenever volume spikes.
const forecast = ml.ridge(ret6, features, window: 500, horizon: 6, retrain: 24,
                          retrainOn: volume > sma(volume, 24) * 3, alpha: 0.5);
// The chance the next 6 hours close higher.
const up = ml.logistic(ret6, features, window: 500, horizon: 6, retrain: 24);
metric("forecast", forecast);
metric("p_up", up);
when (forecast > 0.004 && up > 0.6) { paper.buy({ symbol: "BTC-USD", quote: 100 }); }
when (forecast < 0) { paper.sell({ symbol: "BTC-USD" }); }
```

- **How it trains.** At every bar at which `y` and every predictor are
  decided, the model keeps a row of them, the last `window + horizon` rows.
  A training example pairs one row's predictors with `y` from `horizon` rows
  later, so the model learns what `y` will be `horizon` bars after what it
  sees, and never trains on a target that is in the future of the bar it
  answers at. `horizon` is 1 when omitted; `horizon: 0` fits `y` to the
  predictors of the same bar, as `ols` does.
- **When it retrains.** The model is fitted when its rows first fill, again
  every `retrain` new rows (1 when omitted, so every bar), and again at any
  row where `retrainOn` is true. `retrain: 0` fits once and keeps that model,
  unless `retrainOn` asks for another. Between fits it keeps its parameters,
  which are part of the run's state: a resumed run continues with the same
  model. A fit that the rows do not determine (one class only for a
  classifier, a predictor that does not move for `ml.linear`) keeps the model
  it had.
- **What it answers.** At each new row, the model's prediction from that
  row's predictors; at a bar with no new row it holds its last answer. A
  regression predicts `y`; `ml.logistic` and `ml.boostClassifier` answer the
  probability that `y` is above zero; `ml.svm` answers its signed margin, above zero for "`y` above
  zero". `na` until the first fit.
- **Predictors are standardised** over each fit's examples (centred and
  divided by their standard deviation) and a prediction standardises its row
  with the same numbers, so a penalty treats every predictor alike whatever
  its units. A predictor constant over the window is left out of that fit.
  Bounded, power-of-two moment calculations preserve changing predictors
  even in very small or large units; only exactly constant predictors are
  omitted. A nonconstant spread that cannot be represented refuses the fit,
  and a prediction with a nonfinite standardized input is `na`.
  `window`, `horizon`, `retrain` and every setting are numbers written in the
  source (or `const`s), since they set the model's state and work.

| Model | Settings (default) | What it is |
|---|---|---|
| `ml.linear` | | Ordinary least squares on a constant and the predictors |
| `ml.ridge` | `alpha` (0.1) | Least squares with an L2 penalty, `(1/2n)·‖y − Xw‖² + (alpha/2)·‖w‖²`, on a standardised target |
| `ml.lasso` | `alpha` (0.01) | An L1 penalty, `alpha·‖w‖₁`, which drops predictors: one whose correlation with the target is below about `alpha` gets no weight |
| `ml.elasticNet` | `alpha` (0.01), `l1Ratio` (0.5) | The two penalties mixed, `alpha·(l1Ratio·‖w‖₁ + ((1 − l1Ratio)/2)·‖w‖²)` |
| `ml.logistic` | `C` (1) | L2-regularised logistic regression on "`y` above zero", `C·Σ logloss + ½‖w‖²` (scikit-learn's) |
| `ml.svm` | `C` (1), `kernel` (`"linear"`), `gamma` | A support-vector classifier on "`y` above zero"; `kernel: "rbf"` with `gamma` (1 / the number of predictors when omitted) for a curved boundary |
| `ml.svr` | `C` (1), `epsilon` (0.1), `kernel`, `gamma` | Support-vector regression, `epsilon` in standard deviations of the target |
| `ml.knn` | `k` (5) | The mean target of the `k` training examples nearest the row |
| `ml.boost` | `trees` (100), `depth` (3), `learningRate` (0.1), `minLeaf` (20) | Gradient-boosted regression trees on the squared error of a standardised target: `trees` trees of `depth` levels, each fitted to what the trees before it missed and added at `learningRate`, every leaf holding at least `minLeaf` examples. Trees find thresholds and interactions (a feature that matters only in a trend, a reversal past an extreme) that a linear model cannot |
| `ml.boostClassifier` | as `ml.boost` | Gradient-boosted trees on the log loss of "`y` above zero": the probability that `y` is above zero |

Every evaluator fits with one Rust implementation (`flowscript/src/ml.rs`),
in plain IEEE arithmetic with no randomness: least squares by Householder
QR, ridge by its normal equations, lasso and elastic net by coordinate
descent, logistic regression by Newton's method, and support-vector models by
dual coordinate descent (LIBLINEAR's), boosted trees by second-order
gradient boosting over 32 quantile split points per predictor (XGBoost's
leaves with λ = 1), each stopping at a fixed tolerance or
iteration cap. So a backtest, the optimizer and a live run fit the same
model to the bit. A fit's work is charged against the bar's evaluation
budget before it starts, and a model whose fit could exceed it is refused at
compile time: reduce `window`, the predictors, or a boosted model's `trees`
or `depth`. An RBF model or `ml.knn`
keeps its training rows, so its `window` is at most 1,000. Refitting every
bar is the default and is cheap for `ml.linear` and `ml.ridge`; for the
iterative models and boosted trees, a `retrain` cadence keeps backtests
fast. `window` must hold at least two `minLeaf`s of examples.

### Market profile

A market profile (TPO, time price opportunity) counts the time price spent
at each level: every bar puts one block in each price row its range touched.
`tpo.<level>(high, low, close, volume, t, window: n, …)` reads a level of the
profile of the last whole session (or, with `previous: false`, of the
session still forming) from the last `n` bars, in a backtest and live alike.
The blocks are the bars the program runs on, so the interval sets the
resolution: 30-minute bars for a daily profile and 4-hour bars for a weekly
one are the conventions. The chart's TPO study draws the same profiles.

```flowscript
uses { bars: "^1", paper: "^1" }
const high = bars.high("BTC-USD", "1h");
const low = bars.low("BTC-USD", "1h");
const close = bars.close("BTC-USD", "1h");
const volume = bars.volume("BTC-USD", "1h");
const t = bars.time("BTC-USD", "1h");
// Yesterday's profile, from the last two days of hourly bars.
const poc = tpo.poc(high, low, close, volume, t, window: 48);
const poorLow = tpo.poorLow(high, low, close, volume, t, window: 48);
// Volume sat below where the time was spent: sellers did the business.
const shift = tpo.vpocShift(high, low, close, volume, t, window: 48);
metric("poc", poc);
metric("shift", shift);
// Buy back into value over a poor low left yesterday, target its POC.
when (poorLow == 1 && crossover(close, tpo.low(high, low, close, volume, t, window: 48))) {
  paper.buy({ symbol: "BTC-USD", quote: 100 });
}
when (close >= poc) { paper.sell({ symbol: "BTC-USD" }); }
```

The series are the bars' high, low, close, volume and start time `t` (unix
seconds). The levels:

| Level | |
|---|---|
| `poc` | the time point of control: the middle of the row with the most blocks (a tie goes to the row nearest the middle of the range) |
| `vah`, `val` | the value area's top and bottom: grown from the POC two rows at a time toward the heavier pair until it holds `valueArea` of the blocks |
| `vpoc`, `vvah`, `vval` | the same over volume, each bar's spread evenly over the rows it touched |
| `vpocShift` | `vpoc − poc`: positive when the volume sat above where the time was spent |
| `high`, `low` | the session's range |
| `ibHigh`, `ibLow` | the initial balance: the first two bars' range |
| `poorHigh`, `poorLow` | 1 when the extreme row has two or more blocks (no single-print tail: an unfinished auction, which price tends to revisit), else 0 |
| `singleAbove`, `singleBelow` | the nearest single print (a one-block row inside a profile, not its tail) above or below the close that no later bar has traded through, over every whole session in the window |
| `nakedPocAbove`, `nakedPocBelow` | the nearest session POC above or below the close that no later bar has traded at |

Settings, each a literal or a `const`:

- `window: n` (required): the bars kept. A session is read only once it is
  whole in the window, so keep at least two sessions of bars (96 on 30m for
  a daily profile); more widens the search for single prints and naked POCs.
- `session`: `"day"` (UTC, the default), `"week"` (from Monday 00:00 UTC),
  `"window"` (the whole window as one profile), or a length in seconds;
  `offset` shifts where a numbered session starts.
- `previous`: `true` (the default) for the last whole session, `false` for
  the one still forming.
- `row`: the row height in price; 0 (the default) picks a round number near
  a 36th of the median session's range. At most 2000 rows a profile.
- `valueArea`: the value area's share, 0.7 by default.

A level not there to read (no session whole yet, no single print above,
a session with no volume) is `na`.

### Exact integers

Ordinary numbers use IEEE 754 binary64. Consecutive integers are safe only
through 9,007,199,254,740,991 (2^53 − 1). In an 18-decimal token that is about
**0.009 tokens**, so balances and contract base units must use exact integers.

Flowscript 0.3 provides checked `u256` (0 through 2^256 − 1) and `i64`
(−2^63 through 2^63 − 1, a signed `long`) functions. Their integer results
are canonical **decimal text**, preserving every digit through action arguments,
JSON, saved state and replay. They are a math library over text, not new
operator-overloaded types: use `u256Add`/`i64Add` and `u256Cmp`/`i64Cmp`.
Ordinary `+` on text concatenates; ordinary text ordering is lexical.

```flowscript
flowscript "0.3";
import "std/math";
const budget = parseUnits("1.000000000000000001", 18);
const minimum = basisPoints(budget, 9970);
metric("minimum", formatUnits(minimum, 18));
metric("signed", i64Add(long("-9223372036854775808"), 1));
metric("aboveHalf", u256Cmp(minimum, parseUnits("0.5", 18)) > 0);
```

- **Inputs.** Exact integers accept decimal text; unsigned integers also accept
  `0x` hexadecimal text. Use quoted text or exact source fields for large
  values. In 0.3 integer arguments supplied as numbers must be finite safe
  integers. A literal beyond that range is refused at compile time; an
  unavailable or invalid dynamic operand produces `na`.
  All numeric literals and expressions are floats before this check; it
  validates the represented value, not the original decimal spelling. Even
  a fractional literal can round to an integer first. Text is required when
  every input decimal digit matters.
- **Unsigned arithmetic.** `u256Add`, `u256Sub`, `u256Mul`, `u256Div`,
  `u256Mod`, `u256Min`, `u256Max` and `u256Cmp` are exact and checked.
  Division rounds down. `u256DivUp(a, b)` rounds up.
- **Full precision products.** `u256MulDiv(a, b, denominator)` computes the
  complete 512-bit product before dividing, rounding down. `u256MulDivUp`
  rounds up. An intermediate product beyond uint256 is valid when the final
  answer fits. Division by zero or a final answer beyond uint256 is `na`.
- **Signed long arithmetic.** `i64Add`, `i64Sub`, `i64Mul`, `i64Div`,
  `i64Mod`, `i64Neg`, `i64Abs`, `i64Min`, `i64Max` and `i64Cmp` are checked.
  Signed division truncates toward zero; the remainder has the dividend's
  sign. `i64Div("-9223372036854775808", -1)` overflows; its mathematical
  remainder is `"0"`. Negating or taking the absolute value of that minimum
  also overflows. No operation wraps or saturates.
- **Units and formatting.** `u256Units(amount, decimals)` converts an unsigned
  decimal amount to base units without rounding. `u256Format(value, decimals)`
  produces exact whole-token decimal text, trimming trailing fractional zeros.
  Decimal places are whole numbers from 0 to 77. Excess nonzero fractional
  digits refuse; scientific notation in text refuses. A numeric amount uses
  its shortest decimal representation and cannot restore digits already lost
  in floating-point calculations. Use text for exact input.
- **Display conversions.** `u256Number(value, decimals?)` and `i64Number(value)`
  explicitly round to a float for charts. Never route that result back into
  a monetary amount. `u256SafeNumber(value)` and `i64SafeNumber(value)` instead
  return `na` outside the safe integer range.
- **Failure.** Invalid operands, overflow and division by zero produce `na`.
  An action with an `na` argument refuses before signing. No value is silently
  replaced with zero.

`import "std/math";` adds `uint256`, `long`, `parseUnits`, `formatUnits`,
`mulDiv`, `mulDivUp`, `basisPoints` and `basisPointsUp`. Basis-point functions
divide the full product by 10,000; the `Up` form rounds up. `std/erc20`'s
older `tokenUnits` helper uses ordinary floating-point math; use `parseUnits`
for exact amounts.

Programs explicitly saved as 0.1 or 0.2 keep their earlier `u256` numeric
operand semantics and function names. New exact helpers require 0.3, and
0.3 artifacts record distinct exact operations, so a saved historical artifact
is not silently reinterpreted with the stricter input policy.

The compiler publishes its own list: `flowscript_core::vocabulary()` returns
the built-ins, the prelude source and the diagnostic registry, which is what an
editor or a code-writing model should read rather than a copy.

## Diagnostics

Every compile error has a stable code (`FS0412`), a slug (`record.field`), a
message, and a position. A code never changes meaning and is never reused, so
tooling matches on it rather than on the message. The registry is
`flowscript_core::diagnostic_codes()`.

```flowscript error
uses { bars: "^1" }
const close = bars.clsoe("BTC-USD", "1h");
```

That is `stream.unknown`: "did you mean `bars.close`?".

### Warnings

Some programs compile and then do something other than what they seem to
say. `flowscript_core::warnings_in(source, &host)` (`program.warnings` in
`@flowscript/core`) lists them, each located and coded like an error, and the
program still compiles: the author may mean it.

| Code | Slug | What it finds |
|---|---|---|
| `FS0901` | `lint.never` | a condition that is never true: `x > highest(x, n)` or `x < lowest(x, n)` (this bar is in the window), or one written of literals that is false |
| `FS0902` | `lint.repeat` | a `while` that buys or opens a position with no position guard, so it sends the order at every bar its condition holds |
| `FS0903` | `lint.unused` | a `const` nothing reads (name it `_x` to keep it) |
| `FS0904` | `lint.na` | a divide or remainder by a literal 0, which is `na` at every bar |
| `FS0905` | `lint.unit` | `bps(n)` under arithmetic or a comparison, where it is the number `n`, not the rate `n / 10000` |

```flowscript warning
uses { bars: "^1", paper: "^1" }
const close = bars.close("BTC-USD", "1h");
when (close > highest(close, 20)) { paper.buy({ symbol: "BTC-USD", quote: 100 }); }
```

That is `lint.never`, at `close > highest(close, 20)`: compare with
`highest(close, 20)[1]`.

A replay says the rest: its `quiet` lists each `when` or `while` with actions
that fired at no bar, with how its condition decided (`na` at every bar,
never true, or true and held back by a cooldown, guard or phase). A
strategy that never trades says why instead of returning no orders.

## Common pitfalls

Each of these compiles, and each does something other than what it seems to
say. They matter most in a strategy that trades.

- **`while` repeats** (`FS0902`). `while (rsi(close, 14) < 30) { paper.buy(…) }` buys at
  every bar of a long dip. Entries belong in a `when`, which fires once per
  crossing; keep `while` for an action meant to repeat, with a guard that
  turns false once it has done its job.
- **`when` fires again on every new crossing.** An entry that can turn true
  twice before its exit adds to the position each time. Gate it on
  `!inPosition()` where the host keeps a book, or cap entries in the broker
  (`pyramiding`).
- **A window includes its own bar** (`FS0901`). `close > highest(close, 20)` is never
  true, since this bar's close is in the window. Compare with the window as
  of the bar before: `highest(close, 20)[1]`.
- **`na` is not false.** `!(close > avg)` is `na`, not true, while `avg` warms
  up, so a `when` on it waits. Write the condition you mean (`close < avg`),
  and use `nz` or `isNa` where a missing value should count as something.
- **A fold that does not test for `na` stays `na`.** `fold` carries its state
  from bar to bar, so one missing sample makes the state `na` for the rest of
  the run unless the step leaves the state as it was (`isNa(x) ? st : …`). The
  prelude's indicators all do this.
- **Some windows are partial at first, some `na`.** `sma`, `stddev` and the
  other averaging windows average what they have until the window fills,
  while `highest`, `lowest` (`rolling_high`, `rolling_low`), `median` and
  `percentile` are `na` until it fills, as `ema`, `rsi` and `atr` are until
  they warm up. Gate on `barIndex(close) >= n` where the first bars must not
  trade, and `nz` or scale what a window has (`cummax(x) - cummin(x)` is the
  range since the start) where they must.
- **Time needs the bar's time.** `every`, `cooldown`, `daily` and `during`
  count in the time each bar carries (`time` in a replay's history, the
  `time` of `step`). Without one a bar's time is its number, so
  `every("1d")` fires once and `cooldown(hours(1))` waits 3600 bars.
  Run times must be nondecreasing whole seconds from 0 through
  9,007,199,254,740,991, the largest consecutively exact integer the numeric
  representation supports. Closed and forming bars refuse an invalid time
  before changing state.
- **A watermark has one input budget.** All its sources together may supply
  at most 1,000,000 values and 64 MiB of logical allocation charges: 64 bytes
  per value and record entry, plus text/key bytes. Text and keys are limited
  to 4,096 UTF-8 bytes, nesting to 128 levels. Source keys are billed by their
  canonical stream/key identity, including when restored. Internally generated
  clock, position, phase and lifecycle views have a separate allowance of the
  same size, so they cannot make an admitted external observation impossible
  to restore. These admission budgets also apply alongside retained state and
  evaluation-work limits.
- **A run has one retained-state allowance.** Folds, history, held reads,
  private caches, shared live state, the last input view and paper-book state
  share 256 MiB of logical charges. Each value and map/cell entry costs 64
  bytes plus text and key bytes, even when allocations are shared. Shared
  handles and reservation entries also pay for their metadata, so total limit
  boundaries can differ by that overhead from a private materialization.
  Retained values may nest at most 32 levels. A resource fault after evaluation begins
  stops the run; recover explicitly from the last successful checkpoint.
  Optional shared memo/version/index caches have a separate 64 MiB allowance
  per shared runtime. Pressure can discard optional cache entries; it never
  discards a live fold or changes a decision.
- **Checkpointing can refuse.** Encoded checkpoints are bounded to 128 MiB
  while writing. Rust `Run::snapshot()` returns `Result`; npm returns
  `{ ok, snapshot }` or `{ ok: false, error }`. Hosts must handle refusal
  before replacing a durable checkpoint. Restore checks encoded and expanded
  input limits and rebuilds live accounting from the actual values.
- **An order is sized by a literal.** A paper broker sizes from a number (or
  a constant or `param` bound to one) and refuses a program with an order
  sized by anything computed before its first bar. Size by equity with the
  host's percent order where it has one, and sell a share of a position
  with its percent-of-position sell (a `{ position: "pct" }` size).

```flowscript
uses { bars: "^1", paper: "^1" }
const close = bars.close("BTC-USD", "1h");
const top = highest(close, 20)[1];
const n = fold(close, 0, (st, x) => isNa(x) ? st : (x > top ? st + 1 : st));
metric("breakouts", n);
when (barIndex(close) >= 20 && close > top && !inPosition()) {
  paper.buy({ symbol: "BTC-USD", quote: 100 });
}
when (close < sma(close, 20)) { paper.sell({ symbol: "BTC-USD" }); }
```

## Testing a program

A test feeds a program sources you write and says what it should do with
them. The same runner is in `flowscript-core` (`testing::run`),
`@flowscript/core` (`flowscript.test(source, suite, host)`) and ftw's CLI
(`flowscript test program.flow program.test.yaml`). A check is compiled into
the program as one more metric and replayed by the evaluator a backtest uses,
so a passing test says what the real run does. `flowscript.suite(text)` reads
a suite's text into the object `test` takes, or says why it is not one, for an
editor that keeps the cases rather than the text.

A suite is JSON or YAML: an optional `program` (the source every case runs,
when none is given beside it), an optional `paper` broker, and `tests`. Here
is one for the strategy in [A first program](#a-first-program):

```yaml
paper:
  cash: 1000
  fee_bps: 10
  orders:
    paper.buy: { side: buy, price: bars.close, size: { quote: quote } }
    paper.sell: { side: sell, price: bars.close, size: all }
tests:
  - name: buys the rally, sells the fall
    bars: 60
    ohlc: { steps: [[0, 100], [20, 120], [40, 90]] }
    paper: true
    expect:
      - { check: "fast > slow", at: 21 }
      - { fires: paper.buy, at: 20, args: { quote: 100 } }
      - { fills: paper.sell, at: 40 }
      - { check: "close > 0", at: always }
      - { warns: none }
  - name: a flat market never trades
    sources: { bars.close: { constant: 100 } }
    expect:
      - { fires: paper.buy, count: 0 }
      - { metric: fast, at: last, equals: 100 }
```

**A case** has a `name`, the `sources` it feeds and what it `expect`s. Bars are
counted from 0. `bars` is how many (the longest written-out source, or 100).
The replay limit of 1,000,000 bars is checked before generated sources allocate.
`time` is a bar's length in seconds or a list of closes, for `every` and
`cooldown`. `paper` is a broker's terms, or `true` for the suite's (or the
host's). `program` gives a case its own source: a library's tests are cases
whose programs import it.

`runs: 50` runs a case 50 times, each `walk` with the next seed, so an
expectation is held over many random markets rather than one, as a property
test is (D1257). It passes only when every run does, and a failure names its
run: `run 17 of 50: \`exposure <= 0.2\` is false at bar 31`. `runs` must be
from 1 to 200. Bar times must fit whole unsigned 64-bit seconds; a generated
time that would overflow is refused.

```yaml
  - name: never more than a fifth of equity in, over any market
    bars: 200
    runs: 50
    ohlc: { walk: { from: 100, step: 2 } }
    paper: true
    expect:
      - { check: "exposure <= 0.2", at: always }
```

**A source** is named as the program reads it (`bars.close`, or
`bars.close|BTC-USD` for one key of it) and is:

| Written | Feeds |
|---|---|
| `[100, 101, null, 103]` | numbers; `null` is `na`; a short list holds its last value |
| `[true, false]`, `["hot", "cold"]` | a bool or text series |
| `[{ a: 1, b: "x" }, …]` | a record, one per bar |
| `[[3, { price: 10, size: 2 }], …]` | a tape: each event at its bar |
| `{ constant: 100 }` | the same number at every bar |
| `{ ramp: [100, 120] }` | a straight line from the first bar to the last |
| `{ sine: { mid: 100, amp: 5, period: 20, phase: 0 } }` | a wave |
| `{ steps: [[0, 100], [20, 120]] }` | each value from its bar on |
| `{ walk: { from: 100, step: 1, seed: 7 } }` | a random walk; a seed walks one path everywhere |

Every record row must supply the same fields. Use an explicit `null` for a
numeric field that is `na`; leaving a field out is refused, so a later
observation cannot shift into an earlier bar.

Any generator takes `na: [bar, …]` to blank those bars. `ohlc: <a close
series>` feeds `bars.close` and derives `bars.open` (the close before),
`bars.high`, `bars.low` and `bars.volume` (1000) from it; `ohlc: { source:
pool, close: … }` does the same for another source's bars. A read the host
adds for an action and the program never names (an order's live price, its
pool) is fed `na` when a case leaves it out, and the report lists it under
`unfed`. A read the program names is the case's to give.

**An expectation** is one of:

| Written | Holds when |
|---|---|
| `{ check: "<condition>", at: 12 }` | the condition is true at bar 12 |
| `{ check: …, at: ever \| always \| never \| last }` | at some bar; at every bar it is decided, and at least one; at none; at the last (`ever` without `at`). `from` and `to` bound the bars |
| `{ metric: fast, at: 12, equals: 101.5, within: 0.01 }` | a metric's value (within 1e-9 relative unless `within`); `at: last` |
| `{ metric: fast, at: 3, na: true }` | a metric is `na` there |
| `{ fires: paper.buy, at: 20, count: 1, args: { quote: 100 } }` | an action (`paper.buy`, `buy`, or its site) fired: at a bar, that many times (`count: 0` is never), with those arguments. A contract call's arguments are compared as they were at the bar it fired, `{ amount: 250000000 }` for `tokenUnits(250, 6)`; a record or list is compared field by field |
| `{ fills: paper.buy, at: 20, count: 1 }`, `{ reverts: … }` | the paper broker filled, or reverted, that action's orders |
| `{ paused: paper.buy, at: 15, by: drawdown }` | the invariant cage refused that action's entry, by that invariant when `by` is given; `count: 0` is never |
| `{ refuses: FS0103, line: 3 }` | the program is refused with that code or slug, on that line |
| `{ warns: FS0901 }`, `{ warns: none }` | the compiler warns with that code or slug; or not at all |

A check reads the program's `const`s and sources, not its metric names. Every
case but a `refuses` one must compile. Checks must produce numeric or boolean
values. Their `from` and `to` range must lie within the replay, with `from` at
or before `to`; an empty range cannot make a `never` check pass. A metric
expectation supplies exactly one of `equals` or `na: true`. `within` is an
absolute, finite tolerance at or above zero and requires `equals`.

**The report** gives each case's `failures`, each saying what happened
instead (`` `paper.buy` fired 0 times, not 1 ``, `` `fast > slow` is false
at bar 21 ``), or why the case could not run (`expect: null`). The CLI exits
1 when one fails.

A `fires … at` that fails also says what the action's `when` read at that
bar: each comparison in its condition and the values it compared (D1255).

```text
`paper.buy` did not fire at bar 3; it fired at 7. `fast > slow && close < 20` at bar 3:
`fast > slow` = true, `fast` = 18.5, `slow` = 17.2, `close < 20` = false, `close` = 25
```

## What runs where

`flowscript-core` and `@flowscript/core` compile any program in this reference,
and replay or run all of it except the parts each says it does not model:

- **Replay** (`replay`, `flowscript.replay`) evaluates a whole history at once.
  With a paper broker it fills the orders and runs their handlers. Give it
  each bar's close as `time` (`replay_timed` in Rust) for `every` and
  `cooldown` to count in chain time. A metric or trigger that reads only
  number series is computed for every bar at once by the compiled study plan,
  and the rest is stepped bar by bar; the answers are the same to the bit, so
  a long backtest costs about what a chart study does (D1270).
- **Live run** (`live::Run`, `flowscript.run`) steps one bar at a time and makes
  the replay's decisions on the same bars. Outcomes come from a paper broker or
  from the application (`report`).
- **Not modelled here yet**: `maintain` blocks are listed in the result's
  `unmodelled` with the reason, never silently dropped. So are invariants
  in a run with no paper broker.

Some of the language is for a full execution host such as ftw's and needs data
this library does not supply on its own: position context (`inPosition()`,
`avgEntry()`, `unrealizedPnl()` …) reads the strategy's own execution stream,
`param(…)` and `config(…)` read a configuration stream, and `pool(…)`,
`token(…)` and `market(…)` name an application's venues.

## Parameters and search spaces

`const lookback = param(7, { min: 3, max: 30, step: 1 });` declares a
parameter: its value is the default until a run's settings change it. The
bounds say what may change it and what an optimizer searches:

- `min` and `max` bound an edit, and the default sits between them.
- `step`, with both, makes min to max by step the search space (at most 1000
  values).
- `options: [...]` lists the values instead, up to 64 of the default's type,
  the default among them. It is not combined with min, max or step.

The compiler refuses any other bound (`param.bounds`, `param.step`,
`param.options`). A host that runs a strategy may bind each declared value
in place as a constant before compiling, as ftw.trade does, so a parameter can
size a window (`close[lookback]`); read as a configuration stream it can't.
On ftw.trade the declarations are the strategy's parameters, and an
optimization with no space named searches the declared steps and options.

## Coming from Pine Script

Most Pine indicators port line for line, and an importer does the porting
(D1194): `pineToFlowscript` in `@ftw-trade/charts/pine` translates the common
v5/v6 subset of an indicator to a chart study and of a strategy to a
ftw.trade strategy, and names, by Pine line, what it could not take
(`while`, a `for` it cannot port, `request.security` of another symbol,
`:=` on a name that is not a `var`). A `for i = 0 to len - 1` that adds, or
takes the max or min of, one series' `x[i]` becomes `rolling_sum`, `highest`
or `lowest`; a `for` over constant bounds (at most 64 steps) that only
accumulates is unrolled. A `var` and its `:=`, `+=` … updates, under `if`s too, become one
`fold` that applies them in order each bar: `var int n = 0` with
`n := up ? n + 1 : 0` is `const n = fold(close, 0, (n, _) => nz(up, false) ? n + 1 : 0);`. The charts site's Flowscript studio
and ftw.trade's Strategies page take a pasted script, and an agent
calls `get_pine_translation` over MCP. The differences are deliberate:

- Data is read by name, so a program says which market and interval it reads.
- Every run is replayable, so there are no loops and no mutation.
- Orders are a host's capabilities, not a built-in simulator.

```flowscript
uses { bars: "^1", alerts: "^1" }
const close = bars.close("BTC-USD", "1h");
const high = bars.high("BTC-USD", "1h");
const low = bars.low("BTC-USD", "1h");
const k = sma(stoch(close, high, low, 14), 3);
const d = sma(k, 3);
metric("k", k);
metric("d", d);
metric("bars_since_oversold", barssince(k < 20));
when (crossover(k, d) && k < 20) { alerts.send("stochastic turned up from oversold"); }
```

| Pine | Flowscript |
|---|---|
| `close`, `high`, `close[1]` | `bars.close("BTC-USD", "1h")`, read once into a `const`; history is the same `x[1]` |
| `ta.sma`, `ta.ema`, `ta.wma`, `ta.rma`, `ta.rsi`, `ta.stdev`, `ta.vwap`, `ta.roc`, `ta.mom`, `ta.correlation` | `sma`, `ema`, `wma`, `rma`, `rsi`, `stddev`, `vwap(price, vol, len)` (a rolling window; anchored, `anchoredVwap(src, vol, anchor)` or a session's `periodVwap`), `roc`, `momentum`, `corr` |
| `ta.atr(14)`, `ta.tr` | `wilderAtr(high, low, close, 14)`, `trueRange(high, low, close)` |
| `ta.highest`, `ta.lowest`, `math.sum`, `ta.cum` | `highest`, `lowest`, `rolling_sum`, `cum` |
| `ta.stoch`, `ta.linreg(src, len, 0)` | `stoch`, `linreg(src, len)` |
| `ta.barssince`, `ta.valuewhen(c, src, 0)` | `barssince`, `valuewhen(c, src)` |
| `ta.pivothigh(src, l, r)`, `ta.pivotlow` | `pivothigh(src, l, r)`, `pivotlow` |
| `[m, s, h] = ta.macd(src, 12, 26, 9)` | `macd(src, 12, 26)`, `macdSignal(src, 12, 26, 9)`, `macdHist(src, 12, 26, 9)`: one function per line |
| `[mid, up, lo] = ta.bb(src, 20, 2)`, `ta.variance` | `sma(src, 20)`, `bbUpper(src, 20, 2)`, `bbLower(src, 20, 2)`, `variance` |
| `[p, m, adx] = ta.dmi(14, 14)` | `diPlus(high, low, close, 14)`, `diMinus(…)`, `adx(high, low, close, 14, 14)` |
| `[st, dir] = ta.supertrend(3, 10)`, `ta.sar(0.02, 0.02, 0.2)` | `supertrend(high, low, close, 3, 10)`, `supertrendDir(…)`, `sar(high, low, close, 0.02, 0.02, 0.2)` |
| `ta.vwma`, `ta.swma`, `ta.wpr`, `ta.cmo`, `ta.mfi`, `ta.obv`, `ta.tsi` | the same names; a read Pine makes itself (the bars, the volume) is an argument |
| `ta.hma`, `ta.alma`, `ta.cci`, `ta.dev`, `ta.percentrank`, `ta.highestbars`, `ta.lowestbars`, `ta.cog`, `ta.range`, `ta.cross` | the same names |
| `[mid, up, lo] = ta.kc(src, 20, 2)`, `ta.kcw`, `ta.bbw` | `ema(src, 20)`, `kcUpper(src, high, low, close, 20, 2)`, `kcLower(…)`, `kcw(…)`, `bbw(src, 20, 2)` |
| `ta.pvt`, `ta.accdist`, `ta.wad`, `ta.nvi`, `ta.pvi`, `ta.iii`, `ta.wvad` | the same names, with the bars and the volume as arguments |
| `ta.crossover`, `ta.crossunder`, `ta.change` | `crossover`, `crossunder`, `change` |
| `math.abs`, `round`, `floor`, `ceil`, `sign`, `log`, `log10`, `pow`, `sqrt`, `sin` … | the same names without `math.`; `log` is `ln` |
| `na(x)`, `nz(x, y)` | `isNa(x)`, `nz(x, y)` |
| `var float x = 0` then `x := x + 1` | `fold(series, seed, (acc, x) => next)` |
| `import user/lib/1 as lib`, `export f(x) => …` | a library of `fn` definitions and `import "lib";`, its functions called by name |
| `plot(x, "name")` | `metric("name", x)`; in a chart study, `// @plot name histogram #26a69a` styles it |
| `plot(x, color = x > 0 ? green : red)` | `// @plot x up=green down=red`, or `by=other` to colour by another metric's sign |
| `plotshape`, `barcolor`, `bgcolor`, `display = display.none` | the `@plot` styles `up` and `down`, `bars`, `bg` and `hidden` |
| `plotshape(c, location = location.belowbar, text = "B")` | `// @plot c up below text="B"` (`above` for over the bar), with `metric("c", cond ? 1 : 0)` |
| `if c` … `label.new(bar_index, high, "H " + str.tostring(x))` | `// @plot l down above text="H {{x}}"` with `metric("l", c ? 1 : 0)` and `x` published as a metric (D1213) |
| `line.new` from pivot to pivot (a zigzag) | `// @plot p line connect`, with `metric("p", …)` set only at the pivots and `na` between |
| `box.new`, `table.new` | a box is a `// @fill` between two lines; a table's values read in the legend |
| `fill(p1, p2, color)`, `hline(70)` | `// @fill upper lower #2962ff`, `// @hline 30 70` |
| `input.int(14)` | a top-level `const len = 14;` in a chart study, which its settings edit; `param(14, { min: 2, max: 50 })` in a strategy |
| `input.int(14, "Length", minval = 2, group = "MA", tooltip = "…")` | `// @input len "Length" min=2 group="MA" tooltip="…"` over the `const` |
| `input.bool(true, "Show")`, `input.string("EMA", options = ["SMA", "EMA"])` | `// @input show bool "Show"` over `const show = 1;`; `// @input kind options="SMA,EMA"` over `const kind = 1;` (the picked option's index) |
| `hour`, `minute`, `dayofweek`, `dayofmonth`, `month`, `year`, `bar_index` | `hour(time)` … `year(time)` in a chart study (UTC), `barIndex(price)` |
| `time(timeframe.period, "0930-1600:23456", "America/New_York")`, `timezone`, `session.isfirstbar` | `inWeekdaySession(nyTime(time), 930, 1600)`; `hour(nyTime(time))`; `sessionStarts(active)` |
| `alertcondition(c)`, `alert(msg)` | `when (c) { alerts.send(msg); }`; ftw's host names it `notify(msg)` |
| `alertcondition(c, message = "RSI {{plot("rsi")}} at {{close}}")` | in a chart study, `// @alert c "RSI {{rsi}} at {{close}}"`: `{{value}}`, the bar's `{{open}}` … `{{volume}}`, `{{time}}` and any line by name |
| `strategy.entry`, `strategy.close` | the host's order actions in a `when` body, such as ftw's `orders.marketBuy` and `orders.sell` |
| `strategy.entry(limit=, stop=)`, `strategy.exit(stop=, limit=)` at a price | a broker rule with `rest` (D1212), such as ftw.trade's `paper.buyLimit({ quote, at })` and `paper.sellStop({ at })`: it rests at `at`, a number or an expression the program also publishes with `metric()`, and fills at the first later close through it |
| `request.security(syminfo.tickerid, "D", ta.sma(close, 20))` | `sample(periodEnds(time, 86400), close, c => sma(c, 20))`: the closed day's value, known on the bar that closes it and held, so it never repaints |
| `request.security(syminfo.tickerid, "D", high - low)` | `sample(periodEnds(time, 86400), {h: periodHigh(high, time, 86400), l: periodLow(low, time, 86400)}, b => b.h - b.l)` |
| `request.security(sym, "1D", close)` of another market | a read at that market and interval, `bars.close("BTC-USD", "1d")`, where the host publishes it |
| `for`, arrays and maps | not in the language: a window function, `fold`, or `percentile` and `median` over a window |

---

# Embed Flowscript

> Use the compiler and runtime in your own application: declare a host, replay data, step a live run and retain checkpoints.

[Canonical documentation](https://flowscript.ftw.trade/docs/embedding)

An application embeds Flowscript by declaring a host, compiling a program against it and supplying the observations that program reads. The Rust library is `flowscript-core`; `@flowscript/core` exposes the compiler and evaluator to JavaScript and TypeScript through WebAssembly. The JavaScript package has no runtime dependencies and does not depend on ftw.trade.

## Install and load

There is currently no public package release or public download of `@flowscript/core`, and it is not published to the npm registry. Embedding it locally requires authorized access to the source repository. These docs describe the library that exists in that checkout; they do not offer a public installation URL.

With Node.js, npm, Rust with the `wasm32-unknown-unknown` target, and `just` installed, run this from the checkout's root:

```sh
just flowscript-pack
```

The recipe installs the library's development dependencies, type-checks, builds the JavaScript and WebAssembly, runs the tests and packs the result. At the current package version, its output is `flowscript/npm/flowscript-core-0.1.0.tgz`; the version in `flowscript/npm/package.json` determines the filename. Packing does not publish the artifact.

Install the resulting tarball from your application directory. Replace the example checkout path with your actual source location:

```sh
npm install /path/to/authorized-checkout/flowscript/npm/flowscript-core-0.1.0.tgz
```

In Node, `await loadFlowscript()` loads the WebAssembly shipped beside that installed package. In a browser it fetches that file. A bundled application must serve the file itself and pass its bytes or a compiled `WebAssembly.Module` to `loadFlowscript`.

Compiler and evaluator calls are synchronous. Run them in a Web Worker when embedding in a browser so evaluation does not block the interface.

## Declare your host

The host determines what a program may read and call:

- **Sources** declare names, value types, key shapes and available intervals. The application supplies the actual samples.
- **Capabilities** are manifests declaring action names and arguments. Declaring an action does not implement or authorize an external transaction.
- **Libraries** supply named source imports. **Integrations** describe which implementations serve particular interfaces and markets.

An undeclared read or action is a compiler refusal. A host can declare sources without any capabilities, as the [quickstart](https://flowscript.ftw.trade/docs/quickstart) does.

Store the program source, its host and library configuration, and its compiled language version together. A program can pin its version with `flowscript "0.3";`; a host can record a version for source that omits that line. Restoring a checkpoint requires the same compiled program identity.

Use `flowscript.resolveLibraries(source, host)` to obtain and persist the exact
transitive dependency sources, including reached standard libraries. The
[extension guide](https://flowscript.ftw.trade/docs/extending) shows how to compose and test user libraries,
implement custom tool consumers and record external model predictions.

## Replay and checkpoint

`compile` returns a program or located problems. `replay` takes a program and a history with `len` rows, input columns by source name, and optional evaluation timestamps in seconds. It returns per-bar metrics and decisions, or an error. Inspect `unmodelled` too: a successful result can identify behavior the selected evaluation configuration did not model.

For batches, `{ save: true }` returns a checkpoint in `snapshot`. Pass that text as `{ resume: snapshot }` with only the observations after it. This complete example uses illustrated hourly inputs and no actions:

```js
import { loadFlowscript } from '@flowscript/core';

const flowscript = await loadFlowscript();
const host = {
  sources: [
    { name: 'bars.close', type: 'number', keyed: true, intervals: ['1h'] },
  ],
  capabilities: [],
};
const source = `flowscript "0.3";
uses { bars: "^1" }
const close = bars.close("DEMO-USD", "1h");
metric("average", sma(close, 3));
`;
const compiled = flowscript.compile(source, host);
if (!compiled.ok) throw new Error(JSON.stringify(compiled.problems));

try {
  const firstClose = Date.UTC(2026, 0, 1, 1) / 1000;
  const first = flowscript.replay(compiled.program, {
    len: 3,
    series: { 'bars.close': new Float64Array([100, 102, 104]) },
    time: new Float64Array([firstClose, firstClose + 3600, firstClose + 7200]),
  }, { save: true });
  if (!first.ok) throw new Error(first.error);
  if (first.unmodelled.length) throw new Error(first.unmodelled.join('; '));
  if (typeof first.snapshot !== 'string') throw new Error('No checkpoint returned');

  // Your application persists this text with its input cursor and configuration.
  const saved = first.snapshot;

  const next = flowscript.replay(compiled.program, {
    len: 2,
    series: { 'bars.close': new Float64Array([106, 108]) },
    time: new Float64Array([firstClose + 10800, firstClose + 14400]),
  }, { resume: saved, save: true });
  if (!next.ok) throw new Error(next.error);
  if (next.unmodelled.length) throw new Error(next.unmodelled.join('; '));
  if (typeof next.snapshot !== 'string') throw new Error('No checkpoint returned');

  console.log(Array.from(next.metrics.average)); // [104, 106]
} finally {
  flowscript.drop(compiled.program);
}
```

Persist a new checkpoint and the cursor naming its consumed inputs as one application-level commit. Flowscript produces checkpoint text; it does not provide a database, subscription cursor or transaction around your storage.

For one bar at a time, `flowscript.run(program)` creates a run. `run.step(values, time)` consumes one completed bar; `run.snapshot()` returns a result containing checkpoint text. Restore with `flowscript.run(program, { snapshot })`, check each result and call `run.drop()` when finished. Supply the same paper-broker configuration when restoring a run that used one. Call `flowscript.drop(program)` after its runs have been dropped.

Each successful step returns structured metrics, text and decisions for your application to consume. [Outputs and consumers](https://flowscript.ftw.trade/docs/outputs) shows a complete adapter that builds chart rows, unsent action records and application logs from those real results.

## Preserve the boundary

The application owns data collection, bar construction, units, ordering, freshness and durable input cursors. An omitted observation in `run.step` holds its prior value; `null` explicitly supplies an unknown observation. Choose that behavior deliberately for your feed.

An action decision records what the program requested. Sending it to a venue, protecting signing keys, enforcing trading permissions and reconciling the actual outcome are application responsibilities. The optional paper broker models explicitly configured orders; it is not a venue depth or partial-fill simulator.

Runtime refusals and `unmodelled` behavior must reach the caller. Do not replace them with fabricated values or silently restart evaluation. A WebAssembly trap invalidates existing program and run handles; compile explicitly and restore a validated checkpoint before continuing. Checkpoint identity mismatches are refused.

Read the [language reference](https://flowscript.ftw.trade/docs/reference) for the complete host contract, runtime semantics and diagnostics. For ftw.trade's own host, modules, accounts and execution workflow, use [its platform guide](https://docs.ftw.trade/strategies/overview).

---

# Build libraries and tools

> Compose and test your own libraries, declare custom data and actions, and feed recorded external model predictions into an incremental strategy.

[Canonical documentation](https://flowscript.ftw.trade/docs/extending)

The standalone compiler takes a host declaration; it has no dependency on
ftw.trade. An application chooses the reads, libraries and actions its programs
can use. These extension paths have different responsibilities:

| Extension | Declare | Execute |
|---|---|---|
| Pure language helper | `Host.libraries[name]`, then `import "name";` | Flowscript evaluates the imported `.flow` functions |
| Data or external model output | A typed entry in `Host.sources` | The application records observations and supplies them to `run.step` / `replay` |
| Application tool | A capability manifest with arguments and host authority | The application authorizes and consumes the returned decisions |
| Several providers of an interface | `Host.integrations` and their served members/markets | The application connects the declared runtime implementations |

Imports provide source functions, not JavaScript callbacks or installed tools.
A capability manifest describes an action; declaring it does not implement its
consumer, grant signing authority, or authorize network access. Unknown imports,
reads and actions are compiler refusals. Use host documentation for source and
action descriptions; comments document imported functions for editor help.

## Author and compose libraries

Supply your `.flow` source under a name in `Host.libraries`. A library may
import other libraries and declare functions or contract interfaces. It cannot
declare `uses`, metrics, triggers or action side effects; the calling program
owns its host capabilities. See [Libraries](https://flowscript.ftw.trade/docs/reference#libraries) and
[Embedding](https://flowscript.ftw.trade/docs/embedding).

Dependencies form a closure of at most 15 unique libraries, including reached
standard libraries. Shared dependencies in a diamond are loaded once. Repeating
an import in the same file, an import cycle, an unknown dependency or a duplicate
function name is refused. Function names are global and unqualified:
`import "user/risk";` exposes `userCappedEdge(...)`, not `risk.userCappedEdge(...)`.
Choose distinct prefixes for reusable helpers. On ftw.trade, take observations
as function arguments rather than hiding source reads in a helper, so the
platform can discover the caller's data subscriptions.

Test a library through a small importing program. Resolve and save the exact
dependency sources with the program and its compiled language version:

```js
import { loadFlowscript } from '@flowscript/core';
const fs = await loadFlowscript();
const host = { libraries: {
  'user/math': 'fn userPositiveEdge(x: number): number { return max(x, 0); }',
  'user/risk': `import "user/math";
fn userCappedEdge(x: number, cap: number): number {
  return min(userPositiveEdge(x), cap);
}`,
} };
const source = 'import "user/risk"; metric("edge", userCappedEdge(3, 2));';
const resolved = fs.resolveLibraries(source, host);
if (!resolved.ok) throw new Error(JSON.stringify(resolved.problems));
const pinnedHost = { ...host, libraries: resolved.libraries };
const compiled = fs.compile(source, pinnedHost);
if (!compiled.ok) throw new Error(JSON.stringify(compiled.problems));
try {
  const tested = fs.test(source, { tests: [{
    name: 'cap an imported positive edge', bars: 1, sources: {},
    expect: [{ metric: 'edge', at: 'last', equals: 2 }],
  }] }, pinnedHost);
  if (!tested.ok) throw new Error(tested.error);
  if (tested.report.failed) throw new Error(JSON.stringify(tested.report));
  const saved = { source, language: compiled.program.language, libraries: resolved.libraries };
  // Persist saved with the rest of your host configuration and input cursor.
} finally { fs.drop(compiled.program); }
```

`resolveLibraries` returns the selected source map without typechecking the
strategy against its data host. Compilation and the test still have to pass.
When restoring, use the saved map and language, not the current contents of a
library registry. The closure includes the exact standard-library copies used
by the program. Changed dependency implementations change program identity and
cannot silently reuse an incompatible checkpoint.

## Built-in learning and external inference

Built-in `ml.*` models fit on the program's recorded series in the evaluator.
Their training rows, parameters and work participate in its state and budgets;
replay and restored live runs use the same implementation. See
[Trained models](https://flowscript.ftw.trade/docs/reference#trained-models) for available methods, horizon and
retraining semantics. They are bounded rolling models, not an import mechanism
for arbitrary Python, ONNX, GPU or JavaScript runtimes.

An external model runs in the application's chosen backend. Publish its output
as a typed observation, just as another data source. The runnable
[external-model.ts](https://github.com/johnny-emp/flywheel/blob/main/flowscript/npm/examples/external-model.ts) example combines that
path with an imported freshness helper and a custom `research.record` action:

```sh
cd flowscript/npm
npm run build:wasm
node examples/external-model.ts
```

The example has no additional dependencies. Its fixed logistic coefficients are
illustrative and are not presented as a trained model, profitable strategy or
production inference engine. The model document owns feature order, bounds,
coefficients and intercept; its SHA-256 identity appears in the program's read
key and every recorded output. Inference reads that same document. Replacing
the document changes the compiled program identity; an old checkpoint cannot
silently resume under the new model.

The application computes a score, records `{time, asOf, model, score}`, then
steps the program. `time` is when the prediction became available to the
strategy; `asOf` is the input data's time. A response delivered at 110 cannot be
inserted into bar 109 merely because its features came from 109. All times in
this example are whole evaluation seconds. A future `asOf`, nonfinite or
out-of-range probability, wrong model identity, unsupported feature dimension
or feature outside the declared bounds is refused. Unavailable inference is
recorded explicitly as `score: null`.

The strategy checks the model identity and uses the `.flow` helper to exclude
unknown, stale, future and out-of-range observations before emitting a signal.
Omission in `run.step` holds the previous observation, so an outage must send explicit unknown values
when holding the old prediction is inappropriate. A freshness guard also
limits how long an earlier valid prediction can remain usable.

`research.record` has a real consumer: it validates the compiled action's host
operation and evaluated arguments before appending candidate signals to an
application-owned journal. It authorizes no trade. The example validates an
entire batch before retaining effects; it does not parse rendered argument IR
or report fabricated fills. A real application's storage, effect outbox,
permissions, retries and action settlement belong at this boundary.

## Reproduce the observations, not the inference request

Replay the recorded predictions at their original availability watermarks.
Do not call a remote model again during replay, substitute a newer model, or
backfill historical predictions using features or training data unavailable
then. Record model artifact identity, backend/precision configuration, feature
schema and input cursor with the inference outputs in a real integration.
The example pins a small fixed model; its test history is explicitly synthetic.

Persist the input cursor, observations, evaluator checkpoint and durable effect
outbox consistently. A Flowscript checkpoint contains evaluator state; it does
not preserve an external model server, in-progress request or model-training
state. Asynchronous inference needs the host's own correlated request/result
coordinator, recorded delivery and timeout policy. The generic `Run.report`
venue-outcome seam is not a task-result dispatcher.

The [example tests](https://github.com/johnny-emp/flywheel/blob/main/flowscript/npm/test/external-model.test.ts) exercise actual WebAssembly compilation, replay, live steps,
checkpoint restoration, delayed availability, input bounds and the action
consumer. There are no latency claims: measure the chosen inference backend,
transport and evaluation workload together before selecting a deployment mode.

---

# Use strategy outputs

> Consume evaluated metrics, text and action intents in charts, application logs and your own data consumers, with delivery and storage owned by the host.

[Canonical documentation](https://flowscript.ftw.trade/docs/outputs)

A program's outputs can become data in your own application: chart series, status labels, event rows, alerts or inputs to another consumer. The core returns structured values. Your host chooses where they go and which consumers may read them.

## What comes out

| Output | Core API | Example consumer |
|---|---|---|
| Numeric or boolean metrics | `step.metrics` | A chart, table, monitor or derived dataset |
| Text metrics | `step.texts` | A status label, annotation or application log message |
| Action decisions | `step.decisions` | An event stream, notification adapter or execution adapter |
| Application logs | Records your application constructs | A log viewer or observability service |
| Stored rows | Records your application persists | A database, API, dashboard or another application |

`metric("average", average)` publishes a number. `metric("state", "ready")` publishes text, returned through `texts`. In a replay those fields contain one column per metric; `run.step` returns the values for the bar just evaluated.

An action decision means the program requested a declared action. It is not a receipt, fill or confirmation that an external effect happened. An application can inspect or store decisions without attaching an execution adapter.

## Turn evaluated values into application data

The following complete example computes an average, publishes a text state and requests a host-defined `signals.publish` action when the condition changes. Its six hourly prices are an illustrated input sequence, not recorded market data. The example collects outputs in memory; it does not send notifications, place orders or write a database.

Use an authorized source build of the package as described in [Embedding Flowscript](https://flowscript.ftw.trade/docs/embedding). Save this as `outputs.mjs` in an application with that built package installed and run `node outputs.mjs`.

```js
import { loadFlowscript } from '@flowscript/core';

const flowscript = await loadFlowscript();
const host = {
  sources: [
    { name: 'bars.close', type: 'number', keyed: true, intervals: ['1h'] },
  ],
  capabilities: [JSON.stringify({
    name: 'signals',
    actions: {
      publish: {
        args: { message: 'Text', close: 'Number' },
        required: ['message', 'close'],
        evaluated: ['message', 'close'],
        authority: { kind: 'host', operation: 'signals.publish' },
      },
    },
  })],
};
const source = `flowscript "0.3";
uses { bars: "^1", signals: "^1" }
const close = bars.close("DEMO-USD", "1h");
const average = isNa(close[2]) ? na : sma(close, 3);
const above = close > average;
metric("close", close);
metric("average", average);
metric("state", isNa(average) ? "warming up" : above ? "above average" : "at or below average");
when (above) { signals.publish({ message: "above average", close: close }); }
when (!above) { signals.publish({ message: "at or below average", close: close }); }
`;
const compiled = flowscript.compile(source, host);
if (!compiled.ok) throw new Error(JSON.stringify(compiled.problems));

try {
  if (compiled.program.warnings.length) {
    throw new Error(JSON.stringify(compiled.program.warnings));
  }
  const started = flowscript.run(compiled.program);
  if (!started.ok) throw new Error(started.error);
  try {
    const run = started.run;
    if (run.unmodelled.length) throw new Error(run.unmodelled.join('; '));
    const closes = [100, 102, 104, 101, 99, 105];
    const firstClose = Date.UTC(2026, 0, 1, 1) / 1000;
    const runId = 'illustrated-signal-run';
    const chartRows = [];
    const actionIntents = [];
    const applicationLogs = [];
    // Preserve unknown values as explicit chart gaps when encoding JSON.
    const chartNumber = (value) => {
      if (Number.isNaN(value)) return null;
      if (!Number.isFinite(value)) throw new Error('Invalid output metric');
      return value;
    };

    for (let i = 0; i < closes.length; i++) {
      const time = firstClose + i * 3600;
      const step = run.step({ 'bars.close': closes[i] }, time);
      if (!step.ok) throw new Error(step.error);
      if (step.orders.length || step.refused.length) {
        throw new Error('Unexpected broker order or invariant refusal');
      }

      chartRows.push({
        time,
        close: chartNumber(step.metrics.close),
        average: chartNumber(step.metrics.average),
        state: step.texts.state,
      });
      for (const decision of step.decisions) {
        actionIntents.push({ runId, bar: step.bar, time, decision });
      }
      // This log record belongs to the application, not a core stdout stream.
      applicationLogs.push({
        level: 'info',
        event: 'flowscript.step',
        runId,
        bar: step.bar,
        time,
        message: step.texts.state,
        actionCount: step.decisions.length,
      });
    }

    console.log(JSON.stringify({ chartRows, actionIntents, applicationLogs }, null, 2));
  } finally {
    started.run.drop();
  }
} finally {
  flowscript.drop(compiled.program);
}
```

The program explicitly waits for three observations with `isNa(close[2])`, so its average is unknown for the first two bars, then `102`, `102.333…`, `101.333…` and `101.666…`. A chart can draw `close` and `average` against `time`, leave the initial unknown values as gaps, and use `state` for labels. `time` is the input bar's close in Unix seconds; convert it explicitly if your visualization expects milliseconds.

The three actual decisions occur at bars `2`, `3` and `5`. Each retains the core's `site`, `capability`, `action`, symbolic `args` and evaluated `values`. Here, `values.message` and `values.close` contain the text and price at the moment the action fired. A consumer can place markers on those bars or store them as events. These records do not claim that anything was delivered or executed.

## Where logs come from

The core returns metrics, text, decisions and result errors; this example does not call a Flowscript `log` function or receive a core stdout stream. The JavaScript application creates `applicationLogs` from each successful step, then prints its collected data with its own `console.log`.

A host can instead send those structured records to its own logging service, store text metrics as annotations, or declare a separate logging capability. In each case the host implements delivery and chooses retention. Compiler diagnostics and runtime errors should remain visible as failures, not successful evaluation log entries.

## Connect a durable consumer

Choose the output contract your consumers need: program identity and version, run identity, source identity and units, input cursor, evaluation timestamp, metric names, and action site. Persist that identity with the output so a replay can be recognized rather than inserted as a new event.

Commit output rows, the input cursor and the next [checkpoint](https://flowscript.ftw.trade/docs/embedding#replay-and-checkpoint) together where your storage supports a transaction. For delivery to another system, an application-owned durable outbox can carry committed events; the consumer needs an idempotency key that identifies the same run, input and action site. An in-memory array like this example has no durability or delivery guarantee.

An adapter that performs an external action must retain and reconcile its real outcome. `run.report` can feed supported outcomes back to the run for handlers; an emitted decision alone must never be marked as a receipt. The language does not provide your database, charting library, event bus, signing service or consumer access policy.

These boundaries also let an application publish strategy outputs as its own data product or use them as inputs to another process. The host owns the schema, permissions, delivery and storage. For ftw.trade's particular strategy and visualization workflow, read [its platform documentation](https://docs.ftw.trade/strategies/overview); for the underlying API, read the [language reference](https://flowscript.ftw.trade/docs/reference).