@finos/legend-query-builder 4.19.13 → 4.19.15

package/docs/query-lambda-round-trip.md

@@ -0,0 +1,707 @@
+# Query Builder — The Lambda Round Trip
+
+> Technical reference for `@finos/legend-query-builder`.
+>
+> Audience: engineers working on the query builder, the graph manager
+> (`@finos/legend-graph`), or any application that embeds `QueryBuilderState`.
+
+A query in Legend has no single representation. It exists as five different
+things at different points in its life, and the query builder's central job is
+converting between them without losing information:
+
+```
+ raw JSON  ⇄  V1_RawLambda  ⇄  ValueSpecification / LambdaFunction  ⇄  QueryBuilderState
+    │                                                                      │
+    └──────────────────── PURE grammar text ───────────────────────────────┘
+                          (via the engine)
+```
+
+This document traces that cycle in both directions, explains why each hop
+exists, and covers where the engine sits in it.
+
+**Contents**
+
+1. [The representations](#1-the-representations)
+2. [Inbound: JSON → UI state](#2-inbound-json--ui-state)
+3. [Outbound: UI state → JSON](#3-outbound-ui-state--json)
+4. [How the lambda reaches the engine](#4-how-the-lambda-reaches-the-engine)
+5. [Grammar (text) mode](#5-grammar-text-mode)
+6. [When the round trip fails](#6-when-the-round-trip-fails)
+7. [Change detection](#7-change-detection)
+
+---
+
+## 1. The representations
+
+### 1.1 `RawLambda` — the transport form
+
+[`RawLambda`](../../legend-graph/src/graph/metamodel/pure/rawValueSpecification/RawLambda.ts)
+is deliberately dumb:
+
+```ts
+export class RawLambda extends RawValueSpecification implements Hashable {
+  body?: object | undefined;
+  parameters?: object | undefined;
+}
+```
+
+`body` and `parameters` are **untyped JSON**. Nothing is resolved, nothing is
+validated. Its protocol twin `V1_RawLambda` serializes them with serializr's
+`raw()`, which passes the payload through verbatim:
+
+```ts
+export const V1_rawLambdaModelSchema = createModelSchema(V1_RawLambda, {
+  _type: usingConstantValueSchema(V1_RawValueSpecificationType.LAMBDA),
+  body: raw(),
+  parameters: raw(),
+});
+```
+
+That opacity is the point. A `RawLambda` can hold a query using functions this
+version of Studio has never heard of, round-trip it to the engine, and store it
+again — byte-for-byte. It is what gets **persisted** (`Query.content`, service
+executions) and what goes **over the wire**.
+
+### 1.2 `ValueSpecification` / `LambdaFunction` — the metamodel form
+
+[`LambdaFunction`](../../legend-graph/src/graph/metamodel/pure/valueSpecification/LambdaFunction.ts)
+is the resolved tree:
+
+```ts
+export class LambdaFunction implements Hashable {
+  functionType: FunctionType; // parameters + return type
+  openVariables: Map<string, VariableExpression>;
+  expressionSequence: ValueSpecification[]; // the actual expressions
+}
+```
+
+Every node is a real `ValueSpecification` — `SimpleFunctionExpression`,
+`AbstractPropertyExpression`, `VariableExpression`, `InstanceValue`, … — and
+every reference into the model is a resolved `PackageableElementReference`
+pointing at a live `Class`, `Property`, or `Enum` in the `PureModel` graph.
+
+This is the form the query builder can actually reason about: you cannot ask a
+blob of JSON "what class does this property belong to", but you can ask a
+resolved `AbstractPropertyExpression`.
+
+`LambdaFunction` is wrapped in a `LambdaFunctionInstanceValue` whenever it needs
+to be treated as a `ValueSpecification` (which is how it crosses the
+serialization boundary — see below).
+
+### 1.3 `QueryBuilderState` — the UI form
+
+[`QueryBuilderState`](../src/stores/QueryBuilderState.ts) is not a tree at all.
+It is a set of MobX-observable, purpose-built sub-states:
+
+| Sub-state               | Holds                                                   |
+| ----------------------- | ------------------------------------------------------- |
+| `explorerState`         | the class explorer tree + mapping model coverage        |
+| `filterState`           | the filter tree                                         |
+| `fetchStructureState`   | projection / graph-fetch columns, aggregations, sorting |
+| `parametersState`       | `LambdaParameterState[]` — parameters and their values  |
+| `constantState`         | `let` constants                                         |
+| `milestoningState`      | business/processing temporal parameters                 |
+| `watermarkState`        | watermark expression                                    |
+| `executionContextState` | mapping + runtime                                       |
+| `resultState`           | execution results, grid config                          |
+| `unsupportedQueryState` | the escape hatch (§6)                                   |
+
+The mapping from one flat expression tree to a dozen independent observable
+states is lossy in one direction and reconstructive in the other. That
+asymmetry is the source of most of the complexity below.
+
+### 1.4 Why not fewer representations?
+
+- **Raw ⇄ metamodel** exists because persistence must survive functions the
+  client cannot interpret, while the UI needs resolved references.
+- **Metamodel ⇄ UI state** exists because a query builder is not a tree editor.
+  Users think in "filters", "columns", "sorts" — not in nested
+  `SimpleFunctionExpression` parameters.
+- **Grammar text** exists because the engine is the only thing that can parse
+  and print PURE.
+
+---
+
+## 2. Inbound: JSON → UI state
+
+Entry point:
+[`QueryBuilderState.initializeWithQuery(query: RawLambda, …)`](../src/stores/QueryBuilderState.ts),
+which delegates to `rebuildWithQuery` and then snapshots for change detection:
+
+```ts
+initializeWithQuery(query, defaultParameterValues?, gridConfig?): void {
+  this.rebuildWithQuery(query, { defaultParameterValues });
+  this.resetQueryResult({ gridConfig });
+  this.changeDetectionState.initialize(query);
+  this.changeHistoryState.initialize(query);
+}
+```
+
+### 2.1 `RawLambda` → `ValueSpecification`
+
+Inside `rebuildWithQuery`, the conversion is two graph-manager calls composed:
+
+```ts
+const valueSpec = observe_ValueSpecification(
+  this.graphManagerState.graphManager.buildValueSpecification(
+    this.graphManagerState.graphManager.serializeRawValueSpecification(query),
+    this.graphManagerState.graph,
+  ),
+  this.observerContext,
+);
+```
+
+Read it inside-out — **JSON is the pivot**:
+
+| Step | Call                                        | Transformation                                          |
+| ---- | ------------------------------------------- | ------------------------------------------------------- |
+| 1    | `serializeRawValueSpecification(rawLambda)` | `RawLambda` → `V1_RawLambda` → `PlainObject` (raw JSON) |
+| 2    | `buildValueSpecification(json, graph)`      | JSON → `V1_ValueSpecification` → `ValueSpecification`   |
+| 3    | `observe_ValueSpecification(...)`           | makes the tree MobX-observable                          |
+
+Step 2 is where the real work happens
+([`V1_PureGraphManager.buildValueSpecification`](../../legend-graph/src/graph-manager/protocol/pure/v1/V1_PureGraphManager.ts)):
+
+```ts
+buildValueSpecification(json: PlainObject, graph: PureModel): ValueSpecification {
+  return V1_buildValueSpecification(
+    V1_deserializeValueSpecification(json, plugins),
+    new V1_GraphBuilderContextBuilder(graph, graph, extensions, logService).build(),
+  );
+}
+```
+
+- `V1_deserializeValueSpecification` dispatches on the `_type` discriminator —
+  `'func'`, `'property'`, `'var'`, `'lambda'`, `'collection'`, `'string'`,
+  `'packageableElementPtr'`, `'classInstance'`, … (the full set is
+  `V1_ValueSpecificationType` in
+  [`V1_ValueSpecificationSerializer.ts`](../../legend-graph/src/graph-manager/protocol/pure/v1/transformation/pureProtocol/serializationHelpers/V1_ValueSpecificationSerializer.ts)).
+  Output: a `V1_*` protocol tree — still just data, but typed.
+- `V1_buildValueSpecification` walks that tree with a **graph builder context**
+  and resolves every path against the `PureModel`. `"model::Person"` stops being
+  a string and becomes a reference to the actual `Class`.
+
+Note the `V1_Lambda` case specifically — the protocol `V1_Lambda` becomes a
+`LambdaFunctionInstanceValue` wrapping a built `LambdaFunction`, with a **cloned
+processing context** so the lambda's own variables don't leak into the enclosing
+scope:
+
+```ts
+visit_Lambda(valueSpecification: V1_Lambda): ValueSpecification {
+  const instanceValue = new LambdaFunctionInstanceValue();
+  instanceValue.values = [
+    V1_buildLambdaBody(
+      valueSpecification.body,
+      valueSpecification.parameters,
+      this.context,
+      this.processingContext.clone(), // clone the context for lambda
+    ),
+  ];
+  return instanceValue;
+}
+```
+
+This is why the top-level result is unwrapped with a `guaranteeType` before
+processing:
+
+```ts
+const compiledValueSpecification = guaranteeType(
+  valueSpec,
+  LambdaFunctionInstanceValue,
+  `Can't build query state: query builder only support lambda`,
+);
+processQueryLambdaFunction(
+  guaranteeNonNullable(compiledValueSpecification.values[0]), // the LambdaFunction
+  this,
+  { parameterValues: previousStateParameterValues },
+);
+```
+
+### 2.2 `LambdaFunction` → `QueryBuilderState`
+
+[`processQueryLambdaFunction`](../src/stores/QueryBuilderStateBuilder.ts) is
+short, and its brevity hides the dispatch machinery underneath:
+
+```ts
+export const processQueryLambdaFunction = (
+  lambdaFunction,
+  queryBuilderState,
+  parameterOptions?,
+) => {
+  if (lambdaFunction.functionType.parameters.length) {
+    processParameters(
+      lambdaFunction.functionType.parameters,
+      queryBuilderState,
+      parameterOptions,
+    );
+  }
+  lambdaFunction.expressionSequence.map((expression) =>
+    QueryBuilderValueSpecificationProcessor.process(
+      expression,
+      lambdaFunction,
+      queryBuilderState,
+    ),
+  );
+};
+```
+
+`QueryBuilderValueSpecificationProcessor` is a `ValueSpecificationVisitor<void>`
+that walks the tree and **mutates the appropriate sub-state** as it recognises
+each function.
+
+**The traversal is inverted relative to how you read the query.** The source
+comment on the processor explains this better than a paraphrase can, so it is
+worth reading in full — but the essential point:
+
+```
+Person.all()->filter(x|$x.age > 0)->project([x|$x.name], ['Name'])->sort([desc('Name')])
+```
+
+is, structurally:
+
+```
+sort(project(filter(all(Person), …), …), …)
+```
+
+So the tree root is `sort`, and `getAll` is the _deepest_ node. Reading order is
+`all → filter → project → sort`; traversal order is the reverse. The processor
+therefore carries two pieces of context:
+
+- `parentExpression` — the enclosing `SimpleFunctionExpression`, used to
+  validate usage (e.g. `desc()` is only legal inside `sort()`).
+- `parentLambda` — the enclosing `LambdaFunction`, needed to resolve variables.
+
+`processChild(...)` is how the processor recurses while supplying that context.
+
+Recognised functions are matched against `QUERY_BUILDER_SUPPORTED_FUNCTIONS` and
+routed to the owning sub-state — `filter()` populates `filterState`, `project()`
+and `groupBy()` populate `fetchStructureState`, `let` statements populate
+`constantState`, and so on. Anything unrecognised takes the path in §6.
+
+Execution-context wrappers are recognised too, so a lambda saved with its
+context embedded (§3.1, step 5) can be reopened in form mode: `from()` is
+consumed into `executionContextState`, and `with(body, dataProduct)` — emitted
+for Data Product-backed contexts — is processed by stepping straight into its
+first parameter, the query body.
+
+Finally `fetchStructureState.initializeWithQuery()` runs, letting the
+fetch-structure implementation do its own post-processing once the whole tree
+has been consumed.
+
+---
+
+## 3. Outbound: UI state → JSON
+
+Entry point: [`QueryBuilderState.buildQuery()`](../src/stores/QueryBuilderState.ts).
+
+```ts
+buildQuery(options?: { keepSourceInformation: boolean }): RawLambda {
+  if (!this.isQuerySupported) { /* … see §6 … */ }
+  return buildRawLambdaFromLambdaFunction(
+    buildLambdaFunction(this, {
+      keepSourceInformation: Boolean(options?.keepSourceInformation),
+      useTypedRelationFunctions: this.isFetchStructureTyped,
+    }),
+    this.graphManagerState,
+  );
+}
+```
+
+### 3.1 `QueryBuilderState` → `LambdaFunction`
+
+[`buildLambdaFunction`](../src/stores/QueryBuilderValueSpecificationBuilder.ts)
+assembles the expression sequence **in a fixed order**, because the order of
+composition _is_ the semantics of the query:
+
+1. **Source.** A `Class` source produces `getAll()` /
+   `getAllVersions()` / `getAllVersionsInRange()` depending on
+   `queryBuilderState.getAllFunction` and the class's milestoning stereotype
+   (milestoned classes get their temporal parameters injected here by
+   `milestoningState`). A non-class source produces an `AccessorInstanceValue`.
+2. **Watermark** — `buildWatermarkExpression(watermarkState, lambdaFunction)`.
+3. **Filter** — `buildFilterExpression(filterState, lambdaFunction)`.
+4. **Fetch structure** — `buildFetchStructure(...)`; projection columns,
+   aggregations, sorting, graph-fetch trees.
+5. **Execution context** — `buildExecutionContextExpression(...)`. Whether
+   anything is emitted depends on the kind of `executionContextState`:
+
+   - `QueryBuilderExternalExecutionContextState` (the default) — **nothing**
+     is added. Mapping and runtime travel as separate fields on the execute
+     input instead (§4.1).
+   - `QueryBuilderEmbeddedFromExecutionContextState` — the body is wrapped in
+     `->from(mapping, runtime)` by `buildExecutionContextState`.
+
+   `reconcileExecutionContextState()` swaps between the two according to
+   `requiresEmbeddedExecutionContext`, which is true for typed/relation fetch
+   structures, accessor sources, data products, and data spaces whose execution
+   context has a Data Product mapping provider. Those last two override
+   `buildExecutionContextExpression` again to emit
+   `->with(dataProduct)->from(runtime)` (`attachWithFromQuery`), because their
+   mapping comes from the Data Product rather than the project.
+
+   Skippable via `skipExecutionContext` (see §3.3).
+
+6. **Constants** — `let` expressions are **prepended** to the expression
+   sequence.
+7. **Parameters** — assigned to `lambdaFunction.functionType.parameters`.
+
+Each step takes the `lambdaFunction` built so far and wraps it, so the tree
+grows outward from `getAll()`.
+
+### 3.2 `LambdaFunction` → `RawLambda`
+
+[`buildRawLambdaFromLambdaFunction`](../../legend-graph/src/graph-manager/helpers/ValueSpecificationGraphManagerHelper.ts):
+
+```ts
+export const buildRawLambdaFromLambdaFunction = (
+  lambdaFunction,
+  graphManagerState,
+): RawLambda => {
+  const lambdaFunctionInstanceValue = new LambdaFunctionInstanceValue();
+  lambdaFunctionInstanceValue.values = [lambdaFunction];
+  return guaranteeType(
+    graphManagerState.graphManager.transformValueSpecToRawValueSpec(
+      lambdaFunctionInstanceValue,
+      graphManagerState.graph,
+    ),
+    RawLambda,
+  );
+};
+```
+
+And `transformValueSpecToRawValueSpec` is, again, **JSON as the pivot**:
+
+```ts
+transformValueSpecToRawValueSpec(valueSpecification, graph): RawValueSpecification {
+  const json = this.serializeValueSpecification(valueSpecification); // metamodel → V1 → JSON
+  return this.buildRawValueSpecification(json, graph);               // JSON → V1_RawLambda → RawLambda
+}
+```
+
+- `serializeValueSpecification` runs `V1_transformRootValueSpecification`
+  (metamodel → `V1_*` protocol, dropping resolved references back down to
+  paths) then `V1_serializeValueSpecification` (protocol → JSON).
+- `buildRawValueSpecification` deserializes that same JSON as a
+  `V1_RawValueSpecification` and builds a `RawLambda` — whose `body` and
+  `parameters` are the JSON sub-objects, untouched.
+
+So the outbound path is the exact mirror of §2.1. In both directions the two
+worlds only ever meet as plain JSON; there is no direct `LambdaFunction ⇄
+RawLambda` converter, by design.
+
+### 3.3 The three build variants
+
+| Method                                  | Used for                        | Difference                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `buildQuery()`                          | general use, text mode, compile | the full lambda                                                                                                                                                                                                                                                                                                                             |
+| `buildQueryForPersistence()`            | saving to the query store       | delegates to `buildQuery()` by default; overridden by `DataSpaceQueryBuilderState`, `DataProductQueryBuilderState`, and `AccessorQueryBuilderState` to build without the execution context (`skipExecutionContext`) — the context is persisted separately on `Query.executionContext`, so embedding it in the lambda too would duplicate it |
+| `resultState.buildExecutionRawLambda()` | running the query               | passes `isBuildingExecutionQuery: true`, which routes parameters through `buildExecutionQueryFromLambdaFunction`                                                                                                                                                                                                                            |
+
+That last one matters. For execution, parameters whose values are **function
+calls** cannot stay as lambda parameters — the engine would have nothing to bind
+them to. `buildExecutionQueryFromLambdaFunction`
+([`LambdaParameterState.ts`](../src/stores/shared/LambdaParameterState.ts))
+handles this by:
+
+1. removing those parameters from `functionType.parameters`, and
+2. prepending `let` statements that assign their values.
+
+Plain-valued parameters are left as parameters and supplied separately as
+`parameterValues` on the execution input.
+
+---
+
+## 4. How the lambda reaches the engine
+
+Everything the client sends the engine carries a **`V1_RawLambda`**, never a
+`LambdaFunction`. The engine does its own parsing and compilation; shipping the
+resolved metamodel would be both redundant and lossy.
+
+### 4.1 Execution
+
+[`V1_ExecuteInput`](../../legend-graph/src/graph-manager/protocol/pure/v1/engine/execution/V1_ExecuteInput.ts)
+is the payload:
+
+```ts
+export class V1_ExecuteInput {
+  clientVersion: string | undefined;
+  /**
+   * Studio does not process value specification, they are left in raw JSON form
+   * @discrepancy model
+   */
+  function!: V1_RawLambda;
+  mapping: string | undefined;
+  model!: V1_PureModelContext;
+  runtime: V1_Runtime | undefined;
+  context!: V1_RawExecutionContext;
+  parameterValues: V1_ParameterValue[] = [];
+}
+```
+
+Assembled by `createExecutionInputWithPureModelContext` in
+[`V1_PureGraphManager.ts`](../../legend-graph/src/graph-manager/protocol/pure/v1/V1_PureGraphManager.ts):
+
+- `V1_transformRawLambda(lambda, …)` — `RawLambda` → `V1_RawLambda`.
+- `model` — the `V1_PureModelContext`, chosen in `createExecutionInput`:
+
+  ```ts
+  let context: V1_PureModelContext = graph.origin
+    ? this.buildPureModelSDLCPointer(graph.origin, undefined) // GAV pointer
+    : this.getFullGraphModelData(graph); // the whole model inline
+  ```
+
+  When the graph carries an `origin` — which is exactly what the minimal-graph
+  build stamps on it (`{ origin: new LegendSDLC(groupId, artifactId, version) }`)
+  — only a **pointer** is sent and the engine resolves the model itself. This is
+  what makes the minimal graph viable end-to-end: the client never held the
+  whole model, and never needs to send it.
+
+  Elements that exist only client-side (`options.floatingExecutionElements` —
+  e.g. the adhoc Lakehouse runtimes registered as `_internal_`) are appended as
+  a `V1_PureModelContextData` and combined via `V1_PureModelContextCombination`,
+  so a pointer-based context can still carry them.
+
+- `mapping` / `runtime` — sent as separate fields…
+
+…**unless** `options.forceFromExpression` is set. In that case the manager
+rewrites the lambda body to wrap it in a `from()` expression and clears the
+separate fields:
+
+```ts
+__fromExpression = (
+  mapping: string | undefined,
+  runtime: string,
+  body: object,
+): object => ({
+  _type: 'func',
+  function: 'from',
+  parameters: [
+    body,
+    mapping ? { _type: 'packageableElementPtr', fullPath: mapping } : undefined,
+    { _type: 'packageableElementPtr', fullPath: runtime },
+  ].filter(isNonNullable),
+});
+```
+
+Note this is hand-built **raw JSON**, not metamodel construction — legitimate
+precisely because `V1_RawLambda.body` is opaque. Multi-expression bodies (i.e.
+lambdas with `let` statements) get only their **last** expression wrapped, since
+that is the one producing the result.
+
+### 4.2 Compilation / type-checking
+
+`compileQuery()` does not use a separate compile endpoint — it asks the engine
+for the lambda's return type and treats success as "compiles":
+
+```ts
+yield this.graphManagerState.graphManager.getLambdaReturnType(
+  this.buildQuery({ keepSourceInformation: true }),
+  this.graphManagerState.graph,
+  { keepSourceInformation: true },
+);
+```
+
+`keepSourceInformation: true` is deliberate. Source information maps expressions
+back to positions, which is what lets a compilation error be **pinned to the
+right element in form mode** rather than reported as an opaque failure. It is
+pruned everywhere it isn't needed (`pruneSourceInformation`), since it
+substantially inflates the payload.
+
+`getLambdaRelationType` is the equivalent for relation-typed fetch structures.
+
+### 4.3 Grammar transformation
+
+| Direction          | Graph manager API                                                     | Engine                                                                                  |
+| ------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| text → lambda      | `pureCodeToLambda(code, lambdaId, options)`                           | `transformCodeToLambda`; result becomes `new RawLambda(result.parameters, result.body)` |
+| lambda → text      | `lambdaToPureCode(lambda, pretty)` / `lambdasToPureCode(map, pretty)` | `transformLambdaToCode(s)`                                                              |
+| value specs → text | `valueSpecificationsToPureCode(map, pretty)`                          | serializes each via `serializeValueSpecification` first                                 |
+
+The client never parses or prints PURE itself.
+
+---
+
+## 5. Grammar (text) mode
+
+[`QueryBuilderTextEditorState`](../src/stores/QueryBuilderTextEditorState.ts)
+implements the "edit as text" escape hatch, and it is a complete lap of the
+cycle.
+
+**Opening the modal** (`openModal`):
+
+```ts
+const rawLambda = this.queryBuilderState.buildQuery(); // §3
+if (mode === TEXT) {
+  this.setQueryRawLambdaState(new QueryBuilderRawLambdaState(rawLambda));
+}
+if (mode === JSON) {
+  this.setLambdaJson(
+    JSON.stringify(
+      pruneSourceInformation(
+        graphManager.serializeRawValueSpecification(rawLambda),
+      ),
+      null,
+      DEFAULT_TAB_SIZE,
+    ),
+  );
+}
+```
+
+JSON mode is **read-only** — it displays the exact protocol payload, source
+information stripped.
+
+**While open**, `convertLambdaObjectToGrammarString` calls `lambdasToPureCode`
+to render the text; `convertLambdaGrammarStringToObject` calls `pureCodeToLambda`
+to parse edits back, capturing `ParserError` for inline display.
+
+**Closing the modal** (`closeModal`) — the round trip completes:
+
+```ts
+yield flowResult(this.convertLambdaGrammarStringToObject()); // text → RawLambda
+if (this.parserError) {
+  notifyError(`Can't parse query. Please fix error before closing: …`);
+} else {
+  this.queryBuilderState.rebuildWithQuery(this.rawLambdaState.lambda, {
+    // → §2
+    preserveParameterValues: true,
+    preserveResult: true,
+  });
+}
+```
+
+A parse error **blocks closing**; the user cannot escape text mode with a query
+the client cannot represent. But a query that parses and yet isn't
+_recognisable_ to the processor will close fine and land in the unsupported
+state below — those are different failures.
+
+---
+
+## 6. When the round trip fails
+
+`rebuildWithQuery` wraps the entire inbound conversion in a `try`/`catch`. On
+any failure — deserialization, unresolvable reference, unrecognised function
+shape — it degrades rather than throwing:
+
+```ts
+} catch (error) {
+  logService.error(LogEvent.create(QUERY_BUILDER_EVENT.UNSUPPORTED_QUERY_LAUNCH), error);
+  this.resetQueryResult({ preserveResult: options?.preserveResult });
+  this.resetQueryContent();
+  this.unsupportedQueryState.setLambdaError(error);
+  this.unsupportedQueryState.setRawLambda(query);   // keep the original, verbatim
+  this.setSourceElement(undefined);
+  const parameters = buildLambdaVariableExpressions(query, this.graphManagerState)
+    .map((param) => observe_ValueSpecification(param, this.observerContext))
+    .filter(filterByType(VariableExpression));
+  processParameters(parameters, this, { parameterValues: previousStateParameterValues });
+}
+```
+
+Two things survive the failure:
+
+- **The original `RawLambda`**, stored on `unsupportedQueryState`. The user gets
+  a text view instead of the form, and can still run and save the query — it is
+  never rewritten or lost.
+- **The parameters**, recovered independently via
+  `buildLambdaVariableExpressions`, which converts only
+  `rawLambda.parameters[]` (not the body). Parameters are structurally simple
+  enough to build even when the body is not, so the parameter panel keeps
+  working.
+
+`buildQuery()` mirrors this on the way out — when `!isQuerySupported`, it
+returns the stored raw lambda with freshly serialized parameters spliced in,
+rather than trying to rebuild from state that was never populated:
+
+```ts
+if (!this.isQuerySupported) {
+  const parameters = this.parametersState.parameterStates.map((e) =>
+    this.graphManagerState.graphManager.serializeValueSpecification(
+      e.parameter,
+    ),
+  );
+  this.unsupportedQueryState.setRawLambda(
+    new RawLambda(parameters, this.unsupportedQueryState.rawLambda?.body), // body untouched
+  );
+  return guaranteeNonNullable(this.unsupportedQueryState.rawLambda);
+}
+```
+
+There is also a node-level escape hatch: `INTERNAL__UnknownValueSpecification`
+holds an unrecognised sub-tree as `readonly content: PlainObject`, letting a
+_mostly_ supported query keep one opaque fragment (e.g. a derivation expression
+inside `project()`) without failing wholesale.
+
+**Design principle:** the query builder will refuse to _edit_ a query it does
+not understand, but it will never silently _alter_ one.
+
+---
+
+## 7. Change detection
+
+[`QueryBuilderChangeDetectionState`](../src/stores/QueryBuilderChangeDetectionState.ts)
+answers "has the user modified the query?" — and notably does **not** do it by
+rebuilding and comparing lambdas:
+
+```ts
+initialize(initialQuery: RawLambda): void {
+  this.hashCodeSnapshot = this.querybuilderState.hashCode;  // hash of the UI STATE
+  this.querySnapshot = initialQuery;                        // the raw lambda, for diffing
+}
+
+get hasChanged(): boolean {
+  return this.querybuilderState.hashCode !== this.hashCodeSnapshot;
+}
+```
+
+The comparison is on `QueryBuilderState.hashCode` — a hash over the observable
+sub-states (see `QueryBuilderStateHashUtils.ts`), not over the serialized
+lambda. This is a deliberate performance trade: checking for changes on every
+keystroke by running the full §3 pipeline (build tree → transform → serialize)
+would be far too expensive, whereas the state hash is cheap and MobX-memoized.
+
+`querySnapshot` retains the original `RawLambda` separately, so the diff view
+(`QueryBuilderDiffViewState`) can show a real before/after in grammar form.
+
+One consequence worth knowing: because the hash covers UI state rather than the
+emitted lambda, two states that serialize to equivalent lambdas but differ in
+some non-semantic way can register as "changed". This errs toward prompting the
+user to save — the safe direction.
+
+---
+
+## 8. Summary
+
+```
+                    PERSISTENCE (Query.content)  ◄──────────┐
+                             │                              │
+                             ▼                              │
+   ┌──────────────────  RawLambda  ─────────────────────┐    │
+   │                  (opaque JSON)                     │    │
+   │                        │                           │    │
+   │  serializeRawValueSpecification                    │ buildRawValueSpecification
+   │                        ▼                           │    │
+   │                    raw JSON  ────────────────────► │    │
+   │                        │            ▲              │    │
+   │  buildValueSpecification            │ serializeValueSpecification
+   │  (resolves against PureModel)       │              │    │
+   │                        ▼            │              │    │
+   │              LambdaFunction ────────┘              │    │
+   │                        │            ▲              │    │
+   │  processQueryLambdaFunction         │ buildLambdaFunction
+   │  (visitor → sub-states)             │ (ordered assembly)
+   │                        ▼            │              │    │
+   │                 QueryBuilderState ──┘              │    │
+   └────────────────────────────────────────────────────┘    │
+                             │                               │
+                             └──────► V1_ExecuteInput.function (V1_RawLambda) ──► ENGINE
+```
+
+Three invariants hold throughout:
+
+1. **JSON is the only bridge** between the raw and metamodel worlds, in both
+   directions. There is no direct converter, and adding one would bypass the
+   protocol layer that makes version tolerance work.
+2. **The engine only ever sees `V1_RawLambda`.** The resolved metamodel is a
+   client-side convenience; it never crosses the wire.
+3. **An unparseable query is preserved, not repaired.** Every failure path keeps
+   the user's original bytes.