@dbsp/nql 1.6.0 → 1.8.0

package/dist/index.js

@@ -43,6 +43,69 @@ var NqlSemanticException = class extends Error {
     this.relatedSymbol = relatedSymbol;
   }
 };
+
+// src/compiler/binding-column-types.ts
+function freezeColumnTypes(types) {
+  for (const info of Object.values(types)) {
+    Object.freeze(info);
+  }
+  return Object.freeze(types);
+}
+function buildBindingColumnTypes(columns, candidates) {
+  const attemptsByColumn = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const bucket = attemptsByColumn.get(candidate.column);
+    if (bucket) {
+      bucket.push(candidate);
+    } else {
+      attemptsByColumn.set(candidate.column, [candidate]);
+    }
+  }
+  const types = /* @__PURE__ */ Object.create(
+    null
+  );
+  for (const column of columns) {
+    const attempts = attemptsByColumn.get(column) ?? [];
+    if (attempts.length > 1) {
+      return { untypeable: { column, reason: "duplicate-output-name" } };
+    }
+    const candidate = attempts[0];
+    if (candidate?.typed === void 0) {
+      return {
+        untypeable: {
+          column,
+          reason: candidate?.untypeable ?? "unresolvable-source"
+        }
+      };
+    }
+    types[column] = candidate.typed;
+  }
+  return { columnTypes: freezeColumnTypes(types) };
+}
+var DEFAULT_RELATION_TARGET_COLUMN = "id";
+function relationForeignKeys(relation) {
+  if (!relation) return void 0;
+  const columns = toColumnList(relation.foreignKey);
+  return columns.length > 0 ? columns : void 0;
+}
+function relationCardinality(relation) {
+  return relation?.type === "hasMany" || relation?.type === "belongsToMany" ? "many" : "one";
+}
+function scalarRelationJoinColumns(relation) {
+  if (!relation) return void 0;
+  if (relation.type !== "belongsTo" && relation.type !== "hasOne" && relation.type !== "hasMany") {
+    return void 0;
+  }
+  const fkColumns = relationForeignKeys(relation);
+  if (!fkColumns) return void 0;
+  const sourceKeys = toColumnList(relation.sourceKey);
+  const targetKeys = toColumnList(relation.targetKey);
+  const sourceJoinColumn = relation.type === "belongsTo" ? fkColumns : sourceKeys.length > 0 ? sourceKeys : [DEFAULT_RELATION_TARGET_COLUMN];
+  const targetJoinColumn = relation.type === "belongsTo" ? targetKeys.length > 0 ? targetKeys : [DEFAULT_RELATION_TARGET_COLUMN] : fkColumns;
+  return { sourceJoinColumn, targetJoinColumn };
+}
+
+// src/compiler/column-validator.ts
 var ColumnValidator = class _ColumnValidator {
   constructor(schema) {
     this.schema = schema;
@@ -90,6 +153,31 @@ var ColumnValidator = class _ColumnValidator {
     if (virtualColumns) return virtualColumns;
     return this.schema.getTable(name)?.columns.map((column) => column.name);
   }
+  getPhysicalTableColumns(name) {
+    return this.schema.getTable(name)?.columns.map((column) => column.name);
+  }
+  /**
+   * Resolve a physical column's neutral type info for binding-snapshot
+   * type propagation (#213). Returns undefined when the table/column is
+   * unknown OR the schema did not supply a `type` for it — the caller
+   * treats undefined as untypeable, never falls back to a guess.
+   */
+  getTableColumnType(table, column) {
+    const resolvedName = this.resolvePhysicalColumnName(table, column);
+    if (resolvedName === void 0) return void 0;
+    const columnInfo = this.schema.getTable(table)?.columns.find((candidate) => candidate.name === resolvedName);
+    if (columnInfo?.type === void 0) return void 0;
+    return {
+      kind: "column",
+      type: columnInfo.type,
+      ...columnInfo.originalDbType !== void 0 && {
+        originalDbType: columnInfo.originalDbType
+      }
+    };
+  }
+  getPseudoColumns(name) {
+    return this.schema.getTable(name)?.pseudoColumns ?? [];
+  }
   hasPhysicalTable(name) {
     return !this.virtualBindingTables.has(name) && !!this.schema.getTable(name);
   }
@@ -233,10 +321,54 @@ var ColumnValidator = class _ColumnValidator {
     if (!sourceTable) {
       return "the binding source table could not be proven";
     }
+    const recursiveReason = this.explainVirtualBindingRecursiveScalarRelationRejection(
+      bindingName,
+      relationName,
+      sourceTable,
+      metadata
+    );
+    if (recursiveReason) return recursiveReason;
     const relation = this.getRelation(sourceTable, relationName);
     if (!relation) {
       return `relation '${relationName}' is not declared on source table '${sourceTable}'`;
     }
+    if (relation.type === "belongsToMany") {
+      if (relation.recursive !== void 0 || relation.source !== void 0 && relation.source === relation.target) {
+        return `relation '${relationName}' is recursive/self-referential; binding relation columns for recursive relations require recursive CTE handling and are not supported (ref-#193)`;
+      }
+      if (typeof relation.through !== "string" || relation.through.length === 0) {
+        return `relation '${relationName}' is many-to-many but does not declare a resolvable junction table (ref-#192)`;
+      }
+      const sourceColumns2 = toColumnList(relation.sourceKey).length > 0 ? toColumnList(relation.sourceKey) : ["id"];
+      const throughSourceColumns = toColumnList(relation.foreignKey);
+      const throughTargetColumns = toColumnList(relation.otherKey);
+      const targetColumns = toColumnList(relation.targetKey).length > 0 ? toColumnList(relation.targetKey) : ["id"];
+      if (sourceColumns2.length !== 1) {
+        return `relation '${relationName}' source key is composite; binding many-to-many relation columns require a single source key column (ref-#179)`;
+      }
+      if (throughSourceColumns.length !== 1) {
+        return `relation '${relationName}' junction source FK is composite or missing; binding many-to-many relation columns require a single junction source FK column (ref-#179)`;
+      }
+      if (throughTargetColumns.length !== 1) {
+        return `relation '${relationName}' junction target FK is composite or missing; binding many-to-many relation columns require a single junction target FK column (ref-#179)`;
+      }
+      if (targetColumns.length !== 1) {
+        return `relation '${relationName}' target key is composite; binding many-to-many relation columns require a single target key column (ref-#179)`;
+      }
+      const [sourceColumn] = sourceColumns2;
+      if (sourceColumn === void 0) {
+        return `relation '${relationName}' source key is missing; binding many-to-many relation columns require a single source key column (ref-#179)`;
+      }
+      const directProjection = metadata.directProjectionLineage?.find(
+        (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, sourceColumn)
+      );
+      if (!directProjection) {
+        const available3 = this.virtualBindingTables.get(bindingName)?.join(", ");
+        return `relation '${relationName}' source key column '${sourceColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available3 ? ` (available columns: ${available3})` : ""}`;
+      }
+      const available2 = this.virtualBindingTables.get(bindingName)?.join(", ");
+      return `relation '${relationName}' many-to-many source column '${sourceColumn}' is not available through binding '${bindingName}'${available2 ? ` (available columns: ${available2})` : ""}`;
+    }
     const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
       relationName,
       relation
@@ -257,6 +389,64 @@ var ColumnValidator = class _ColumnValidator {
     const available = this.virtualBindingTables.get(bindingName)?.join(", ");
     return `relation '${relationName}' source columns '${sourceColumns.join(", ")}' are not available through binding '${bindingName}'${available ? ` (available columns: ${available})` : ""}`;
   }
+  static recursiveDirection(value) {
+    if (value === null || typeof value !== "object") return void 0;
+    const direction = value.direction;
+    if (direction === "up" || direction === "ancestors") return "up";
+    if (direction === "down" || direction === "descendants") return "down";
+    return void 0;
+  }
+  explainVirtualBindingRecursiveScalarRelationRejection(bindingName, relationName, sourceTable, metadata) {
+    const lowerRelationName = relationName.toLowerCase();
+    const pseudoColumn = this.getPseudoColumns(sourceTable).find(
+      (candidate) => candidate.ascendantKeyword?.toLowerCase() === lowerRelationName || candidate.descendantKeyword?.toLowerCase() === lowerRelationName
+    );
+    if (!pseudoColumn) return void 0;
+    const direction = pseudoColumn.ascendantKeyword?.toLowerCase() === lowerRelationName ? "up" : "down";
+    const recursiveRelations = this.getRelationsFrom(sourceTable).filter(
+      (relation) => relation.recursive !== void 0 && relation.source === relation.target && relation.source === sourceTable && _ColumnValidator.recursiveDirection(relation.recursive) === direction
+    );
+    if (recursiveRelations.length === 0) {
+      return `recursive traversal '${relationName}' is missing recursive relation metadata for direction '${direction}' (ref-#193)`;
+    }
+    for (const relation of recursiveRelations) {
+      const relationFkColumns = toColumnList(relation.foreignKey);
+      const fkColumns = relationFkColumns.length > 0 ? relationFkColumns : toColumnList(pseudoColumn.foreignKeyColumn);
+      if (fkColumns.length !== 1) {
+        return `relation '${relation.name}' self-ref FK is composite or missing; binding recursive relation columns require a single self-ref FK column (ref-#193)`;
+      }
+      const relationTargetColumns = toColumnList(relation.targetKey);
+      const targetColumns = relationTargetColumns.length > 0 ? relationTargetColumns : pseudoColumn.targetColumn !== void 0 ? [pseudoColumn.targetColumn] : [DEFAULT_RELATION_TARGET_COLUMN];
+      if (targetColumns.length !== 1) {
+        return `relation '${relation.name}' target key is composite; binding recursive relation columns require a single target key column (ref-#193)`;
+      }
+      const selfRefColumn = fkColumns[0];
+      const targetKeyColumn = targetColumns[0];
+      if (selfRefColumn === void 0 || targetKeyColumn === void 0) {
+        return `relation '${relation.name}' recursive metadata is missing a single-column seed; binding recursive relation columns require a single self-ref FK and target key column (ref-#193)`;
+      }
+      if (pseudoColumn.foreignKeyColumn !== void 0 && !_ColumnValidator.columnsMatch(
+        pseudoColumn.foreignKeyColumn,
+        selfRefColumn
+      ) || pseudoColumn.targetColumn !== void 0 && !_ColumnValidator.columnsMatch(
+        pseudoColumn.targetColumn,
+        targetKeyColumn
+      )) {
+        continue;
+      }
+      const seedColumn = direction === "up" ? selfRefColumn : targetKeyColumn;
+      const directProjection = metadata.directProjectionLineage?.find(
+        (projection) => projection.sourceTable === sourceTable && _ColumnValidator.columnsMatch(projection.sourceColumn, seedColumn)
+      );
+      if (!directProjection) {
+        const available = this.virtualBindingTables.get(bindingName)?.join(", ");
+        const seedLabel = direction === "up" ? "self-ref FK column" : "target key column";
+        return `recursive traversal '${relationName}' ${seedLabel} '${seedColumn}' is not projected as a direct source-column projection by binding '${bindingName}'${available ? ` (available columns: ${available})` : ""} (ref-#193)`;
+      }
+      return void 0;
+    }
+    return `recursive traversal '${relationName}' pseudo metadata does not match a single-column recursive self-reference (ref-#193)`;
+  }
   /**
    * Convert camelCase to snake_case for column name matching.
    * NQL queries may use either form (e.g., viewCount or view_count).
@@ -288,6 +478,14 @@ var ColumnValidator = class _ColumnValidator {
       (c) => _ColumnValidator.columnsMatch(column, c.name)
     )?.name;
   }
+  resolvePhysicalColumnName(table, column) {
+    if (column === "*") return 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);
@@ -354,28 +552,6 @@ var ColumnValidator = class _ColumnValidator {
     );
   }
 };
-var DEFAULT_RELATION_TARGET_COLUMN = "id";
-function relationForeignKeys(relation) {
-  if (!relation) return void 0;
-  const columns = toColumnList(relation.foreignKey);
-  return columns.length > 0 ? columns : void 0;
-}
-function relationCardinality(relation) {
-  return relation?.type === "hasMany" || relation?.type === "belongsToMany" ? "many" : "one";
-}
-function scalarRelationJoinColumns(relation) {
-  if (!relation) return void 0;
-  if (relation.type !== "belongsTo" && relation.type !== "hasOne" && relation.type !== "hasMany") {
-    return void 0;
-  }
-  const fkColumns = relationForeignKeys(relation);
-  if (!fkColumns) return void 0;
-  const sourceKeys = toColumnList(relation.sourceKey);
-  const targetKeys = toColumnList(relation.targetKey);
-  const sourceJoinColumn = relation.type === "belongsTo" ? fkColumns : sourceKeys.length > 0 ? sourceKeys : [DEFAULT_RELATION_TARGET_COLUMN];
-  const targetJoinColumn = relation.type === "belongsTo" ? targetKeys.length > 0 ? targetKeys : [DEFAULT_RELATION_TARGET_COLUMN] : fkColumns;
-  return { sourceJoinColumn, targetJoinColumn };
-}
 var FORBIDDEN_PARAM_NAMES = /* @__PURE__ */ new Set([
   "__proto__",
   "constructor",
@@ -652,6 +828,43 @@ function resolveBindingRelationColumn(ctx, bindingName, relationPath, selectedCo
     hops
   };
 }
+function resolveBindingRecursiveRelationColumn(ctx, bindingName, traversal, selectedColumn, maxDepth) {
+  if (!isBindingTable(ctx, bindingName)) return void 0;
+  const traversalName = traversal.toLowerCase();
+  const isRecursiveTraversal = ctx.recursiveKeywords.has(traversalName) || traversalName === "ascendant" || traversalName === "descendant";
+  const actualBindingName = bindingName;
+  if (!ctx.validator) {
+    if (!isRecursiveTraversal) return void 0;
+    throwBindingRelationColumn182(
+      actualBindingName,
+      traversalName,
+      "model metadata is not available"
+    );
+  }
+  const virtualRelation = ctx.validator.getVirtualBindingScalarRelation(
+    actualBindingName,
+    traversalName
+  );
+  if (!isRecursiveTraversal && !virtualRelation?.recursive) {
+    return void 0;
+  }
+  if (!virtualRelation?.recursive) {
+    const reason = ctx.validator.explainVirtualBindingScalarRelationRejection(
+      actualBindingName,
+      traversalName
+    );
+    throwBindingRelationColumn182(actualBindingName, traversalName, reason);
+  }
+  ctx.validator.validateColumn(virtualRelation.targetTable, selectedColumn);
+  if (maxDepth === void 0) return virtualRelation;
+  return {
+    ...virtualRelation,
+    recursive: {
+      ...virtualRelation.recursive,
+      maxDepth
+    }
+  };
+}
 function assertNoBindingRelationPath(ctx, bindingName, path) {
   if (!isBindingTable(ctx, bindingName)) return;
   throw new NqlSemanticException(
@@ -964,11 +1177,14 @@ function compileMutationPipeline(pipeline, ctx, fns, bindings) {
   ctx.currentFromTable = pipeline.mutation.table;
   const mutation = compileMutation(pipeline.mutation, ctx, fns, bindings);
   let returning;
+  let returningItems;
   for (const clause of pipeline.clauses) {
     if (clause.type === "select") {
-      returning = extractReturningColumns(clause, ctx);
+      returningItems = extractReturningItems(clause, ctx);
+      returning = returningItems === "star" ? ["*"] : returningItems.map((item) => item.output);
     }
   }
+  ctx.lastMutationReturningItems = returningItems;
   if (returning) {
     return {
       mutation: { ...mutation, returning }
@@ -1156,11 +1372,11 @@ function compileUpsertFrom(upsertFrom, ctx, fns, bindings) {
     }
   };
 }
-function extractReturningColumns(clause, ctx) {
-  const columns = [];
+function extractReturningItems(clause, ctx) {
+  const items = [];
   for (const item of clause.items) {
     if (item.type === "star") {
-      return ["*"];
+      return "star";
     }
     if (item.type === "expression") {
       const field = expressionToField(item.expression);
@@ -1168,11 +1384,14 @@ function extractReturningColumns(clause, ctx) {
         if (ctx.currentFromTable && !field.includes(".")) {
           ctx.validator?.validateColumn(ctx.currentFromTable, field);
         }
-        columns.push(item.alias ?? field);
+        items.push({
+          output: item.alias ?? field,
+          aliased: item.alias !== void 0
+        });
       }
     }
   }
-  return columns;
+  return items;
 }
 function resolveBindingsInWhere(where, bindings) {
   if (!bindings || bindings.size === 0) return where;
@@ -1287,6 +1506,12 @@ var PORTABLE_BINDING_FINAL_FUNCTIONS = /* @__PURE__ */ new Set([
   ...NQL_SELECT_AGGREGATE_FUNCTIONS,
   ...NQL_SELECT_VALUE_FUNCTIONS
 ]);
+var UnresolvedSelectAllOutputSchemaError = class extends NqlSemanticException {
+  constructor(message) {
+    super(NqlErrorCodes.SEM_INVALID_SYNTAX, message);
+    this.name = "UnresolvedSelectAllOutputSchemaError";
+  }
+};
 function compileNestedQuery(query, ctx, fns, bindings) {
   const savedContext = {
     currentFromTable: ctx.currentFromTable,
@@ -1373,6 +1598,21 @@ function relationForeignKeysOnSource(relation) {
   const fkColumns = toColumnList(relation.foreignKey);
   return fkColumns.length > 0 ? fkColumns : void 0;
 }
+function recursiveDirection(recursive) {
+  if (recursive === null || typeof recursive !== "object") return void 0;
+  const direction = recursive.direction;
+  if (direction === "up" || direction === "ancestors") return "up";
+  if (direction === "down" || direction === "descendants") return "down";
+  return void 0;
+}
+function recursiveMaxDepth(recursive) {
+  if (recursive === null || typeof recursive !== "object") return void 0;
+  const maxDepth = recursive.maxDepth;
+  return typeof maxDepth === "number" && Number.isSafeInteger(maxDepth) && maxDepth > 0 ? maxDepth : void 0;
+}
+function pseudoColumnMatchesSelfRef(pseudoColumn, sourceTable, selfRefColumn, targetKeyColumn) {
+  return (pseudoColumn.table === void 0 || pseudoColumn.table === sourceTable) && (pseudoColumn.foreignKeyColumn === void 0 || columnsMatch(pseudoColumn.foreignKeyColumn, selfRefColumn)) && (pseudoColumn.targetColumn === void 0 || columnsMatch(pseudoColumn.targetColumn, targetKeyColumn));
+}
 function unsafeBindingRelationReason(intent, ctx, bindingDependencies) {
   if (!ctx.validator) return "model metadata is not available";
   if (!ctx.validator.hasQualifiedRelationLookup()) {
@@ -1443,8 +1683,119 @@ function virtualRelationForBinding(relation, sourceTable, directProjectionLineag
     cardinality: "one"
   };
 }
+function singleResolvedColumn(columns) {
+  return columns.length === 1 ? columns[0] : void 0;
+}
+function manyToManyVirtualRelationForBinding(relation, sourceTable, directProjectionLineage) {
+  if (relation?.type !== "belongsToMany") return void 0;
+  if (typeof relation.through !== "string" || relation.through.length === 0 || relation.recursive !== void 0 || relation.source !== void 0 && relation.source === relation.target) {
+    return void 0;
+  }
+  const sourceKeys = toColumnList(relation.sourceKey);
+  const sourceColumn = singleResolvedColumn(
+    sourceKeys.length > 0 ? sourceKeys : [DEFAULT_RELATION_TARGET_COLUMN]
+  );
+  const targetKeys = toColumnList(relation.targetKey);
+  const targetColumn = singleResolvedColumn(
+    targetKeys.length > 0 ? targetKeys : [DEFAULT_RELATION_TARGET_COLUMN]
+  );
+  const throughSourceColumn = singleResolvedColumn(
+    toColumnList(relation.foreignKey)
+  );
+  const throughTargetColumn = singleResolvedColumn(
+    toColumnList(relation.otherKey)
+  );
+  if (!sourceColumn || !targetColumn || !throughSourceColumn || !throughTargetColumn) {
+    return void 0;
+  }
+  const sourceProjection = findDirectSourceProjection(
+    sourceTable,
+    sourceColumn,
+    directProjectionLineage
+  );
+  if (!sourceProjection) return void 0;
+  return {
+    relation: relation.name,
+    sourceTable,
+    targetTable: relation.target,
+    sourceColumn: [sourceProjection.outputColumn],
+    targetColumn: [targetColumn],
+    hops: [],
+    through: relation.through,
+    throughSourceColumn,
+    throughTargetColumn,
+    cardinality: "many",
+    relationType: "manyToMany"
+  };
+}
+function recursiveVirtualRelationForBinding(relation, sourceTable, directProjectionLineage, pseudoColumns) {
+  const direction = recursiveDirection(relation?.recursive);
+  if (!relation || !direction) return void 0;
+  if (relation.source !== relation.target || relation.source !== sourceTable) {
+    return void 0;
+  }
+  const fkColumns = toColumnList(relation.foreignKey);
+  const targetKeys = toColumnList(relation.targetKey);
+  const pseudoColumn = pseudoColumns.find((candidate) => {
+    const candidateFkColumns = fkColumns.length > 0 ? fkColumns : toColumnList(candidate.foreignKeyColumn);
+    const candidateTargetColumns = targetKeys.length > 0 ? targetKeys : candidate.targetColumn !== void 0 ? [candidate.targetColumn] : [DEFAULT_RELATION_TARGET_COLUMN];
+    const candidateSelfRefColumn = singleResolvedColumn(candidateFkColumns);
+    const candidateTargetKeyColumn = singleResolvedColumn(
+      candidateTargetColumns
+    );
+    return candidateSelfRefColumn !== void 0 && candidateTargetKeyColumn !== void 0 && pseudoColumnMatchesSelfRef(
+      candidate,
+      sourceTable,
+      candidateSelfRefColumn,
+      candidateTargetKeyColumn
+    );
+  });
+  if (!pseudoColumn) return void 0;
+  const selfRefColumn = singleResolvedColumn(
+    fkColumns.length > 0 ? fkColumns : toColumnList(pseudoColumn.foreignKeyColumn)
+  );
+  const targetKeyColumn = singleResolvedColumn(
+    targetKeys.length > 0 ? targetKeys : pseudoColumn.targetColumn !== void 0 ? [pseudoColumn.targetColumn] : [DEFAULT_RELATION_TARGET_COLUMN]
+  );
+  if (!selfRefColumn || !targetKeyColumn) return void 0;
+  const relationName = direction === "up" ? pseudoColumn.ascendantKeyword : pseudoColumn.descendantKeyword;
+  if (!relationName) return void 0;
+  const seedColumn = direction === "up" ? selfRefColumn : targetKeyColumn;
+  const sourceProjection = findDirectSourceProjection(
+    sourceTable,
+    seedColumn,
+    directProjectionLineage
+  );
+  if (!sourceProjection) return void 0;
+  return {
+    relation: relationName.toLowerCase(),
+    sourceTable,
+    targetTable: relation.target,
+    sourceColumn: [sourceProjection.outputColumn],
+    targetColumn: [direction === "up" ? targetKeyColumn : selfRefColumn],
+    hops: [],
+    cardinality: "many",
+    relationType: relation.type,
+    recursive: {
+      direction,
+      maxDepth: recursiveMaxDepth(relation.recursive) ?? 10,
+      selfRefColumn,
+      targetKeyColumn
+    }
+  };
+}
 function scalarVirtualRelationForBinding(relation, sourceTable, directProjectionLineage) {
   if (!relation) return void 0;
+  if (relation.type === "belongsToMany") {
+    return manyToManyVirtualRelationForBinding(
+      relation,
+      sourceTable,
+      directProjectionLineage
+    );
+  }
+  if (relation.recursive !== void 0 || relation.source !== void 0 && relation.source === relation.target) {
+    return void 0;
+  }
   if (relation.type !== "belongsTo" && relation.type !== "hasOne" && relation.type !== "hasMany") {
     return void 0;
   }
@@ -1493,6 +1844,13 @@ function getBindingRelationFilterMetadata(intent, ctx, outputSchema, bindingDepe
   );
   for (const relationName of relationNames ?? []) {
     const relation = ctx.validator?.getRelation(sourceTable, relationName);
+    const recursiveRelation = recursiveVirtualRelationForBinding(
+      relation,
+      sourceTable,
+      outputSchema.directProjectionLineage ?? [],
+      ctx.validator?.getPseudoColumns(sourceTable) ?? []
+    );
+    if (recursiveRelation) scalarRelations.push(recursiveRelation);
     const virtualRelation = virtualRelationForBinding(
       relation,
       sourceTable,
@@ -1527,6 +1885,15 @@ function validateBindingFinalPath(expr, ctx, bindingName) {
   }
   const firstSegment = segments[0];
   if (ctx.pseudoColumnKeywords.has(firstSegment.toLowerCase())) {
+    if (segments.length === 2 && resolveBindingRecursiveRelationColumn(
+      ctx,
+      bindingName,
+      firstSegment,
+      segments[1],
+      expr.depthHint
+    )) {
+      return;
+    }
     assertNoBindingRelationConstruct(
       ctx,
       bindingName,
@@ -1757,12 +2124,20 @@ function validateBindingFinalSelectClause(clause, ctx, bindingName) {
           const segments = item.expression.segments;
           const firstSegment = segments[0];
           if (ctx.pseudoColumnKeywords.has(firstSegment.toLowerCase())) {
-            assertNoBindingRelationConstruct(
+            if (segments.length !== 2 || !resolveBindingRecursiveRelationColumn(
               ctx,
               bindingName,
-              "use pseudo-column traversals",
-              firstSegment
-            );
+              firstSegment,
+              segments[1],
+              item.expression.depthHint
+            )) {
+              assertNoBindingRelationConstruct(
+                ctx,
+                bindingName,
+                "use pseudo-column traversals",
+                firstSegment
+              );
+            }
           } else {
             resolveBindingRelationColumn(
               ctx,
@@ -2155,44 +2530,78 @@ function resolveSourceOutputColumns(intent, ctx, bindingName) {
   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,
+  throw new UnresolvedSelectAllOutputSchemaError(
     `Cannot compute output schema for NQL binding '${bindingName}' from SELECT * on '${intent.from}' without a concrete table schema.`
   );
 }
-function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []) {
+function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = [], sourceBindingSchemas) {
   const columns = [];
   const seen = /* @__PURE__ */ new Set();
   const directProjectionLineage = [];
+  const typeCandidates = [];
+  const sourceIsPhysicalTable = ctx.validator?.hasPhysicalTable(intent.from) ?? false;
+  const sourceBindingSchema = sourceIsPhysicalTable ? void 0 : sourceBindingSchemas?.get(intent.from);
   const addColumn = (column) => addUnique(columns, seen, column);
   const resolveSourceColumn = (column) => ctx.validator?.resolveColumnName(intent.from, column) ?? column;
   const addDirectProjection = (outputColumn, sourceColumn) => {
+    const resolvedSourceColumn = resolveSourceColumn(sourceColumn);
+    let typeInfo;
+    let untypeableReason = "unresolvable-source";
+    if (sourceIsPhysicalTable) {
+      typeInfo = ctx.validator?.getTableColumnType(
+        intent.from,
+        resolvedSourceColumn
+      );
+    } else if (sourceBindingSchema?.columnTypes) {
+      typeInfo = sourceBindingSchema.columnTypes[resolvedSourceColumn];
+    } else if (sourceBindingSchema?.columnTypesUnavailable) {
+      untypeableReason = sourceBindingSchema.columnTypesUnavailable.reason;
+    }
+    typeCandidates.push(
+      typeInfo !== void 0 ? { column: outputColumn, typed: typeInfo } : { column: outputColumn, untypeable: untypeableReason }
+    );
     if (!addColumn(outputColumn)) return;
     directProjectionLineage.push({
       kind: "directProjection",
       sourceTable: intent.from,
-      sourceColumn: resolveSourceColumn(sourceColumn),
+      sourceColumn: resolvedSourceColumn,
       outputColumn
     });
   };
+  const addUntypedColumn = (outputColumn, reason) => {
+    typeCandidates.push({ column: outputColumn, untypeable: reason });
+    addColumn(outputColumn);
+  };
+  const addCountAggregateColumn = (outputColumn) => {
+    typeCandidates.push({
+      column: outputColumn,
+      typed: { kind: "aggregate", fn: "count" }
+    });
+    addColumn(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 };
+  const finalizeOutputSchema = () => {
+    const outputSchema = { columns, directProjectionLineage };
+    const typesResult = buildBindingColumnTypes(columns, typeCandidates);
     return {
-      columns: outputSchema2.columns,
+      columns: outputSchema.columns,
       relationFilters: getBindingRelationFilterMetadata(
         intent,
         ctx,
-        outputSchema2,
+        outputSchema,
         bindingDependencies
-      )
+      ),
+      ..."columnTypes" in typesResult ? { columnTypes: typesResult.columnTypes } : { columnTypesUnavailable: typesResult.untypeable }
     };
+  };
+  const { select } = intent;
+  if (!select || select.type === "all") {
+    addSourceColumns();
+    return finalizeOutputSchema();
   }
   if (select.type === "fields") {
     for (const field of select.fields) {
@@ -2202,16 +2611,7 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
         addDirectProjection(field, field);
       }
     }
-    const outputSchema2 = { columns, directProjectionLineage };
-    return {
-      columns: outputSchema2.columns,
-      relationFilters: getBindingRelationFilterMetadata(
-        intent,
-        ctx,
-        outputSchema2,
-        bindingDependencies
-      )
-    };
+    return finalizeOutputSchema();
   }
   if (select.type === "aggregate") {
     for (const field of select.fields ?? []) {
@@ -2224,18 +2624,13 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
           `Cannot compute output schema for NQL binding '${bindingName}': aggregate '${aggregate.function}' must use an alias.`
         );
       }
-      addColumn(aggregate.as);
+      if (aggregate.function === "count") {
+        addCountAggregateColumn(aggregate.as);
+      } else {
+        addUntypedColumn(aggregate.as, "unsupported-aggregate");
+      }
     }
-    const outputSchema2 = { columns, directProjectionLineage };
-    return {
-      columns: outputSchema2.columns,
-      relationFilters: getBindingRelationFilterMetadata(
-        intent,
-        ctx,
-        outputSchema2,
-        bindingDependencies
-      )
-    };
+    return finalizeOutputSchema();
   }
   for (const expr of select.columns) {
     if (expr.kind === "column" && expr.column === "*") {
@@ -2259,20 +2654,16 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
       addDirectProjection(outputColumn, expr.column);
     } else if (expr.kind === "columnAlias") {
       addDirectProjection(outputColumn, expr.column);
+    } else if (expr.kind === "aggregate" && expr.function === "count") {
+      addCountAggregateColumn(outputColumn);
     } else {
-      addColumn(outputColumn);
+      let reason = "computed-expression";
+      if (expr.kind === "relationColumn") reason = "relation-column";
+      else if (expr.kind === "aggregate") reason = "unsupported-aggregate";
+      addUntypedColumn(outputColumn, reason);
     }
   }
-  const outputSchema = { columns, directProjectionLineage };
-  return {
-    columns: outputSchema.columns,
-    relationFilters: getBindingRelationFilterMetadata(
-      intent,
-      ctx,
-      outputSchema,
-      bindingDependencies
-    )
-  };
+  return finalizeOutputSchema();
 }
 function validateNqlExpressionPaths(expr, ctx) {
   switch (expr.type) {
@@ -3539,12 +3930,6 @@ 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) {
@@ -3571,6 +3956,44 @@ function compileMultiSegmentPath(expr, item, ctx) {
       );
     }
     const targetColumn = segments[i];
+    const bindingRelation2 = traversals.length === 1 ? resolveBindingRecursiveRelationColumn(
+      ctx,
+      ctx.currentFromTable,
+      firstSegment,
+      targetColumn,
+      depthHint
+    ) : void 0;
+    if (bindingRelation2) {
+      const relationColumnIntent2 = {
+        kind: "relationColumn",
+        relation: bindingRelation2.relation,
+        column: targetColumn,
+        as: item.alias ?? `${bindingRelation2.relation}.${targetColumn}`
+      };
+      return markNqlTrustedRelationFilter(relationColumnIntent2, {
+        relation: bindingRelation2.relation,
+        targetTable: bindingRelation2.targetTable,
+        sourceColumn: bindingRelation2.sourceColumn,
+        targetColumn: bindingRelation2.targetColumn,
+        hops: bindingRelation2.hops,
+        selectedColumn: targetColumn,
+        ...bindingRelation2.cardinality !== void 0 && {
+          cardinality: bindingRelation2.cardinality
+        },
+        ...bindingRelation2.relationType !== void 0 && {
+          relationType: bindingRelation2.relationType
+        },
+        ...bindingRelation2.recursive !== void 0 && {
+          recursive: bindingRelation2.recursive
+        }
+      });
+    }
+    assertNoBindingRelationConstruct(
+      ctx,
+      ctx.currentFromTable,
+      "use pseudo-column traversals",
+      segments[0]
+    );
     if (ctx.currentFromTable) {
       validateColumnForTable(ctx, ctx.currentFromTable, targetColumn);
     }
@@ -3627,12 +4050,24 @@ function compileMultiSegmentPath(expr, item, ctx) {
     sourceColumn: bindingRelation.sourceColumn,
     targetColumn: bindingRelation.targetColumn,
     hops: bindingRelation.hops,
+    ...bindingRelation.through !== void 0 && {
+      through: bindingRelation.through
+    },
+    ...bindingRelation.throughSourceColumn !== void 0 && {
+      throughSourceColumn: bindingRelation.throughSourceColumn
+    },
+    ...bindingRelation.throughTargetColumn !== void 0 && {
+      throughTargetColumn: bindingRelation.throughTargetColumn
+    },
     selectedColumn: column,
     ...bindingRelation.cardinality !== void 0 && {
       cardinality: bindingRelation.cardinality
     },
     ...bindingRelation.relationType !== void 0 && {
       relationType: bindingRelation.relationType
+    },
+    ...bindingRelation.recursive !== void 0 && {
+      recursive: bindingRelation.recursive
     }
   }) : relationColumnIntent;
 }
@@ -3781,16 +4216,17 @@ function allowsInternalParams(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");
+  return error instanceof UnresolvedSelectAllOutputSchemaError;
 }
-function programSequenceStepFromResult(result, bindName, final, bindingDependencies) {
+function programSequenceStepFromResult(result, bindName, final, bindingDependencies, snapshotReadBindings) {
   if (result.query) {
     return {
       kind: "query",
       query: result.query,
       ...bindName !== void 0 && { bindName },
       final,
-      bindingDependencies
+      bindingDependencies,
+      ...bindName !== void 0 && snapshotReadBindings.has(bindName) && { snapshot: true }
     };
   }
   if (result.mutation) {
@@ -3810,6 +4246,34 @@ function stringArraysEqual(left, right) {
 function isNqlAstRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function classifyReadBindingSnapshotShape(query, ctx, sourceWasBinding, outputSchema) {
+  if (!sourceWasBinding && ctx.validator?.getPhysicalTableColumns(query.from) === void 0) {
+    return {
+      supported: false,
+      reason: `no physical model table source '${query.from}'`
+    };
+  }
+  if (outputSchema?.columnTypes) {
+    return { supported: true };
+  }
+  const untypeable = outputSchema?.columnTypesUnavailable;
+  if (untypeable?.reason === "unsupported-aggregate") {
+    return {
+      supported: false,
+      reason: `aliased/computed/aggregate columns (unsupported aggregate column '${untypeable.column}')`
+    };
+  }
+  if (untypeable) {
+    return {
+      supported: false,
+      reason: `${untypeable.reason} column '${untypeable.column}'`
+    };
+  }
+  if (sourceWasBinding) {
+    return { supported: false, reason: "a binding source" };
+  }
+  return { supported: false, reason: "aliased/computed/aggregate columns" };
+}
 function addReadBindingReference(references, readBindingNames, name) {
   if (typeof name === "string" && readBindingNames.has(name)) {
     references.add(name);
@@ -3973,23 +4437,31 @@ function collectTransitiveReadBindingDependencies(directReferences, bindingDepen
   }
   return ordered;
 }
-function rejectReadBindingReferenceAcrossMutation(bindName, definitionIndex, mutationIndex, referenceIndex, statementCount) {
+function rejectReadBindingReferenceAcrossMutation(bindName, reason) {
   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.`
+    `read binding referenced across a mutation: unsupported snapshot shape (#186): snapshotting currently supports only a direct single-table column projection; binding '${bindName}' has ${reason}, so it cannot be materialized - move the reference before the mutation, or bind the mutation RETURNING result.`
   );
 }
-function rejectInvalidReadBindingDependencies(statementBindingDependencies, readBindingDefinitions, lastMutationStatement, referenceIndex, statementCount) {
+function markReadBindingReferenceAcrossMutation(bindName, snapshotReadBindings, readBindingSnapshotShapes) {
+  const snapshotShape = readBindingSnapshotShapes.get(bindName);
+  if (snapshotShape?.supported !== true) {
+    rejectReadBindingReferenceAcrossMutation(
+      bindName,
+      snapshotShape?.reason ?? "an unavailable output shape"
+    );
+  }
+  snapshotReadBindings.add(bindName);
+}
+function markReadBindingDependenciesRequiringSnapshot(statementBindingDependencies, readBindingDefinitions, lastMutationStatement, snapshotReadBindings, readBindingSnapshotShapes) {
   for (const referencedBindName of statementBindingDependencies) {
     const definitionIndex = readBindingDefinitions.get(referencedBindName);
     if (definitionIndex === void 0) continue;
     if (lastMutationStatement > definitionIndex) {
-      rejectReadBindingReferenceAcrossMutation(
+      markReadBindingReferenceAcrossMutation(
         referencedBindName,
-        definitionIndex,
-        lastMutationStatement,
-        referenceIndex,
-        statementCount
+        snapshotReadBindings,
+        readBindingSnapshotShapes
       );
     }
   }
@@ -4043,6 +4515,7 @@ var NqlCompiler = class {
     } finally {
       this.ctx.bindingOutputColumns.clear();
       this.ctx.bindingRelationFilters.clear();
+      this.ctx.lastMutationReturningItems = void 0;
       this.ctx.validator?.clearVirtualBindingTables();
     }
   }
@@ -4069,6 +4542,8 @@ var NqlCompiler = class {
     const seenBindNames = /* @__PURE__ */ new Map();
     const nqlProgramSequence = [];
     const readBindingDefinitions = /* @__PURE__ */ new Map();
+    const readBindingSnapshotShapes = /* @__PURE__ */ new Map();
+    const snapshotReadBindings = /* @__PURE__ */ new Set();
     const definedBindingNames = /* @__PURE__ */ new Set();
     const bindingDependencies = /* @__PURE__ */ new Map();
     let lastMutationStatement = -1;
@@ -4094,12 +4569,12 @@ var NqlCompiler = class {
         readBindingReferences,
         bindingDependencies
       );
-      rejectInvalidReadBindingDependencies(
+      markReadBindingDependenciesRequiringSnapshot(
         statementBindingDependencies,
         readBindingDefinitions,
         lastMutationStatement,
-        i,
-        program.statements.length
+        snapshotReadBindings,
+        readBindingSnapshotShapes
       );
       lastResult = this.compileSingleStatement(stmt, bindings);
       collectCompileResultReadBindingReferences(
@@ -4111,24 +4586,36 @@ var NqlCompiler = class {
         readBindingReferences,
         bindingDependencies
       );
-      rejectInvalidReadBindingDependencies(
+      markReadBindingDependenciesRequiringSnapshot(
         statementBindingDependencies,
         readBindingDefinitions,
         lastMutationStatement,
-        i,
-        program.statements.length
+        snapshotReadBindings,
+        readBindingSnapshotShapes
       );
       if (stmt.type === "mutationPipeline") {
         lastMutationStatement = i;
       }
       if (bindName) {
         if (lastResult.query) {
+          const sourceWasBinding = definedBindingNames.has(
+            lastResult.query.from
+          );
           const outputSchema = this.registerQueryBindingOutputSchema(
             bindName,
             lastResult.query,
             bindingOutputSchemas,
             statementBindingDependencies
           );
+          readBindingSnapshotShapes.set(
+            bindName,
+            classifyReadBindingSnapshotShape(
+              lastResult.query,
+              this.ctx,
+              sourceWasBinding,
+              outputSchema
+            )
+          );
           bindings.set(bindName, lastResult.query);
           if (outputSchema) {
             this.ctx.validator?.addVirtualBindingTable(
@@ -4176,7 +4663,8 @@ var NqlCompiler = class {
         lastResult,
         bindName,
         i === program.statements.length - 1,
-        statementBindingDependencies
+        statementBindingDependencies,
+        snapshotReadBindings
       );
       if (sequenceStep !== void 0) {
         nqlProgramSequence.push(sequenceStep);
@@ -4192,14 +4680,19 @@ var NqlCompiler = class {
     }
     const hasMutationBindings = mutationBindings.size > 0;
     const hasBindingOutputSchemas = bindingOutputSchemas.size > 0;
-    const hasNqlProgramSequence = nqlProgramSequence.length === program.statements.length;
+    const taggedNqlProgramSequence = nqlProgramSequence.map(
+      (step) => step.kind === "query" && step.bindName !== void 0 && snapshotReadBindings.has(step.bindName) ? { ...step, snapshot: true } : step
+    );
+    const hasNqlProgramSequence = taggedNqlProgramSequence.length === program.statements.length;
     if (bindings.size > 0) {
       return {
         ...lastResult,
         bindings,
         ...hasBindingOutputSchemas && { bindingOutputSchemas },
         ...hasMutationBindings && { mutationBindings },
-        ...hasNqlProgramSequence && { nqlProgramSequence }
+        ...hasNqlProgramSequence && {
+          nqlProgramSequence: taggedNqlProgramSequence
+        }
       };
     }
     return lastResult;
@@ -4210,7 +4703,12 @@ var NqlCompiler = class {
         query,
         this.ctx,
         bindName,
-        bindingDependencies
+        bindingDependencies,
+        // #213 B2: earlier bindings are already registered here (this
+        // map is populated in program-statement order), so a
+        // transitive `from` = binding chains through the SOURCE's
+        // typed schema instead of staying untypeable.
+        bindingOutputSchemas
       );
       bindingOutputSchemas.set(bindName, outputSchema);
       this.ctx.bindingOutputColumns.set(bindName, outputSchema.columns);
@@ -4250,20 +4748,50 @@ var NqlCompiler = class {
     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 };
+      const columns2 = this.ctx.validator?.getTableColumns(mutation.table);
+      if (columns2 !== void 0) {
+        return {
+          columns: columns2,
+          ...this.buildMutationReturningColumnTypes(mutation.table, columns2)
+        };
+      }
       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.`
       );
     }
+    const columns = returning.map(
+      (column) => this.ctx.validator?.resolveColumnName(mutation.table, column) ?? column
+    );
     return {
-      columns: returning.map(
-        (column) => this.ctx.validator?.resolveColumnName(mutation.table, column) ?? column
-      )
+      columns,
+      ...this.buildMutationReturningColumnTypes(mutation.table, columns)
     };
   }
+  /**
+   * Build `columnTypes`/`columnTypesUnavailable` for a mutation-RETURNING
+   * binding. #213 B2: detection consumes `ctx.lastMutationReturningItems`
+   * (alias-aware, positional) — NEVER the collapsed `columns` names — so an
+   * alias colliding with a real column (`returning email as name`) is
+   * flagged 'aliased-returning' rather than silently mistyped as the
+   * colliding column's type.
+   */
+  buildMutationReturningColumnTypes(table, columns) {
+    const items = this.ctx.lastMutationReturningItems;
+    const candidates = columns.map(
+      (column, index) => {
+        const item = items !== void 0 && items !== "star" ? items[index] : void 0;
+        if (item?.aliased) {
+          return { column, untypeable: "aliased-returning" };
+        }
+        const typeInfo = this.ctx.validator?.getTableColumnType(table, column);
+        return typeInfo !== void 0 ? { column, typed: typeInfo } : { column, untypeable: "unresolvable-source" };
+      }
+    );
+    const typesResult = buildBindingColumnTypes(columns, candidates);
+    return "columnTypes" in typesResult ? { columnTypes: typesResult.columnTypes } : { columnTypesUnavailable: typesResult.untypeable };
+  }
   compileSingleStatement(stmt, bindings) {
     if (stmt.type === "withQuery") {
       return compileWithQuery(stmt, this.ctx, this.fns);