@dbsp/nql 1.3.0 → 1.5.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { NQL_INTERNAL_COMPILER_OPTIONS, isNqlBindingRef, getNqlBindingRefName, createNqlBindingRef } from '@dbsp/types/internal';
-import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, isParamIntent, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction } from '@dbsp/types';
+import { NQL_INTERNAL_COMPILER_OPTIONS, markNqlTrustedRelationFilter, createNqlBindingRef, isNqlBindingRef, getNqlBindingRefName } from '@dbsp/types/internal';
+import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_VALUE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction, isParamIntent } from '@dbsp/types';
 import { createToken, Lexer, CstParser } from 'chevrotain';
 
 // src/compiler/index.ts
@@ -51,6 +51,8 @@ var ColumnValidator = class _ColumnValidator {
   }
   schema;
   knownCteTables = /* @__PURE__ */ new Set();
+  virtualBindingTables = /* @__PURE__ */ new Map();
+  virtualBindingRelationFilters = /* @__PURE__ */ new Map();
   /**
    * Register CTE names so validateTable() skips validation for them.
    * CTE names are not physical tables in the schema, but are valid FROM targets.
@@ -64,6 +66,124 @@ var ColumnValidator = class _ColumnValidator {
   clearKnownCteTables() {
     this.knownCteTables.clear();
   }
+  /**
+   * Register an NQL binding as a virtual table with a concrete output schema.
+   * Binding columns are logical output names, so matching is exact.
+   */
+  addVirtualBindingTable(name, columns, relationFilters) {
+    this.virtualBindingTables.set(name, columns);
+    if (relationFilters) {
+      this.virtualBindingRelationFilters.set(name, relationFilters);
+    }
+  }
+  /** Clear all registered virtual binding tables (used between compilations). */
+  clearVirtualBindingTables() {
+    this.virtualBindingTables.clear();
+    this.virtualBindingRelationFilters.clear();
+  }
+  isVirtualBindingTable(name) {
+    return name !== void 0 && this.virtualBindingTables.has(name);
+  }
+  getVirtualBindingColumns(name) {
+    return this.virtualBindingTables.get(name);
+  }
+  getTableColumns(name) {
+    const virtualColumns = this.virtualBindingTables.get(name);
+    if (virtualColumns) return virtualColumns;
+    return this.schema.getTable(name)?.columns.map((column) => column.name);
+  }
+  hasPhysicalTable(name) {
+    return !this.virtualBindingTables.has(name) && !!this.schema.getTable(name);
+  }
+  hasQualifiedRelationLookup() {
+    return typeof this.schema.getRelation === "function";
+  }
+  getRelation(sourceTable, relationName) {
+    return this.schema.getRelation?.(`${sourceTable}.${relationName}`) ?? this.schema.getRelationsFrom(sourceTable).find((relation) => relation.name === relationName);
+  }
+  getRelationsFrom(sourceTable) {
+    return this.schema.getRelationsFrom(sourceTable);
+  }
+  getVirtualBindingRelation(bindingName, relationName) {
+    return this.virtualBindingRelationFilters.get(bindingName)?.relations.find((relation) => relation.relation === relationName);
+  }
+  getVirtualBindingScalarRelation(bindingName, relationName) {
+    return this.virtualBindingRelationFilters.get(bindingName)?.scalarRelations?.find((relation) => relation.relation === relationName);
+  }
+  explainVirtualBindingRelationRejection(bindingName, relationName) {
+    const metadata = this.virtualBindingRelationFilters.get(bindingName);
+    if (!metadata) {
+      return "no binding relation-filter metadata is available";
+    }
+    if (metadata.unsafeReason) return metadata.unsafeReason;
+    const sourceTable = metadata.sourceTable;
+    if (!sourceTable) {
+      return "the binding source table could not be proven";
+    }
+    const relation = this.getRelation(sourceTable, relationName);
+    if (!relation) {
+      return `relation '${relationName}' is not declared on source table '${sourceTable}'`;
+    }
+    const fk = relation.foreignKey;
+    const fkColumns = typeof fk === "string" ? [fk] : Array.isArray(fk) ? [...fk] : [];
+    if (relation.type !== "belongsTo") {
+      return `relation '${relationName}' is '${relation.type ?? "unknown"}'; A-lite only supports relations whose FK column is on the binding source table`;
+    }
+    if (fkColumns.length !== 1) {
+      return `relation '${relationName}' must have exactly one FK column for A-lite binding relation filters`;
+    }
+    const fkColumn = fkColumns[0];
+    if (fkColumn === void 0) {
+      return `relation '${relationName}' must have exactly one FK column for A-lite binding relation filters`;
+    }
+    const directProjection = metadata.directProjectionLineage?.find(
+      (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, fkColumn)
+    );
+    if (!directProjection) {
+      const available2 = this.virtualBindingTables.get(bindingName)?.join(", ");
+      return `relation '${relationName}' FK column '${fkColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available2 ? ` (available columns: ${available2})` : ""}`;
+    }
+    const available = this.virtualBindingTables.get(bindingName)?.join(", ");
+    return `relation '${relationName}' FK column '${fkColumn}' is not available through binding '${bindingName}'${available ? ` (available columns: ${available})` : ""}`;
+  }
+  explainVirtualBindingScalarRelationRejection(bindingName, relationName) {
+    const metadata = this.virtualBindingRelationFilters.get(bindingName);
+    if (!metadata) {
+      return "no binding relation metadata is available";
+    }
+    if (metadata.unsafeReason) return metadata.unsafeReason;
+    const sourceTable = metadata.sourceTable;
+    if (!sourceTable) {
+      return "the binding source table could not be proven";
+    }
+    const relation = this.getRelation(sourceTable, relationName);
+    if (!relation) {
+      return `relation '${relationName}' is not declared on source table '${sourceTable}'`;
+    }
+    const fk = relation.foreignKey;
+    const fkColumns = typeof fk === "string" ? [fk] : Array.isArray(fk) ? [...fk] : [];
+    if (relation.type !== "belongsTo" && relation.type !== "hasOne") {
+      return `relation '${relationName}' is '${relation.type ?? "unknown"}'; binding relation columns require a scalar belongsTo/hasOne relation`;
+    }
+    if (fkColumns.length !== 1) {
+      return `relation '${relationName}' must have exactly one FK column for binding relation columns`;
+    }
+    const fkColumn = fkColumns[0];
+    if (fkColumn === void 0) {
+      return `relation '${relationName}' must have exactly one FK column for binding relation columns`;
+    }
+    const sourceColumn = relation.type === "belongsTo" ? fkColumn : relation.sourceKey ?? "id";
+    const directProjection = metadata.directProjectionLineage?.find(
+      (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, sourceColumn)
+    );
+    if (!directProjection) {
+      const available2 = this.virtualBindingTables.get(bindingName)?.join(", ");
+      const sourceColumnLabel = relation.type === "belongsTo" ? "FK column" : "source key column";
+      return `relation '${relationName}' ${sourceColumnLabel} '${sourceColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available2 ? ` (available columns: ${available2})` : ""}`;
+    }
+    const available = this.virtualBindingTables.get(bindingName)?.join(", ");
+    return `relation '${relationName}' source column '${sourceColumn}' is not available through binding '${bindingName}'${available ? ` (available columns: ${available})` : ""}`;
+  }
   /**
    * Convert camelCase to snake_case for column name matching.
    * NQL queries may use either form (e.g., viewCount or view_count).
@@ -79,14 +199,40 @@ var ColumnValidator = class _ColumnValidator {
     if (queryCol === schemaCol) return true;
     return _ColumnValidator.toSnakeCase(queryCol) === _ColumnValidator.toSnakeCase(schemaCol);
   }
+  /**
+   * Resolve a user-authored column spelling to the model column name.
+   * Uses the same exact-or-snake/camel equivalence as validateColumn().
+   */
+  resolveColumnName(table, column) {
+    if (column === "*") return column;
+    const virtualColumns = this.virtualBindingTables.get(table);
+    if (virtualColumns) {
+      return virtualColumns.find((c) => c === column);
+    }
+    const tableInfo = this.schema.getTable(table);
+    if (!tableInfo) return void 0;
+    return tableInfo.columns.find(
+      (c) => _ColumnValidator.columnsMatch(column, c.name)
+    )?.name;
+  }
   validateColumn(table, column) {
     if (column === "*") return;
+    const virtualColumns = this.virtualBindingTables.get(table);
+    if (virtualColumns) {
+      const exists = virtualColumns.some((c) => c === column);
+      if (!exists) {
+        const available = virtualColumns.join(", ") || "(none)";
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_UNKNOWN_COLUMN,
+          `Column '${column}' is not projected by NQL binding '${table}'. Available columns: ${available}`
+        );
+      }
+      return;
+    }
     const tableInfo = this.schema.getTable(table);
     if (!tableInfo) return;
