FLUXFLUX
  • Introduction
  • Quickstart
  • From Your Data to a Synthetic Copy
  • Two Specs, One Substrate
  • The Six Families
  • The FLUID Seam
  • Deterministic & Governed
  • Runtime & Evidence
  • Anatomy
  • The Nineteen Kinds
  • Versions
  • Changelog
  • JSON Schema 0.5.4
  • UI Hints 0.5.4
  • Enforcement Contract 0.5.0
  • Bundle Manifest 0.5.0
  • Overview
  • Tutorial
  • How-to guides
  • Reference
  • Explanation
  • Command line
  • Error codes
  • Accuracy program
  • The vNext Plan
  • The Nine RFCs
  • Playback Source (proposed)
  • Conformance Profiles
Examples
What's New
FLUID
GitHub
  • Introduction
  • Quickstart
  • From Your Data to a Synthetic Copy
  • Two Specs, One Substrate
  • The Six Families
  • The FLUID Seam
  • Deterministic & Governed
  • Runtime & Evidence
  • Anatomy
  • The Nineteen Kinds
  • Versions
  • Changelog
  • JSON Schema 0.5.4
  • UI Hints 0.5.4
  • Enforcement Contract 0.5.0
  • Bundle Manifest 0.5.0
  • Overview
  • Tutorial
  • How-to guides
  • Reference
  • Explanation
  • Command line
  • Error codes
  • Accuracy program
  • The vNext Plan
  • The Nine RFCs
  • Playback Source (proposed)
  • Conformance Profiles
Examples
What's New
FLUID
GitHub
  • FLUX Simulation Engine
  • Tutorial
    • First evidence pack in five minutes
  • How-to guides
    • Model your customers
    • Add a journey
    • Use the FLUID seam
    • Calibrate from aggregates: declare a scorecard
    • Draw a column given another
    • Ship with evidence
    • Write a bundle from a profile
    • Score a run against a profile, in full or sampled
    • Seal and score a prediction
    • Load a simulation into a database
  • Reference
    • Command line
      • fluxsim init
      • fluxsim validate
      • fluxsim plan
      • fluxsim apply
      • fluxsim run
      • fluxsim verify
      • fluxsim ship
      • fluxsim replay
      • fluxsim calibrate
      • fluxsim accuracy
      • fluxsim gate
      • fluxsim expr
      • fluxsim describe
      • fluxsim plugins
      • fluxsim explain
    • Error codes
    • Python API
    • Schemas
    • Specifications
      • FLUX Simulation Engine: kernel normative specification (v0.1)
      • FLUX Simulation Engine: kernel v2 normative specification (v0.2)
      • Seam generator and fidelity check: normative specification (v0.1)
      • Profile document: normative specification (format 1-1-0)
      • Scorecard: normative specification (format 1-1-0)
      • Sample-based verification: normative specification
      • Parameter register: normative specification (format 1-1-0)
      • flux-expr/1: normative specification (v0.1)
      • flux-expr/2: normative specification (v0.1)
      • flux-expr/3: normative specification (v0.1)
  • Explanation
    • Architecture and patterns
    • The six-step loop
    • Determinism and the seed tree
    • The FLUID seam
    • The evidence pack, and what it does not claim
  • Accuracy program

    • The accuracy program: design
    • Accuracy report

flux-expr/1: normative specification (v0.1)

Segment.spec.queryLanguage is const: flux-expr/1 in FLUX 0.5.0 and no grammar exists anywhere in the spec. This document defines it. The grammar is closed: anything not derivable is a parse error (FLX-6001), never an extension point. Growth requests go to flux-expr/2 by policy. CEL was evaluated and diverged from deliberately (ADR-0002): the shipped example products.has('tv') is not CEL, the grammar must be frozen and digest-stable, and the cold path must not carry a parser-generator dependency.

1. Grammar (EBNF)

expr        = or_expr ;
or_expr     = and_expr , { "||" , and_expr } ;
and_expr    = not_expr , { "&&" , not_expr } ;
not_expr    = [ "!" ] , primary ;
primary     = "(" , expr , ")" | comparison | membership | method | bool_lit ;
comparison  = operand , cmp_op , operand ;
cmp_op      = "==" | "!=" | "<" | "<=" | ">" | ">=" ;
membership  = operand , "in" , list_lit
            | operand , "in" , path ;                      (* right side must be set<string> *)
