Documentation Index
Fetch the complete documentation index at: https://docs.fluxamerica.io/llms.txt
Use this file to discover all available pages before exploring further.
Glossary
The terms below are the Flux Platform’s canonical public vocabulary. Synonyms are bugs — when reading partner SDKs, wire envelopes, audit-event payloads, and this site’s other pages, expect these terms verbatim. This page is auto-generated fromdocs/GLOSSARY.md in the platform repository. Internal-only terms (marked <!-- visibility: internal --> in the source) are filtered out by the generator — the rendered partner-facing surface carries only the PUBLIC subset.
Tenant
The boundary of data isolation. Every persistent row is owned by exactly one tenant. A tenant corresponds 1:1 with a WorkOS organization. The platform stores a local cache of organization identity but treats WorkOS as the authority. Isolation is physical: each tenant’s data lives in its own SurrealDB namespace (a tenant namespace); no table is shared across tenants. See ADR-0028.Principal
An authenticated identity making a request. A principal is always associated with exactly one tenant for the duration of a request.Model
A user-defined logical type within a tenant — for example “Customer”, “Work Order”. A model is created with a pretty name and is durably identified by a system-derived slug. Models are versioned: eachmodel has a sequence of model_version rows, exactly one of which is the active version at any time.
Field
A typed attribute belonging to a model. A field has a pretty name for display, a system-derived slug for machine identity, a primitive type, an optional preset, a cardinality, zero or more validation rules, and a structured field metadata block. Fields are first-class entities (field_def table), not anonymous strings inside a JSON blob.
A field’s slug is unique within its model and is never reused — including across deletions. Two different models may both have a field with slug name; they are distinct fields with distinct identities.
A field may be marked internal (field_def.internal = true), in which case it is hidden from the Fx record binding, hidden from calculated-field expressions, and not surfaced in user-facing record APIs. Internal fields are reserved for platform-managed bookkeeping (e.g., per-model autonumber counters).
Primitive
The canonical type a field’s value takes. Drawn from a closed enum:text, integer, decimal, boolean, date, time, datetime, duration, reference, select, attachment, geopoint, geoshape, address, lookup, json. Adding a new primitive is an ADR amendment plus a SurrealDB migration. See ADR-0014.
Preset
A registry-defined bundle of(default validation rules, default cardinality, optional sub-shape, UI hint) that overlays a primitive. A field’s preset is a string identifier resolved against the preset registry at model-version publish time. Presets are data, not code: adding a new “format” (e.g., a country-specific phone or postcode regex) is a registry update. The v1 catalogue and the future tenant-defined extension path are described in ADR-0014. Presets are versioned; updating a preset never retroactively changes existing fields.
Sub-shape
The optional structured payload a preset attaches on top of its primitive. Two flavours in v1: currency-decimal ({ amount, currency } where currency is an ISO 4217 code) and address-country (a country-specific validation overlay on the address primitive). A field’s effective wire shape is the primitive’s wire shape augmented by the preset’s sub-shape, when the preset declares one. See ADR-0014 and the design doc § 2.
Cardinality
The shape of a field’s value:single, list, or set, with optional min, max, and ordered (list-only) parameters. min = 1 replaces the legacy notion of “required”. Cardinality evolves across model versions with deterministic auto-migration for total directions and tenant-declared reduction policies for lossy ones. See ADR-0014 and the design doc.
Reference handle
The Fx-visible representation of areference field’s value. Exposes .exists (boolean check against the live record set) and .slug (a tenant-stable pseudo-id, not the SurrealDB RecordId). Reading a field on the linked record uses Fx’s reference-traversal syntax (record.<ref>.<projected>). Chains compose to any depth; total cost is bounded by the surface’s op budget, not a per-surface depth cap (per ADR-0017). Per-step safety checks (tenant ownership, tombstone state, internality) run on every hop. This is the safety boundary that prevents rules from reaching internal storage identifiers. Realised as an authoritative SurrealDB graph edge (ADR-0032); the Fx contract above is unchanged. With namespace-per-tenant (ADR-0028) cross-tenant traversal is physically impossible, not policed; tombstone state and internality remain enforced on every hop.
Attachment
A binary file referenced by a record. Bytes live in S3-compatible object storage (content-addressable, per-tenant key prefix); the record holds an attachment handle. Attachments are malware-scanned by a separateplatform-scanner binary (ClamAV) before downloads are permitted. Writes that reference an attachment in pending state are allowed; downloads are gated on scan_state = clean. See ADR-0015.
Attachment handle
The structured value stored on a record for anattachment field: { object_key, sha256, byte_size, mime_type, original_filename, scan_state, scan_at, scanner_version, uploaded_by, uploaded_at }. The handle is what Fx expressions see; the bytes are reachable only via the platform’s pre-signed download endpoint, which enforces the scan-state gate.
Object key
The opaque, slash-segmented S3 path that addresses an attachment’s bytes:tenants/{tenant_slug}/attachments/{sha256[0:2]}/{sha256[2:4]}/{sha256}. Content-addressable within a tenant (same sha256 → same object); cross-tenant collisions are deliberately prevented by the per-tenant prefix to avoid an existence side-channel (ADR-0015 § “Storage”). The platform generates the key at initiate time; clients store and pass the full key, but APIs that take a path parameter use the trailing sha256 for routing convenience.
Scan state
The lifecycle marker on an attachment row:pending | clean | infected | expired. ADR-0015 § “Scan state machine”:
pending→ set on initiate; record writes referencing the attachment are permitted, downloads return425 Too Early.clean→ set when the scanner reports no threats; downloads return302to a fresh presigned S3 URL.infected→ set on any-state → infected transition (initial scan or rescan reclassification); downloads return451; new record writes referencing the attachment are rejected.expired→ set when apendingrow exceedspending_max_age(24 h default); downloads return410 Gone. Terminal — a stale scanner verdict is rejected with409 Conflict.
Lookup field
A first-class field type whose value is mechanically projected from a referenced record’s field. Defined as{ via: <reference field slug>, project: <field slug on referenced model> }. No expression engine. Recomputed and cached on referenced-record write per ADR-0008. Distinct from a calculated field, which uses an Fx expression for genuine derivation (per ADR-0017). See ADR-0014.
Calculated field
A field whose value is derived at read time from an Fx expression rather than written directly. Replaces Airtable’s Formula, Rollup, and Count concepts. Inputs are the same record’s fields, reference-traversal chains (any depth, op-budget-bounded),now, and actor — never SurrealDB metadata. Bounded by the calculated-field surface’s per-evaluation budgets (wall-clock, max ops, memory caps). Results cached in the projection per the expression’s grammar-derived read-set; cross-record invalidation via ADR-0021; expression-change backfill via ADR-0022. See ADR-0017.
Field metadata
The structured per-field metadata block onfield_def: { tags, sensitivity, retention_class, description, examples }. tags are freeform but constrained by a per-tenant tag registry. sensitivity is a fixed enum (see Sensitivity) that drives downstream access control. retention_class keys into a tenant retention policy. Surfaced in catalogue / data-dictionary UIs and consumed by governance tooling.
Sensitivity
The fixed four-level enum on field metadata:public | internal | confidential | restricted. Default is internal. Drives downstream access control, redaction in logs, and exposure in the audit / catalogue surfaces. The values are intentionally coarse — finer-grained policy lives in retention class and tag registry, not here.
Sensitivity propagation
The rule that an Fx expression’s result type carries the maximum sensitivity of the inputs it touches. A computed field whose expression reads arestricted field is itself restricted unless its metadata explicitly downgrades — and downgrading is an audit-emitting action. Visibility rules use sensitivity propagation to gate redaction. See ADR-0017.
Tag registry
A per-tenant, append-mostly namespace of allowed tag names that field metadata may reference. Ensures consistent labelling (e.g.,pii, gdpr_personal_data, hipaa_phi) across fields within a tenant and prevents tag drift.
Slug
A short, URL-safe, system-derived identifier. Slugs are generated from the pretty name and are never user-visible (they are internal addressing). On collision with an existing or tombstoned slug, a short random suffix is appended (e.g.customer_a3f9k). Slugs are immutable for the lifetime of the entity.
Slug character set: [a-z0-9_]+. Maximum length: 64.
Reserved slug
A slug name the slug-derivation function refuses to assign to a user-defined field. Reserved set:- Auto-projected metadata:
created_at,created_by,updated_at,updated_by,version,id. - The
_dlt_*namespace, reserved for dlt translation and future internal-only ingest metadata.
created_at_a3f9k).
Pretty name
The human-facing label for a model or field. Shown in all userland UI. Mutable. Has no identity role — renaming a field does not change its slug.Record
An instance of a model. Records carry typed field values that conform to the validation rules of the model version under which they were created or last updated. Each field value carries field-level metadata (last updater, last update time) materialized from the audit log. Physically, a record is projected (ADR-0007) into a per-model value table, a record metadata sidecar, and a version sidecar; all three are replay-rebuildable. See ADR-0030.Model version
An immutable snapshot of a model’s field definitions and validation rules. A new version is created whenever fields are added, removed, or rules change. Records are bound to the model version they were written under.Audit log
The append-only system of record for every state-changing event in the platform. Every record write produces exactly one audit event carrying the field-level diff. The audit log is the canonical source of truth; all other read models (records, projections) are derivable by replay.Validation rule
An Fx expression evaluated against a candidate field value at write time. A field carries zero or more rules. Each rule has aname, an expression, and a message shown to the caller on rejection. The expression’s static type must be bool. See ADR-0017.
Default expression (default_expr)
An optional Fx source on FieldDef evaluated at record-create time when the field’s value is absent from the write payload. Coexists with the literal default_value: payload > expression > literal > null. The expression is materialized once and the resolved value is written to the cell — replay reads the materialized value, never re-runs the expression, so now, actor, and reference projections are safe. References (record.<ref>.<projected>) are supported in v1. See ADR-0036.
Visibility expression (visibility_expr)
An optional Fx source on FieldDef evaluated at record-read time against the requesting actor. Fail-closed: any outcome other than Some(true) (false, null, runtime error, budget exceeded) hides the field. Hide semantics: the field is omitted from the returned record’s fields map (not surfaced as null). Applies on GetRecord, ListRecords, and subscription event delivery alike. A field with visibility_expr set is not addressable in Index-surface filters — protocol::fx_eval::compile_filter rejects filters that reference any gated field. See ADR-0037.
Compute expression (compute_expr)
An optional Fx source on FieldDef that derives the field’s value from other fields (and reference projections) at write time. A field with compute_expr is “calculated”: the write payload MUST NOT supply a value for it. Materialized into m_<model>.<slug> (active version) and record_version_sidecar (superseded versions). Mutually exclusive with default_expr. Forbidden on Primitive::Reference fields in v1 (the derived-edge semantic conflicts with ADR-0032’s authoritative-edge contract). See ADR-0022.
Eager-recompute opt-in (recompute_on_invalidate)
A bool on FieldDef (default false) paired with compute_expr. When true, ADR-0021’s invalidation walker eagerly recomputes the field synchronously at the triggering write instead of merely marking the cache row stale. Lifts the synchronous recompute cost from read-time to write-time — appropriate for low-fanout dependent fields with hot reads. Setting true without compute_expr is a publish-time error. See ADR-0021, ADR-0022.
Invalidation broadcast (ComputedInvalidated event)
A lightweight broker-only event the platform emits to subscribers when a cross-record write triggers ADR-0021’s invalidation cascade. Carries only metadata — model slug, record id, field slug, optional source context — never the recomputed value. Subscribers maintaining a local cache use it as a cache-coherence signal; they decide when (or whether) to refetch. Not persisted to the audit log: the source-record write is the audit-ground-truth event, and the broadcast is its transient consequence. See ADR-0021, ADR-0022.
Fx
The platform’s expression language. Used by validation rules, computed fields, default values, index expressions, and visibility rules. Domain-typed: every expression has a static type drawn from primitive × cardinality × sensitivity. Pure by construction (no I/O in the grammar, no recursion).now is bindable on every surface; expressions that read it are flagged volatile by the analyzer and the projection writer adapts caching strategy accordingly. Single-parameter arrow lambdas (x => body) appear only as method-call arguments and may capture outer-scope identifiers. Statically analyzable for read-set, volatility, side-effect freedom, and sensitivity flow. Named for Flux, the platform. One evaluator implementation (the fx-lang Rust evaluator, driven by the GrammarManifest) with multiple deployment targets — see Fx evaluator target. See ADR-0017, ADR-0034.
Volatility
A static flag on an Fx expression:stable if the result depends only on the record state at write time; volatile if it depends on now (directly or transitively, including through a lambda body). Volatile expressions on the index surface are not query-ready in v1; the storage / queryability strategy (recompute-on-read, scheduled refresh, or reject-on-publish) is deferred to a future ADR (tracked as PLAT-116) — the v1 language commits only that now is bindable on the index surface and that the analyzer emits the Volatility::Volatile flag. Volatile validators / computed fields are valid; computed-field cache freshness is owned by ADR-0008. See ADR-0017 §“Static analysis”.
Decision trace
A tree-shaped record of how a boolean Fx expression evaluated, used by visibility rules for explanation-grade audit. Nodes captureLeaf (atomic comparisons), And/Or (with the index of the short-circuited child when applicable), Not, SensitivityGate (required vs actual sensitivity, granted), and PredicateEval (one node per element of a lambda-taking iteration, with the element’s index and record_slug). Validators in v1 do not emit traces (rule names + messages already serve); visibility rules emit a trace per redaction (see ADR-0017 §“Visibility audit volume” for the per-request-summary policy). See ADR-0017 §“Decision traces”.
Read-set
The set of fields and reference-traversal chains that an Fx expression depends on, derived from the typed AST at publish time and stored onfield_def. Drives cache invalidation in projections per ADR-0008: when a record write changes any field in a calculated field’s read-set, the dependent calc cells are invalidated. There is no runtime read-set violation — the grammar makes it impossible to author one. See ADR-0017.
Lifecycle
The state of a model or model version:draft, active, or retired. Lifecycle is independent of the model’s pretty name and slug.
Tombstone
A persisted marker that a slug has been used and may not be reused. Tombstones are how the platform enforces slug uniqueness across deletions.Session
A WebTransport connection between a client and the platform, established by a QUIC handshake followed by an application-layer auth handshake on the control stream. Bound to exactly one principal and one tenant for its lifetime. Carries one control stream plus on-demand op streams and data streams. See ADR-0023.Control stream
The single bidirectional WebTransport stream opened immediately after a session is established. Carries session-lifetime traffic: auth handshake, capability negotiation, heartbeat, server-pushed subscription events, versioning frames, graceful shutdown. There is exactly one control stream per session. See ADR-0023.Op
A single application-layer interaction with the platform — for example “create record”, “list models”, “open subscription”. Each op is a typed Postcard variant ofOp with a corresponding OpResponse (or OpError). Ops run on their own bidirectional op stream; stream identity is op identity. See ADR-0023.
Op stream
The bidirectional WebTransport stream that carries one op from request to response. The first frame is the op envelope (op kind, protocol version, capability bits used, trace context); subsequent frames carry the request body and the response. Cancellation is stream close. See ADR-0023.Data stream
A unidirectional WebTransport stream that carries bulk Avro-encoded data (an Object Container File) for an op. Parented by an op stream; the op envelope or response declares which data streams to expect. May flow server-to-client (e.g., query results) or client-to-server (e.g., bulk import). See ADR-0023.Protocol version
The major version of the platform protocol, negotiated as au32 at handshake. The server advertises supported versions; the client selects one. Major bumps are ADR-gated and rare; day-to-day evolution uses capabilities. See ADR-0023.
Capability
A named feature flag advertised by the server and selected (or downgraded) by the client at handshake. Capabilities are additive within a protocol version; old capabilities can be retired by removing them from the server’s advertisement. Capabilities are the platform’s primary protocol-evolution unit. See ADR-0023.Subscription
A long-lived op type that delivers server-pushed events on a dedicated stream until canceled. Subscription events are projections of the audit log per ADR-0007; every event carries the audit event’scorrelation_id for deduplication on reconnect. V1 subscription kinds: record events (per tenant and model, optionally filtered by an Fx predicate), model events, audit-log tail. See ADR-0023.
OpError
The typed error result of an op, returned in place of anOpResponse. A closed Postcard enum with variants Auth, Validation, NotFound, RateLimited, PreconditionFailed, Conflict, and Internal. Every variant carries something correlatable to the audit log (a trace_id, a slug, or a structured detail). Replaces RFC 7807 problem+json (per ADR-0012, now superseded). See ADR-0023.