-    const exists = tableInfo.columns.some(
-      (c) => _ColumnValidator.columnsMatch(column, c.name)
-    );
-    if (!exists) {
+    const resolvedColumn = this.resolveColumnName(table, column);
+    if (resolvedColumn === void 0) {
       const available = tableInfo.columns.map((c) => c.name).join(", ");
       throw new NqlSemanticException(
         NqlErrorCodes.SEM_UNKNOWN_COLUMN,
@@ -95,6 +241,7 @@ var ColumnValidator = class _ColumnValidator {
     }
   }
   validateTable(table) {
+    if (this.virtualBindingTables.has(table)) return;
     if (this.knownCteTables.has(table)) return;
     const tableInfo = this.schema.getTable(table);
     if (!tableInfo) {
@@ -105,10 +252,34 @@ var ColumnValidator = class _ColumnValidator {
     }
   }
   resolveRelationTarget(sourceTable, relationName) {
-    const relations = this.schema.getRelationsFrom(sourceTable);
-    const rel = relations.find((r) => r.name === relationName);
+    if (this.virtualBindingTables.has(sourceTable)) {
+      const virtualRelation = this.getVirtualBindingRelation(
+        sourceTable,
+        relationName
+      );
+      if (virtualRelation) return virtualRelation.targetTable;
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Query '${sourceTable}' reads from an NQL binding and cannot use relation filters (${relationName}) under A-lite (ref-#182): ${this.explainVirtualBindingRelationRejection(sourceTable, relationName)}.`
+      );
+    }
+    const rel = this.getRelation(sourceTable, relationName);
     return rel?.target;
   }
+  assertNoBindingRelationConstruct(bindingName, construct, detail) {
+    if (!this.isVirtualBindingTable(bindingName)) return;
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Query '${bindingName}' reads from an NQL binding and cannot ${construct} (${detail}). Relation constructs require a physical model table, not a CTE binding.`
+    );
+  }
+  assertNoBindingRelationPath(bindingName, path) {
+    if (!this.isVirtualBindingTable(bindingName)) return;
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `Query '${bindingName}' reads from an NQL binding and cannot reference relation path '${path}'. Relation paths require a physical model table, not a CTE binding.`
+    );
+  }
 };
 var FORBIDDEN_PARAM_NAMES = /* @__PURE__ */ new Set([
   "__proto__",
@@ -197,6 +368,125 @@ function expressionToField(expr, aliasContext) {
   }
   return null;
 }
+function isBindingTable(ctx, table) {
+  if (table === void 0) return false;
+  return ctx.bindingOutputColumns.has(table) || ctx.validator?.isVirtualBindingTable?.(table) === true;
+}
+function bindingColumns(ctx, table) {
+  if (table === void 0) return void 0;
+  if (ctx.bindingOutputColumns.has(table)) {
+    return ctx.bindingOutputColumns.get(table);
+  }
+  return ctx.validator?.getVirtualBindingColumns?.(table);
+}
+function getKnownBindingColumns(ctx, table) {
+  return bindingColumns(ctx, table);
+}
+function assertNoBindingRelationConstruct(ctx, bindingName, construct, detail) {
+  if (!isBindingTable(ctx, bindingName)) return;
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot ${construct} (${detail}). Relation constructs require a physical model table, not a CTE binding.`
+  );
+}
+function throwBindingRelationFilter182(bindingName, relationName, reason) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot use relation filters (${relationName}) under A-lite (ref-#182): ${reason}.`
+  );
+}
+function throwBindingRelationColumn182(bindingName, relationName, reason) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot select relation column '${relationName}' under A-full (ref-#182): ${reason}.`
+  );
+}
+function resolveBindingRelationFilter(ctx, bindingName, relationPath) {
+  if (!isBindingTable(ctx, bindingName)) return void 0;
+  const actualBindingName = bindingName;
+  const relationName = relationPath.join(".");
+  if (relationPath.length !== 1) {
+    throwBindingRelationFilter182(
+      actualBindingName,
+      relationName,
+      "multi-hop binding relation filters are not supported; the relation path must be a single source-table relation"
+    );
+  }
+  const relation = relationPath[0];
+  if (!relation) {
+    throwBindingRelationFilter182(
+      actualBindingName,
+      relationName,
+      "the relation path must name a source-table relation"
+    );
+  }
+  const virtualRelation = ctx.validator?.getVirtualBindingRelation(
+    actualBindingName,
+    relation
+  );
+  if (virtualRelation) return virtualRelation;
+  const reason = ctx.validator?.explainVirtualBindingRelationRejection(
+    actualBindingName,
+    relation
+  ) ?? "model metadata is not available";
+  throwBindingRelationFilter182(actualBindingName, relation, reason);
+}
+function resolveBindingRelationColumn(ctx, bindingName, relationPath, selectedColumn) {
+  if (!isBindingTable(ctx, bindingName)) return void 0;
+  const actualBindingName = bindingName;
+  const relationName = relationPath.join(".");
+  if (relationPath.length !== 1) {
+    throwBindingRelationColumn182(
+      actualBindingName,
+      relationName,
+      "multi-hop binding relation columns are not supported; the relation path must be a single source-table relation"
+    );
+  }
+  const relation = relationPath[0];
+  if (!relation) {
+    throwBindingRelationColumn182(
+      actualBindingName,
+      relationName,
+      "the relation path must name a source-table relation"
+    );
+  }
+  const virtualRelation = ctx.validator?.getVirtualBindingScalarRelation(
+    actualBindingName,
+    relation
+  );
+  if (!virtualRelation) {
+    const reason = ctx.validator?.explainVirtualBindingScalarRelationRejection(
+      actualBindingName,
+      relation
+    ) ?? "model metadata is not available";
+    throwBindingRelationColumn182(actualBindingName, relation, reason);
+  }
+  ctx.validator?.validateColumn(virtualRelation.targetTable, selectedColumn);
+  return virtualRelation;
+}
+function assertNoBindingRelationPath(ctx, bindingName, path) {
+  if (!isBindingTable(ctx, bindingName)) return;
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot reference relation path '${path}'. Relation paths require a physical model table, not a CTE binding.`
+  );
+}
+function validateColumnForTable(ctx, table, column) {
+  if (table === void 0 || column === "*") return;
+  if (isBindingTable(ctx, table)) {
+    const columns = bindingColumns(ctx, table);
+    if (columns === void 0) return;
+    if (!columns.some((c) => c === column)) {
+      const available = columns.join(", ") || "(none)";
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_UNKNOWN_COLUMN,
+        `Column '${column}' is not projected by NQL binding '${table}'. Available columns: ${available}`
+      );
+    }
+    return;
+  }
+  ctx.validator?.validateColumn(table, column);
+}
 function expressionToValue(expr, ctx) {
   switch (expr.type) {
     case "namedParam":
@@ -216,6 +506,22 @@ function expressionToValue(expr, ctx) {
     case "null":
       return null;
     case "path":
+      if (ctx) {
+        const field = expr.segments.join(".");
+        const isBindingReference = expr.segments.length === 1 && isBindingTable(ctx, field);
+        if (isBindingReference) {
+          return createNqlBindingRef(field);
+        }
+        const sourceTable = ctx.currentFromTable;
+        const isVirtualBindingSource = sourceTable !== void 0 && isBindingTable(ctx, sourceTable);
+        if (isVirtualBindingSource) {
+          if (field.includes(".")) {
+            assertNoBindingRelationPath(ctx, sourceTable, field);
+          } else {
+            validateColumnForTable(ctx, sourceTable, field);
+          }
+        }
+      }
       return createNqlBindingRef(expr.segments.join("."));
     case "function": {
       return {
@@ -382,6 +688,24 @@ function isAggregateFunction(name) {
   );
 }
 function validateWhereField(ctx, field, aliasContext, originalExpr) {
+  if (!aliasContext && !field.includes(".") && ctx.currentHavingAliases?.has(field)) {
+    throw new NqlSemanticException(
+      NqlErrorCodes.SEM_INVALID_SYNTAX,
+      `HAVING cannot reference SELECT alias '${field}'. PostgreSQL does not allow SELECT aliases in HAVING; repeat the aggregate expression or filter the result in an outer query.`
+    );
+  }
+  if (!aliasContext && ctx.currentRelationTarget && !field.includes(".")) {
+    ctx.validator?.validateColumn(ctx.currentRelationTarget, field);
+    return;
+  }
+  if (!aliasContext && ctx.currentFromTable && isBindingTable(ctx, ctx.currentFromTable)) {
+    if (field.includes(".")) {
+      assertNoBindingRelationPath(ctx, ctx.currentFromTable, field);
+    } else {
+      validateColumnForTable(ctx, ctx.currentFromTable, field);
+    }
+    return;
+  }
   if (!ctx.validator) return;
   if (aliasContext) {
     const isInnerScope = originalExpr?.type === "path" && originalExpr.segments.length > 1 && originalExpr.segments[0] === aliasContext;
@@ -396,12 +720,14 @@ function validateWhereField(ctx, field, aliasContext, originalExpr) {
     }
     return;
   }
-  if (ctx.currentRelationTarget && !field.includes(".")) {
-    ctx.validator.validateColumn(ctx.currentRelationTarget, field);
+  if (ctx.currentFromTable && field.includes(".")) {
+    if (isBindingTable(ctx, ctx.currentFromTable)) {
+      assertNoBindingRelationPath(ctx, ctx.currentFromTable, field);
+    }
     return;
   }
   if (ctx.currentFromTable && !field.includes(".")) {
-    ctx.validator.validateColumn(ctx.currentFromTable, field);
+    validateColumnForTable(ctx, ctx.currentFromTable, field);
   }
 }
 function coerceToStringKey(expr, contextLabel, ctx) {
@@ -768,30 +1094,573 @@ function applyIncludeLimit(includes, path, limit) {
 }
 
 // src/compiler/compile-query.ts
+var activeBindingScopes = /* @__PURE__ */ new WeakMap();
+var PORTABLE_BINDING_FINAL_FUNCTIONS = /* @__PURE__ */ new Set([
+  ...NQL_SELECT_AGGREGATE_FUNCTIONS,
+  ...NQL_SELECT_VALUE_FUNCTIONS
+]);
+var DEFAULT_RELATION_TARGET_COLUMN = "id";
 function compileNestedQuery(query, ctx, fns, bindings) {
   const savedContext = {
     currentFromTable: ctx.currentFromTable,
-    currentRelationTarget: ctx.currentRelationTarget
+    currentRelationTarget: ctx.currentRelationTarget,
+    currentHavingAliases: ctx.currentHavingAliases
   };
   try {
-    if (bindings) {
-      return compileQuery(query, ctx, fns, bindings);
+    const nestedBindings = bindings ?? activeBindingScopes.get(ctx);
+    if (nestedBindings) {
+      return compileQuery(query, ctx, fns, nestedBindings);
     }
     return fns.compileQuery(query, ctx);
   } finally {
     ctx.currentFromTable = savedContext.currentFromTable;
     ctx.currentRelationTarget = savedContext.currentRelationTarget;
+    ctx.currentHavingAliases = savedContext.currentHavingAliases;
   }
 }
 function compileQuery(query, ctx, fns, bindings) {
+  const hadPreviousBindingScope = activeBindingScopes.has(ctx);
+  const previousBindingScope = activeBindingScopes.get(ctx);
+  if (bindings) {
+    activeBindingScopes.set(ctx, bindings);
+  }
+  try {
+    return compileQueryInternal(query, ctx, fns, bindings);
+  } finally {
+    if (hadPreviousBindingScope && previousBindingScope) {
+      activeBindingScopes.set(ctx, previousBindingScope);
+    } else {
+      activeBindingScopes.delete(ctx);
+    }
+  }
+}
+function collectSelectAliasesFromQuery(query) {
+  const aliases = /* @__PURE__ */ new Set();
+  for (const clause of query.clauses) {
+    if (clause.type !== "select") continue;
+    for (const item of clause.items) {
+      if (item.type === "expression" && item.alias) {
+        aliases.add(item.alias);
+      }
+    }
+  }
+  return aliases;
+}
+function throwUnsupportedBindingFinal(bindingName, feature) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Query '${bindingName}' reads from an NQL binding and cannot use ${feature} in a binding-final query (#183). Binding-final queries are restricted to portable common-ground SQL over projected binding columns: SELECT (including plain DISTINCT), WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET, and UNION/INTERSECT/EXCEPT.`
+  );
+}
+function toSnakeCase(name) {
+  return name.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+function columnsMatch(left, right) {
+  return left === right || toSnakeCase(left) === toSnakeCase(right);
+}
+function expressionIntentContainsAggregate(value) {
+  if (!value || typeof value !== "object") return false;
+  const record = value;
+  if (record.kind === "aggregate") return true;
+  for (const child of Object.values(record)) {
+    if (Array.isArray(child)) {
+      if (child.some((item) => expressionIntentContainsAggregate(item))) {
+        return true;
+      }
+    } else if (expressionIntentContainsAggregate(child)) {
+      return true;
+    }
+  }
+  return false;
+}
+function selectContainsAggregate(select) {
+  if (!select) return false;
+  if (select.type === "aggregate") return true;
+  if (select.type !== "expressions") return false;
+  return select.columns.some(
+    (column) => expressionIntentContainsAggregate(column)
+  );
+}
+function relationForeignKeysOnSource(relation) {
+  if (!relation || relation.type !== "belongsTo") return void 0;
+  if (typeof relation.foreignKey === "string") return [relation.foreignKey];
+  if (Array.isArray(relation.foreignKey)) return relation.foreignKey;
+  return void 0;
+}
+function relationForeignKeys(relation) {
+  if (!relation) return void 0;
+  if (typeof relation.foreignKey === "string") return [relation.foreignKey];
+  if (Array.isArray(relation.foreignKey)) return relation.foreignKey;
+  return void 0;
+}
+function relationCardinality(relation) {
+  return relation?.type === "hasMany" || relation?.type === "belongsToMany" ? "many" : "one";
+}
+function unsafeBindingRelationReason(intent, ctx, bindingDependencies) {
+  if (!ctx.validator) return "model metadata is not available";
+  if (!ctx.validator.hasQualifiedRelationLookup()) {
+    return "model.getRelation metadata is not available";
+  }
+  if (bindingDependencies.length > 0 || isBindingTable(ctx, intent.from)) {
+    return "the binding body reads from another NQL binding";
+  }
+  if (!ctx.validator.hasPhysicalTable(intent.from)) {
+    return `the binding source '${intent.from}' is not a single real model table`;
+  }
+  if (intent.batchValuesSource) {
+    return "the binding body reads from a batch-values source";
+  }
+  if ((intent.joins?.length ?? 0) > 0) {
+    return "the binding body uses joins";
+  }
+  if ((intent.include?.length ?? 0) > 0) {
+    return "the binding body uses relation includes";
+  }
+  if ((intent.groupBy?.length ?? 0) > 0 || intent.having) {
+    return "the binding body uses GROUP BY or HAVING";
+  }
+  if (selectContainsAggregate(intent.select)) {
+    return "the binding body uses aggregate projections";
+  }
+  return void 0;
+}
+function findDirectSourceProjection(sourceTable, sourceColumn, directProjectionLineage) {
+  return directProjectionLineage.find(
+    (projection) => projection.sourceTable === sourceTable && columnsMatch(projection.sourceColumn, sourceColumn)
+  );
+}
+function virtualRelationForBinding(relation, sourceTable, directProjectionLineage) {
+  const fkColumns = relationForeignKeysOnSource(relation);
+  if (!relation || !fkColumns || fkColumns.length !== 1) return void 0;
+  const fkColumn = fkColumns[0];
+  const sourceProjection = findDirectSourceProjection(
+    sourceTable,
+    fkColumn,
+    directProjectionLineage
+  );
+  if (!sourceProjection) return void 0;
+  return {
+    relation: relation.name,
+    sourceTable,
+    targetTable: relation.target,
+    sourceColumn: sourceProjection.outputColumn,
+    targetColumn: relation.targetKey ?? DEFAULT_RELATION_TARGET_COLUMN,
+    cardinality: "one"
+  };
+}
+function scalarVirtualRelationForBinding(relation, sourceTable, directProjectionLineage) {
+  if (!relation) return void 0;
+  if (relation.type !== "belongsTo" && relation.type !== "hasOne") {
+    return void 0;
+  }
+  const fkColumns = relationForeignKeys(relation);
+  if (!fkColumns || fkColumns.length !== 1) return void 0;
+  const fkColumn = fkColumns[0];
+  const sourceJoinColumn = relation.type === "belongsTo" ? fkColumn : relation.sourceKey ?? DEFAULT_RELATION_TARGET_COLUMN;
+  const targetJoinColumn = relation.type === "belongsTo" ? relation.targetKey ?? DEFAULT_RELATION_TARGET_COLUMN : fkColumn;
+  const sourceProjection = findDirectSourceProjection(
+    sourceTable,
+    sourceJoinColumn,
+    directProjectionLineage
+  );
+  if (!sourceProjection) return void 0;
+  return {
+    relation: relation.name,
+    sourceTable,
+    targetTable: relation.target,
+    sourceColumn: sourceProjection.outputColumn,
+    targetColumn: targetJoinColumn,
+    cardinality: relationCardinality(relation)
+  };
+}
+function getBindingRelationFilterMetadata(intent, ctx, outputSchema, bindingDependencies) {
+  const unsafeReason = unsafeBindingRelationReason(
+    intent,
+    ctx,
+    bindingDependencies
+  );
+  if (unsafeReason) {
+    return {
+      unsafeReason,
+      directProjectionLineage: outputSchema.directProjectionLineage,
+      relations: []
+    };
+  }
+  const sourceTable = intent.from;
+  const relations = [];
+  const scalarRelations = [];
+  const relationNames = new Set(
+    ctx.validator?.getRelationsFrom(sourceTable).map((relation) => relation.name)
+  );
+  for (const relationName of relationNames ?? []) {
+    const relation = ctx.validator?.getRelation(sourceTable, relationName);
+    const virtualRelation = virtualRelationForBinding(
+      relation,
+      sourceTable,
+      outputSchema.directProjectionLineage ?? []
+    );
+    if (virtualRelation) relations.push(virtualRelation);
+    const scalarRelation = scalarVirtualRelationForBinding(
+      relation,
+      sourceTable,
+      outputSchema.directProjectionLineage ?? []
+    );
+    if (scalarRelation) scalarRelations.push(scalarRelation);
+  }
+  return {
+    sourceTable,
+    directProjectionLineage: outputSchema.directProjectionLineage,
+    relations,
+    scalarRelations
+  };
+}
+function validateBindingFinalPath(expr, ctx, bindingName) {
+  const { segments } = expr;
+  if (segments.length === 1) {
+    if (ctx.currentHavingAliases?.has(segments[0])) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `HAVING cannot reference SELECT alias '${segments[0]}'. PostgreSQL does not allow SELECT aliases in HAVING; repeat the aggregate expression or filter the result in an outer query.`
+      );
+    }
+    validateColumnForTable(ctx, bindingName, segments[0]);
+    return;
+  }
+  const firstSegment = segments[0];
+  if (ctx.pseudoColumnKeywords.has(firstSegment.toLowerCase())) {
+    assertNoBindingRelationConstruct(
+      ctx,
+      bindingName,
+      "use pseudo-column traversals",
+      firstSegment
+    );
+    return;
+  }
+  assertNoBindingRelationPath(ctx, bindingName, segments.join("."));
+}
+function validateBindingFinalFunction(expr, ctx, bindingName, allowRelationFilters) {
+  const fn = expr.name.toLowerCase();
+  if (!PORTABLE_BINDING_FINAL_FUNCTIONS.has(fn)) {
+    throwUnsupportedBindingFinal(bindingName, `function ${expr.name}()`);
+  }
+  for (const arg of expr.args) {
+    validateBindingFinalExpression(arg, ctx, bindingName, allowRelationFilters);
+  }
+}
+function validateBindingFinalExpression(expr, ctx, bindingName, allowRelationFilters = false) {
+  switch (expr.type) {
+    case "path":
+      validateBindingFinalPath(expr, ctx, bindingName);
+      break;
+    case "binary":
+      validateBindingFinalExpression(
+        expr.left,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      validateBindingFinalExpression(
+        expr.right,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      break;
+    case "unary":
+      validateBindingFinalExpression(
+        expr.operand,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      break;
+    case "comparison":
+      validateBindingFinalExpression(
+        expr.left,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      validateBindingFinalExpression(
+        expr.right,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      break;
+    case "in":
+      validateBindingFinalExpression(
+        expr.expression,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      if (Array.isArray(expr.values)) {
+        for (const value of expr.values) {
+          validateBindingFinalExpression(
+            value,
+            ctx,
+            bindingName,
+            allowRelationFilters
+          );
+        }
+      } else if (expr.values.type === "dateRange") ; else ;
+      break;
+    case "between":
+      validateBindingFinalExpression(
+        expr.expression,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      validateBindingFinalExpression(
+        expr.low,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      validateBindingFinalExpression(
+        expr.high,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      break;
+    case "isNull":
+      validateBindingFinalExpression(
+        expr.expression,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      break;
+    case "function":
+      validateBindingFinalFunction(
+        expr,
+        ctx,
+        bindingName,
+        allowRelationFilters
+      );
+      break;
+    case "case":
+      if (expr.subject) {
+        validateBindingFinalExpression(
+          expr.subject,
+          ctx,
+          bindingName,
+          allowRelationFilters
+        );
+      }
+      for (const when of expr.whenClauses) {
+        validateBindingFinalExpression(
+          when.condition,
+          ctx,
+          bindingName,
+          allowRelationFilters
+        );
+        validateBindingFinalExpression(
+          when.result,
+          ctx,
+          bindingName,
+          allowRelationFilters
+        );
+      }
+      if (expr.elseClause) {
+        validateBindingFinalExpression(
+          expr.elseClause,
+          ctx,
+          bindingName,
+          allowRelationFilters
+        );
+      }
+      break;
+    case "relationFilter":
+      if (allowRelationFilters) {
+        resolveBindingRelationFilter(
+          ctx,
+          bindingName,
+          expr.relation
+        );
+        break;
+      }
+      assertNoBindingRelationConstruct(
+        ctx,
+        bindingName,
+        "use relation filters",
+        expr.relation.join(".")
+      );
+      break;
+    case "any":
+      throwUnsupportedBindingFinal(bindingName, "ANY(:param)");
+      break;
+    case "rangeOp":
+    case "rangeLiteral":
+      throwUnsupportedBindingFinal(bindingName, "PostgreSQL range operators");
+      break;
+    case "jsonAccess":
+    case "jsonComparison":
+      throwUnsupportedBindingFinal(bindingName, "PostgreSQL JSON operators");
+      break;
+    case "window":
+      throwUnsupportedBindingFinal(bindingName, "window functions");
+      break;
+    case "exists":
+      throwUnsupportedBindingFinal(bindingName, "EXISTS subqueries");
+      break;
+    case "subquery":
+      throwUnsupportedBindingFinal(bindingName, "scalar subqueries");
+      break;
+    case "variable":
+      throwUnsupportedBindingFinal(bindingName, `variable '${expr.name}'`);
+      break;
+    case "namedParam":
+    case "string":
+    case "number":
+    case "boolean":
+    case "null":
+    case "dateRange":
+      break;
+    /* v8 ignore next — defensive: default-reject future expression shapes in binding-final queries -- @preserve */
+    default:
+      throwUnsupportedBindingFinal(
+        bindingName,
+        `expression type '${expr.type ?? "unknown"}'`
+      );
+  }
+}
+function validateBindingFinalSelectClause(clause, ctx, bindingName) {
+  const distinctOn = clause.distinctOn;
+  if (distinctOn !== void 0) {
+    throwUnsupportedBindingFinal(bindingName, "DISTINCT ON");
+  }
+  for (const item of clause.items) {
+    switch (item.type) {
+      case "star":
+        break;
+      case "relationStar":
+        assertNoBindingRelationConstruct(
+          ctx,
+          bindingName,
+          "select relation columns",
+          item.relation.join(".")
+        );
+        break;
+      case "expression":
+        if (item.expression.type === "path" && item.expression.segments.length > 1) {
+          const segments = item.expression.segments;
+          const firstSegment = segments[0];
+          if (ctx.pseudoColumnKeywords.has(firstSegment.toLowerCase())) {
+            assertNoBindingRelationConstruct(
+              ctx,
+              bindingName,
+              "use pseudo-column traversals",
+              firstSegment
+            );
+          } else {
+            resolveBindingRelationColumn(
+              ctx,
+              bindingName,
+              segments.slice(0, -1),
+              segments.at(-1)
+            );
+          }
+        } else {
+          validateBindingFinalExpression(item.expression, ctx, bindingName);
+        }
+        break;
+      /* v8 ignore next — defensive: default-reject future select item shapes in binding-final queries -- @preserve */
+      default:
+        throwUnsupportedBindingFinal(
+          bindingName,
+          `SELECT item type '${item.type ?? "unknown"}'`
+        );
+    }
+  }
+}
+function validateBindingFinalQuery(query, ctx) {
+  const groupByIndex = query.clauses.findIndex((c) => c.type === "groupBy");
+  const havingAliases = collectSelectAliasesFromQuery(query);
+  for (let i = 0; i < query.clauses.length; i++) {
+    const clause = query.clauses[i];
+    switch (clause.type) {
+      case "where": {
+        if (groupByIndex >= 0 && i > groupByIndex) {
+          const previousHavingAliases = ctx.currentHavingAliases;
+          ctx.currentHavingAliases = havingAliases;
+          try {
+            validateBindingFinalExpression(clause.condition, ctx, query.table);
+          } finally {
+            ctx.currentHavingAliases = previousHavingAliases;
+          }
+        } else {
+          validateBindingFinalExpression(
+            clause.condition,
+            ctx,
+            query.table,
+            true
+          );
+        }
+        break;
+      }
+      case "select":
+        validateBindingFinalSelectClause(clause, ctx, query.table);
+        break;
+      case "groupBy":
+        for (const expr of clause.expressions) {
+          validateBindingFinalExpression(expr, ctx, query.table);
+        }
+        break;
+      case "orderBy":
+        for (const item of clause.items) {
+          validateBindingFinalExpression(item.expression, ctx, query.table);
+        }
+        break;
+      case "limit":
+        if (clause.relation) {
+          assertNoBindingRelationConstruct(
+            ctx,
+            query.table,
+            "use relation include limits",
+            clause.relation
+          );
+        }
+        break;
+      case "offset":
+      case "bind":
+      case "setOperation":
+        break;
+      case "flat":
+        throwUnsupportedBindingFinal(query.table, "flat relation include mode");
+        break;
+      case "lock":
+        throwUnsupportedBindingFinal(
+          query.table,
+          "row-level locks (FOR UPDATE / SKIP LOCKED), because locks over a CTE binding are silently ineffective"
+        );
+        break;
+      /* v8 ignore next — defensive: default-reject future clauses in binding-final queries -- @preserve */
+      default:
+        throwUnsupportedBindingFinal(
+          query.table,
+          `clause '${clause.type ?? "unknown"}'`
+        );
+    }
+  }
+}
+function compileQueryInternal(query, ctx, fns, bindings) {
+  const bindingSource = bindings?.get(query.table);
+  const isBindingSource = bindingSource !== void 0 || isBindingTable(ctx, query.table);
+  ctx.currentFromTable = query.table;
+  ctx.validator?.validateTable(query.table);
+  if (isBindingSource) {
+    validateBindingFinalQuery(query, ctx);
+  }
   const setClauseIndex = query.clauses.findIndex(
     (c) => c.type === "setOperation"
   );
   if (setClauseIndex >= 0) {
     return compileSetOperation(query, setClauseIndex, ctx, fns, bindings);
   }
-  ctx.currentFromTable = query.table;
-  ctx.validator?.validateTable(query.table);
   let groupByIndex = -1;
   for (let i = 0; i < query.clauses.length; i++) {
     if (query.clauses[i]?.type === "groupBy") {
@@ -799,6 +1668,7 @@ function compileQuery(query, ctx, fns, bindings) {
       break;
     }
   }
+  const havingAliases = collectSelectAliasesFromQuery(query);
   const whereConditions = [];
   const havingConditions = [];
   let select;
@@ -816,13 +1686,33 @@ function compileQuery(query, ctx, fns, bindings) {
     const clause = query.clauses[i];
     switch (clause.type) {
       case "where": {
-        const condition = resolveBindingsInWhere(
-          fns.compileExpression(clause.condition, ctx, fns),
-          bindings
-        );
         if (groupByIndex >= 0 && i > groupByIndex) {
+          const previousHavingAliases = ctx.currentHavingAliases;
+          ctx.currentHavingAliases = havingAliases;
+          const condition = (() => {
+            try {
+              return resolveBindingsInWhere(
+                fns.compileExpression(
+                  clause.condition,
+                  ctx,
+                  fns
+                ),
+                bindings
+              );
+            } finally {
+              ctx.currentHavingAliases = previousHavingAliases;
+            }
+          })();
           havingConditions.push(condition);
         } else if (currentIncludeBatch && currentIncludeBatch.length > 0) {
+          const condition = resolveBindingsInWhere(
+            fns.compileExpression(
+              clause.condition,
+              ctx,
+              fns
+            ),
+            bindings
+          );
           const targetInclude = currentIncludeBatch[currentIncludeBatch.length - 1];
           const mutableInclude = targetInclude;
           if (targetInclude.where) {
@@ -834,6 +1724,14 @@ function compileQuery(query, ctx, fns, bindings) {
             mutableInclude.where = condition;
           }
         } else {
+          const condition = resolveBindingsInWhere(
+            fns.compileExpression(
+              clause.condition,
+              ctx,
+              fns
+            ),
+            bindings
+          );
           whereConditions.push(condition);
         }
         break;
@@ -881,7 +1779,7 @@ function compileQuery(query, ctx, fns, bindings) {
       }
     }
   }
-  if (select && select.type === "expressions") {
+  if (select && select.type === "expressions" && !isBindingSource) {
     const relationPaths = /* @__PURE__ */ new Set();
     for (const expr of select.columns) {
       if (expr.kind === "relationColumn") {
@@ -909,6 +1807,12 @@ function compileQuery(query, ctx, fns, bindings) {
     }
   }
   if (includeLimits.size > 0) {
+    if (isBindingSource) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Query '${query.table}' reads from an NQL binding and cannot use relation include limits (${[...includeLimits.keys()].join(", ")}). Relation includes require a physical model table, not a CTE binding.`
+      );
+    }
     for (const [relation, limitCount] of includeLimits) {
       const rootRelation = relation.split(".")[0];
       const targetInclude = allIncludes.find(
@@ -935,7 +1839,7 @@ function compileQuery(query, ctx, fns, bindings) {
   } else if (havingConditions.length > 1) {
     having = { kind: "and", conditions: havingConditions };
   }
-  return {
+  const compiledQuery = {
     type: "select",
     from: query.table,
     ...select !== void 0 && { select },
@@ -949,6 +1853,7 @@ function compileQuery(query, ctx, fns, bindings) {
     ...offset !== void 0 && { offset },
     ...lock !== void 0 && { lock }
   };
+  return compiledQuery;
 }
 function getExplicitColumnCount(intent) {
   if ("kind" in intent && intent.kind === "setOperation") {
@@ -972,6 +1877,272 @@ function getExplicitColumnCount(intent) {
       return void 0;
   }
 }
+function expressionOutputColumn(expr) {
+  switch (expr.kind) {
+    case "column":
+      if (expr.column === "*") return void 0;
+      return expr.as ?? expr.column;
+    case "columnAlias":
+      return expr.alias;
+    case "relationColumn":
+      if (expr.column === "*") return void 0;
+      return expr.as;
+    case "aggregate":
+    case "function":
+    case "subquery":
+    case "arithmetic":
+    case "literal":
+    case "case":
+    case "jsonExtract":
+    case "jsonPathExtract":
+    case "customOp":
+    case "customFn":
+    case "array":
+    case "unary":
+    case "param":
+      return expr.as;
+    case "coalesce":
+    case "raw":
+    case "pseudoColumn":
+      return expr.as;
+    case "window":
+      return expr.alias;
+    case "comparison":
+    case "jsonContains":
+    case "jsonExists":
+    case "ref":
+    case "cast":
+    case "namedArg":
+    case "star":
+      return void 0;
+    /* v8 ignore next — defensive: exhaustive switch -- @preserve */
+    default:
+      return void 0;
+  }
+}
+function addUnique(columns, seen, column) {
+  if (seen.has(column)) return false;
+  seen.add(column);
+  columns.push(column);
+  return true;
+}
+function resolveSourceOutputColumns(intent, ctx, bindingName) {
+  const bindingColumns2 = getKnownBindingColumns(ctx, intent.from);
+  if (bindingColumns2 !== void 0) return bindingColumns2;
+  const columns = ctx.validator?.getTableColumns(intent.from);
+  if (columns !== void 0) return columns;
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `Cannot compute output schema for NQL binding '${bindingName}' from SELECT * on '${intent.from}' without a concrete table schema.`
+  );
+}
+function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []) {
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  const directProjectionLineage = [];
+  const addColumn = (column) => addUnique(columns, seen, column);
+  const resolveSourceColumn = (column) => ctx.validator?.resolveColumnName(intent.from, column) ?? column;
+  const addDirectProjection = (outputColumn, sourceColumn) => {
+    if (!addColumn(outputColumn)) return;
+    directProjectionLineage.push({
+      kind: "directProjection",
+      sourceTable: intent.from,
+      sourceColumn: resolveSourceColumn(sourceColumn),
+      outputColumn
+    });
+  };
+  const addSourceColumns = () => {
+    for (const column of resolveSourceOutputColumns(intent, ctx, bindingName)) {
+      addDirectProjection(column, column);
+    }
+  };
+  const { select } = intent;
+  if (!select || select.type === "all") {
+    addSourceColumns();
+    const outputSchema2 = { columns, directProjectionLineage };
+    return {
+      columns: outputSchema2.columns,
+      relationFilters: getBindingRelationFilterMetadata(
+        intent,
+        ctx,
+        outputSchema2,
+        bindingDependencies
+      )
+    };
+  }
+  if (select.type === "fields") {
+    for (const field of select.fields) {
+      if (field === "*") {
+        addSourceColumns();
+      } else {
+        addDirectProjection(field, field);
+      }
+    }
+    const outputSchema2 = { columns, directProjectionLineage };
+    return {
+      columns: outputSchema2.columns,
+      relationFilters: getBindingRelationFilterMetadata(
+        intent,
+        ctx,
+        outputSchema2,
+        bindingDependencies
+      )
+    };
+  }
+  if (select.type === "aggregate") {
+    for (const field of select.fields ?? []) {
+      addDirectProjection(field, field);
+    }
+    for (const aggregate of select.aggregates) {
+      if (!aggregate.as) {
+        throw new NqlSemanticException(
+          NqlErrorCodes.SEM_INVALID_SYNTAX,
+          `Cannot compute output schema for NQL binding '${bindingName}': aggregate '${aggregate.function}' must use an alias.`
+        );
+      }
+      addColumn(aggregate.as);
+    }
+    const outputSchema2 = { columns, directProjectionLineage };
+    return {
+      columns: outputSchema2.columns,
+      relationFilters: getBindingRelationFilterMetadata(
+        intent,
+        ctx,
+        outputSchema2,
+        bindingDependencies
+      )
+    };
+  }
+  for (const expr of select.columns) {
+    if (expr.kind === "column" && expr.column === "*") {
+      addSourceColumns();
+      continue;
+    }
+    if (expr.kind === "relationColumn" && expr.column === "*") {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Cannot compute output schema for NQL binding '${bindingName}' from relation SELECT * '${expr.relation}.*'. Use explicit aliases for binding outputs.`
+      );
+    }
+    const outputColumn = expressionOutputColumn(expr);
+    if (!outputColumn) {
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Cannot compute output schema for NQL binding '${bindingName}': selected expression must use an alias.`
+      );
+    }
+    if (expr.kind === "column") {
+      addDirectProjection(outputColumn, expr.column);
+    } else if (expr.kind === "columnAlias") {
+      addDirectProjection(outputColumn, expr.column);
+    } else {
+      addColumn(outputColumn);
+    }
+  }
+  const outputSchema = { columns, directProjectionLineage };
+  return {
+    columns: outputSchema.columns,
+    relationFilters: getBindingRelationFilterMetadata(
+      intent,
+      ctx,
+      outputSchema,
+      bindingDependencies
+    )
+  };
+}
+function validateNqlExpressionPaths(expr, ctx) {
+  switch (expr.type) {
+    case "path":
+      if (expr.segments.length === 1) {
+        if (ctx.currentFromTable && isBindingTable(ctx, ctx.currentFromTable)) {
+          validateColumnForTable(ctx, ctx.currentFromTable, expr.segments[0]);
+        }
+      } else if (ctx.currentFromTable && isBindingTable(ctx, ctx.currentFromTable)) {
+        assertNoBindingRelationPath(
+          ctx,
+          ctx.currentFromTable,
+          expr.segments.join(".")
+        );
+      }
+      break;
+    case "binary":
+      validateNqlExpressionPaths(expr.left, ctx);
+      validateNqlExpressionPaths(expr.right, ctx);
+      break;
+    case "unary":
+      validateNqlExpressionPaths(expr.operand, ctx);
+      break;
+    case "comparison":
+    case "jsonComparison":
+      validateNqlExpressionPaths(expr.left, ctx);
+      validateNqlExpressionPaths(expr.right, ctx);
+      break;
+    case "rangeOp":
+      validateNqlExpressionPaths(expr.left, ctx);
+      if (expr.scalar) {
+        validateNqlExpressionPaths(expr.scalar, ctx);
+      }
+      break;
+    case "in":
+      validateNqlExpressionPaths(expr.expression, ctx);
+      if (Array.isArray(expr.values)) {
+        for (const value of expr.values) {
+          validateNqlExpressionPaths(value, ctx);
+        }
+      }
+      break;
+    case "any":
+      validateNqlExpressionPaths(expr.column, ctx);
+      break;
+    case "between":
+      validateNqlExpressionPaths(expr.expression, ctx);
+      validateNqlExpressionPaths(expr.low, ctx);
+      validateNqlExpressionPaths(expr.high, ctx);
+      break;
+    case "isNull":
+      validateNqlExpressionPaths(expr.expression, ctx);
+      break;
+    case "function":
+      for (const arg of expr.args) {
+        validateNqlExpressionPaths(arg, ctx);
+      }
+      break;
+    case "window":
+      for (const arg of expr.args) {
+        validateNqlExpressionPaths(arg, ctx);
+      }
+      for (const item of expr.orderBy) {
+        validateNqlExpressionPaths(item.expression, ctx);
+      }
+      for (const partitionBy of expr.partitionBy) {
+        validateNqlExpressionPaths(partitionBy, ctx);
+      }
+      break;
+    case "case":
+      if (expr.subject) {
+        validateNqlExpressionPaths(expr.subject, ctx);
+      }
+      for (const when of expr.whenClauses) {
+        validateNqlExpressionPaths(when.condition, ctx);
+        validateNqlExpressionPaths(when.result, ctx);
+      }
+      if (expr.elseClause) {
+        validateNqlExpressionPaths(expr.elseClause, ctx);
+      }
+      break;
+    case "jsonAccess":
+      validateNqlExpressionPaths(expr.base, ctx);
+      break;
+    case "relationFilter":
+      assertNoBindingRelationConstruct(
+        ctx,
+        ctx.currentFromTable,
+        "use relation filters",
+        expr.relation.join(".")
+      );
+      break;
+  }
+}
 function compileSetOperation(query, setClauseIndex, ctx, fns, bindings) {
   const setClause = query.clauses[setClauseIndex];
   if (setClauseIndex < query.clauses.length - 1) {
@@ -981,6 +2152,7 @@ function compileSetOperation(query, setClauseIndex, ctx, fns, bindings) {
     );
   }
   const leftQuery = {
+    type: "query",
     table: query.table,
     clauses: query.clauses.slice(0, setClauseIndex)
   };
@@ -1016,10 +2188,11 @@ function compileSetOperation(query, setClauseIndex, ctx, fns, bindings) {
 }
 function compileGroupByClause(clause, ctx) {
   return clause.expressions.map((expr) => {
+    validateNqlExpressionPaths(expr, ctx);
     if (expr.type === "path") {
       const field = expr.segments.join(".");
       if (ctx.currentFromTable && !field.includes(".")) {
-        ctx.validator?.validateColumn(ctx.currentFromTable, field);
+        validateColumnForTable(ctx, ctx.currentFromTable, field);
       }
       return field;
     }
@@ -1030,10 +2203,13 @@ function compileOrderByClause(clause, ctx) {
   return clause.items.map((item) => compileOrderItem(item, ctx));
 }
 function compileOrderItem(item, ctx) {
+  validateNqlExpressionPaths(item.expression, ctx);
   const field = expressionToField(item.expression);
   if (field) {
-    if (ctx.currentFromTable && !field.includes(".") && !field.includes("(")) {
-      ctx.validator?.validateColumn(ctx.currentFromTable, field);
+    if (ctx.currentFromTable && field.includes(".") && isBindingTable(ctx, ctx.currentFromTable)) {
+      assertNoBindingRelationPath(ctx, ctx.currentFromTable, field);
+    } else if (ctx.currentFromTable && !field.includes(".") && !field.includes("(")) {
+      validateColumnForTable(ctx, ctx.currentFromTable, field);
     }
     return { field, direction: item.direction };
   }
@@ -1318,6 +2494,13 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
       return intent2;
     }
   }
+  const havingAggregateComparison = compileHavingAggregateComparison(
+    comp,
+    ctx,
+    aliasContext,
+    outerAliases
+  );
+  if (havingAggregateComparison) return havingAggregateComparison;
   const field = expressionToField(comp.left, aliasContext);
   if (!field) {
     throw new NqlSemanticException(
@@ -1344,6 +2527,26 @@ function compileComparison(expr, ctx, _fns, aliasContext, outerAliases) {
   };
   return intent;
 }
+function compileHavingAggregateComparison(comp, ctx, aliasContext, outerAliases) {
+  if (ctx.currentHavingAliases === void 0 || aliasContext || comp.left.type !== "function") {
+    return null;
+  }
+  const fn = comp.left.name.toLowerCase();
+  if (fn !== "count" || comp.left.args.length !== 0) {
+    return null;
+  }
+  const exprIntent = {
+    kind: "aggregate",
+    function: "count",
+    field: "*"
+  };
+  return {
+    kind: "expression",
+    expr: exprIntent,
+    operator: mapComparisonOperator(comp.operator),
+    value: resolveFilterValue(comp.right, ctx, aliasContext, outerAliases)
+  };
+}
 function compileRange(expr, ctx, _fns, aliasContext, outerAliases) {
   const rangeExpr = expr;
   const field = expressionToField(rangeExpr.left, aliasContext);
@@ -1617,11 +2820,18 @@ function compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases) {
   const relFilter = expr;
   const nestedOuterAliases = aliasContext ? [...outerAliases ?? [], aliasContext] : outerAliases ?? [];
   const prevRelationTarget = ctx.currentRelationTarget;
-  if (ctx.currentFromTable && ctx.validator && relFilter.relation[0]) {
-    ctx.currentRelationTarget = ctx.validator.resolveRelationTarget(
-      ctx.currentFromTable,
-      relFilter.relation[0]
-    );
+  const bindingRelation = ctx.currentFromTable && relFilter.relation[0] ? resolveBindingRelationFilter(
+    ctx,
+    ctx.currentFromTable,
+    relFilter.relation
+  ) : void 0;
+  if (ctx.currentFromTable && relFilter.relation[0]) {
+    if (ctx.validator) {
+      ctx.currentRelationTarget = ctx.validator.resolveRelationTarget(
+        ctx.currentFromTable,
+        relFilter.relation[0]
+      );
+    }
   }
   const where = compileExpression(
     relFilter.condition,
@@ -1631,13 +2841,27 @@ function compileRelationFilter(expr, ctx, fns, aliasContext, outerAliases) {
     nestedOuterAliases
   );
   ctx.currentRelationTarget = prevRelationTarget;
-  return {
+  const relationFilterIntent = {
     kind: "relationFilter",
     relation: relFilter.relation,
     where,
     mode: relFilter.mode,
-    ...relFilter.alias !== void 0 && { alias: relFilter.alias }
+    ...relFilter.alias !== void 0 && { alias: relFilter.alias },
+    ...bindingRelation !== void 0 && {
+      targetTable: bindingRelation.targetTable,
+      sourceColumn: bindingRelation.sourceColumn,
+      targetColumn: bindingRelation.targetColumn
+    }
   };
+  return bindingRelation ? markNqlTrustedRelationFilter(relationFilterIntent, {
+    relation: bindingRelation.relation,
+    targetTable: bindingRelation.targetTable,
+    sourceColumn: bindingRelation.sourceColumn,
+    targetColumn: bindingRelation.targetColumn,
+    ...bindingRelation.cardinality !== void 0 && {
+      cardinality: bindingRelation.cardinality
+    }
+  }) : relationFilterIntent;
 }
 function expandDateRangeList(field, patterns, negated) {
   const conditions = patterns.map((pattern) => {
@@ -1744,23 +2968,31 @@ var SELECT_SCALAR_FUNCTION_NAMES = /* @__PURE__ */ new Set([
   ...NQL_SELECT_SCALAR_FUNCTIONS
 ]);
 function validateSelectPathExpression(expr, ctx) {
-  if (!ctx.currentFromTable || !ctx.validator) return;
+  if (!ctx.currentFromTable) return;
   const { segments } = expr;
   if (segments.length === 1) {
-    ctx.validator.validateColumn(ctx.currentFromTable, segments[0]);
+    validateColumnForTable(ctx, ctx.currentFromTable, segments[0]);
     return;
   }
   const firstSegmentLower = segments[0].toLowerCase();
   if (ctx.pseudoColumnKeywords.has(firstSegmentLower)) {
+    assertNoBindingRelationConstruct(
+      ctx,
+      ctx.currentFromTable,
+      "use pseudo-column traversals",
+      segments[0]
+    );
     let i = 1;
     while (i < segments.length && ctx.pseudoColumnKeywords.has(segments[i].toLowerCase())) {
       i++;
     }
     if (i < segments.length) {
-      ctx.validator.validateColumn(ctx.currentFromTable, segments[i]);
+      validateColumnForTable(ctx, ctx.currentFromTable, segments[i]);
     }
     return;
   }
+  assertNoBindingRelationPath(ctx, ctx.currentFromTable, segments.join("."));
+  if (!ctx.validator) return;
   const targetTable = ctx.validator.resolveRelationTarget(
     ctx.currentFromTable,
     segments[0]
@@ -1790,6 +3022,12 @@ function compileSelectClause(clause, ctx, fns) {
     } else if (item.type === "relationStar") {
       hasExpressions = true;
       const relation = item.relation.join(".");
+      assertNoBindingRelationConstruct(
+        ctx,
+        ctx.currentFromTable,
+        "select relation columns",
+        relation
+      );
       expressions.push({
         kind: "relationColumn",
         relation,
@@ -1935,14 +3173,14 @@ function compileSelectExpression(item, ctx, fns) {
     const partitionBy = windowExpr.partitionBy.length > 0 ? windowExpr.partitionBy.map((e) => {
       const f = expressionToValidatedField(e, ctx) ?? expressionToSql(e);
       if (ctx.currentFromTable && !f.includes(".") && !f.includes("(")) {
-        ctx.validator?.validateColumn(ctx.currentFromTable, f);
+        validateColumnForTable(ctx, ctx.currentFromTable, f);
       }
       return f;
     }) : void 0;
     const orderBy = windowExpr.orderBy.length > 0 ? windowExpr.orderBy.map((o) => {
       const f = expressionToValidatedField(o.expression, ctx) ?? expressionToSql(o.expression);
       if (ctx.currentFromTable && !f.includes(".") && !f.includes("(")) {
-        ctx.validator?.validateColumn(ctx.currentFromTable, f);
+        validateColumnForTable(ctx, ctx.currentFromTable, f);
       }
       return { field: f, direction: o.direction };
     }) : void 0;
@@ -2060,6 +3298,12 @@ function compileMultiSegmentPath(expr, item, ctx) {
   const segments = expr.segments;
   const firstSegmentLower = segments[0].toLowerCase();
   if (ctx.pseudoColumnKeywords.has(firstSegmentLower)) {
+    assertNoBindingRelationConstruct(
+      ctx,
+      ctx.currentFromTable,
+      "use pseudo-column traversals",
+      segments[0]
+    );
     const firstSegment = firstSegmentLower;
     const depthHint = expr.depthHint;
     if (depthHint !== void 0) {
@@ -2087,7 +3331,7 @@ function compileMultiSegmentPath(expr, item, ctx) {
     }
     const targetColumn = segments[i];
     if (ctx.currentFromTable) {
-      ctx.validator?.validateColumn(ctx.currentFromTable, targetColumn);
+      validateColumnForTable(ctx, ctx.currentFromTable, targetColumn);
     }
     const defaultAlias = segments.map((s) => s.toLowerCase()).join(".");
     if (traversals.length === 1) {
@@ -2109,21 +3353,42 @@ function compileMultiSegmentPath(expr, item, ctx) {
   }
   const column = segments[segments.length - 1];
   const relation = segments.slice(0, -1).join(".");
-  if (ctx.currentFromTable && ctx.validator) {
-    const targetTable = ctx.validator.resolveRelationTarget(
+  const bindingRelation = resolveBindingRelationColumn(
+    ctx,
+    ctx.currentFromTable,
+    segments.slice(0, -1),
+    column
+  );
+  if (!bindingRelation) {
+    assertNoBindingRelationConstruct(
+      ctx,
       ctx.currentFromTable,
-      segments[0]
+      "select relation columns",
+      relation
     );
+  }
+  if (ctx.currentFromTable && ctx.validator) {
+    const targetTable = bindingRelation?.targetTable ?? ctx.validator.resolveRelationTarget(ctx.currentFromTable, segments[0]);
     if (targetTable) {
       ctx.validator.validateColumn(targetTable, column);
     }
   }
-  return {
+  const relationColumnIntent = {
     kind: "relationColumn",
     relation,
     column,
     as: item.alias ?? `${relation}.${column}`
   };
+  return bindingRelation ? markNqlTrustedRelationFilter(relationColumnIntent, {
+    relation: bindingRelation.relation,
+    targetTable: bindingRelation.targetTable,
+    sourceColumn: bindingRelation.sourceColumn,
+    targetColumn: bindingRelation.targetColumn,
+    selectedColumn: column,
+    ...bindingRelation.cardinality !== void 0 && {
+      cardinality: bindingRelation.cardinality
+    }
+  }) : relationColumnIntent;
 }
 function compileCaseExpression(caseExpr, item, ctx, fns) {
   if (caseExpr.subject) {
@@ -2269,6 +3534,220 @@ function allowsInternalParams(options) {
   const internalOptions = options?.[NQL_INTERNAL_COMPILER_OPTIONS];
   return internalOptions?.allowInternalParams === true;
 }
+function isUnresolvedSelectAllOutputSchemaError(error) {
+  return error instanceof NqlSemanticException && error.message.includes("from SELECT *") && error.message.includes("without a concrete table schema");
+}
+function programSequenceStepFromResult(result, bindName, final, bindingDependencies) {
+  if (result.query) {
+    return {
+      kind: "query",
+      query: result.query,
+      ...bindName !== void 0 && { bindName },
+      final,
+      bindingDependencies
+    };
+  }
+  if (result.mutation) {
+    return {
+      kind: "mutation",
+      mutation: result.mutation,
+      ...bindName !== void 0 && { bindName },
+      final,
+      bindingDependencies
+    };
+  }
+  return void 0;
+}
+function stringArraysEqual(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function isNqlAstRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function addReadBindingReference(references, readBindingNames, name) {
+  if (typeof name === "string" && readBindingNames.has(name)) {
+    references.add(name);
+  }
+}
+function withoutLocalCteNames(readBindingNames, ctes) {
+  if (ctes.length === 0) return readBindingNames;
+  const localCteNames = new Set(ctes.map((cte) => cte.name));
+  if (![...localCteNames].some((name) => readBindingNames.has(name))) {
+    return readBindingNames;
+  }
+  return new Set(
+    [...readBindingNames].filter((name) => !localCteNames.has(name))
+  );
+}
+function collectQueryReadBindingReferences(query, readBindingNames, references) {
+  addReadBindingReference(references, readBindingNames, query.table);
+  collectNodeReadBindingReferences(query.clauses, readBindingNames, references);
+}
+function collectWithQueryReadBindingReferences(withQuery, readBindingNames, references) {
+  const scopedReadBindingNames = withoutLocalCteNames(
+    readBindingNames,
+    withQuery.ctes
+  );
+  for (const cte of withQuery.ctes) {
+    collectQueryReadBindingReferences(
+      cte.query,
+      scopedReadBindingNames,
+      references
+    );
+  }
+  collectQueryReadBindingReferences(
+    withQuery.query,
+    scopedReadBindingNames,
+    references
+  );
+}
+function collectInListReadBindingReference(values, readBindingNames, references) {
+  if (!Array.isArray(values) || values.length !== 1) return;
+  const value = values[0];
+  if (!isNqlAstRecord(value) || value.type !== "path") return;
+  const segments = value.segments;
+  if (!Array.isArray(segments) || segments.length !== 1) return;
+  addReadBindingReference(references, readBindingNames, segments[0]);
+}
+function collectNodeReadBindingReferences(node, readBindingNames, references) {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectNodeReadBindingReferences(item, readBindingNames, references);
+    }
+    return;
+  }
+  if (!isNqlAstRecord(node)) return;
+  switch (node.type) {
+    case "query":
+      collectQueryReadBindingReferences(
+        node,
+        readBindingNames,
+        references
+      );
+      return;
+    case "withQuery":
+      collectWithQueryReadBindingReferences(
+        node,
+        readBindingNames,
+        references
+      );
+      return;
+    case "mutationPipeline":
+      collectNodeReadBindingReferences(
+        node.mutation,
+        readBindingNames,
+        references
+      );
+      collectNodeReadBindingReferences(
+        node.clauses,
+        readBindingNames,
+        references
+      );
+      return;
+    case "insert_from":
+    case "upsert_from":
+      addReadBindingReference(references, readBindingNames, node.source);
+      collectNodeReadBindingReferences(
+        node.where,
+        readBindingNames,
+        references
+      );
+      return;
+    case "setOperation":
+      addReadBindingReference(references, readBindingNames, node.boundName);
+      collectNodeReadBindingReferences(
+        node.right,
+        readBindingNames,
+        references
+      );
+      return;
+    case "in":
+      collectNodeReadBindingReferences(
+        node.expression,
+        readBindingNames,
+        references
+      );
+      collectInListReadBindingReference(
+        node.values,
+        readBindingNames,
+        references
+      );
+      collectNodeReadBindingReferences(
+        node.values,
+        readBindingNames,
+        references
+      );
+      return;
+    case "subquery":
+      collectNodeReadBindingReferences(
+        node.query,
+        readBindingNames,
+        references
+      );
+      return;
+  }
+  for (const child of Object.values(node)) {
+    collectNodeReadBindingReferences(child, readBindingNames, references);
+  }
+}
+function collectStatementReadBindingReferences(stmt, readBindingNames) {
+  const references = /* @__PURE__ */ new Set();
+  if (readBindingNames.size === 0) return references;
+  collectNodeReadBindingReferences(stmt, readBindingNames, references);
+  return references;
+}
+function collectCompileResultReadBindingReferences(result, readBindingNames, references) {
+  if (result.query) {
+    addReadBindingReference(references, readBindingNames, result.query.from);
+  }
+}
+function addTransitiveBindingDependency(bindName, bindingDependencies, ordered, seen) {
+  if (seen.has(bindName)) return;
+  seen.add(bindName);
+  for (const dependency of bindingDependencies.get(bindName) ?? []) {
+    addTransitiveBindingDependency(
+      dependency,
+      bindingDependencies,
+      ordered,
+      seen
+    );
+  }
+  ordered.push(bindName);
+}
+function collectTransitiveReadBindingDependencies(directReferences, bindingDependencies) {
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const reference of directReferences) {
+    addTransitiveBindingDependency(
+      reference,
+      bindingDependencies,
+      ordered,
+      seen
+    );
+  }
+  return ordered;
+}
+function rejectReadBindingReferenceAcrossMutation(bindName, definitionIndex, mutationIndex, referenceIndex, statementCount) {
+  throw new NqlSemanticException(
+    NqlErrorCodes.SEM_INVALID_SYNTAX,
+    `read binding referenced across a mutation (#186): binding '${bindName}' is defined by read-only statement ${definitionIndex + 1} of ${statementCount} and referenced by statement ${referenceIndex + 1} after mutation statement ${mutationIndex + 1}. Read-only bindings are not materialized snapshots; move the reference before the mutation or bind the mutation RETURNING result instead.`
+  );
+}
+function rejectInvalidReadBindingDependencies(statementBindingDependencies, readBindingDefinitions, lastMutationStatement, referenceIndex, statementCount) {
+  for (const referencedBindName of statementBindingDependencies) {
+    const definitionIndex = readBindingDefinitions.get(referencedBindName);
+    if (definitionIndex === void 0) continue;
+    if (lastMutationStatement > definitionIndex) {
+      rejectReadBindingReferenceAcrossMutation(
+        referencedBindName,
+        definitionIndex,
+        lastMutationStatement,
+        referenceIndex,
+        statementCount
+      );
+    }
+  }
+}
 var NqlCompiler = class {
   ctx;
   fns;
@@ -2292,9 +3771,12 @@ var NqlCompiler = class {
     this.ctx = {
       currentFromTable: void 0,
       currentRelationTarget: void 0,
+      currentHavingAliases: void 0,
       pseudoColumnKeywords,
       recursiveKeywords,
       validator,
+      bindingOutputColumns: /* @__PURE__ */ new Map(),
+      bindingRelationFilters: /* @__PURE__ */ new Map(),
       params,
       maxAnyItems: maxAnyItemsRaw ?? MAX_ANY_ITEMS,
       allowUnfilteredMutations: options?.allowUnfilteredMutations ?? false,
@@ -2310,6 +3792,15 @@ var NqlCompiler = class {
    * Compile an NQL program to IntentAST.
    */
   compile(program) {
+    try {
+      return this.compileProgram(program);
+    } finally {
+      this.ctx.bindingOutputColumns.clear();
+      this.ctx.bindingRelationFilters.clear();
+      this.ctx.validator?.clearVirtualBindingTables();
+    }
+  }
+  compileProgram(program) {
     if (program.statements.length === 0) {
       return {};
     }
@@ -2326,30 +3817,124 @@ var NqlCompiler = class {
       }
     }
     const bindings = /* @__PURE__ */ new Map();
+    const bindingOutputSchemas = /* @__PURE__ */ new Map();
     const mutationBindings = /* @__PURE__ */ new Map();
     const materializedBindStatements = /* @__PURE__ */ new Set();
+    const seenBindNames = /* @__PURE__ */ new Map();
+    const nqlProgramSequence = [];
+    const readBindingDefinitions = /* @__PURE__ */ new Map();
+    const definedBindingNames = /* @__PURE__ */ new Set();
+    const bindingDependencies = /* @__PURE__ */ new Map();
+    let lastMutationStatement = -1;
     let lastResult = {};
     for (let i = 0; i < program.statements.length; i++) {
       const stmt = program.statements[i];
-      lastResult = this.compileSingleStatement(stmt, bindings);
       const bindName = extractBindName(stmt);
+      if (bindName) {
+        const previousStatement = seenBindNames.get(bindName);
+        if (previousStatement !== void 0) {
+          throw new NqlSemanticException(
+            NqlErrorCodes.SEM_INVALID_SYNTAX,
+            `NQL binding name '${bindName}' is used more than once (statements ${previousStatement + 1} and ${i + 1}). NQL binding names must be unique.`
+          );
+        }
+        seenBindNames.set(bindName, i);
+      }
+      const readBindingReferences = collectStatementReadBindingReferences(
+        stmt,
+        definedBindingNames
+      );
+      let statementBindingDependencies = collectTransitiveReadBindingDependencies(
+        readBindingReferences,
+        bindingDependencies
+      );
+      rejectInvalidReadBindingDependencies(
+        statementBindingDependencies,
+        readBindingDefinitions,
+        lastMutationStatement,
+        i,
+        program.statements.length
+      );
+      lastResult = this.compileSingleStatement(stmt, bindings);
+      collectCompileResultReadBindingReferences(
+        lastResult,
+        definedBindingNames,
+        readBindingReferences
+      );
+      statementBindingDependencies = collectTransitiveReadBindingDependencies(
+        readBindingReferences,
+        bindingDependencies
+      );
+      rejectInvalidReadBindingDependencies(
+        statementBindingDependencies,
+        readBindingDefinitions,
+        lastMutationStatement,
+        i,
+        program.statements.length
+      );
+      if (stmt.type === "mutationPipeline") {
+        lastMutationStatement = i;
+      }
       if (bindName) {
         if (lastResult.query) {
+          const outputSchema = this.registerQueryBindingOutputSchema(
+            bindName,
+            lastResult.query,
+            bindingOutputSchemas,
+            statementBindingDependencies
+          );
           bindings.set(bindName, lastResult.query);
+          if (outputSchema) {
+            this.ctx.validator?.addVirtualBindingTable(
+              bindName,
+              outputSchema.columns,
+              outputSchema.relationFilters
+            );
+          }
           materializedBindStatements.add(i);
+          readBindingDefinitions.set(bindName, i);
+          definedBindingNames.add(bindName);
+          bindingDependencies.set(bindName, statementBindingDependencies);
         } else if (lastResult.mutation?.returning?.length) {
-          mutationBindings.set(bindName, lastResult.mutation);
+          const canonicalBinding = this.canonicalizeMutationBinding(
+            bindName,
+            lastResult.mutation
+          );
+          lastResult = { mutation: canonicalBinding.mutation };
+          mutationBindings.set(bindName, canonicalBinding.mutation);
+          const outputSchema = canonicalBinding.outputSchema;
+          const bindingFields = outputSchema?.columns ?? canonicalBinding.mutation.returning ?? [];
+          this.ctx.bindingOutputColumns.set(bindName, outputSchema?.columns);
           bindings.set(bindName, {
             type: "select",
-            from: lastResult.mutation.table,
+            from: canonicalBinding.mutation.table,
             select: {
               type: "fields",
-              fields: [...lastResult.mutation.returning]
+              fields: [...bindingFields]
             }
           });
+          if (outputSchema) {
+            bindingOutputSchemas.set(bindName, outputSchema);
+            this.ctx.validator?.addVirtualBindingTable(
+              bindName,
+              outputSchema.columns,
+              outputSchema.relationFilters
+            );
+          }
           materializedBindStatements.add(i);
+          definedBindingNames.add(bindName);
+          bindingDependencies.set(bindName, []);
         }
       }
+      const sequenceStep = programSequenceStepFromResult(
+        lastResult,
+        bindName,
+        i === program.statements.length - 1,
+        statementBindingDependencies
+      );
+      if (sequenceStep !== void 0) {
+        nqlProgramSequence.push(sequenceStep);
+      }
     }
     for (let i = 0; i < program.statements.length - 1; i++) {
       const bindName = extractBindName(program.statements[i]);
@@ -2360,15 +3945,79 @@ var NqlCompiler = class {
       }
     }
     const hasMutationBindings = mutationBindings.size > 0;
+    const hasBindingOutputSchemas = bindingOutputSchemas.size > 0;
+    const hasNqlProgramSequence = nqlProgramSequence.length === program.statements.length;
     if (bindings.size > 0) {
       return {
         ...lastResult,
         bindings,
-        ...hasMutationBindings && { mutationBindings }
+        ...hasBindingOutputSchemas && { bindingOutputSchemas },
+        ...hasMutationBindings && { mutationBindings },
+        ...hasNqlProgramSequence && { nqlProgramSequence }
       };
     }
     return lastResult;
   }
+  registerQueryBindingOutputSchema(bindName, query, bindingOutputSchemas, bindingDependencies) {
+    try {
+      const outputSchema = getQueryOutputSchema(
+        query,
+        this.ctx,
+        bindName,
+        bindingDependencies
+      );
+      bindingOutputSchemas.set(bindName, outputSchema);
+      this.ctx.bindingOutputColumns.set(bindName, outputSchema.columns);
+      if (outputSchema.relationFilters) {
+        this.ctx.bindingRelationFilters.set(
+          bindName,
+          outputSchema.relationFilters
+        );
+      }
+      return outputSchema;
+    } catch (error) {
+      if (!this.ctx.validator && isUnresolvedSelectAllOutputSchemaError(error)) {
+        this.ctx.bindingOutputColumns.set(bindName, void 0);
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  canonicalizeMutationBinding(bindName, mutation) {
+    const outputSchema = this.getMutationBindingOutputSchema(
+      bindName,
+      mutation
+    );
+    const returning = mutation.returning;
+    if (returning === void 0 || returning.length === 0 || returning.includes("*") || outputSchema === void 0 || stringArraysEqual(returning, outputSchema.columns)) {
+      return { mutation, outputSchema };
+    }
+    return {
+      mutation: {
+        ...mutation,
+        returning: outputSchema.columns
+      },
+      outputSchema
+    };
+  }
+  getMutationBindingOutputSchema(bindName, mutation) {
+    const returning = mutation.returning;
+    if (!returning || returning.length === 0) return void 0;
+    if (returning.includes("*")) {
+      const columns = this.ctx.validator?.getTableColumns(mutation.table);
+      if (columns !== void 0) return { columns };
+      if (!this.ctx.validator) return void 0;
+      throw new NqlSemanticException(
+        NqlErrorCodes.SEM_INVALID_SYNTAX,
+        `Cannot compute output schema for NQL binding '${bindName}' from mutation RETURNING * on '${mutation.table}' without a concrete table schema.`
+      );
+    }
+    return {
+      columns: returning.map(
+        (column) => this.ctx.validator?.resolveColumnName(mutation.table, column) ?? column
+      )
+    };
+  }
   compileSingleStatement(stmt, bindings) {
     if (stmt.type === "withQuery") {
       return compileWithQuery(stmt, this.ctx, this.fns);