method      = path , "." , method_name , "(" , [ literal , { "," , literal } ] , ")" ;
method_name = "has" | "isNull" | "startsWith" | "endsWith" | "contains" ;
operand     = path | literal ;
path        = ident , { "." , ident } ;
ident       = ( letter | "_" ) , { letter | digit | "_" } ;
literal     = string | number | bool_lit | null_lit ;
list_lit    = "[" , [ literal , { "," , literal } ] , "]" ;
string      = "'" , { char - "'" | "\'" } , "'" ;
number      = [ "-" ] , digit , { digit } , [ "." , digit , { digit } ] ;
bool_lit    = "true" | "false" ;
null_lit    = "null" ;

Precedence, tightest first: method/path · ! · comparison and in · && · ||. All left-associative. Whitespace: space, tab. No arithmetic, no lambdas, no regex (matches is a reserved word that parses to FLX-6002 naming flux-expr/2), no temporal operators, no user functions, no double-quoted strings.

Method set (closed): has(string) on set<string>; isNull() on any path; startsWith, endsWith, contains (one string literal) on string.

2. Types

Five static types: bool, number (evaluated as Decimal), string, set<string>, enum<…> (a string drawn from a declared closed set; compares as string; a literal outside the set is FLX-6003 at plan time). null is a value any path may carry, not a type.

Static type check at plan time against the attribute model: unknown path FLX-6004; type mismatch (market > 3, traits.digitalFluency.has('x')) FLX-6005; comparison between different types is an error (no coercion; '1' == 1 is FLX-6005). Numeric literals are parsed as Decimal, never float.

Runtime totality: a type-checked expression never raises. A null operand makes every comparison and in evaluate to false, != null to true, and isNull() to true. Methods on null return false.

3. Attribute model (expr/attrs.py): three scopes, derived at plan time, printed by fluxsim expr model

A versioned, canonical JSON document (attrmodel/1) whose digest is inside inputDigest.

subject scope: Segment.spec.query, Journey guards

pathtypesource
idstringsubject id
ordinalnumberpopulation ordinal
personaenum(Persona ids referenced by the Simulation)assignment
lifecycleenum(keys of World.spec.population.lifecycleMix)LRM cohort
marketenum(World.spec.population.markets)market assignment
traits.<name>number (scalar or normal) | enum(levels) (categorical)Persona trait declarations
worldview.<name>numberPersona worldview
vertical-pack attributes (telco: products: set<string>, tenureMonths: number, latePaymentCount: number, arpu: number)per packWorld.spec.vertical → verticals/<pack>.py (v0.1 stopgap; FLUX 0.6 RFC moves the declaration into the spec)
Bare lifecycle, products, … are sugar for subject.<name> where unambiguous.

event scope: Detector.pattern[].predicate, Journey.spec.trigger.condition

CloudEvents context: type, source, time (string, RFC 3339), subject (the subject id); payload fields typed from the Signal's dataschema when it is a bundled/fetchable JSON Schema, else from a signalAttributes block in the vertical pack (telco sig-payment-aborted: amount: number, attempts: number, channel: string). Payload paths are addressed as data.<field>; bare amount is sugar for data.amount.

observed scope: Playback.spec.personaMapping[].behaviorPattern

Aggregate features per observed subject computed by the ingest step (telco: late_payment_count: number, tenure_months: number, arpu: number). Never raw records.

4. Evaluation

Hand-written tokenizer + Pratt parser → frozen dataclass AST → compile(expr, scope_model) -> Callable[[View], bool] (closure tree). unparse(parse(x)) is a fixed point and is the canonical form stored in plan.json. The AST JSON (canonical) is golden-pinned per expression.

5. Published vectors (expr-vectors.json, upstream to the open spec repo)

Each vector: {id, expr, scope, model_fragment, expect: {parse: ast|error_code, check?: "ok"|error_code, unparse?: text, eval?: [{row, result}]}}. id is the vector's stable name; model_fragment names an entry of the file's top-level models table rather than inlining a model; expect.check is "ok" or the static-check error code; expect.unparse is the canonical text; expect.eval is a list of {row, result} cases, of which the single-case form is one entry. The v0.1 set covers: the four shipped example expressions; each operator; precedence; each method; each error code; null rules; NFC/NFD identifier equivalence (é composed vs decomposed identifies the same path); the reserved matches.

Last Updated: 11/19/26, 8:45 AM
Prev
Parameter register: normative specification (format 1-1-0)
Next
flux-expr/2: normative specification (v0.1)