values

func AccessorNamePath ¶

func AccessorNamePath(v Value) ([]string, bool)

AccessorNamePath returns the ordered accessor NAME path (root QOV/alias EXCLUDED) of a plan-time column reference, from the two STRUCTURED representations only (RFC-187 §3.0):

(a) nested Child chain → walk Child, prepend each Field, stop at the root QOV
(b) baked Resolved     → Resolved.Accessors[].Field (Child is the root QOV, excluded)

ok=false — a conservative "cannot establish identity", callers MUST NOT match — when:

• any accessor is pure-ordinal (Field==""): a machinery-owned bake has no name to compare, so identity is asserted-unknown here rather than falling back to a silent name match;
• a LAZY Field carries a '.' (flat-dotted "form c"): the string is AMBIGUOUS — a real nested path (addr.city) and an alias-qualified leaf (T.city / leg.COL, composed by clustered_outer_scalar / cascades_translator) are indistinguishable as strings, so splitting on '.' would be the very string hack this kills AND could mis-root an alias as an accessor. We deliberately do NOT split (this also disposes of the quoted-"a.b"-identifier concern — no split, no hack). Such a value must not reach a match site; if one does, ok=false makes it a loud conservative miss, never a wrong bind.

Names are UPPER-cased to the resolver's normalization rule so identity is case-insensitive at every accessor.

This is the match-DOMAIN column identity: the candidate side is name-based by construction (columnNames []string, no ordinals), so identity can only be compared in the name domain. The ordinal identity (FieldPath.Equals) is a different, evaluation-domain concern; unifying them by ordinalizing the candidate is the RFC-187 §8 / RFC-173-endgame follow-up.

func AccessorNamePathKey ¶

func AccessorNamePathKey(v Value) (string, bool)

AccessorNamePathKey returns a canonical map key for a column reference's accessor path (the path segments joined with a NUL separator), or ok=false when the path cannot be established (AccessorNamePath !ok). It is the map-keyed form of column identity over plain FieldValue references: two such references produce the same key iff ColumnNamePathsEqual reports them equal, so a set keyed by this string distinguishes a nested addr.city from a same-leaf-named top-level city. (It does NOT cover the CardinalityValue wrapper ColumnNamePathsEqual also handles — a CardinalityValue yields ok=false here; the key-form callers, S7/S9 grouping keys, never pass one.)

func AccessorNamePathMatchesNames ¶

func AccessorNamePathMatchesNames(v Value, candidate []string) bool

AccessorNamePathMatchesNames reports whether v's accessor name path equals the given candidate name path (already UPPER-cased accessor names, root→leaf). It is the value↔declared-path form used by the sites whose candidate side is a string path (aggregate group/agg columns, ordered index/PK sort columns) rather than a Value. A single-element candidate (a top-level column) therefore cannot match a nested query path — the fix for those sites (RFC-187 §3.2/§3.3).

THE ToUpper ON THE CANDIDATE IS LOAD-BEARING AND MUST NOT BE DELETED ALONE. It looks like one more site of RFC-237's fold class, and the candidate side genuinely does arrive canonical now. But AccessorNamePath (above) still folds the VALUE side, deliberately: five tests pin case-insensitive accessor identity as a match-domain rule (`lazyFlat("city")` equals `lazyFlat("CITY")`, `bakedFused("ADDR","City")` equals `bakedFused("addr","city")`). Fold one side and not the other and a verbatim candidate can never meet an upper-folded path — measured: an aggregate index over quoted columns silently stopped matching. The two folds are one decision. Change them together or not at all, and see RFC-237 §9 for what would settle whether to remove both.

func AccessorPathCensus ¶

func AccessorPathCensus() [accessorPathClassCount]int

AccessorPathCensus reports the class vector.

func AccessorPathDottedOrigins ¶

func AccessorPathDottedOrigins() []string

AccessorPathDottedOrigins returns the captured producer stacks.

func AccessorPathDottedWitnesses ¶

func AccessorPathDottedWitnesses() map[string]int

AccessorPathDottedWitnesses returns a copy of the witness set.

func AssertAccessorPathCensus ¶

func AssertAccessorPathCensus(w io.Writer, gates *AccessorPathGates) bool

AssertAccessorPathCensus checks the process census against its gates.

func AssertDottedLegQualifierCensus ¶

func AssertDottedLegQualifierCensus(w io.Writer, floors *DottedLegQualifierFloors) bool

AssertDottedLegQualifierCensus checks the census's hard zeros and its floors.

There are TWO hard zeros and they are different failures of the same table.

MATCH-ALIAS-DIFFERS: a leg matched on its OWN BINDING text while stating a different identity. That is the leg table having two spellings that disagree, resolved by the weaker one — the same contradiction the seed-window census refuses, seen through the one channel that cannot be re-keyed. A leg matched through its scan TABLE name is a different fact and has its own class; the zero would be unsatisfiable if the two were folded together, which is what the first measurement did. It is worth asserting HERE precisely because this reader will keep matching on text until its counterparty carries parsed segments: the guarantee that the text it matches names the leg the identity names is all that holds the channel together in the meantime.

MATCH-NO-ALIAS: a leg matched and states NO identity at all. This class was documented as blocking from the day it was written and was never gated, so its zero was a sentence rather than a check. It is the same defect the seed-window authority now declines on (an Alias-less leg files under the zero identifier and a second one displaces it), seen from the reader side: the leg table carries an entry whose identity nothing can compare, so the day the counterparty carries segments this leg has nothing to be matched against and the conversion silently loses it. Fix the PRODUCER; the two documented text boundaries that mint a leg from a string both set Name and Alias from that one string, so a leg reaching here without an identity came from neither.

func AssertDottedRowTypeProducerCensus ¶

func AssertDottedRowTypeProducerCensus(w io.Writer, floor *DottedRowTypeProducerFloor) bool

AssertDottedRowTypeProducerCensus checks the process census against a floor.

func AssertDottedWitnessAttribution ¶

func AssertDottedWitnessAttribution(w io.Writer, floors *DottedWitnessFloors) bool

AssertDottedWitnessAttribution checks both floors and the owner-collision zero.

func AssertFieldValueMintCensus ¶

func AssertFieldValueMintCensus(w io.Writer, gates *FieldValueMintGates) bool

AssertFieldValueMintCensus checks the process census against its gates.

func AssertLegIdentityCensus ¶

func AssertLegIdentityCensus(w io.Writer, floors map[LegIdentitySite]int64) bool

AssertLegIdentityCensus checks the census and reports whether it failed.

The ZERO assertions hold over ANY population — a fold-only pair, a diverged text/identity pair, an unstated identity, a RETIRED-VERDICT divergence, or a mixed instrument is a defect whether the corpus was one query or the whole suite — so they run always. That is FIVE, and callers must enumerate all five when they announce what a narrowed run still checks: an enumeration that omits the retired-verdict zero omits the one assertion that measures the conversion itself, which is the reason this census exists. Only the population FLOORS describe a particular corpus, and those are checked only for the sites the caller supplies: pass nil to assert the zeros over a narrowed run. Skipping the zeros along with the floors is how a filtered invocation used to report "floors not checked" while quietly also not checking the five things that are always checkable.

func AssertLegIdentityCensusWith ¶

func AssertLegIdentityCensusWith(w io.Writer, exp LegIdentityExpectations) bool

AssertLegIdentityCensusWith is AssertLegIdentityCensus with the zero-side guards a corpus may declare. See LegIdentityExpectations.

func AssertNameSplitCensus ¶

func AssertNameSplitCensus(w io.Writer, floors *NameSplitFloors) bool

AssertNameSplitCensus checks the census's hard zero and its floors, writing a report to w. Returns TRUE if anything FAILED — the convention its siblings on this path use, so a call site reading `if failed := ...` means what it says.

The HARD ZERO is SPLIT-QUALIFIED at both of THIS CENSUS's two sites — not at every splitter in Go — and it is asserted rather than floored because it is not a population to be kept healthy: it is the debt, and the whole claim of the projection-channel conversion is that production traffic no longer produces any AT THESE ARMS. A non-zero means either an un-migrated producer has started carrying dotted text where a triple belongs, or a machinery-minted label has acquired a dot. The failure text names both readings because the fix differs — and for the second it names the RULING rather than an escalation, since Java settles what a nameless projection output resolves to (nothing).

func AssertOrdinalJoinSeed ¶

func AssertOrdinalJoinSeed(rc *RecordConstructorValue)

AssertOrdinalJoinSeed is the LOUD ordinal-join seed-shape validator: the translator calls it on every ordinal join RC it builds, where the pristine shape IS guaranteed by construction — every field a BAKED FieldValue over a leg QuantifiedObjectValue flowing a *RecordType, consecutive full-coverage leg runs with baked ordinals 0..width-1 ascending. Any violation panics: at the SEED a malformed ordinal RC is unconditionally a planner bug (strictness lives at seed-time, where legitimate result-value rewrites — wrapper merges, folded projections, partial coverage — cannot yet have happened; the executor's cursor-side ordinalJoinSpans probe DECLINES those shapes instead of panicking).

Lives in values (not executor) because the translator is the caller of record — a seed must never be built without this assert.

func AssertQualifierRecoveryCensus ¶

func AssertQualifierRecoveryCensus(w io.Writer, exp *QualifierRecoveryExpectations, corpus string) bool

AssertQualifierRecoveryCensus checks the census's hard zero, its saturation guards and its floors, writing a report to w. Returns TRUE if anything FAILED — the convention its siblings on this path use.

THE HARD ZERO IS **DIVERGED**, and it is the only zero this census asserts. That is a deliberate departure from its sibling, which asserts its debt bucket at zero: here MANUFACTURED is expected to be non-zero at several sites, because the whole finding is that these splitters exist and are reached. Asserting it at zero would either be false on the day it was written or would have to be relaxed into meaninglessness. What CANNOT be tolerated is a split that contradicts an identity the site was holding at the time — that is not debt, it is a wrong answer.

func AssertSeedWindowReaderCensus ¶

func AssertSeedWindowReaderCensus(w io.Writer, floors *SeedWindowReaderFloors) bool

AssertSeedWindowReaderCensus checks the two hard zeros and the floors.

floors is nil when the run is NARROWED (-test.run), exactly as its siblings do it: the zeros still run, over whatever population the filter reached, and at zero they hold vacuously.

func AssertSelectResultMintCensus ¶

func AssertSelectResultMintCensus(w io.Writer, floors *SelectResultMintFloors) bool

AssertSelectResultMintCensus checks the per-site partition, the untyped-QOV zero, and the per-site call floors.

func BuildStructMessage ¶

func BuildStructMessage(
	md protoreflect.MessageDescriptor,
	fields map[string]any,
	convert func(fd protoreflect.FieldDescriptor, v any) (protoreflect.Value, error),
) (protoreflect.Value, error)

BuildStructMessage builds the nested message a STRUCT value stores, from the evaluated record constructor's field map. It is the structural half of Java's RecordConstructorValue.eval (RecordConstructorValue.java:113-139): walk the TARGET descriptor's fields, set each field present in the map, leave a NULL field ABSENT (:135's null branch — absence is what makes a nullable struct field read back as NULL), and reject a NULL at a non-nullable field.

The per-field VALUE conversion is the caller's, passed in: the plan-time writer (INSERT … VALUES) and the executor writer (UPDATE, INSERT … SELECT) have their own scalar lanes, already documented as siblings, and this exists so the STRUCTURE is not implemented twice alongside them.

func CanBridgeOrderingFieldValues ¶

func CanBridgeOrderingFieldValues(left, right Value) bool

CanBridgeOrderingFieldValues reports whether two non-structurally-equal ordering Values may safely be reconciled by their ordinal-free column name.

