Vocabulary | BizFirst Expression Evaluation

A–C

Term	Definition
AtBrace Syntax	The default wildcard syntax: `{@ $directive.path @option }`. Delimited by `{@` and `}`. See WildcardSyntax.
AtSign Syntax	Canned expression shorthand: `@alias.name`. Parsed by `AtSignWildcardParser`. Only routes to the canned expression directive.
Alias	The name portion of a canned expression reference (e.g., `company.currency` in `@company.currency`).
Assignment Layer	The layer above the directive system. Reads `OutputFieldName` and `OutputTarget` from `FieldConstraints` to know where to write the resolved value in the node's output.
BaseDirectiveEvaluator	Abstract base class in the Domain project. Handles timing, stores the active request, exposes protected helpers (`ChainExpressionAsync`, `ChainToDirectiveAsync`, `GuardChainDepth`). All concrete directives extend this.
Canned Expression	A named alias stored in the `Expression_CannedExpressions` database table that maps to a full expression string. Resolved via the `@alias` syntax. Supports tenant and app-level scoping.
CacheHit	A flag on `EvaluationResponse` set to `true` when the response was served from the `IExpressionCache` rather than evaluated by the directive. `DurationMs` is `0` for cache hits.
CacheScope	Enum controlling cache lifetime: `Node` (current node execution), `Thread` (workflow thread), `Process` (top-level workflow process).
Chain / Chaining	When a directive's resolved value is itself an expression that needs further evaluation. Chains increment `Depth`. Two methods: `ChainExpressionAsync` (re-parse) and `ChainToDirectiveAsync` (direct route).

D–F

Term	Definition
Default Directive	The fallback directive used when an expression has no explicit `$directive` name. Registered as `IDefaultExpressionDirectiveService`. Configured via `ExpressionEvaluation:DefaultDirectiveName`.
Depth	Integer counter on `EvaluationRequest` tracking how many chain levels deep the evaluation is. Hard limit: 10. Shared across directive chaining and multi-pass template interpolation.
Directive	A named, DI-registered implementation of `IExpressionDirectiveService` that resolves a specific type of expression. The name (without `$`) is the DI lookup key. Examples: `ctx`, `var`, `input`.
DirectiveName	The string property on a directive (e.g., `"ctx"` for the `$ctx` directive). Used as the DI key. Never includes the `$` prefix.
DirectiveToken	A parsed token from an expression representing a directive segment. An expression may have two directive tokens: the first routes to the directive, the second (optional) specifies a data-source sub-context.
DoubleBrace Syntax	n8n/Handlebars-compatible wildcard syntax: `{{ $directive.path @option }}`. Parsed by `DoubleBraceWildcardParser`.
EvaluationContext	Immutable (init-only) object created once per node execution. Contains TenantId, ExecutionId, NodeKey, IsolationLevel, ActiveSyntax, Cache, Memory, NodeExecutionData, and CurrentUser. Passed through all directive invocations.
EvaluationRequest	Immutable per-expression payload: parsed Directives[], Path, Options[], RawExpression, Depth, VisitedKeys, and reference to Context. Created by the orchestrator; a new request is created for each chain.
EvaluationResponse	Immutable result returned by a directive. Created via factory methods: `Success(value)`, `Failure(errorCode, msg)`, `FromCache(source)`, `ShortCircuit(rawValue)`. Has lazy `FormattedValue` property.
ExpressionOrchestrator	The main pipeline entry point in `Core.Services`. Implements `IExpressionOrchestrator`. Detects wildcards, coordinates parsing, directive routing, option application, caching, and template interpolation.
FieldConstraints	Object on `EvaluationResponse` populated by options during `PopulateConstraints`. Holds `IsRequired`, `MustNotBeEmpty`, `DefaultValue`, `OutputFieldName`, and `OutputTarget`.
FormattedValue	Lazy string property on `EvaluationResponse`. Computed on first access by calling `FormatOutput` on the active option (or `ToString()` on the raw value). Used for string substitution in templates.

