How to read the operator reference

Each operator page has two independent parts:

1. SrotaX behavior: definition, syntax, plain-language parameters, behavior, runnable examples and downloadable regression cases. Full input matrices are collapsed by default.
2. MongoDB differences: a separately marked final section with live comparison results and exact evidence.

The behavior tables are the documented contract for their tested inputs. They do not promise behavior for every input combination. Metadata types are authoring hints; observed runtime behavior can be broader or stricter. A compiler or Data Contract may reject an input before it reaches the engine.

Current coverage

The live comparison used MongoDB 9.0.4 and the Core source snapshot identified in the evidence. It ran 6,495 cases for 159 registered expression operators:

Outcome	Cases
Exact result, including BSON types	2,100
Both implementations rejected the expression	3,360
Different value, type, missing/null behavior, or acceptance	697
Same typed values; different object field order	7
Extension or different MongoDB context; not compared	331

99 operators have at least one observed difference. This suite does not establish full MongoDB compatibility. For example, an int32 result and an equal-valued double are reported as different. Both-rejected cases do not establish matching error codes or messages.

The eight names not compared as MongoDB expressions are $coalesce, $endsWith, $expr, $minDistance, $nin, $nor, $setIsSuperset, and $startsWith.

Interpreting the input tables

For each argument, the test replaces only that argument in the page's example. All others stay the same. Null means an explicitly null value; missing means an absent field. Typed dates and Decimal128 use Extended JSON in the downloadable input document. Ordinary JSON strings remain strings.

Tables include numeric, string, boolean, object and array inputs, empty values, mixed arrays and null/missing cases. Advertised optional named arguments are also probed individually, including options absent from the baseline. These are individual substitutions, not the cross-product of every argument, timezone, locale or option.

Scope: expression evaluation inside a document. Pipeline stages, grouping accumulators and window functions need their own suites. Live results do not certify Studio authoring of every expression or complete released Flow execution.

The JVM timezone is fixed to America/Toronto and locale to en-IN. Some older calendar operators use these defaults. Object field order is recorded in live comparisons but ignored by the engine regression baseline because some returned maps have unstable ordering. Array order and BSON numeric types remain significant.

Resource boundaries

An extreme $range endpoint exhausted the test JVM heap. This is documented on that operator's page. The bounded matrix excludes allocation stress cases; resource limits need separate process-isolated tests.

Maintaining the reference

Core's AllOperatorParityTest verifies engine results against the checked-in behavior baseline. A deliberate behavior change requires reviewing affected examples, refreshing live comparison evidence and regenerating these pages. The documentation's local-link, JSON and strict-build checks validate publication structure, not engine semantics.

Operator pages are generated by scripts/generate-operator-behavior.py using verification/all-operator-behavior.json. The evidence records source and case hashes. The general reference generator invokes the behavior generator so metadata-only generation cannot overwrite verified behavior.

To omit all MongoDB sections while keeping SrotaX behavior:

python scripts/generate-operator-behavior.py \
  --report verification/all-operator-behavior.json --without-mongo

To remove only one page's comparison section, delete the block between BEGIN MONGO PARITY and END MONGO PARITY. Regeneration restores it unless the omission option is used.

Stage reference

The stage reference follows the same structure. Its 86 cases cover all 21 registered Core stages and run through PipelineExecutor with a fresh context. These are Core behavior checks, not live MongoDB stage parity tests.

Regenerate both reference sections and the grouped navigation:

python scripts/generate-reference.py

Use --without-mongo to omit the comparison blocks from both operators and stages. Keep reference/stage-catalog.json prose and examples/stages.json examples aligned with the implementation. Stage verification runs with JDK 21 and the Core build:

mvn -f ../fluxion-core-engine/pom.xml test-compile dependency:build-classpath -Dmdep.outputFile=target/docs-classpath.txt
sh scripts/verify-stages.sh

The verifier compares actual results against verification/stage-behavior.json. Its --record option refreshes evidence only after intentional changes have been reviewed. Generated pages must not be edited by hand.