The bridge is deliberately narrow. SQL requested orderings are often plan-time-baked (COL#ordinal), while candidate orderings are rebuilt as lazy flat fields (COL); those two representations need to meet. Two baked fields never meet through this helper: different ordinals are different reads, even when their display names match. Childful/nested paths are also excluded because a leaf name does not identify their source slot.

Callers must test structural equality first. This helper handles only the representation bridge, including the harmless case-only difference between two lazy flat field names.

func CanBridgeOrderingValueRoots ¶

func CanBridgeOrderingValueRoots(left, right Value) bool

CanBridgeOrderingValueRoots reconciles the two safe representation seams an ordering request crosses on its way to a scan candidate:

• a lazy flat field and the same baked flat field;
• a field rooted at its owning SELECT quantifier and the same source-local candidate field.

The second bridge normally requires exactly one QOV-rooted side and compares the complete accessor name path. There is one deliberately narrower rooted exception: a values-owned tagged-current root may bridge to one ordinary named root. That is the physical-provider -> logical-request phase boundary; two named roots remain ambiguous (self-join hazard), and two independently minted current roots name different owner phases. A shared current handle is accepted only for an otherwise structurally identical value.

When both values carry baked paths, their ordinal paths must also agree; this prevents a QOV-rooted NAME#1 from collapsing with source-local NAME#2. A baked value may still bridge to a lazy value with the same complete name path. Callers must scope a request to its owning quantifier before using this bridge.

func CastPairDefined ¶

func CastPairDefined(from, to TypeCode) bool

CastPairDefined reports whether an explicit CAST from `from` to `to` has a defined operator (Java CastValue's construction-time gate — "No cast defined from X to Y" otherwise). Identity always casts; NULL casts to anything.

func ClaimableOrderingPrefix ¶

func ClaimableOrderingPrefix(layout Type, names []string) int

ClaimableOrderingPrefix returns how many of names (resolved against layout, in order) may be claimed as an ordering — the count of leading columns before the first one that terminates the claim.

This is the single entry point for producers that build an ordering key list from a metadata column-NAME sequence. Asking it in one place is the point: a producer that re-implements the predicate at its own call site is how two derivations drift apart and classify the same column differently.

It is NOT the only shape a producer comes in, and an earlier revision of this comment claimed it was ("the single entry point for every producer"). That was false, and the two producers it did not cover — the streaming aggregation and the aggregate index, whose ordering is over GROUPS rather than rows — were returning wrong rows on a real cluster while this file asserted they could not. A producer holding already-typed key VALUES asks TypeTerminatesOrderingClaim directly instead; the predicate is shared, the entry point is not. plans/ordering.go's header enumerates which producer asks which, and which need not ask at all.

func ClaimableTypedKeyPrefix ¶

func ClaimableTypedKeyPrefix(keys []Value) int

ClaimableTypedKeyPrefix is ClaimableOrderingPrefix for keys that carry their OWN declared type and have no flowed layout to resolve against — grouping keys, which the translator mints already typed.

A nil key is skipped rather than treated as terminating: an unidentifiable key is the same "burden of proof sits on the float side" trade TypeTerminatesOrderingClaim documents.

Two DIFFERENT questions are answered by this one count, and it is worth naming both because only the first is about ordering:

• Does the producer's advertised ORDER hold? Only for the leading prefix, so the claim is truncated there.
• Is the input CLUSTERED by the full grouping key? A streaming aggregation compares each row against the PREVIOUS group only, which is sound exactly when rows equal under the grouping identity are ADJACENT. A float coordinate breaks that too, and more sharply: the grouping identity is java.lang.Double.equals, which makes every NaN payload one value, while the tuple encoding scatters those payloads into two blocks at OPPOSITE ENDS of the key space. So the same group opens, closes and reopens, and the aggregation emits it twice. A consumer asking that question needs the count to reach len(keys) — a prefix is not enough, because clustering is a property of the whole key.

func ColumnCanExtendOrderingClaim ¶

func ColumnCanExtendOrderingClaim(layout Type, name string) bool

ColumnCanExtendOrderingClaim resolves name against layout and reports whether that column may extend an ordering claim.

Returns true when the column cannot be shown to be a FLOAT/DOUBLE — see TypeTerminatesOrderingClaim for why the burden of proof sits on that side.

An AMBIGUOUS name (a layout declaring it twice, which is constructible because NewRecordType's duplicate check is case-SENSITIVE while column resolution is case-INSENSITIVE) terminates the claim if ANY matching field is a float. Addressability of an ambiguous key is a SEPARATE contract, already enforced downstream by the unique-match rule in bakeOrderingColumnIn — this predicate deliberately does not duplicate it, and answers only the question it owns: could this coordinate be a float?

func ColumnCouldBeFloat ¶

func ColumnCouldBeFloat(layout Type, name string) bool

ColumnCouldBeFloat resolves name against layout and reports whether that coordinate COULD hold a float — the question a signed-zero widening decision needs, and deliberately NOT the negation of ColumnCanExtendOrderingClaim.

The two differ exactly where the layout cannot answer, and the difference is the whole reason this exists. ColumnCanExtendOrderingClaim is permissive on an unresolvable layout (nil, not a *RecordType, no fields, name absent) because its own use is "may this coordinate extend a claim?", where permissive means GRANT and the burden of proof sits on the float side.

Inverted into a float test that answer flips meaning: "not a float" becomes "no signed zero", which becomes "this equality PINS", which is assume-SOUND — the unsound direction. A burden-of-proof direction does not survive an inversion, and reading one predicate backwards to answer the other silently turned a conservative default into an optimistic one.

That state is not hypothetical. plans.NewRecordQueryIndexPlan defaults a nil flowedType to UnknownType, and AggregateIndexMatchCandidate passes UnknownType explicitly; UnknownType is a *PrimitiveType, so it takes the not-a-record arm and every coordinate on such a plan reads as non-float. MEASURED live: a reachability probe in that arm fired under the planner suite.

So this asks positively and fails CLOSED — an unresolvable coordinate could be a float, so a zero-capable equality on it does not pin and the claim is refused. The cost is a sort that may not have been needed; the alternative cost is a wrong row order.

func ColumnNamePathsEqual ¶

func ColumnNamePathsEqual(a, b Value) bool

ColumnNamePathsEqual reports whether two plan-time column references denote the same accessor path (RFC-187 §3.0). It is the single match-domain column-identity notion; every value↔value match site routes through it.

Returns false — a conservative reject (the caller leaves the predicate a residual filter / does not elide the sort → correct rows, correct order via the slower path) — when either side's AccessorNamePath is !ok, or the paths differ at ANY position: every intermediate accessor is compared, not just the leaf, not leaf+root — which is what distinguishes a nested path from a same-leaf-named top-level column.

CardinalityValue is a transparent wrapper: CARDINALITY(x) matches CARDINALITY(y) iff x and y denote the same column. (DistanceRowNumber's metric-class discrimination is handled at its call site, which then compares the partition/argument column paths through this function.)

func ColumnNameValue ¶

func ColumnNameValue(v Value) string

ColumnNameValue renders v exactly like ExplainValue but WITHOUT the baked `#<ordinal>` accessor discriminators — the NAME-derivation rendering. Every place that derives an OUTPUT COLUMN NAME from a Value (aggregate result columns, group-key output columns, sort-key field refs, projection column defs) must use this form, never ExplainValue: a reference's column NAME must not change when the reference is bound to its ordinal at plan time, or the naming lockstep between the layers that render the name from DIFFERENT instances of the same reference (one baked, one lazy) silently breaks. ExplainValue keeps the ordinal discriminators for EXPLAIN/debug output, where collapsing two different reads is itself a bug.

func CompareExactInts ¶

func CompareExactInts(a, b any) (int, bool)

CompareExactInts compares two values EXACTLY when both are admitted integer forms — int/int8/int16/int32/int64 plus the uint/uint64 half the tuple layer uses for positive values above math.MaxInt64. ok=false when either side is not an integer. The order is by true numeric value — the order the FDB tuple integer encoding gives an indexed column — computed on (negative, magnitude) form so no pair round-trips through float64 (promotion ties adjacent values above 2^53 and at the 2^63 boundary).

func CompareFloat64 ¶

func CompareFloat64(a, b float64) int

CompareFloat64 is a total order over float64 faithful to Java's java.lang.Double.compare and Double.doubleToLongBits. Java Record Layer ordered comparisons use that order, and its boxed equality uses Double.equals, so both distinguish the zero signs and canonicalize NaNs. Go predicate comparison intentionally prechecks native IEEE equality in predicates.cmpAny: it makes -0 equal +0 while retaining this total order for non-equal values and NaNs. Sort, merge, and dedup consumers call this helper directly and therefore retain the Java/FDB-compatible zero-sign order.

Two edge values differ from Go's native float comparison:

• NaN sorts GREATER than every non-NaN value, and NaN compares equal to NaN (native `<`/`>` are both false, and `==` is false).
• Negative zero sorts strictly BEFORE positive zero: -0.0 < 0.0 (native `==` treats them as equal).

This matches FDB tuple order for ordinary values and the two zero signs, but deliberately not for arbitrary raw NaN encodings. FDB preserves NaN sign and payload, placing negative and positive NaNs in separate physical regions; this logical comparator canonicalizes them. Planner ordering/SARG proofs must therefore reject an unbounded or range-bound FLOAT/DOUBLE coordinate unless a separate normalization or compensation proof is available.

func CompareOrdered ¶

func CompareOrdered(a, b any) (int, error)

CompareOrdered is a total order over the concrete scalar/binary Go types the query engine's row and IN-list values take (the int/uint/float variants, bool, string, []byte, [16]byte UUID, and nil). It is the single Java-faithful natural order this codebase uses wherever two runtime values must be ranked against each other outside of an indexed comparison: in-memory sort, merge-cursor ordering keys, and a SORTED IN-join's literal list (cascades.sortInJoinValues).

Two edge cases differ from Go's native comparison operators, matching java.lang.Double.compare exactly (see CompareFloat64): NaN sorts greater than every non-NaN value and compares equal to NaN, and -0.0 sorts strictly before +0.0. Every other typed arm matches FDB's own tuple encoding order, so an in-memory ordering agrees with what an indexed scan of the same column would produce.

nil sorts before every other value (a nil pair compares equal). A pair with no shared typed arm returns a loud error rather than silently picking a wrong order — the planner's type checking is expected to exclude cross-type comparisons before this is ever called on production data, so this arm is a defensive backstop, not a designed code path.

func ContainsAggregate ¶

func ContainsAggregate(v Value) bool

ContainsAggregate reports whether v has any AggregateValue in its subtree. Common gate for rules that only apply to scalar expressions — aggregates need the accumulator path, not per-row Evaluate.

func ContainsBakedOrdinal ¶

func ContainsBakedOrdinal(v Value) bool

ContainsBakedOrdinal reports whether any FieldValue in v's subtree carries a MACHINERY-OWNED (FrontierPinned) baked-ordinal marker — the structural "is this an ordinal-join value tree" probe the join machinery keys on (SelectMergeRule target loop, the executor's ordinal-join construction). Deliberately blind to UNPINNED baked nodes (source-relative resolver bakes): those carry no join-frontier contract and must not trip join-seed machinery.

func DependsOnStatementClock ¶

func DependsOnStatementClock(v Value) bool

DependsOnStatementClock reports whether the value tree contains a CURRENT_TIMESTAMP-family function — one whose result is defined by the statement clock rather than by its (zero) arguments. The executor computes this ONCE per operator to decide whether a bare frontier row must be wrapped in a clock-bearing RowEvalContext: evaluating such a value against a bare OrdinalRow falls back to per-row time.Now() and drifts across the rows of one statement, which SQL forbids.

func DescribeType ¶

func DescribeType(typ Type) string

DescribeType renders a Type as a compact, comparable shape for a diagnostic: `RECORD(LID:LONG,VAL:LONG?)`, `ARRAY<INT>`, `LONG?`. A trailing `?` marks nullable. It is the public twin of the rendering the exact-type conflicts use, for callers outside this package that hold a Type rather than a handle.

func DisplayColumnName ¶

func DisplayColumnName(v Value, alias string) string

DisplayColumnName is the USER-VISIBLE label for a projected column: the alias when the column carries one, else its own name with the QUALIFIER removed — Java's Identifier.withoutQualifier, applied by the top-level clearQualifier (Identifier.java:101-106). `SELECT n.sk` is column SK.

This is deliberately NOT OutputColumnName. The qualifier belongs in the internal slot key, where it is what keeps two legs' same-named columns apart; it does not belong in anything a user names the column by. Wherever a projection's name CROSSES into SQL — a result-set label, a CTE's column list — the display form is the authority, and disagreeing about that is how one recursive CTE came to declare its column N.SK while every reference to it resolved SK.

The leaf is taken from the RESOLVED ACCESSORS, never by splitting the rendered name: a column may legally be named with a dot in it (`"A.ID"`), and a last-dot split would tear that name in half.

func DottedLegQualifierCensus ¶

func DottedLegQualifierCensus() ([dottedLegSiteCount][dottedLegClassCount]int, []string)

DottedLegQualifierCensus reports the per-site class matrix and the witnesses.

func DottedRowTypeProducerCensus ¶

func DottedRowTypeProducerCensus() (dotted, plain int, witnesses []string)

DottedRowTypeProducerCensus reports the counts and the distinct dotted row shapes the generic path derived.

func DottedWitnessAttribution ¶

func DottedWitnessAttribution() (attributed, unattributed []string, mintedCount int)

DottedWitnessAttribution reports, per observed name, whether it is attributed to a correlated-scalar seed inner leg BY IDENTITY.

func DumpAccessorPathCensus ¶

func DumpAccessorPathCensus(w io.Writer, label string)

DumpAccessorPathCensus renders the class vector.

func DumpFieldValueMintCensus ¶

func DumpFieldValueMintCensus(w io.Writer, label string)

DumpFieldValueMintCensus renders the census, with the partition check and the vacuity guard ahead of any zero-class claim.

func DumpOrderingBridgeDottedCensus ¶

func DumpOrderingBridgeDottedCensus(w io.Writer, label string)

DumpOrderingBridgeDottedCensus renders it, vacuity guard first.

func EffectiveListField ¶

func EffectiveListField(fd protoreflect.FieldDescriptor) (list protoreflect.FieldDescriptor, wrapped, ok bool)

EffectiveListField resolves a column field to its effective REPEATED field:

• a flat repeated field returns itself (wrapped=false);
• a singular message field whose message is the wrapper returns the inner `values` field (wrapped=true);
• anything else returns (nil, false, false).

func EqualsWithoutChildren ¶

func EqualsWithoutChildren(a, b Value) bool

EqualsWithoutChildren checks whether two Values are the same type with the same non-child attributes, WITHOUT recursing into children. This is the Go equivalent of Java's Value.equalsWithoutChildren().

For leaf values (no children) this is equivalent to ValuesStructurallyEqual. For composite values it checks the type and any type-specific attributes (operator, field names, etc.) but does NOT compare children.

Returns true if a and b have the same concrete type and the same non-child attributes (e.g. same ArithmeticOp, same field names in RecordConstructorValue, same CastValue target type, etc.).

func EvaluateConstant ¶

func EvaluateConstant(v Value) (out any, ok bool)

EvaluateConstant attempts to fold v to a concrete literal at plan time. Returns (literal, true) when v is constant (per IsConstantValue); (nil, false) otherwise. Safe on nil (returns (nil, false)). Useful for rules that want to pre-compute a constant sub-expression without writing an `if isConstant { eval and wrap }` dance every time.

A data-dependent runtime error from Evaluate (arithmetic overflow, division by zero, invalid cast, type mismatch) is reported as "not foldable" — (nil, false). This is the plan-time decline-to-fold path: the typed runtime-error family now returns via the error channel, so the error is swallowed here (leave the node) rather than surfacing a query error from the planner.

Genuinely programmer-invariant panics (e.g. an AggregateValue buried inside a constant tree that IsConstantValue should have excluded) are planner bugs and now surface rather than being silently swallowed — the residual recover that masked them has been collapsed.

func ExactTypesEqual ¶

func ExactTypesEqual(left, right ExactTypeHandle) bool

ExactTypesEqual reports whether two exact handles denote the same type. It is FlowedTypesEqual for callers that hold bare handles rather than quantifiers — an expression's snapshotted target or result type, say — and it exists for the same reason: `left.Type().Equals(right.Type())` builds two whole graphs to answer a boolean, and both operands were already immutable identities.

Read its contract off exactTypesEqual, not off pointer identity: two handles can denote one type and still be two objects, because interning keys on the record and enum name that Type.Equals ignores.

Two absent handles are NOT equal, matching FlowedTypesEqual. `Type()` on a nil handle yields a nil Type and the comparison it replaces panicked there, so there is no prior answer to preserve — and "neither side can state a type" is not evidence that they state the same one.

func ExplainPlanValues ¶

func ExplainPlanValues(vs []Value) []string

ExplainPlanValues renders one plan node's retained Value program in a stable local correlation namespace. Unique correlations are allocation identities, so their process-global numeric suffixes must not leak into plan text: doing so makes two structurally identical plans explain differently solely because another query happened to allocate aliases first.

A program with one unique correlation and no bare QOV omits that root, which preserves the familiar `ID#0` spelling for a projection over one input. With multiple unique roots (or a bare scalar QOV) the roots are numbered q$0, q$1, ... by first structural occurrence. Named correlations — including a quoted user alias whose text looks like q$7 — are never rewritten.

func ExplainValue ¶

func ExplainValue(v Value) string

ExplainValue renders a Value as a readable expression string. Free function rather than a Value-interface method so existing third-party Value impls (once the port grows) don't have to track another method. Walks children recursively for composite values like ArithmeticValue / CastValue.

Output style matches SQL-ish expression rendering:

ConstantValue     → the literal as %v
FieldValue        → the field name
ArithmeticValue   → (left OP right)
BooleanValue      → TRUE / FALSE / NULL
CastValue         → CAST(child AS TypeX)
NullValue         → NULL

func FieldNameForProtoField ¶

func FieldNameForProtoField(field protoreflect.FieldDescriptor) string

FieldNameForProtoField is THE single authority for the NAME a stored column's slot carries in a values.Type: the user identifier, VERBATIM.

A protobuf field name is the STORAGE spelling — `$`, `.` and `__` are escaped (`a$b` is stored as `A__1B`). Java keeps the two apart on the type itself: `Type.Record.fromDescriptorPreservingName` records `ProtoUtils.toUserIdentifier(descriptor.getName())` as the name and the raw descriptor name as the storage name, and `Type.Record.Field` does the same per column — the wire keeps the escaped spelling, the SQL surface sees the user's.

Go's SQL catalog already un-escapes (rlcatalog), so a Value-tier type built straight off the descriptor states a DIFFERENT name for the same column than the reference that reads it. Under RFC-232 those two are compared as exact types, so the disagreement is not cosmetic: it is a hard "type disagrees with declared binding" at evaluation, and every query over a table with an escaped identifier fails.

It does not FOLD, for the same reason Java does not: the only normalization in the language is at the parse boundary (SemanticAnalyzer.normalizeString — quoted keeps its case, unquoted folds UPPER), and every catalog comparison after it is exact. A fold here was invisible for a DDL-created schema, whose descriptor names are already the normalized spelling, and wrong for everything else — it named a column something no reference could spell, and it made the index-matching bridge miss SILENTLY (RFC-237 §2.1).

func FieldValueMintCensus ¶

func FieldValueMintCensus() (total int, counts [fieldMintClassCount]int)

FieldValueMintCensus returns the independent total and the class vector.

func FieldValueMintOrigins ¶

func FieldValueMintOrigins() []string

FieldValueMintOrigins returns the captured producer stacks for the dotted classes.

func FlowedRowShapeEquals ¶

func FlowedRowShapeEquals(value QuantifiedObjectValue, typ Type) bool

FlowedRowShapeEquals is FlowedRowShapesAgree against an ordinary Type — a declared row an executor binding carries, say — where there is no second handle to compare with.

It routes the quantifier's side through the SHARED thawed graph, so the walk runs against a graph allocated once per interned type rather than once per call. That is the whole saving available on this shape; see FlowedTypeEquals.

func FlowedRowShapesAgree ¶

func FlowedRowShapesAgree(left, right QuantifiedObjectValue) bool

FlowedRowShapesAgree reports whether two quantified object values denote the SAME BOUND ROW, answered from the exact handles. It is QuantifiedRowShapesAgree's question — see that function for why the top-level nullable bit is excluded from a row's shape and why one alias legitimately carries two QOVs differing only there — with neither graph built.

Same relation, not an approximation of it: exactRowShapesAgree is the handle-side twin, and every ordered pair of a type corpus is swept in exact_type_equality_differential_test.go to keep the two answering alike.

func FlowedTypeEquals ¶

func FlowedTypeEquals(value QuantifiedObjectValue, typ Type) bool

FlowedTypeEquals reports whether value flows exactly typ.

The other side is an ordinary Type here — a layout's carrier, a plan's declared row, a query result — so there is no second handle to compare against and the graph has to be walked. What this avoids is BUILDING one: SharedFlowedType hands back the thawed graph cached on the interned handle, so the walk runs against a value that is allocated once per interned type for the life of the process instead of once per call.

Argument order does not affect the answer. Every Type implementation's Equals type-asserts the operand to its own concrete type before comparing anything, so all six are symmetric, and a call site that had the ordinary type on the left reads the same through here. TestTypeEqualsIsSymmetricOverTheCorpus pins that rather than leaving it as a claim, because it is the one property that lets these call sites be rewritten without checking each one's orientation.

The result is READ-ONLY on the value's side and this function never lets it escape — that is the whole reason the shared graph is safe here while FlowedType stays the default everywhere the graph is stored or handed onward.

func FlowedTypesEqual ¶

func FlowedTypesEqual(left, right QuantifiedObjectValue) bool

FlowedTypesEqual reports whether two quantified object values flow the same row type. It is what `left.FlowedType().Equals(right.FlowedType())` asks, answered from the immutable exact handles, building NEITHER graph.

The spelling it replaces allocates two complete Type graphs to produce one bool, and thaw was the single largest allocator in the planner because of it. The handles are already there: a quantified object value IS an exact handle plus a correlation, and comparing two handles is a pointer test, then a hash, then one bytes.Equal over a canonical encoding.

It is `exactTypesEqual` and NOT handle pointer identity, and the difference is the whole reason this function exists rather than being written inline at each call site. Identity is strictly STRICTER than Type.Equals: the intern table keys on the record and enum NAME, while RecordType.Equals and EnumType.Equals deliberately ignore it to match Java. Two Equals-equal rows can therefore hold two handles, and an identity test would call them different — a false negative, in the direction that changes plans. The canonical encoding exact_type.go builds excludes the name precisely because Equals does, which is what makes this substitution equal by construction rather than by an argument about interning. exact_type_equality_differential_test.go sweeps every ordered pair of a type corpus to keep it that way, and fails on 22 pairs if anyone "simplifies" this to `==`.

A value that cannot state a flowed row answers FALSE rather than panicking, as the expression it replaces did when the LEFT side was unusable — and answered false, inconsistently, when the right side was. Every caller here is asking whether two rows are the same, and "cannot tell" and "not the same" lead to the same fail-safe branch: rebuild, refuse the rewrite, miss the lookup.

func FormatDottedLegQualifierCensus ¶

func FormatDottedLegQualifierCensus() string

FormatDottedLegQualifierCensus renders the census for a harness to log.

func FormatDottedRowTypeProducerCensus ¶

func FormatDottedRowTypeProducerCensus() string

FormatDottedRowTypeProducerCensus renders the process census for a harness to log.

func FormatDottedWitnessAttribution ¶

func FormatDottedWitnessAttribution() string

FormatDottedWitnessAttribution renders the census for a harness to log.

func FormatSeedWindowReaderCensus ¶

func FormatSeedWindowReaderCensus() string

FormatSeedWindowReaderCensus renders the per-site table for a harness to log.

func FormatSelectResultMintCensus ¶

func FormatSelectResultMintCensus() string

FormatSelectResultMintCensus renders the census for a harness to log.

func GetCorrelatedToOfValue ¶

func GetCorrelatedToOfValue(v Value) map[CorrelationIdentifier]struct{}

GetCorrelatedToOfValue walks v + its descendants and returns the union of every correlation-bearing leaf Value's alias. Handles QuantifiedObjectValue, QuantifiedRecordValue, ScalarSubqueryValue, ObjectValue, UnmatchedAggregateValue, and ConstantObjectValue. ExistsValue is a transparent composite — its child QuantifiedObjectValue is reached via the Children() descent.

Returns nil for nil input. Returns a non-nil empty map for trees with no correlations.

Ports Java's Value.getCorrelatedTo().

func GetCorrelatedToWithoutChildrenOfValue ¶

func GetCorrelatedToWithoutChildrenOfValue(
	v Value,
) map[CorrelationIdentifier]struct{}

GetCorrelatedToWithoutChildrenOfValue returns only the correlations carried by v itself, excluding correlations contributed by descendant Values.

This is the Go counterpart of Java Value.getCorrelatedToWithoutChildren(). Keep the switch in lockstep with the correlation-bearing leaf cases in GetCorrelatedToOfValue. Composite wrappers such as FieldValue and ExistsValue deliberately contribute nothing here even though their full subtree correlation set is non-empty.

func IsAny ¶

func IsAny(t Type) bool

IsAny reports whether t is the universal supertype. Mirrors Java's `Type.isAny()`.

func IsArray ¶

func IsArray(t Type) bool

IsArray reports whether t is an ARRAY (concrete or erased). Mirrors Java's `Type.isArray()`.

func IsCanonicalCurrentOnlyOrdinalLayout ¶

func IsCanonicalCurrentOnlyOrdinalLayout(layout OrdinalLayout) (bool, error)

IsCanonicalCurrentOnlyOrdinalLayout reports whether layout carries only its tagged-current object and therefore needs no retained-source bindings or per-row window presence. Record tile shape may be flat or nested: both are canonical carrier-relative addressing once source windows are absent.

A valid windowed layout returns (false, nil). Foreign, nil, and typed-nil views fail loudly before any interface method is invoked, matching the other layout purpose APIs.

func IsCascadesSafeScalarFunction ¶

func IsCascadesSafeScalarFunction(name string) bool

IsCascadesSafeScalarFunction reports whether the named scalar function is admitted to the Cascades SQL pipeline.

func IsConstantValue ¶

func IsConstantValue(v Value) bool

IsConstantValue reports whether v's Evaluate is row-context- independent — its value is known at plan time. True for ConstantValue, NullValue, BooleanValue, and any composite whose children are all constants (`1 + 2`, `CAST(5 AS STRING)`). False for FieldValue / QuantifiedObjectValue / AggregateValue and any composite containing them.

Used by rule matchers that only fire on fully-foldable operands (e.g. ComparisonConstantSimplifyRule's whitelist).

func IsEnum ¶

func IsEnum(t Type) bool

IsEnum reports whether t is an ENUM. Mirrors Java's `Type.isEnum()`.

func IsFunctionallyDependentOn ¶

func IsFunctionallyDependentOn(v Value, otherValue Value) bool

IsFunctionallyDependentOn reports whether v is functionally dependent on otherValue — meaning v's output is fully determined by otherValue's output. Ports Java's Value.isFunctionallyDependentOn.

Returns true if all correlation-bearing leaves in v reference the same correlation as otherValue (when otherValue is a QOV). Returns false if any leaf references a different scope, or if otherValue is not a QOV.

func IsIndexOnly ¶

func IsIndexOnly(v Value) bool

IsIndexOnly is a helper that any Value can call to check whether v requires an index scan to produce its result.

func IsMixedSeedElementType ¶

func IsMixedSeedElementType(t Type) bool

IsMixedSeedElementType decides whether a bare QuantifiedObjectValue carrying this type is the MIXED seed's whole-object SCALAR element — Java's `isPrimitive()` branch, the element the seed cannot ofOrdinal-bake and so gives its own synthesized 1-field window.

It is one predicate rather than two identical ones because the planner's window derivation (OrdinalSeedLegWindows) and the executor's span derivation (unnestMixedSeedSpans / ordinalJoinSpans) must agree on it BIT FOR BIT: they walk independently, and a disagreement about which field is the element is a wrong-offset read of every field after it. Two copies of a rule agree until one of them is edited.

The test is "not a RECORD", and it is a PROXY for the question actually being asked — is this field one slot, or is it a leg occupying width-many? — so it is worth being exact about why the proxy holds, because it did not always.

It holds because a LEG's quantifier object now states its row. While the flowed object value was minted untyped, an untyped leg was not a record either, so a leg flowing a whole multi-column row was admitted as a one-column element and a 2-slot record constructor of bare untyped quantifier objects was accepted outright, at widths nobody had checked. Typing the flowed value closed that: a leg reads as a RecordType and is rejected here, measured as flowed 848 of 848 leg derivations over the real-FDB corpus with underivable at zero. The bakeability census asserts that zero, so the fact this proxy rests on is enforced rather than assumed.

What it does NOT do is demand a STATED type, and that is deliberate rather than an oversight. An unnest element over an array of STRUCTS is a genuine whole-object element — one slot, the whole struct, exactly the case this arm exists for — and its type is UNKNOWN because Go does not infer array element types that far. Requiring a stated type declines it and `SELECT "X" FROM TS, TS."ITEMS" AS "X"` stops resolving. So an unstated type stays admitted, and the leg side is what carries the discrimination.

func IsNonEvaluable ¶

func IsNonEvaluable(v Value) bool

IsNonEvaluable is a helper that any Value can call to check whether v is plan-time-only. Avoids type-assertion boilerplate in callers.

func IsNone ¶

func IsNone(t Type) bool

IsNone reports whether t is the NONE type (untyped empty array). Mirrors Java's `Type.isNone()`.

func IsNull ¶

func IsNull(t Type) bool

IsNull reports whether t is the NULL literal's type (TypeCodeNull). Mirrors Java's `Type.isNull()`.

func IsOrdinalFieldName ¶

func IsOrdinalFieldName(name string) bool

IsOrdinalFieldName reports whether name is a planner-internal ordinal-addressed field key (`_0`, `_1`, …) — OrdinalFieldName's inverse, digits-only (OrdinalFieldName never emits signs, so `_-1`/`_+0` are NOT ordinal keys). User columns cannot take this form (a parsed identifier's leading `_` is legal, but the positional-merge and Explode-ordinality producers are the only writers of these keys in a merged row).

func IsOrdinalJoinRV ¶

func IsOrdinalJoinRV(v Value) bool

IsOrdinalJoinRV reports whether v is an ordinal-model JOIN-SELECT result value: a raw (non-anchored) RC whose every field is a FrontierPinned baked reference over a quantifier — the flat N-leg seed and its TranslationMap- translated upper forms (fused multi-accessor paths included) — spanning at least two distinct root quantifiers. This is the ordinal counterpart of the AnchoredJoin marker for the interning gate: the shapes whose quantifiers have no external identity consumer, where alias-IDENTITY dedup re-explodes the join re-enumeration's shared sub-products per bipartition. A lazy field anywhere (CTE column renames, computed projections) declines — those selects keep the alias-identity dedup that Go's column derivation requires.

func IsPositionalMergeRC ¶

func IsPositionalMergeRC(v Value) bool

IsPositionalMergeRC is the VALUE-level half of the structural merge-select recognition (no imperative marker — the exact shape PartitionSelectRule.java:284-291 builds and nothing else can): an RC whose every field is auto-generated-named ("_i", in position order — Java Type.java:2922 isAutoGenerated) and whose value is a BARE QOV of a distinct quantifier. The SELECT-level half (the QOVs are the select's own owned ForEach quantifiers, covering them) lives at the interning gate; the executor checks the QOVs against its two legs. Unconstructible from SQL: the generator names all columns, so CTE column-rename selects never match. Lives beside ContainsBakedOrdinal — the two value-shape probes ordinal join construction triggers on.

func IsPromotable ¶

func IsPromotable(from, to Type) bool

IsPromotable reports whether `from` can be implicitly promoted to `to` without an explicit CAST. Returns true when:

• from.Code() == to.Code() (identity, same type code).
• The (from.Code, to.Code) pair is in the promotionMap.

Mirrors Java's `PromoteValue.isPromotable`. Nullability is NOT part of the promotion check — a NOT NULL value can always be stored in a nullable slot of the same code, and a nullable value being stored in a NOT NULL slot is rejected at the caller (NOT NULL constraint), not by promotion.

Arrays / records / enums / vectors with structural inner types need element-by-element checks done by the caller (Java's isPromotionNeeded recurses for these); IsPromotable only handles the top-level code pair.

func IsRecord ¶

func IsRecord(t Type) bool

IsRecord reports whether t is a RECORD. Mirrors Java's `Type.isRecord()`.

func IsRelation ¶

func IsRelation(t Type) bool

IsRelation reports whether t is a RELATION. Mirrors Java's `Type.isRelation()`.

func IsRowVersionPseudoField ¶

func IsRowVersionPseudoField(name string, t Type) bool

IsRowVersionPseudoField reports whether a resolved field is THE row-version pseudo-field: name and type must both match, mirroring the two-sided check Java applies before emitting VersionKeyExpression.VERSION for it (MaterializedViewIndexGenerator.toFieldKeyExpression, MaterializedViewIndexGenerator.java:821-823: type equality with PseudoField.ROW_VERSION.getType() AND field-name equality).

func IsUnresolved ¶

func IsUnresolved(t Type) bool

IsUnresolved reports whether t is one of the placeholder types (UNKNOWN / NULL / NONE / ANY) — i.e. the type isn't a concrete shape that can carry data on its own. Mirrors Java's `Type.isUnresolved()`.

func IsUuid ¶

func IsUuid(t Type) bool

IsUuid reports whether t is a UUID. Mirrors Java's `Type.isUuid()`.

func IsWrappedArrayDescriptor ¶

func IsWrappedArrayDescriptor(md protoreflect.MessageDescriptor) bool

IsWrappedArrayDescriptor reports whether md is the NullableArrayWrapper shape: exactly one field, named "values", repeated. Mirrors Java's NullableArrayUtils.isWrappedArrayDescriptor.

func JavaDoubleToString ¶

func JavaDoubleToString(f float64) string

JavaDoubleToString is Java's Double.toString(double).

func JavaFloatToString ¶

func JavaFloatToString(f float32) string

JavaFloatToString is Java's Float.toString(float).

func LayoutProvides ¶

func LayoutProvides(layout OrdinalLayout, source QuantifiedObjectValue) (bool, error)

LayoutProvides reports whether layout contains the exact source window. A missing window is a typed optional physical miss, not an untyped false.

func LayoutSatisfies ¶

func LayoutSatisfies(layout OrdinalLayout, required RequiredBindings) (bool, error)

LayoutSatisfies applies one immutable binding manifest to a candidate provided layout. Missing windows are a normal physical incompatibility; malformed/extra/colliding sources remain errors.

func LayoutWindowNullSupplying ¶

func LayoutWindowNullSupplying(layout OrdinalLayout, source QuantifiedObjectValue) (bool, error)

LayoutWindowNullSupplying reports whether one exact local source window is null-supplying. This is physical layout authority: record nullability alone cannot distinguish a retained nullable value from a source which was absent because an outer-join edge did not match.

func LegAwareRootOrdinal ¶

func LegAwareRootOrdinal(vt FieldValue, srcOrd int, rc *RecordConstructorValue, fallbackOrd int) int

LegAwareRootOrdinal resolves the seed-RC slot for a SourceRelativeBaked reference collapsed over a flat leg-concatenation seed (a merged box/join whose RC concatenates each leg's columns, every field a baked FieldValue over its OWN leg's QOV — NewRawRecordConstructorValue, values.go). The reference's baked ordinal is relative to its OWN leg, so applying it directly to the seed picks the wrong slot; and with columns colliding across legs (dept.id AND emp.id) a bare-name match picks the first occurrence — again the wrong leg, the raw-RC duplicate-name conflation. Disambiguate by the reference's OWN leg (vt.Child's correlation): pick the seed field whose value is a FieldValue over that SAME correlation, matched by leg-relative ORDINAL.

Two name arms used to sit under that, and both are gone (RFC-197 item 3):

• a within-leg name TIEBREAK, for a seed field carrying no baked ordinal. "A single source has unique column names" is the argument it rested on, and it is an argument for the ordinal, not against it: where the names are unique the ordinal answers identically, and where they are not the name is wrong. A seed field with no ordinal states nothing, so it is skipped.
• a cross-leg name FALLBACK, for a seed whose leg field is a bare QOV rather than a per-column FieldValue (a lateral unnest). It resolved a UNIQUE name and poisoned a duplicate — the guard being the admission that the key was wrong, since two bare-QOV legs exposing the same column reach here indistinguishable. Every such seed now poisons.

Poison (-1) is the fail-closed answer for both: the caller leaves the reference UN-COLLAPSED rather than collapsing it onto a slot chosen by a display name, which is loud on a positional row and never a wrong slot. It is the same ambiguity-poison discipline bakeMergeComparisonKeys and rich_ordering apply.

Deliberately NOT falling back to fallbackOrd: that is the reference's RAW leg-relative ordinal, and applying it to the box's concatenated RC picks the FIRST leg's slot — the wrong-leg bug this function exists to prevent (it once turned `e.id IS NULL` into `d.id IS NULL` and made a LEFT-join anti-join return zero rows). fallbackOrd is used only where a leg-relative rebase was never needed.

func LegIdentityCensusEnabled ¶

func LegIdentityCensusEnabled() bool

LegIdentityCensusEnabled reports the gate state.

func LegIdentitySampleCap ¶

func LegIdentitySampleCap() int

LegIdentitySampleCap exposes that bound to the harnesses that gate on the witness sets.

A gate that walks a site's witnesses and clears each one against an allowlist is only as complete as the witness set: once the set is SATURATED, a further DISTINCT anomaly still increments the count but retains no witness, so the walk clears every witness it can see and the gate passes with a real divergence counted. Nothing about the count reveals that — a harness must compare the witness length against this cap and fail on saturation.

func LegSiteNeitherMustBeZero ¶

func LegSiteNeitherMustBeZero(site LegIdentitySite) bool

LegSiteNeitherMustBeZero reports whether a site's Neither population is a FAILURE rather than ordinary traffic.

It is true exactly at the sites whose recorded pair is two spellings of ONE leg that must therefore denote the same thing: a leg's own (Name, Alias.Name()). Everywhere else the pair is a lookup against a leg it is allowed not to be, so Neither counts misses and only FoldOnlyEqual can indict.

LegSiteNLJPlanAlias is deliberately NOT here even though its pair is also two spellings of one leg: measured, the select's source-alias slice can carry a re-minted identifier while its quantifier keeps the user alias, and that divergence is the reason to prefer the quantifier rather than a reason to fail. See that site's comment.

The distinction is the reason FoldOnlyEqual == 0 was not enough on its own: a producer that stores Name "X" against Alias "Y" lands in Neither and leaves the fold-only count at zero while the text channel and the identity channel have diverged.

func LegSiteNeitherSampled ¶

func LegSiteNeitherSampled(site LegIdentitySite) bool

LegSiteNeitherSampled reports whether a site's Neither witnesses are worth retaining.

It is a SUPERSET of LegSiteNeitherMustBeZero, and the gap between them is the whole reason it is a separate predicate. Sampling used to be tied to the assertion, which meant the one site whose Neither = 12 motivated building the sampler — LegSiteNLJPlanAlias, whose Neither is deliberately not asserted because a stale source alias is a reason to prefer the quantifier rather than a failure — never sampled. The number that justified the instrument was the number the instrument could not explain.

The criterion is "is the pair two spellings of ONE leg?", not "is its zero enforced?": at those sites a Neither is diagnostic no matter what the gate does with it. Everywhere else Neither is per-row lookup traffic and sampling it would put a mutex in the row loop.

func LikeMatch ¶

func LikeMatch(pattern, s string, escape rune) bool

LikeMatch implements SQL `LIKE` matching:

• `%` matches zero or more characters, none of which may be a line terminator
• `_` matches exactly one character that is not a line terminator
• `escape` (if non-zero) makes a following `%` or `_` literal

Greedy backtrack; O(|pattern| * |s|) worst case.

Conformance contract: this is the ONE runtime SQL LIKE matcher. It backs the QueryPredicate-layer ComparisonLike (via the predicates package), the Value-layer LikeOperatorValue, and the map-backed INFORMATION_SCHEMA WHERE evaluator. Java's `PatternForLikeValue.eval` (PatternForLikeValue.java:96-117) + `LikeOperatorValue.likeOperation` (LikeOperatorValue.java:93-99) is the spec: Java rewrites the SQL pattern into `^<regex>$`, compiles it with `Pattern.compile` and NO flags, and matches via `.find()`. This matcher must return what that composition would.

NEWLINE semantics — the observable consequences of "no flags":

• No DOTALL: `_` -> `.` and `%` -> `.*` do NOT match a line terminator. Java's line-terminator code points in default mode (java.util.regex.Pattern, "Line terminators") are `\n`, `\r`, U+0085 (NEL), U+2028 (LS) and U+2029 (PS). A terminator in the input can only be matched by a literal terminator in the pattern. So `'a\nb' LIKE 'a_b'` and `'a\nb' LIKE 'a%b'` are FALSE.
• No MULTILINE, so `^` only matches at index 0 — `.find()` on an `^...$` pattern degenerates to an anchored match.
• Default `$` matches at end of input OR when the remaining input is exactly one FINAL line terminator: "\n", "\r\n", "\r", U+0085, U+2028 or U+2029 — and `$` never matches BETWEEN the `\r` and `\n` of a final "\r\n" (java.util.regex.Pattern$Dollar). So `'abc\n' LIKE 'abc'` is TRUE, `'a' + U+2028 LIKE 'a'` is TRUE, and — because `.*` can match empty with `$` sitting before the trailing terminator — `'\n' LIKE '%'` is TRUE even though `%` cannot consume the `\n` itself.

ESCAPE semantics — Java's, exactly, and narrower than the SQL standard's. `PatternForLikeValue` builds its replacement table as exactly TWO escape entries on top of the metacharacter table:

.put(escapeChar + "_", "_")
.put(escapeChar + "%", "%")
.putAll(REPLACE_MAP)

so an escape rune is consumed as an escape ONLY when `_` or `%` follows it. In every other position — before an ordinary character, before a second escape rune, or dangling at the end of the pattern — no escape entry can match, and the rune is instead rewritten by the ordinary per-character rules. Three consequences, each of which differs from the more common "escape makes the next character literal" reading, and each pinned by a test:

• A DANGLING escape is not malformed and is not a no-match: it is the escape rune taken literally (or, if the escape rune is itself `%` or `_`, taken as that wildcard). Java's own corpus records this — `like.yamsql:92` runs `B2 NOT LIKE 'Z' ESCAPE 'Z'` and excludes the two `'Z'` rows, i.e. `'Z' LIKE 'Z' ESCAPE 'Z'` is TRUE. Java's comment there concedes the SQL standard would raise 22025 instead, but the pinned behaviour is the literal match.
• Escape before an ORDINARY character does not make that character literal — the escape rune itself is the literal and the next character is then read normally. `a\b` ESCAPE `\` matches `a\b`, not `ab`.
• There is no escaped-escape: `a\\b` ESCAPE `\` is two literal backslashes, not one.

The escape rune falling through to the ordinary rules is what makes an escape rune of `%` or `_` still act as a wildcard in those positions, which is why the fallthrough is a fallthrough and not an unconditional literal.

`values.sqlPatternToRegex` (PatternForLikeValue) is the same spec expressed as Java's regex translation. The two are cross-checked against each other by TestLikeMatch_CrossCheckSQLPatternToRegex in this package (an exhaustive ASCII pattern/subject/escape grid, evaluating the produced regex under Java's default-mode `.` and `$` semantics), and LikeMatch is independently fuzzed against a Java-semantics regex oracle by FuzzLikeMatch / FuzzLikeMatchEscape in `pkg/recordlayer/query/plan/cascades/predicates/comparisons_test.go`. Any divergence between them, or between either and Java, is a conformance bug.

func NameSplitCensus ¶

func NameSplitCensus() ([nameSplitSiteCount][nameSplitClassCount]int, []string)

NameSplitCensus returns a snapshot of the counters and the debt witnesses.

func NestedResolvedPath ¶

func NestedResolvedPath(v Value) (string, bool)

NestedResolvedPath returns the upper-cased dotted PATH a FUSED NESTED field reference reads, and reports whether v is one.

THE DEFINITION OF "NESTED" IS THE MULTI-ACCESSOR RESOLVED PATH, and it is one function because the predicate is the whole subtlety. The SQL resolver FUSES `n.sk` into ONE FieldValue with Resolved=[N,SK] — Java does exactly the same fuse (SemanticAnalyzer.lookupNestedField, SemanticAnalyzer.java:598 `FieldValue.ofFieldsAndFuseIfPossible`) and then names the result by the REQUESTED IDENTIFIER `n.sk` rather than by the fused value (SemanticAnalyzer.java:599).

`Field` cannot substitute, and the reason SURVIVED the mint fix that made it the LEAF name. It used to answer "what struct does this read out of", so `n.sk` and `n.co` shared it; it now answers "which member", so `t1.n.sk` and a flat `sk` share it instead. Either way it is one segment of a path and the question here needs all of them. Every output-naming authority must take the path. Reading `Field` there spells two different columns alike, and a name-keyed reader then serves one of them where the other was asked for.

THE PATH IS QUALIFIED WHEN THE REFERENCE HAS A CHILD, and that is a decision, not a leak. With ≥2 FROM sources the resolver emits the reference through its quantifier (`resolveScopedColumn`'s correlated arm), so the FieldValue carries `Child = QOV(T1)` and this returns `T1.N.SK`; with one source it returns `N.SK`. MEASURED end-to-end: `SELECT n.sk, n.co FROM t1, t2` explains as `Project([T1.N#1.SK#0, T1.N#1.CO#1], ...)` against `Project([N#1.SK#0, ...])` for the single-source form.

The qualifier is KEPT because dropping it would be the same conflation one level up: over `FROM t1, t2` where both declare an `n`, `T1.N.SK` and `T2.N.SK` are different columns and a bare `N.SK` collapses them in exactly the name-keyed maps this predicate exists to protect. It is also what the two neighbouring authorities already do for a childful reference — `sortKeyFieldRef` renders `LEG.COL` (cascades_translator.go) and `deriveProjectionColumnDef`'s non-nested arm calls `ColumnNameValue` when `Child != nil` (cascades_generator.go) — so qualifying here makes the nested arm agree with its siblings rather than inventing a third rule. The remaining asymmetry is ProjectionColumnName's own non-nested arm, which returns a bare `Field`; that arm is deliberately untouched, because changing it moves emitted names for every flat qualified projection and is a separate change.

Java agrees, and structurally: the fused nested reference is named by the REQUESTED IDENTIFIER (`SemanticAnalyzer.java:599`), an `Identifier` whose `fullyQualifiedName()` retains its qualifiers, and the top-level projection then strips them for the user-visible label (`Identifier.withoutQualifier`, Identifier.java:101). Go does the same: the display label for both forms is the bare leaf `SK` — measured, so the qualifier is an INTERNAL slot key and never reaches the user.

A path step can never contain the `#` that explainValueOrdinals escapes: a struct member name must be a valid protobuf identifier and DDL refuses anything else ("field name \"a#1\": a#1 it not a valid protobuf identifier", measured). That is now belt AND braces rather than the only argument — the escape no longer fires on an ordinal-free rendering at all. See the escape's own note in explainValueOrdinals.

func NewWrappedArrayMessage ¶

func NewWrappedArrayMessage(fd protoreflect.FieldDescriptor) (msg *dynamicpb.Message, values protoreflect.List)

NewWrappedArrayMessage builds an empty wrapper message instance for the given wrapper field (a field whose message is the wrapper shape). The caller appends elements to the returned list and stores the message value on the field.

func NoteFieldValueMint ¶

func NoteFieldValueMint(field string, baked bool)

NoteFieldValueMint records one FieldValue construction. The gate is the FIRST statement: disabled, this is one atomic load and a return.

func NoteOrderingBridgeDotted ¶

func NoteOrderingBridgeDotted(leftName, rightName string, answered bool)

NoteOrderingBridgeDotted records a bridge attempt in which at least one side carried a flat-dotted name. Gate first; disabled it is one atomic load.

func OrderingBridgeDottedCensus ¶

func OrderingBridgeDottedCensus() (int, [bridgeDottedClassCount]int, map[string]int)

OrderingBridgeDottedCensus returns the attempt total and class vector.

func OrderingFieldPair ¶

func OrderingFieldPair(a, b Value) bool

OrderingFieldPair reports whether both ordering values are plain FieldValue column reads. It is the TYPE test that dispatches the two ordering comparators: a pair inside this class is decided by SameOrderingColumn and by nothing else, with no fallthrough.

Finality is what the type test buys: an UNKNOWN-domain or rootless FieldValue cannot fall through to a weaker comparison and bridge two distinct exact columns (StatesOrderingColumn carries that witness).

A CardinalityValue wrapping a field is deliberately OUTSIDE the class. It is not a column of any row layout, so it has no column identity to state and is matched as a whole Value instead.

func OrdinalCarrierMatchState ¶

func OrdinalCarrierMatchState(
	layout OrdinalLayout,
	presence WindowMatchPresence,
) (matched bool, known bool, err error)

OrdinalCarrierMatchState reads the optional whole-current-object state after exact-recognizing both inputs. Absence of a carrier marker is not an error: ordinary rows predate no match decision and are therefore treated as present by their executor owner. A hostile presence implementation is never invoked through its public interface.

func OrdinalFieldName ¶

func OrdinalFieldName(ordinal int) string

OrdinalFieldName is the display name for an anonymous record field addressed by ordinal position. Java's planner names anonymous explode-with-ordinality fields `_0` (element) and `_1` (ordinal) — see the `q1._0` / `q1._1` access in the EXPLAIN output. The positional row type carries these names for the WITH-ORDINALITY element/ordinal slots; an ordinal-addressed FieldValue (Java's `FieldValue.ofOrdinalNumber`) reads the slot by ordinal.

func OrdinalSeedLegLayout ¶

func OrdinalSeedLegLayout(rc *RecordConstructorValue) (map[CorrelationIdentifier]OrdinalSeedLegWindow, *RecordType, []OrdinalSeedLegWindow)

OrdinalSeedLegLayout is OrdinalSeedLegWindowsAcceptingNested plus the TOP-LEVEL RUN LIST: the windows that TILE the merged row, in offset order.

THE MAP CANNOT SERVE THIS, and that is why the walk returns it rather than a caller deriving it. finalizeSeedWindows' rightmost-leaf case REPLACES a box run's own entry with a narrower sub-window — deliberately, because the box IS its rightmost leaf under the sourceBinding convention and an alias-qualified read must window the leaf rather than look the name up across the whole concat. So after finalization "the windows that tile the row" is simply not recoverable from the map: one of the tiles has been overwritten by something narrower, and nothing distinguishes that from a seed that always had a narrow leg there.

It is the planner twin of what the executor already returns — ordinalJoinSpansOf's `spans []legSpan`, in offset order — which is the shape this list is modelled on rather than invented against.

Callers that only need the addressable map keep the two-value entries; this answers the different question "how many legs TILE this row, and what shape is each".

ITS ONE PRODUCTION CONSUMER IS GONE. It served an orientation check inside the three-quantifier NLJ arm, and both retired with RFC-235. The run list is kept because the question it answers is not derivable from the map — finalization replaces a box run's entry with a narrower sub-window, after which the map no longer states which windows tile the row — so a future consumer would have to rebuild exactly this. A caller returning here should say why the map cannot serve it.

func OrdinalWindowMatchState ¶

func OrdinalWindowMatchState(
	layout OrdinalLayout,
	presence WindowMatchPresence,
	source QuantifiedObjectValue,
) (bool, error)

OrdinalWindowMatchState returns the exact per-row match state of one null-supplying source window. Both layout and presence are values-owned and exact-recognized; missing state is a malformed physical row, never an invitation to infer absence from all-NULL field values.

func OutputColumnName ¶

func OutputColumnName(v Value, alias string) string

OutputColumnName is the projection OUTPUT-name authority: the name that keys the emitted positional row's slot for a projected column (executeProjection's posNames) and therefore the name any downstream re-reader must use on the ordinal frontier — the upper-cased ALIAS when the column carries one, else the ProjectionColumnName rendering. It lives here so every site derives the name from ONE rule instead of a hand-synchronized copy — two copies of this rule have disagreed before (the executor wrote alias-preferring slot names while the recursive-CTE leg wrap re-read by ProjectionColumnName alone — a loud OrdinalResolutionError on valid SQL, no fallback by design). Both sites delegate here.

func ProjectionColumnName ¶

func ProjectionColumnName(v Value) string

ProjectionColumnName is the projection output-column NAMING CONTRACT: the name a projected Value's result is keyed under, alias-absent, in the emitted positional row's type (executeProjection's posNames). A NESTED FieldValue projects under its resolved PATH ("N.SK"); any other FieldValue under its (possibly dotted) Field; any other Value under its upper-cased ORDINAL-FREE rendering (a computed expression like `n + 1` is keyed "(N + 1)"). Shared here so the planner/translator side can READ a projection's output by the exact key the executor WRITES — reading by any other rendering (e.g. the logical layer's un-parenthesized "N + 1") is a loud OrdinalResolutionError on valid SQL.

ORDINAL-FREE IS THE WHOLE POINT OF THE THIRD ARM, and it was ExplainValue until the corpus showed what that costs. An ordinal is a PLAN-TIME BINDING of a reference; a column's name is not, so a name carrying one changes when the same reference is baked — the lockstep ColumnNameValue exists to hold. The composite arm was the one route that could mint such a name (the other two return schema text), and it did: `SELECT id + 1` inside a CTE keyed its output `(C1.ID#0 + 1)`, which the enclosing projection then re-read as a FIELD whose text contains a `#`, so the explain escape doubled it and the slot key read `(C1.ID##0 + 1)`. One line of the corpus carried it (cte.yaml#25) — the escape mechanism is in explainValueOrdinals' fieldValue arm, which now doubles only when it is rendering ordinals to disambiguate from.

The nested arm is NOT a special case bolted on: it is the same rule the sort side already applies (sortKeyExtraColumnName) and the same rule Java applies to every resolved reference. `Field` carries ONE segment — the struct root when this was written, the leaf now — so without the path `SELECT n.sk, n.co` emitted two slots named `N` (measured, visible to the user as duplicate column labels over correct data) and `SELECT t1.n.sk, sk` would emit two named `SK`. The path is what separates them.

func ProjectionOutputIdentityKey ¶

func ProjectionOutputIdentityKey(v Value, alias string) string

ProjectionOutputIdentityKey returns an opaque, boundary-safe discriminator for the parts of a projection's executor-visible output name that semantic Value identity does not already preserve.

A non-empty alias is the entire output-name authority, normalized exactly as OutputColumnName normalizes it. Without an alias, the Value's tree shape, operators, literals, and correlation structure already participate in semantic identity; the missing discriminator is every FieldValue's rendered display path. In particular, baked FieldValues compare by ordinal path alone, while ProjectionColumnName and ExplainValue still render their Field text (and a multi-accessor Explain renders every resolvedAccessor.Field). Walking all nested FieldValues therefore distinguishes both A#0 from B#0 and arithmetic expressions containing those reads.

CorrelationIdentifier spellings are deliberately excluded. They are alpha-renamable planner binders, not SQL output aliases: SemanticEqualsUnderAliasMap equates their Values through an AliasMap and SemanticHashCode is alias-invariant so hash-first memo lookup can find those equal expressions. A stable SQL-visible projection name is carried by an explicit projection alias or by FieldValue display paths, both folded here.

func ProjectionOutputSchemaIdentityOverrides ¶

func ProjectionOutputSchemaIdentityOverrides(
	projections []Value,
	aliases []string,
	outputNames []string,
) ([]string, error)

ProjectionOutputSchemaIdentityOverrides returns only the externally frozen portion of a projection schema: each slot whose authoritative output name differs from the name the Value program and aliases naturally derive. The resulting sparse vector is suitable for memo identity.

This distinction is load-bearing. Internal Value names can contain alpha-renamable correlation identifiers (a scalar-subquery QOV is the canonical example), so folding every derived result field name into a hash breaks alias invariance. Conversely, an SQL boundary may deliberately freeze a different positional key (`S.ID` over a Value naturally named `ID`); that difference is executable schema and must keep the projections apart. nil is returned when no frozen name adds information beyond the natural schema.

func ProtoFieldToRowValue ¶

func ProtoFieldToRowValue(fd protoreflect.FieldDescriptor, v protoreflect.Value) any

ProtoFieldToRowValue converts one proto FIELD value to the engine's row-value domain — the SINGLE conversion both the executor's record→row materialization and this package's struct descent use (exported so the two cannot drift; the executor's protoFieldToGo delegates here). Repeated fields become []any (a downstream Explode's collection); a proto map stays its raw Go value; scalars and UUID/message leaves go through protoScalarToRowValue.

func ProtoScalarKindToRowValue ¶

func ProtoScalarKindToRowValue(kind protoreflect.Kind, v protoreflect.Value) any

ProtoScalarKindToRowValue is the kind-keyed scalar conversion (no UUID/ message handling — that needs the descriptor, see protoScalarToRowValue). Exported as the single source of truth the executor's kind-based conversion calls directly, so the record→row and struct-descent conversions cannot drift on the scalar arms.

func PullUpValues ¶

func PullUpValues(toBePulledUp []Value, resultValue Value, alias CorrelationIdentifier) (map[Value]Value, error)

PullUpValues translates a list of values through a result value, returning a map from original value to pulled-up value. Values that cannot be pulled up are omitted from the map.

This is the batch form used by Ordering.PullUpThroughValue.

func QualifierRecoveryCensus ¶

func QualifierRecoveryCensus() ([qualRecSiteCount][qualRecClassCount]int, [qualRecSiteCount][qualRecClassCount][]string)

QualifierRecoveryCensus returns a snapshot of the counters and witnesses.

func QualifierRecoveryWitnessCap ¶

func QualifierRecoveryWitnessCap() int

QualifierRecoveryWitnessCap exposes the cap so a harness can check saturation.

func QuantifiedRowShapesAgree ¶

func QuantifiedRowShapesAgree(left, right Type) bool

QuantifiedRowShapesAgree reports whether two exact QOV flowed types denote the SAME BOUND ROW. It is the one comparison every runtime QOV *lookup* uses, and it deliberately excludes the top-level nullable bit.

That bit is not part of a row's shape: on a quantifier it declares that the quantifier's row may be ABSENT, and absence is carried structurally by the binding itself — a nil row, or a positive explicit-absence proof — never by the row's type. Evaluating FieldValue(qov, i) against a present row is bit-identical whichever way the bit is set, and against an absent one both yield NULL, so the bit can decide nothing at a lookup.

One alias therefore legitimately carries two QOVs differing only there. That pairing is Java's, not a Go accident: an outer join's OUTPUT columns are pulled up through Quantifier.pullUpResultColumnsWithNullability(true), which mints QuantifiedObjectValue.of(alias, rowType.withNullability(true)), while the same alias's ON/WHERE predicates keep reading getFlowedObjectValue() — the leg's own, non-nullable row. Java binds both by alias alone; Go's exact channel keeps the strictly stronger check on everything that IS shape.

Field names, ordinals, arity, record names and every NESTED nullability still have to match exactly, so a foreign owner spelled with the same alias is still refused. Type DERIVATION sites (layout window construction, the null-supplying proofs, metadata nullability) must keep comparing with Equals: there the bit is the whole point.

func QuantifierFlowsAScalarRow ¶

func QuantifierFlowsAScalarRow(value Value) bool

QuantifierFlowsAScalarRow reports whether value is a quantified object value whose flowed row is NOT a record — the shape an UNNEST leg over a scalar array produces, where the quantifier's "row" is one bare value rather than a struct.

It exists because both callers were spelling the same three-part test inline (is it a QOV, can it state a row, is that row a non-record) and the middle part is only there to make the third safe. Naming the question keeps the guard from being read as redundant and dropped, which would turn "cannot state a row" into "flows a scalar row" — the wrong answer, and a silently wrong output LABEL rather than a crash.

func RecordAccessorPathCall ¶

func RecordAccessorPathCall(class AccessorPathClass)

RecordAccessorPathCall counts one call's outcome. Callers must guard on LegIdentityCensusEnabled().

func RecordAccessorPathDottedWitness ¶

func RecordAccessorPathDottedWitness(name string)

RecordAccessorPathDottedWitness records the flat-dotted NAME that tripped the ratchet arm, so the producer can be found rather than guessed at. Callers must guard on LegIdentityCensusEnabled().

The name is exactly the string the guard refused to split, which is the whole point: it is the only artifact that distinguishes "a real nested path arrived lazy" from "a qualifier was concatenated onto a leaf".

func RecordDottedArmAnswer ¶

func RecordDottedArmAnswer(name string, owner CorrelationIdentifier)

RecordDottedArmAnswer records one name the executor's dotted arm answered on, with the OWNER correlation the reader held. Callers must guard on LegIdentityCensusEnabled().

First writer wins for the map, and a LATER, DIFFERENT owner for the same name is RECORDED as a collision rather than dropped. That is not tidiness: a name answered under two owners, one attributed and one not, would otherwise report as cleanly attributed and the second owner would never appear anywhere. The census's whole claim is per-name, so a name with two owners invalidates the claim for that name.

func RecordDottedLegQualifier ¶

func RecordDottedLegQualifier(site DottedLegSite, qual string, matchedAlias CorrelationIdentifier, matchedBinding string, lookup DottedLegLookup)

RecordDottedLegQualifier counts one qualifier-against-leg-table match. Callers must guard on LegIdentityCensusEnabled().

func RecordDottedRowTypeDerivation ¶

func RecordDottedRowTypeDerivation(fields []Field)

RecordDottedRowTypeDerivation counts ONE RecordType derivation by the generic record-constructor path, cut by whether the row it describes is the DOTTED `LEG.COL` shape. Callers must guard on LegIdentityCensusEnabled().

func RecordInnerScalarLegTitleAt ¶

func RecordInnerScalarLegTitleAt(producer InnerLegProducer, corr CorrelationIdentifier, title string)

RecordInnerScalarLegTitleAt registers one (correlation, title) pair minted for a correlated-scalar seed inner leg, naming the producer. Callers must guard on LegIdentityCensusEnabled().

func RecordLegIdentityComparison ¶

func RecordLegIdentityComparison(site LegIdentitySite, legName, corrName string)

RecordLegIdentityComparison records one leg-identity pair at a site: legName is the leg's stored text, corrName the counterparty correlation's own spelling.

Callers must guard on LegIdentityCensusEnabled() so the disabled path costs one atomic load and no argument evaluation.

func RecordLegIdentityConversion ¶

func RecordLegIdentityConversion(site LegIdentitySite, leg, corr CorrelationIdentifier, retiredVerdict bool)

RecordLegIdentityConversion is recordLegIdentityPair plus the acceptance test the conversion needs: retiredVerdict is what the predicate this site USED TO evaluate says about this same pair, and a disagreement with SameLeg is counted and witnessed.

Every converted site must use this rather than recordLegIdentityPair while the migration is open. Computing the retired predicate at the site costs a string compare inside the census gate — production never evaluates it — and it is what turns "the conversion is representation-only" from three inferences chained across separate zero counts into one measurement of the decision itself. The retired predicates are not uniform (two sites compared exact text, two upper-folded one side), so no single central rule could stand in for them; each site states its own, verbatim.

Callers must guard on LegIdentityCensusEnabled().

func RecordLegIdentityLeg ¶

func RecordLegIdentityLeg(leg RecordTypeLeg)

RecordLegIdentityLeg records a leg's two spellings against each other at the text-vs-identity divergence site. Every reader that walks a leg calls it, so the population is every leg any consumer looked at.

Callers must guard on LegIdentityCensusEnabled().

func RecordNameForDescriptor ¶

func RecordNameForDescriptor(descriptor protoreflect.MessageDescriptor) string

RecordNameForDescriptor is FieldNameForProtoField's twin for the record's own name, un-escaped by the same rule.

func RecordNameSplit ¶

func RecordNameSplit(site NameSplitSite, class NameSplitClass, name string)

RecordNameSplit records one resolution decision at a splitting arm. `name` is the rendered field name the arm was handed; it is used only for the witness list of the debt bucket, so a regrowth arrives with the spelling that caused it rather than only a count.

func RecordQualifierRecovery ¶

func RecordQualifierRecovery(site QualifierRecoverySite, class QualifierRecoveryClass, name, identity string)

RecordQualifierRecovery records ONE resolution decision at a dark splitter.

`name` is the rendered name the site was handed and `identity` is the structured counterparty it had in hand (empty when it had none). Both go into the witness so a regrowth arrives with the pair that caused it — for DIVERGED in particular, the count alone cannot say which side is wrong.

func RecordSeedWindowLookup ¶

func RecordSeedWindowLookup(site SeedWindowSite, found bool)

RecordSeedWindowLookup is the common shape: found or not.

func RecordSeedWindowLookupOfKind ¶

func RecordSeedWindowLookupOfKind(site SeedWindowSite, found bool, kind LegKind)

RecordSeedWindowLookupOfKind is the kind-aware counterpart of RecordSeedWindowLookup, for the readers that dispatch on the window kind.

func RecordSeedWindowRead ¶

func RecordSeedWindowRead(site SeedWindowSite, class SeedWindowReadClass)

RecordSeedWindowRead counts one keyed read of a seed-window map. Callers must guard on LegIdentityCensusEnabled().

func RecordSelectResultMint ¶

func RecordSelectResultMint(site SelectResultMintSite, rv Value)

RecordSelectResultMint counts ONE select-result-value construction and registers its identity.

The gate is the FIRST statement and it returns: with the census off this site must cost one atomic load and nothing else. The shape spelling below is a Sprintf per select expression built, which is planning-path work nothing consumes when the census is disabled.

func ReportLegIdentityCensus ¶

func ReportLegIdentityCensus(w io.Writer, label string)

ReportLegIdentityCensus dumps every site's counts and witnesses. It reports unconditionally — a narrowed corpus still has numbers worth seeing, it just has no floors to check.

func ResetAccessorPathCensus ¶

func ResetAccessorPathCensus()

ResetAccessorPathCensus clears the counters.

func ResetDottedLegQualifierCensus ¶

func ResetDottedLegQualifierCensus()

ResetDottedLegQualifierCensus clears the counters.

func ResetDottedRowTypeProducerCensus ¶

func ResetDottedRowTypeProducerCensus()

ResetDottedRowTypeProducerCensus clears the counters.

func ResetDottedWitnessAttribution ¶

func ResetDottedWitnessAttribution()

ResetDottedWitnessAttribution clears the census.

func ResetFieldValueMintCensus ¶

func ResetFieldValueMintCensus()

ResetFieldValueMintCensus clears the counters.

func ResetLegIdentityCensus ¶

func ResetLegIdentityCensus()

ResetLegIdentityCensus zeroes every site's counts and witnesses.

func ResetNameSplitCensus ¶

func ResetNameSplitCensus()

ResetNameSplitCensus clears the counters. For tests that measure one shape.

func ResetOrderingBridgeDottedCensus ¶

func ResetOrderingBridgeDottedCensus()

ResetOrderingBridgeDottedCensus clears the counters.

func ResetQualifierRecoveryCensus ¶

func ResetQualifierRecoveryCensus()

ResetQualifierRecoveryCensus clears the counters. For tests measuring one shape.

func ResetSeedWindowReaderCensus ¶

func ResetSeedWindowReaderCensus()

ResetSeedWindowReaderCensus clears the counters.

func ResetSelectResultMintCensus ¶

func ResetSelectResultMintCensus()

ResetSelectResultMintCensus clears the counters and the origin registry.

func SameColumnPath ¶

func SameColumnPath(a, b *fieldPath) bool

SameColumnPath reports whether two RESOLVED accessor paths denote the same column. It is the ORDINAL-PATH element of the identity triple asked BETWEEN two references, rather than resolved into a caller's stated layout the way IdentityIn is — the shape a matcher holding both operands needs. The CORRELATION element is not covered here; SameOrderingColumn compares it separately before consulting this path predicate.

Java's FieldPath.equals is element-wise ordinal equality with the per-step name excluded (FieldValue.java:411-420, over resolvedAccessor.equals at :676-685, which is getOrdinal()-only). Go needs two proofs on top, both for shapes Java cannot express:

• the DOMAIN, KNOWN on both sides and equal. Java's childValue is non-null and typed, so the layout an ordinal indexes is always derivable; Go mints childless bakes, and two ordinal-equal paths can address two different layouts. An ordinal conflation reads as authoritative, which is strictly worse than the name conflation it would replace.
• a NON-NEGATIVE ordinal at every step. Java asserts ordinal >= 0 at construction (FieldValue.java:651); Go mints Ordinal -1 name-only accessors at its unnest/gather/index-expansion seeds. Two of those are ordinal-equal BY CONSTRUCTION, so an ordinal comparison over them is vacuous and would bind two distinct nested fields as one.

Both declines are the fail-closed direction: a refused match costs a rewrite, an accepted one binds the wrong column.

func SameLeg ¶

func SameLeg(a, b CorrelationIdentifier) bool

SameLeg reports whether two identifiers name the same quantifier — the CORRELATION element of RFC-197's identity triple, compared in ONE place so every proof that asks "does this value read that leg?" gets the same answer.

The comparison is EXACT, matching Java, whose CorrelationIdentifier.equals is `Objects.equals(id, that.id)` (CorrelationIdentifier.java:132).

Exactness is not merely Java-fidelity here — it is load-bearing. Alias namespaces in this planner are deliberately case-DISJOINT: the semantic scope upper-folds every user correlation at its single registration chokepoint (semantic/scope.go), while UniqueCorrelationIdentifier mints the machine counter in LOWERCASE (`q$1`). scope.go states the consequence it is protecting: a quoted `"q$5"` cannot forge a planner-minted q$5. A case-folding comparison erases exactly that protection — it lets a user alias that upper-folds onto the minted namespace be accepted as the minted leg, and every caller of this helper is a proof about which row a value reads. A forged match there is a wrong-rows plan or a fabricated cardinality, not a lost optimization.

The same call was already made independently at the qualified-key rewrite in rule_implement_nested_loop_join.go, whose comment reads "a fold here would let a quoted user alias cross into the lowercase machine namespace". This helper now agrees with it rather than contradicting it.

Folding was tempting because the translator does not upper-case aliases consistently — some paths fold an alias at construction and others pass the spelling through verbatim — so an exact comparison can fail to recognize a leg that really is the right one. (This used to cite three specific translator lines; two of them had already drifted onto unrelated code, which is why the claim is stated structurally now. A line number is not a citation once the file moves under it.) That costs a DECLINE — every caller reads "cannot tell" as "do not apply the correction" — and it is the translator's inconsistency to fix at the source, not this helper's to mask. Masking it here would trade a recoverable missed optimization for an unrecoverable forged identity. An UNSTATED identifier (the Go zero value, empty name) names nothing, and two of them name nothing in common. Go's zero value has no Java analogue — Quantifier.getAlias() is @Nonnull and a CorrelationIdentifier is never constructed empty — so the only way to hold one here is a producer that forgot to state an identity. Answering "same leg" for that pair is how an unstated-identity leg binds a zero-value correlation and starts serving its slots: every caller reads true as "this correlation names this leg". Declining turns the omission into the miss it actually is.

func SameOrderingColumn ¶

func SameOrderingColumn(a, b Value) bool

SameOrderingColumn reports whether two ORDERING Values denote the same column by identity: the same ordinal path in the same STATED layout, read off the same exact root. Both sides must have stated an identity; a side that has not declines, and nothing here consults a display name.

It is the ordinal-domain counterpart of CanBridgeOrderingValueRoots' name comparison, and it exists because the obvious alternative is unsound: ValuesStructurallyEqual routes two baked FieldValues through FieldPath.Equals, which is ordinal-only and DOMAIN-BLIND (Java's resolvedAccessor.equals, FieldValue.java:675-689 — sound there because a Java FieldValue always has a non-null typed childValue, so the layout an ordinal indexes is never in question). RFC-232 now gives both candidate and request keys exact QOV roots. Requiring root equality keeps self-join columns apart and makes the comparator reflexive, symmetric, and transitive.

func SeedWindowReaderCensus ¶

func SeedWindowReaderCensus() [seedWindowSiteCount][seedWindowReadClassCount]int

SeedWindowReaderCensus reports the per-site class matrix.

func SemanticEqualsUnderAliasMap ¶

func SemanticEqualsUnderAliasMap(a, b Value, aliases AliasMap) bool

SemanticEqualsUnderAliasMap reports whether two Values are equal up to the quantifier-alias correspondence in `aliases` — the bool, alias-map-keyed counterpart of EqualsWithoutChildren+children, for memo interning and relational EqualsWithoutChildren (RFC-040 040.2). Correlation-bearing leaf Values compare their alias through the map (an unmapped alias maps to itself, so identical aliases compare equal under the empty map); every other Value compares structurally via EqualsWithoutChildren and recurses children under the same map.

This is consistent with SemanticHashCode: when this returns true, the two values have equal SemanticHashCode (both alias-invariant on the leaf aliases). Distinct from the cascades ValueEquivalence path, which carries QueryPlanConstraints for match-candidate compensation; this is the constraint-free bool primitive the expression/memo layer needs.

func SemanticHashCode ¶

func SemanticHashCode(v Value) uint64

SemanticHashCode returns an ALIAS-INVARIANT structural hash of a Value: the contract (Java Correlated.semanticHashCode) is

SemanticEqualsUnderAliasMap(a, b, m)  ⟹  SemanticHashCode(a) == SemanticHashCode(b)

for ANY alias map m — so the hash must NOT depend on specific quantifier-alias names. Correlation-bearing leaf Values (QuantifiedObjectValue, QuantifiedRecord, Object, ConstantObject, Exists, ScalarSubquery, UnmatchedAggregate, IndexEntryObject, JoinMerge) hash to a per-type tag with the alias EXCLUDED; value-bearing leaves (ConstantValue, BooleanValue, ParameterValue) fold their literal; structural Values fold a type tag + children.

Lives in the values package (RFC-040 040.1b relocation) so both expressions (for relational EqualsWithoutChildren/HashCodeWithoutChildren, 040.2) and cascades (memoEqual) can use it without an import cycle. Inert until those call sites switch to it.

func SetLegIdentityCensusEnabled ¶

func SetLegIdentityCensusEnabled(on bool)

SetLegIdentityCensusEnabled turns the census on or off. It is OFF in every production path and in every test but the corpus census pass; when off, each comparison pays one relaxed atomic load.

The gate matters more here than for the planner-side censuses: two of these sites are on the PER-ROW executor path, so an always-on counter would put a contended atomic increment in the row loop.

func StatesOrderingColumn ¶

func StatesOrderingColumn(v Value) bool

StatesOrderingColumn reports whether ONE ordering value has stated a column identity SameOrderingColumn can read — a flat-or-nested resolved path in a known layout, off an exact quantifier root.

It is deliberately a ONE-VALUE predicate, and that shape is the whole point. The pairwise form it replaced ("do BOTH sides state an identity?") was used to DISPATCH: identity decided the pair when both stated one, and a pair where either side did not fell through to the domain-blind structural comparison. That dispatch is INTRANSITIVE inside the FieldValue class. Witness, all three values baked at ordinal path [0]:

A = [0] in layout D1          states an identity
B = [0] in layout D2          states an identity
U = [0], layout UNKNOWN       states none

Identity separates A from B (different layouts, EqualsWithoutChildren's FieldValue arm never looks at the layout). Availability dispatch sends both A~U and B~U to the structural arm, which compares ordinals only and says EQUAL. So U≡A, U≡B, A≢B — and a comparator that is not an equivalence relation makes every set it builds depend on INSERTION ORDER, which is a nondeterministic plan.

So dispatch is by TYPE — both operands *fieldValue means identity decides and the decision is FINAL — and this predicate exists only to CLASSIFY the population, never to choose an arm. A value that does not state an identity is UNADDRESSABLE: the comparator declines it, and the fix belongs at the producer that minted it without a layout.

func ToFloat64 ¶

func ToFloat64(v any) (f float64, isFloat, numeric bool)

ToFloat64 reports whether v is numeric (int-like or float) and returns its float64 promotion. isFloat distinguishes native-float inputs from integral ones promoted here — comparison-time promotion uses it to prefer the int path when both sides are integral.

func ToInt64 ¶

func ToInt64(v any) (int64, bool)

ToInt64 reports whether v is an integral type; returns the int64 promotion when so.

func TypeTerminatesOrderingClaim ¶

func TypeTerminatesOrderingClaim(t Type) bool

TypeTerminatesOrderingClaim reports whether a column of type t ends an ordering claim — i.e. whether its FDB tuple key order differs from the order CompareFloat64/compareOrdered impose. True for FLOAT and DOUBLE.

The predicate is deliberately POSITIVE ("prove it is a float") rather than negative ("prove it is safe"). A type we cannot identify returns false, so an unidentified column keeps whatever claim the producer would otherwise make. That is a knowing trade: the alternative — treating every untyped column as claim-terminating — silently deletes sort elimination everywhere a layout is absent, including paths where the column is provably an integer. The soundness that matters is enforced where the type system is actually engaged, which on the SQL path is everywhere a column comes from a table.

KNOWN CONSERVATISM, and it is a missed optimisation rather than a wrong answer. The predicate is keyed on the TYPE alone, so it cannot see the scan RANGE — and the two defects above are not reachable from every range.

The recoverable case is a range with a FINITE LOWER BOUND. Both defects are really about the NEGATIVE-NaN block, which packs below -Inf: it is the one that is physically FIRST and logically LAST, and it is what splits the NaN tie class across two disjoint ranges. A scan starting at a finite value can never reach it. The positive block remains reachable — a range open at the top runs past +Inf — but there it is harmless on both counts: positive NaN is physically LAST and CompareFloat64 ranks NaN GREATEST, so the orders agree, and with only one block in range the tie class is contiguous, so later columns stay ordered within it. Over such a scan the claim could soundly extend through the float column and on into the primary-key suffix; today it terminates anyway and the query materialises a sort it does not need.

Measured on rowdiff seed 3943842, and the measurement corrected the reasoning once already — do not restate this as "a bounded range excludes NaN". That seed reads `e BETWEEN 2.0 AND 5.0`, but only the LOWER bound is pushed into the index; the upper stays a residual predicate, so the scanned range is [2.0, +Inf] and does include the positive-NaN block. The finite LOWER bound is what makes it sound, not the BETWEEN.

Three sibling seeds look identical from the outside and are NOT this case: 3943193 and 3944227 are zero-valued float EQUALITIES, which genuinely span two signed-zero key blocks, and 3943308 is `d IS NOT NULL`, whose range covers the whole non-null domain and so reaches the negative-NaN block. Those three must keep their sort.

The range-aware refinement is UNBUILT, deliberately, and if it is ever built it goes HERE. Closing it needs the ComparisonRange threaded to this decision — the same shape of fix as EqualityPinsSinglePhysicalKeyOnColumn, which threads the COLUMN type to a decision that previously guessed from the operand — and it must land as the ONE authority both consumers already ask, never as a second copy in either. The planner asks it for sort elimination; the rowdiff harness's ordering axis asks it to decide whether a scan provides the order a sort re-imposes. A copy that knew about ranges in only one of them would put the two derivations back out of step, which is the exact drift these shared predicates exist to prevent.

That is also why the harness UNDER-REPORTS by construction here, and why that is correct rather than a gap in it. `d IS NOT NULL` and `e >= 2.0` plan the identical shape — a float leading key under an inequality — so a type-only predicate cannot separate the recoverable case from the unrecoverable one. The detector inherits this conservatism instead of growing its own range-aware rule, so `WHERE e >= 2.0 ORDER BY e, id` is recorded as a missed optimization at the place the rule lives rather than kept alive as a nightly red.

It is not built because, unlike the column-type fix, nothing about it is a soundness defect: it buys latency, not correctness.

func ValidateOrdinalLayoutAdmission ¶

func ValidateOrdinalLayoutAdmission(view OrdinalLayout) error

ValidateOrdinalLayoutAdmission exact-recognizes a layout without invoking methods on a hostile interface implementation.

func ValidateProjectionAliasSources ¶

func ValidateProjectionAliasSources(
	sources []ProjectionAliasSource,
	aliasMinted []bool,
	slots int,
) error

ValidateProjectionAliasSources checks a slot-parallel alias-source vector. A source can exist only for a machinery-minted alias, and absence must carry no hidden correlation. A short vector is valid and means uncaptured sources.

func ValidateRequiredBindingsAdmission ¶

func ValidateRequiredBindingsAdmission(view RequiredBindings) error

ValidateRequiredBindingsAdmission exact-recognizes a binding manifest without invoking methods on a hostile interface implementation.

func ValueSize ¶

func ValueSize(v Value) int

ValueSize returns the total node count in v (v + all descendants). Counterpart to PredicateSize for the Value tree. Rule authors use this to gate expensive rewrites that would otherwise explode tree size.

func ValuesStructurallyEqual ¶

func ValuesStructurallyEqual(a, b Value) bool

ValuesStructurallyEqual reports whether two Values are structurally equal: same concrete Go type, same metadata, and recursively equal children. Stronger than ExplainValue comparison which could theoretically collide on structurally different values that render the same string.

func WalkValue ¶

func WalkValue(v Value, visit func(Value) bool)

WalkValue applies visit to every node in v's subtree, pre-order. If visit returns false, descent into that node's children is skipped (siblings + ancestors continue). Rule authors use this for tree-wide searches — e.g. "does any sub-expression reference this correlation?" or "does this Value tree contain an aggregate?".

Safe on nil: returns immediately. Mirrors WalkPredicate over the Value side of the hierarchy.