G–O

Term	Definition
GuardChainDepth	Protected method on `BaseDirectiveEvaluator`. Throws (or returns a failure response) if `request.Depth >= 10`. Must be called before every chain invocation.
ICacheMarkerOption	Marker interface extending `IDirectiveOption`. Implementations (`@cache`, `@cache-thread`, `@cache-process`) are handled by the orchestrator before directive invocation to check/populate the cache.
IDirectiveOption	Interface for post-resolution transforms. Methods: `PopulateConstraints`, `Apply`, `FormatOutput`. Registered as `IDirectiveOption` in DI; discovered by token name from the expression.
IExpressionDirectiveService	Interface every directive implements. Two members: `DirectiveName` string and `InvokeAsync(request, ct)`.
Interpolation	The process of finding all wildcard regions in a template string, evaluating them in parallel, and substituting their `FormattedValue` back into the original string.
IsolationLevel	Enum on `EvaluationContext` controlling which directives are permitted: `Safe` (data reads only), `Sandboxed` (adds `$js`), `Trusted` (adds `$cs` and `$api`).
Multi-pass Resolution	When an interpolated template string still contains wildcards after substitution, the orchestrator makes additional evaluation passes. Each pass increments Depth. Stops when no wildcards remain or Depth reaches 10.
Option	A post-resolution transform token in an expression, prefixed with `@`: e.g., `@uppercase`, `@json`, `@cache`. Multiple options can be combined in a single expression.
OutputTarget	Property on `FieldConstraints` indicating where the resolved value should be written: `@parent` (replace the parent node), `@parent-merge` (merge into parent), or a named field.

P–Z

Term	Definition
Parser	An implementation of `IWildcardParser`. Three built-in: `AtBraceWildcardParser`, `DoubleBraceWildcardParser`, `AtSignWildcardParser`. Selected via `IWildcardParserResolver` based on `EvaluationContext.ActiveSyntax`.
Path	The dot-separated string after the directive name in an expression. Examples: `user.name`, `customer.address.city`, `items[0].amount`. Each directive interprets its path according to its own rules.
Qualifier (deprecated)	Historical term for "directive" used in early design proposals. Replaced by Directive in Design V1 Decision #1.
RawExpression	The original full expression string including delimiters: e.g., `"{@ $ctx.user.name @uppercase }"`. Stored on `EvaluationRequest` for tracing and cache key construction.
Short-Circuit	An `EvaluationResponse` created via `ShortCircuit(rawValue)` when a field contains no wildcard syntax. Skips all parsing, directive invocation, and option application.
Sub-directive	When an expression has a second directive token specifying a data-source scope (e.g., `{@ $input $myNodeOutput.field }` — the second token `$myNodeOutput` narrows the data source). Not all directives support sub-directives.
Sub-path	The portion of the path after the first segment, used by directives that route internally. For `$ctx.user.name`: the first segment `user` routes to the UserHandler, the sub-path `name` is the specific property.
Template String	A field value containing one or more expressions embedded in literal text. `IWildcardParser.IsTemplate` returns true. Evaluated via parallel interpolation rather than single directive invocation.
Token	A single parsed unit from the expression: directive tokens (the `$name` segments) and option tokens (the `@name` segments).
VisitedKeys	Immutable set of string keys carried on `EvaluationRequest` tracking which expressions have been evaluated in the current chain. Prevents cycles in canned expression chains and multi-pass interpolation. Carried forward across all passes.
WildcardRegion	A span within a template string representing a single expression: start offset, end offset, and the expression text. Produced by `IWildcardParser.FindAllRegions`.
WildcardSyntax	Enum: `AtBrace`, `DoubleBrace`, `AtSign`. Set on `EvaluationContext` to select the active parser for all field evaluations in that node execution.