gudusoft.gsqlparser.resolver2.binding

Class BindingTrace

Object

gudusoft.gsqlparser.resolver2.binding.BindingTrace

public final class BindingTrace
extends Object

Immutable record of HOW one name reference was bound during the final resolver pass (design: dynamic-sql-fragment-provenance-design.md, R3 / R4 step 3).

The dynamic-SQL per-edge publication proof (P3) needs the full binding chain of every evidence reference, and its rule is fail-closed on completeness: trace == null || !trace.complete ⇒ the reference is unprovable. A missing trace is therefore always SAFE — it can only shrink the published-edge set, never let an unproven edge through. This is why the many direct setSourceTable sites in ScopeBuilder do not all need instrumenting at once: uninstrumented paths simply yield no trace.

Captured today:

• the scope-machinery choke point (NameResolver.resolve) — records the winning match's namespace, scope, resolve path and the climb depth from the starting scope (correlated references);
• the typed direct-binding clusters review round 2 named: OUTPUT INSERTED/DELETED, trigger pseudo-tables, MERGE target/SET/INSERT columns and MERGE USING values.

Capture is off by default (TSQLResolverConfig.captureBindingTrace) and observation-only: nothing in resolution reads a trace.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BindingTrace.BinderKind What kind of binder resolved the reference.

Field Summary

Fields

Modifier and Type	Field and Description
BindingTrace.BinderKind	binderKind
boolean	complete TRUE iff the ENTIRE binding chain is known: an exact single-match scope resolution with a recorded namespace, fully consumed name parts and a known climb path — or a typed direct binding with a known target.
Object	definitionNode The AST node that DEFINES the binder: the TTable of a table namespace, the TCTE of a CTE namespace (header column lists included), the TSelectSqlStatement of a derived table, or the direct-binding target table.
TTable	directTarget Direct-binding target table; null for scope resolution.
int	matchCount Number of matches the scope machinery reported (1 for a clean bind).
String	matchedScope Scope-type name where the winning match lives; null when unknown.
INamespace	namespace Winning namespace; null for direct bindings or failed resolution.
TTable	observedSourceTable The reference's sourceTable AS OF capture time.
TObjectName	reference The reference this trace describes (identity key in the registry).
String	resolvePath The winning match's resolve path (display form); null when unknown.
int	scopeClimbDepth Parent-scope hops from the starting scope to the matched scope; 0 for a local bind, > 0 for correlated references, -1 when the matched scope was not on the starting scope's parent chain (unknown — incomplete).
String	startingScope Scope-type name where resolution started; null for direct bindings.
ResolutionStatus	status Scope-machinery outcome; null for direct bindings.

Method Summary

Modifier and Type	Method and Description
static BindingTrace	direct(TObjectName reference, BindingTrace.BinderKind kind, TTable target) Typed direct-binding capture (ScopeBuilder clusters).
static BindingTrace	scopeResolution(TObjectName reference, ResolutionStatus status, INamespace namespace, Object definitionNode, TTable observedSourceTable, String startingScope, String matchedScope, String resolvePath, int matchCount, int scopeClimbDepth, boolean fullyConsumed, boolean exactMatch, boolean fallbackUsed) Scope-machinery capture (NameResolver choke point).
String	toString()

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

reference

public final TObjectName reference

The reference this trace describes (identity key in the registry).

binderKind

public final BindingTrace.BinderKind binderKind

status

public final ResolutionStatus status

Scope-machinery outcome; null for direct bindings.

namespace

public final INamespace namespace

Winning namespace; null for direct bindings or failed resolution.

directTarget

public final TTable directTarget

Direct-binding target table; null for scope resolution.

definitionNode

public final Object definitionNode

The AST node that DEFINES the binder: the TTable of a table namespace, the TCTE of a CTE namespace (header column lists included), the TSelectSqlStatement of a derived table, or the direct-binding target table. This is what the publication proof checks spans against; a trace without it cannot be complete.

observedSourceTable

public final TTable observedSourceTable

The reference's sourceTable AS OF capture time. Two roles: (a) staleness signal — post-resolution correction handlers (QUALIFY / USING / subquery-alias / MERGE restores) may change or clear it, and the registry invalidates the trace when the current value differs by identity; (b) the FROM-reference wrapper node of the binding chain — for CTE and derived-table binds this is the TTable carrying the AS alias, whose span the definition node alone does not cover. A complete scope trace requires it.

startingScope

public final String startingScope

Scope-type name where resolution started; null for direct bindings.

matchedScope

public final String matchedScope

Scope-type name where the winning match lives; null when unknown.

resolvePath

public final String resolvePath

The winning match's resolve path (display form); null when unknown.

matchCount

public final int matchCount

Number of matches the scope machinery reported (1 for a clean bind).

scopeClimbDepth

public final int scopeClimbDepth

Parent-scope hops from the starting scope to the matched scope; 0 for a local bind, > 0 for correlated references, -1 when the matched scope was not on the starting scope's parent chain (unknown — incomplete).

complete

public final boolean complete

TRUE iff the ENTIRE binding chain is known: an exact single-match scope resolution with a recorded namespace, fully consumed name parts and a known climb path — or a typed direct binding with a known target. The P3 rule refuses anything else.

Method Detail

scopeResolution

public static BindingTrace scopeResolution(TObjectName reference,
                                           ResolutionStatus status,
                                           INamespace namespace,
                                           Object definitionNode,
                                           TTable observedSourceTable,
                                           String startingScope,
                                           String matchedScope,
                                           String resolvePath,
                                           int matchCount,
                                           int scopeClimbDepth,
                                           boolean fullyConsumed,
                                           boolean exactMatch,
                                           boolean fallbackUsed)

Scope-machinery capture (NameResolver choke point). Complete only for an exact single match with a recorded namespace AND its definition node, at most the terminal column segment unconsumed, a known climb path, and NO fallback involved (a struct-field fallback replaces the result after the recorded match, so the match data no longer describes the binding).

direct

public static BindingTrace direct(TObjectName reference,
                                  BindingTrace.BinderKind kind,
                                  TTable target)

Typed direct-binding capture (ScopeBuilder clusters).

toString

public String toString()

Overrides:

toString in class Object