@dbsp/core 1.0.5 → 1.1.0

package/dist/index.d.ts

@@ -4915,11 +4915,11 @@ declare class UpsertBuilder<T = void> extends MutationBuilderBase<T, UpsertInten
  * const users = await orm.nql<{ name: string; email: string }>`users | select name, email`.all();
  * ```
  *
- * Each `${value}` interpolation is escaped into a safe NQL literal (string/number/boolean/null).
- * Untrusted string input cannot inject NQL structure because it is always quoted and
- * single-quotes inside are doubled (`''`). For dynamic structural fragments (table names,
- * column names, ORDER BY direction) use the builder API (`orm.select()`). See #134 for
- * upcoming `:param` binding and a `nqlRaw()` escape hatch.
+ * Each non-raw `${value}` interpolation is converted into a generated NQL named
+ * parameter (`:__p0`, `:__p1`, ...) and forwarded to the compiler through its
+ * params map. Values never touch NQL source text. Use `nqlRaw()` only for trusted
+ * dynamic NQL fragments that must participate in parsing, such as an ORDER BY
+ * clause assembled from application-controlled choices.
  *
  * @module nql
  * @since DX-040
@@ -4951,15 +4951,32 @@ interface NqlBuilder<T> {
  * ```
  */
 type NqlTag = <T>(strings: TemplateStringsArray, ...values: unknown[]) => NqlBuilder<T>;
+declare const NQL_RAW_FRAGMENT_TYPE: unique symbol;
+/**
+ * Trusted NQL source fragment for `nql` template interpolation.
+ *
+ * Never wrap untrusted input in `nqlRaw()`: raw fragments are spliced verbatim
+ * into NQL source and parsed as query structure.
+ *
+ * @public
+ */
+interface NqlRawFragment {
+    readonly fragment: string;
+    readonly [NQL_RAW_FRAGMENT_TYPE]: true;
+}
+/**
+ * Mark a trusted fragment to splice verbatim into an NQL template.
+ *
+ * Never pass untrusted input to this function.
+ *
+ * @public
+ */
+declare function nqlRaw(fragment: string): NqlRawFragment;
 /**
  * Create an NQL template tag function.
  *
- * Each `${value}` in the template is escaped into a safe NQL literal before parsing.
- * Supported interpolation types: `string`, `number`, `boolean`, `null`.
- * Untrusted string input is therefore safe from NQL-syntax injection — it is always
- * wrapped in single-quotes with embedded quotes doubled (`''`).
- * For dynamic structural fragments (table names, column names, ORDER BY direction)
- * use the builder API (`orm.select()`). See issue #134 for upcoming `:param` binding.
+ * Each non-raw `${value}` in the template is bound as a generated named param.
+ * Use `nqlRaw()` only for trusted dynamic NQL structure.
  *
  * @param schemaDefinition - Schema definition for validation
  * @param model - ModelIR for plan execution
@@ -7806,6 +7823,26 @@ type SelectField = string | {
  */
 type TraversalDirection = AdjacencyDirection | EdgeTableDirection;
 
+/**
+ * Shared helpers for relation-dotted include path identity.
+ *
+ * Planner intent paths are positional (`include[0].include[1]`). Join identity
+ * and hydration keys use the relation chain actually traversed
+ * (`definition.file`, `manager.manager`), so every consumer must derive that
+ * string the same way.
+ */
+type RelationPathIncludeNode = {
+    readonly relation?: unknown;
+    readonly via?: unknown;
+    readonly include?: readonly unknown[];
+};
+type RelationPathUsage = {
+    readonly relationName?: string | null | undefined;
+    readonly relationPath?: string | null | undefined;
+};
+declare function deriveRelationPathFromIntentPath(includes: readonly unknown[] | undefined, intentPath: string | undefined, fallbackRelation: string | undefined): string | undefined;
+declare function countDistinctRelationPathsByName(usages: readonly RelationPathUsage[]): Map<string, number>;
+
 /**
  * ResultHydrator - Handles result hydration and recursive include processing.
  *
@@ -8184,4 +8221,4 @@ declare const assertIntentHasOrderBy: (result: AssertionQueryResult, expected: b
  */
 declare function runAssertions(blocks: AssertionBlock[], results: AssertionQueryResult[], queries: string[], hasDb?: boolean): AssertionSummary;
 
-export { ASSERTION_TYPES, AdapterRequiredError, type AdjacencyOptions, type AfterMutationHook, type AfterQueryHook, type AggregateOptions, type AliasedColumn, type AliasedExprColumn, type AllColumns, AmbiguousPlanError, AmbiguousRelationError, type Assertion, type AssertionBlock, type AssertionOutcome, type AssertionQueryResult, type AssertionSummary, type AssertionType, BRAND, type BatchValuesOptions, type BatchValuesRef, type BeforeMutationHook, type BeforeQueryHook, type BrandKey, COLUMN_META, type CardinalityShorthand, CaseBuilder, type CaseValue, type ColumnDef, type ColumnMetaKey, ColumnNotFoundError, type ColumnRef, type ColumnSpec, type ColumnTypeToTS, CteBuilder, type CteDump, CteQueryBuilder, type CursorPaginateOptions, type CursorPaginatedResult, DEFAULT_CONVENTIONS, DEFAULT_FEATURE_CHECKERS, DUCKDB_CAPABILITIES, type DefaultFilters, type DefineModelOptions, DeleteBuilder, type DistinctField, type DumpMetaInput, type EdgeTableOptions, ErrorCode, type ErrorHookContext, Errors, ExecutionError, type ExprInput, ExpressionRef, type ExpressionSpec, type FeatureChecker, type FeatureUsage, type FilterOperators, type FilterValue, type FullTextSearchField, type FullTextSearchOptions, type GeneratedBelongsTo, type GeneratedColumn, type GeneratedColumnType, type GeneratedConventions, type GeneratedHasMany, type GeneratedHint, type GeneratedManyToMany, type GeneratedRelation, type GeneratedRelationKind, type GeneratedSchema, type GeneratedTable, type GetSchemaFromDbOptions, type HierarchyOptions, type HookErrorHandler, type HookManager, type HookPriority, type HydrateOptions, IRREGULAR_PLURALS, type IncludeOptions, type IncludeOptionsWithRecursive, type InferColumn, type InferColumnType, type InferColumnTypes, type InferDB, type InferDBFromSchema, type InferRefColumn, type InferRow, type InferRowType, type InferSchemaDB, type InferTableRow, type InferTables, type InferredRangeValue, InsertBuilder, IntentBuilder, type IntentBuilderState, type IntentSummary, InvalidOperationError, InvalidRelationDefinitionError, type JoinOptions, type JsonValue, type LightweightRelationsDef, type ListHierarchyOptions, type ListIndexOptions, type Logger, MSSQL_CAPABILITIES, MYSQL_CAPABILITIES, ModelIRImpl, type MutationDump, type MutationHookContext, type MutationOperation, NamingConventionMismatchError, type NegotiationResult, type NestedInclude, type SchemaColumnType$1 as NewSchemaColumnType, NotFoundError, type NqlBuilder, type NqlTag, type OnErrorHook, type OrderByInput, type OrderByRecord, type OrderBySpec, type OrmInstance, type OrmOf, type OrmOptions, type OrmOptionsWithAdapter, type OrmOptionsWithModel, type OrmOptionsWithSchema, POSTGRESQL_CAPABILITIES, type PaginateOptions, type PaginatedResult, type ParseError, type ParseResult, type ParsedRelationDef, type ParsedRelationKey, type PathOptions, type PrioritizedHook, type QueryAssertionResult, type QueryBuilder, type QueryHookContext, type QueryResultType, RELATION_META, type RangeType, RawCteQueryBuilder, type RecursiveDump, type RecursiveIncludeConfig, type RecursiveOptions, RecursiveShapeMismatchError, type RefDefinition, type RefOptions, type RelationHints, type RelationKey, type RelationMetaKey, RelationNotFoundError, type RelationObjectDef, type RelationRef, type RelationShorthand, type RelationTupleDef, type ResolvedSchema, ResolvedSchemaValidation, ResultHydrator, SQLITE_CAPABILITIES, SQL_RAW_MARKER, type Schema, type SchemaBelongsToRelation, type SchemaCardinality, type SchemaColumnDefinition, type SchemaColumnType, type SchemaConfigInput, type SchemaConstraints, type SchemaConventionsDefinition, type SchemaConversionResult, type SchemaDefinition, type SchemaDefinitionInput, SchemaValidationError$1 as SchemaError, type SchemaExtras, type SchemaFilterStrategy, type SchemaForeignKeyReference, type SchemaHasManyRelation, type SchemaHintDefinition, type SchemaHintsDefinition, type SchemaIndexDefinition, type SchemaIndexOptions, type SchemaIndexesDefinition, type SchemaManyToManyRelation, type SchemaOnDeleteAction, type SchemaOptions, type SchemaRelationDefinition, type SchemaRelationKind, type SchemaRelationsDefinition, type SchemaTableDefinition, type SchemaTableOptions, type SchemaTablesDefinition, SchemaValidationError, type SelectField, type SelfRefRoles, type SetOperationBuilder, type SimplifiedOrmOptions, type SqlRawExpression, type StreamOptions, SubqueryBuilder, SubqueryExpression, TABLE_META, type TableAssertionData, type TableDDL, type TableDef, type TableIndexes, type TableMetaKey, TableNotFoundError, type TableRef, type TraversalDirection, UnhandledTypeInDialect, UnknownDialectError, UnsafeOperationError, UnsupportedCapabilityError, UnsupportedFeatureError, UnsupportedStrategyError, UpdateBuilder, UpsertBuilder, type ValidatedResolvedSchema, type WhereFilter, WindowBuilder, aggOrderBy, and, any, array, arrayAgg, assertCapability, assertContains, assertDbColumnExists, assertDbOutput, assertDbRowsEquals, assertDbRowsMax, assertDbRowsMin, assertDbValueEquals, assertEquals, assertIntentHasGroupBy, assertIntentHasOrderBy, assertIntentHasWhere, assertIntentTable, assertIntentType, assertIntentWith, assertMatches, assertParamsEquals, assertParamsLength, assertParamsType, assertParamsValue, assertResolvedSchemaToGeneratedSchema, assertSQLColumn, assertSQLEquals, assertSQLJoin, assertSQLTable, assertSuccess, assertTypeSupported, batchValues, buildModelFromResolvedSchema, buildModelFromSchema, capitalize, caseWhen, cast, coalesce, col, composeAfterMutationHooks, composeAfterQueryHooks, composeBeforeMutationHooks, composeBeforeQueryHooks, composeOnErrorHooks, createDialectCapabilities, createHookManager, createNqlTag, createOrm, createPseudoColumnMetadata, createRawCteBuilder, createRecursiveMetadata, decapitalize, defaultLogger, defineModel, defineSchema, denseRank, detectForeignKeys, detectManyToMany, distinct, eq, every, exists, ref as exprRef, extendDialect, extractPseudoColumnKeywords, findClosestMatch, fn, fullTextSearch, getAvailableDialects, getDialectCapabilities, getLogger, getRelationKind, getSchemaFromDb, gt, gte, inArray, inSubquery, inferForeignKey, inferRelationsFromSchema, isAliasedColumn, isAllColumns, isBatchValuesRef, isBelongsTo, isCardinalityShorthand, isColumnRef, isDistinctField, isDistinctFrom, isExpressionSpec, isGeneratedSchema, isHasMany, isKnownDialect, isManyToMany, isNotNull, isNull, isOverallSuccess, isRecursiveIncludeOptions, isRecursiveRelation, isRef, isRelationObjectDef, isRelationRef, isRelationTupleDef, isResolvedSchema, isSelfReferential, isSqlRaw, isSubqueryExpression, isTableRef, isWhereIntent, lag, lead, like, literal, lt, lte, namedArg, negotiateFeatures, neq, none, normalizeSQL, normalizeSchema, not, notExists, objectToWhereIntent, op, or, outerRef, param, parseAssertionFile, parseRelationDef, parseRelationKey, pipeAfterMutationHooks, pipeAfterQueryHooks, pipeBeforeMutationHooks, pipeBeforeQueryHooks, pipeOnErrorHooks, plan, planRecursive, pluralize, rangeContainedBy, rangeContains, rangeOverlaps, rank, raw, rawExists, rawNotExists, ref$1 as ref, registerDialect, relationColumn, requiresDatabase, resetLogger, resolveQueryIndex, resolvedSchemaToGeneratedSchema, rowNumber, runAssertions, schema, schemaToModelIR, setLogger, silentLogger, singularize, some, sortByPriority, sql, star, stringAgg, subquery, supportsDDLGeneration, supportsExecution, supportsIntrospection, supportsRawSql, supportsStreaming, supportsTransactions, textScore, unary, validateAssertionBlocks, validateRecursiveInclude, validateRecursiveShape, validateTypeName, wAvg, wCount, wMax, wMin, wSum, withPriority };
+export { ASSERTION_TYPES, AdapterRequiredError, type AdjacencyOptions, type AfterMutationHook, type AfterQueryHook, type AggregateOptions, type AliasedColumn, type AliasedExprColumn, type AllColumns, AmbiguousPlanError, AmbiguousRelationError, type Assertion, type AssertionBlock, type AssertionOutcome, type AssertionQueryResult, type AssertionSummary, type AssertionType, BRAND, type BatchValuesOptions, type BatchValuesRef, type BeforeMutationHook, type BeforeQueryHook, type BrandKey, COLUMN_META, type CardinalityShorthand, CaseBuilder, type CaseValue, type ColumnDef, type ColumnMetaKey, ColumnNotFoundError, type ColumnRef, type ColumnSpec, type ColumnTypeToTS, CteBuilder, type CteDump, CteQueryBuilder, type CursorPaginateOptions, type CursorPaginatedResult, DEFAULT_CONVENTIONS, DEFAULT_FEATURE_CHECKERS, DUCKDB_CAPABILITIES, type DefaultFilters, type DefineModelOptions, DeleteBuilder, type DistinctField, type DumpMetaInput, type EdgeTableOptions, ErrorCode, type ErrorHookContext, Errors, ExecutionError, type ExprInput, ExpressionRef, type ExpressionSpec, type FeatureChecker, type FeatureUsage, type FilterOperators, type FilterValue, type FullTextSearchField, type FullTextSearchOptions, type GeneratedBelongsTo, type GeneratedColumn, type GeneratedColumnType, type GeneratedConventions, type GeneratedHasMany, type GeneratedHint, type GeneratedManyToMany, type GeneratedRelation, type GeneratedRelationKind, type GeneratedSchema, type GeneratedTable, type GetSchemaFromDbOptions, type HierarchyOptions, type HookErrorHandler, type HookManager, type HookPriority, type HydrateOptions, IRREGULAR_PLURALS, type IncludeOptions, type IncludeOptionsWithRecursive, type InferColumn, type InferColumnType, type InferColumnTypes, type InferDB, type InferDBFromSchema, type InferRefColumn, type InferRow, type InferRowType, type InferSchemaDB, type InferTableRow, type InferTables, type InferredRangeValue, InsertBuilder, IntentBuilder, type IntentBuilderState, type IntentSummary, InvalidOperationError, InvalidRelationDefinitionError, type JoinOptions, type JsonValue, type LightweightRelationsDef, type ListHierarchyOptions, type ListIndexOptions, type Logger, MSSQL_CAPABILITIES, MYSQL_CAPABILITIES, ModelIRImpl, type MutationDump, type MutationHookContext, type MutationOperation, NamingConventionMismatchError, type NegotiationResult, type NestedInclude, type SchemaColumnType$1 as NewSchemaColumnType, NotFoundError, type NqlBuilder, type NqlRawFragment, type NqlTag, type OnErrorHook, type OrderByInput, type OrderByRecord, type OrderBySpec, type OrmInstance, type OrmOf, type OrmOptions, type OrmOptionsWithAdapter, type OrmOptionsWithModel, type OrmOptionsWithSchema, POSTGRESQL_CAPABILITIES, type PaginateOptions, type PaginatedResult, type ParseError, type ParseResult, type ParsedRelationDef, type ParsedRelationKey, type PathOptions, type PrioritizedHook, type QueryAssertionResult, type QueryBuilder, type QueryHookContext, type QueryResultType, RELATION_META, type RangeType, RawCteQueryBuilder, type RecursiveDump, type RecursiveIncludeConfig, type RecursiveOptions, RecursiveShapeMismatchError, type RefDefinition, type RefOptions, type RelationHints, type RelationKey, type RelationMetaKey, RelationNotFoundError, type RelationObjectDef, type RelationPathIncludeNode, type RelationPathUsage, type RelationRef, type RelationShorthand, type RelationTupleDef, type ResolvedSchema, ResolvedSchemaValidation, ResultHydrator, SQLITE_CAPABILITIES, SQL_RAW_MARKER, type Schema, type SchemaBelongsToRelation, type SchemaCardinality, type SchemaColumnDefinition, type SchemaColumnType, type SchemaConfigInput, type SchemaConstraints, type SchemaConventionsDefinition, type SchemaConversionResult, type SchemaDefinition, type SchemaDefinitionInput, SchemaValidationError$1 as SchemaError, type SchemaExtras, type SchemaFilterStrategy, type SchemaForeignKeyReference, type SchemaHasManyRelation, type SchemaHintDefinition, type SchemaHintsDefinition, type SchemaIndexDefinition, type SchemaIndexOptions, type SchemaIndexesDefinition, type SchemaManyToManyRelation, type SchemaOnDeleteAction, type SchemaOptions, type SchemaRelationDefinition, type SchemaRelationKind, type SchemaRelationsDefinition, type SchemaTableDefinition, type SchemaTableOptions, type SchemaTablesDefinition, SchemaValidationError, type SelectField, type SelfRefRoles, type SetOperationBuilder, type SimplifiedOrmOptions, type SqlRawExpression, type StreamOptions, SubqueryBuilder, SubqueryExpression, TABLE_META, type TableAssertionData, type TableDDL, type TableDef, type TableIndexes, type TableMetaKey, TableNotFoundError, type TableRef, type TraversalDirection, UnhandledTypeInDialect, UnknownDialectError, UnsafeOperationError, UnsupportedCapabilityError, UnsupportedFeatureError, UnsupportedStrategyError, UpdateBuilder, UpsertBuilder, type ValidatedResolvedSchema, type WhereFilter, WindowBuilder, aggOrderBy, and, any, array, arrayAgg, assertCapability, assertContains, assertDbColumnExists, assertDbOutput, assertDbRowsEquals, assertDbRowsMax, assertDbRowsMin, assertDbValueEquals, assertEquals, assertIntentHasGroupBy, assertIntentHasOrderBy, assertIntentHasWhere, assertIntentTable, assertIntentType, assertIntentWith, assertMatches, assertParamsEquals, assertParamsLength, assertParamsType, assertParamsValue, assertResolvedSchemaToGeneratedSchema, assertSQLColumn, assertSQLEquals, assertSQLJoin, assertSQLTable, assertSuccess, assertTypeSupported, batchValues, buildModelFromResolvedSchema, buildModelFromSchema, capitalize, caseWhen, cast, coalesce, col, composeAfterMutationHooks, composeAfterQueryHooks, composeBeforeMutationHooks, composeBeforeQueryHooks, composeOnErrorHooks, countDistinctRelationPathsByName, createDialectCapabilities, createHookManager, createNqlTag, createOrm, createPseudoColumnMetadata, createRawCteBuilder, createRecursiveMetadata, decapitalize, defaultLogger, defineModel, defineSchema, denseRank, deriveRelationPathFromIntentPath, detectForeignKeys, detectManyToMany, distinct, eq, every, exists, ref as exprRef, extendDialect, extractPseudoColumnKeywords, findClosestMatch, fn, fullTextSearch, getAvailableDialects, getDialectCapabilities, getLogger, getRelationKind, getSchemaFromDb, gt, gte, inArray, inSubquery, inferForeignKey, inferRelationsFromSchema, isAliasedColumn, isAllColumns, isBatchValuesRef, isBelongsTo, isCardinalityShorthand, isColumnRef, isDistinctField, isDistinctFrom, isExpressionSpec, isGeneratedSchema, isHasMany, isKnownDialect, isManyToMany, isNotNull, isNull, isOverallSuccess, isRecursiveIncludeOptions, isRecursiveRelation, isRef, isRelationObjectDef, isRelationRef, isRelationTupleDef, isResolvedSchema, isSelfReferential, isSqlRaw, isSubqueryExpression, isTableRef, isWhereIntent, lag, lead, like, literal, lt, lte, namedArg, negotiateFeatures, neq, none, normalizeSQL, normalizeSchema, not, notExists, nqlRaw, objectToWhereIntent, op, or, outerRef, param, parseAssertionFile, parseRelationDef, parseRelationKey, pipeAfterMutationHooks, pipeAfterQueryHooks, pipeBeforeMutationHooks, pipeBeforeQueryHooks, pipeOnErrorHooks, plan, planRecursive, pluralize, rangeContainedBy, rangeContains, rangeOverlaps, rank, raw, rawExists, rawNotExists, ref$1 as ref, registerDialect, relationColumn, requiresDatabase, resetLogger, resolveQueryIndex, resolvedSchemaToGeneratedSchema, rowNumber, runAssertions, schema, schemaToModelIR, setLogger, silentLogger, singularize, some, sortByPriority, sql, star, stringAgg, subquery, supportsDDLGeneration, supportsExecution, supportsIntrospection, supportsRawSql, supportsStreaming, supportsTransactions, textScore, unary, validateAssertionBlocks, validateRecursiveInclude, validateRecursiveShape, validateTypeName, wAvg, wCount, wMax, wMin, wSum, withPriority };

package/dist/index.js

@@ -2601,7 +2601,8 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
     return;
   }
   const includePath = `${sourceTable}.${relation.name}`;
-  if (state.visitedIncludes.has(includePath)) {
+  const isSelfReferentialRelation = relation.source === relation.target;
+  if (!isSelfReferentialRelation && state.visitedIncludes.has(includePath)) {
     state.warnings.push({
       code: "CIRCULAR_INCLUDE",
       message: `Circular include detected: ${includePath}`,
@@ -2609,12 +2610,12 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
     });
     return;
   }
-  state.visitedIncludes.add(includePath);
+  if (!isSelfReferentialRelation) state.visitedIncludes.add(includePath);
   const relationPath = `${sourceTable}.${relation.name}`;
   const paths = state.relationAccessCounts.get(relationPath) ?? [];
   paths.push(intentPath);
   state.relationAccessCounts.set(relationPath, paths);
-  const isRecursiveInclude = (!!include.recursive || !!relation.recursive) && relation.source === relation.target;
+  const isRecursiveInclude = (!!include.recursive || !!relation.recursive) && isSelfReferentialRelation;
   let includeStrategy;
   if (isRecursiveInclude) {
     if (opts.dialectCapabilities?.supportsRecursiveCTE === false) {
@@ -2749,7 +2750,7 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
       }
     }
   }
-  state.visitedIncludes.delete(includePath);
+  if (!isSelfReferentialRelation) state.visitedIncludes.delete(includePath);
 }
 function disambiguateRelation(relationName, sourceTable, model, state, opts, _intentPath, viaHint) {
   const directRelation = model.getRelation(`${sourceTable}.${relationName}`);
@@ -4105,6 +4106,12 @@ function coalesce(fields, as) {
   };
 }
 function raw(sqlFragment, as) {
+  if (typeof as !== "string" || as.trim().length === 0) {
+    throw new InvalidOperationError(
+      "raw",
+      "raw() requires an alias as second argument, e.g. raw('COUNT(*)', 'count')"
+    );
+  }
   validateIdentifier(as, "column");
   return {
     __expr: true,
@@ -6126,53 +6133,131 @@ function negotiateFeatures(model, capabilities, behavior = "warning", checkers =
 }
 
 // src/dx/nql.ts
-import { compile as nqlCompile } from "@dbsp/nql";
-function toNqlLiteral(value, index) {
-  if (value === null) {
-    return "null";
+import {
+  NqlLexer,
+  compile as nqlCompile
+} from "@dbsp/nql";
+import { NQL_INTERNAL_COMPILER_OPTIONS } from "@dbsp/types/internal";
+var NQL_RAW_FRAGMENT = /* @__PURE__ */ Symbol("NqlRawFragment");
+function nqlRaw(fragment) {
+  if (typeof fragment !== "string") {
+    throw new TypeError("nqlRaw() expects a string fragment");
+  }
+  const raw2 = { fragment };
+  Object.defineProperty(raw2, NQL_RAW_FRAGMENT, {
+    value: true,
+    enumerable: false
+  });
+  return Object.freeze(raw2);
+}
+function isNqlRawFragment(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
   }
-  switch (typeof value) {
-    case "boolean":
-      return value ? "true" : "false";
-    case "number": {
-      if (!Number.isFinite(value)) {
-        throw new Error(
-          `nql\`...\`: cannot interpolate non-finite number (${value}) at position ${index}. Only finite numbers are supported. For dynamic NQL structure use the builder API (orm.select()). See issue #134.`
-        );
-      }
-      const s = value < 0 ? `-${Math.abs(value)}` : String(value);
-      if (/[eE]/.test(s)) {
-        throw new Error(
-          `nql\`...\`: number ${value} at position ${index} has no exact NQL numeric literal form (exponential notation). Convert it yourself or use the builder API (orm.select()). See issue #134.`
-        );
-      }
-      return s;
+  if (!Object.hasOwn(value, NQL_RAW_FRAGMENT)) {
+    return false;
+  }
+  return value[NQL_RAW_FRAGMENT] === true;
+}
+function isInsideGeneratedRange(start, end, generatedRanges) {
+  return generatedRanges.some(
+    (range) => start >= range.start && end <= range.end
+  );
+}
+function findOverlappingGeneratedRange(start, end, generatedRanges) {
+  return generatedRanges.find(
+    (range) => start < range.end && end > range.start
+  );
+}
+function findExactGeneratedRange(name, start, end, generatedRanges) {
+  return generatedRanges.find(
+    (range) => range.name === name && range.start === start && range.end === end
+  );
+}
+function generatedParamLexError(name) {
+  return `Generated NQL parameter :${name} was not recognized as exactly one NamedParam token after raw-fragment assembly; check adjacent nqlRaw() fragments for quotes, comments, or identifier text that can swallow the placeholder.`;
+}
+function findInternalParamSourceError(query, generatedRanges) {
+  const lexResult = NqlLexer.tokenize(query);
+  const generatedTokenCounts = new Map(
+    generatedRanges.map((range) => [range.name, 0])
+  );
+  for (const token of lexResult.tokens) {
+    if (token.tokenType.name !== "NamedParam") {
+      continue;
     }
-    case "string": {
-      if (value.includes("\n") || value.includes("\r")) {
-        throw new Error(
-          `nql\`...\`: cannot interpolate a string containing a newline at position ${index}. NQL string literals do not support raw newline characters. For dynamic NQL structure use the builder API (orm.select()). See issue #134.`
-        );
-      }
-      const escaped = value.replaceAll("'", "''");
-      return `'${escaped}'`;
+    const name = token.image.slice(1);
+    if (!name.startsWith("__p")) {
+      continue;
     }
-    default: {
-      const typeName = value === void 0 ? "undefined" : typeof value;
-      throw new Error(
-        `nql\`...\`: cannot interpolate value of type "${typeName}" at position ${index}. Only string, number, boolean, and null are supported; for dynamic NQL fragments use the builder API (orm.select()). See issue #134.`
+    const start = token.startOffset;
+    const end = (token.endOffset ?? start + token.image.length - 1) + 1;
+    const exactGeneratedRange = findExactGeneratedRange(
+      name,
+      start,
+      end,
+      generatedRanges
+    );
+    if (exactGeneratedRange) {
+      generatedTokenCounts.set(
+        exactGeneratedRange.name,
+        (generatedTokenCounts.get(exactGeneratedRange.name) ?? 0) + 1
       );
+      continue;
+    }
+    const overlappingGeneratedRange = findOverlappingGeneratedRange(
+      start,
+      end,
+      generatedRanges
+    );
+    if (overlappingGeneratedRange) {
+      return generatedParamLexError(overlappingGeneratedRange.name);
     }
+    if (!isInsideGeneratedRange(start, end, generatedRanges)) {
+      return `Reserved NQL parameter namespace "__p" cannot be referenced by user source (${token.image}).`;
+    }
+  }
+  for (const range of generatedRanges) {
+    if (generatedTokenCounts.get(range.name) !== 1) {
+      return generatedParamLexError(range.name);
+    }
+  }
+  return void 0;
+}
+function assembleNqlTemplate(strings, values) {
+  const params = /* @__PURE__ */ Object.create(null);
+  const generatedRanges = [];
+  let query = strings[0] ?? "";
+  let boundIndex = 0;
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    if (isNqlRawFragment(value)) {
+      query += value.fragment;
+    } else {
+      const name = `__p${boundIndex++}`;
+      const placeholder = `:${name}`;
+      const start = query.length;
+      query += placeholder;
+      generatedRanges.push({ name, start, end: start + placeholder.length });
+      params[name] = value;
+    }
+    query += strings[i + 1] ?? "";
   }
+  return {
+    query,
+    params,
+    hasBoundParams: boundIndex > 0,
+    sourceError: findInternalParamSourceError(query, generatedRanges)
+  };
 }
 function createNqlTag(schemaDefinition, model, adapter, schemaName) {
   return function nql(strings, ...values) {
-    let query = strings[0] ?? "";
-    for (let i = 0; i < values.length; i++) {
-      query += toNqlLiteral(values[i], i) + (strings[i + 1] ?? "");
-    }
+    const assembled = assembleNqlTemplate(strings, values);
     return new NqlBuilderImpl(
-      query,
+      assembled.query,
+      assembled.params,
+      assembled.hasBoundParams,
+      assembled.sourceError,
       schemaDefinition,
       model,
       adapter,
@@ -6183,13 +6268,19 @@ function createNqlTag(schemaDefinition, model, adapter, schemaName) {
 var NqlBuilderImpl = class {
   _intent;
   query;
+  params;
+  hasBoundParams;
+  sourceError;
   schemaDefinition;
   model;
   // biome-ignore lint/correctness/noUnusedPrivateClassMembers: Reserved for future schema-scoping support
   _schemaName;
   adapter;
-  constructor(query, schemaDefinition, model, adapter, schemaName) {
+  constructor(query, params, hasBoundParams, sourceError, schemaDefinition, model, adapter, schemaName) {
     this.query = query;
+    this.params = params;
+    this.hasBoundParams = hasBoundParams;
+    this.sourceError = sourceError;
     this.schemaDefinition = schemaDefinition;
     this.model = model;
     this.adapter = adapter;
@@ -6199,7 +6290,14 @@ var NqlBuilderImpl = class {
     if (this._intent) {
       return this._intent;
     }
-    const compilerOptions = extractPseudoColumnKeywords(this.model);
+    if (this.sourceError !== void 0) {
+      throw new Error(`NQL compilation failed: ${this.sourceError}`);
+    }
+    const compilerOptions = {
+      ...extractPseudoColumnKeywords(this.model) ?? {},
+      params: this.params,
+      [NQL_INTERNAL_COMPILER_OPTIONS]: { allowInternalParams: true }
+    };
     const result = nqlCompile(
       this.query,
       this.schemaDefinition,
@@ -6208,7 +6306,8 @@ var NqlBuilderImpl = class {
     );
     if (!result.success) {
       const errors = result.errors?.map((e) => e.message).join(", ") ?? "Unknown error";
-      throw new Error(`NQL compilation failed: ${errors}`);
+      const rawHint = this.hasBoundParams ? " If an interpolation was intended as NQL structure, wrap a trusted fragment with nqlRaw()." : "";
+      throw new Error(`NQL compilation failed: ${errors}${rawHint}`);
     }
     if (result.ast?.mutation && !result.ast?.query) {
       throw new Error(
@@ -6224,12 +6323,15 @@ var NqlBuilderImpl = class {
   toIntentIR() {
     return this.compile();
   }
-  plan() {
+  planInternal() {
     const intent = this.compile();
     return plan(intent, this.model);
   }
+  plan() {
+    return this.planInternal();
+  }
   dump(meta) {
-    const planReport = this.plan();
+    const planReport = this.planInternal();
     if (!this.adapter) {
       return {
         plan: planReport,
@@ -6272,7 +6374,7 @@ var NqlBuilderImpl = class {
         "Cannot execute query: no adapter configured. Pass an adapter to createOrm() or use .toIntentIR() / .plan() for debugging."
       );
     }
-    const planReport = this.plan();
+    const planReport = this.planInternal();
     const compiled = this.adapter.compile(planReport);
     return this.adapter.execute(compiled);
   }
@@ -6661,8 +6763,152 @@ function hydrateJsonAggIncludes(results, planReport) {
   }
 }
 
+// src/dx/relation-paths.ts
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function includeNode(value) {
+  return value !== null && typeof value === "object" ? value : void 0;
+}
+function parseIntentPathIndexes(intentPath) {
+  const indexes = [];
+  const indexPattern = /include\[(\d+)\]/g;
+  let execResult = indexPattern.exec(intentPath);
+  while (execResult !== null) {
+    const rawIndex = execResult[1];
+    if (rawIndex === void 0) break;
+    indexes.push(parseInt(rawIndex, 10));
+    execResult = indexPattern.exec(intentPath);
+  }
+  return indexes;
+}
+function deriveRelationPathFromIntentPath(includes, intentPath, fallbackRelation) {
+  if (includes && intentPath) {
+    let current = includes;
+    const path = [];
+    for (const index of parseIntentPathIndexes(intentPath)) {
+      const item = includeNode(current[index]);
+      if (!item) break;
+      const segment = nonEmptyString(item.via) ?? nonEmptyString(item.relation);
+      if (!segment) break;
+      path.push(segment);
+      current = Array.isArray(item.include) ? item.include : [];
+    }
+    if (path.length > 0) return path.join(".");
+  }
+  return nonEmptyString(fallbackRelation);
+}
+function countDistinctRelationPathsByName(usages) {
+  const pathsByRelationName = /* @__PURE__ */ new Map();
+  for (const usage of usages) {
+    const relationName = nonEmptyString(usage.relationName);
+    if (!relationName) continue;
+    const relationPath = nonEmptyString(usage.relationPath) ?? relationName;
+    const paths = pathsByRelationName.get(relationName) ?? /* @__PURE__ */ new Set();
+    paths.add(relationPath);
+    pathsByRelationName.set(relationName, paths);
+  }
+  const counts = /* @__PURE__ */ new Map();
+  for (const [relationName, paths] of pathsByRelationName) {
+    counts.set(relationName, paths.size);
+  }
+  return counts;
+}
+
 // src/dx/result-hydrator.ts
 var COMPOSITE_KEY_SEP = "\0";
+function stringProp(source, key) {
+  const value = source?.[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function resolveJoinIncludePath(planReport, decision) {
+  const context = decision.context;
+  const decisionRecord = decision;
+  const contextRecord = context;
+  const explicitRelationPath = stringProp(decisionRecord, "relationPath") ?? stringProp(contextRecord, "relationPath");
+  if (explicitRelationPath) return explicitRelationPath;
+  const fallbackRelation = stringProp(contextRecord, "relation") ?? stringProp(contextRecord, "includeAlias") ?? stringProp(decisionRecord, "relationName");
+  const intentPath = stringProp(contextRecord, "intentPath");
+  return deriveRelationPathFromIntentPath(
+    Array.isArray(planReport.intent?.include) ? planReport.intent.include : void 0,
+    intentPath,
+    fallbackRelation
+  );
+}
+function lastRelationSegment(path) {
+  const segments = path.split(".");
+  return segments[segments.length - 1] ?? path;
+}
+function resolveJoinRelationName(decision, relationPath) {
+  const context = decision.context;
+  const decisionRecord = decision;
+  return stringProp(context, "relation") ?? stringProp(context, "includeAlias") ?? stringProp(decisionRecord, "relationName") ?? lastRelationSegment(relationPath);
+}
+function collectJoinHydrationInfos(planReport) {
+  const candidates = [];
+  for (const decision of planReport.decisions) {
+    if (decision.type !== "include-strategy" || decision.choice !== "join") {
+      continue;
+    }
+    const relationPath = resolveJoinIncludePath(planReport, decision);
+    if (!relationPath) continue;
+    const relationName = resolveJoinRelationName(decision, relationPath);
+    const decisionRecord = decision;
+    const contextRecord = decision.context;
+    const hydrationPrefix = stringProp(decisionRecord, "hydrationPrefix") ?? stringProp(contextRecord, "hydrationPrefix");
+    candidates.push({
+      relationName,
+      relationPath,
+      ...hydrationPrefix && { hydrationPrefix }
+    });
+  }
+  const pathCountsByRelationName = countDistinctRelationPathsByName(candidates);
+  const infosByPath = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    if (infosByPath.has(candidate.relationPath)) continue;
+    const usesFullPath = (pathCountsByRelationName.get(candidate.relationName) ?? 0) > 1;
+    const keyPrefix = candidate.hydrationPrefix ?? (usesFullPath ? candidate.relationPath : candidate.relationName);
+    if (!keyPrefix) continue;
+    infosByPath.set(candidate.relationPath, {
+      relationPath: candidate.relationPath,
+      segments: candidate.relationPath.split("."),
+      keyPrefix,
+      keyPrefixWithDot: `${keyPrefix}.`
+    });
+  }
+  return [...infosByPath.values()];
+}
+function findLongestJoinInfo(key, infos) {
+  let best;
+  for (const info of infos) {
+    if (!key.startsWith(info.keyPrefixWithDot)) continue;
+    if (!best || info.keyPrefixWithDot.length > best.keyPrefixWithDot.length) {
+      best = info;
+    }
+  }
+  return best;
+}
+function assignNestedValue(target, path, value) {
+  let cursor = target;
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    if (!segment) return;
+    const existing = cursor[segment];
+    if (existing === null) {
+      return;
+    } else if (typeof existing !== "object" || Array.isArray(existing)) {
+      cursor[segment] = {};
+    }
+    cursor = cursor[segment];
+  }
+  const leaf = path[path.length - 1];
+  if (leaf) cursor[leaf] = value;
+}
+function assignColumnValue(target, columnPath, value) {
+  const segments = columnPath.split(".").filter(Boolean);
+  if (segments.length === 0) return;
+  assignNestedValue(target, segments, value);
+}
 var ResultHydrator = class {
   model;
   from;
@@ -6739,51 +6985,42 @@ var ResultHydrator = class {
    * E2E-004: JOIN strategy for to-one relations returns columns like "author.id", "author.name".
    */
   hydrateJoinIncludes(results, planReport) {
-    const joinDecisions = planReport.decisions.filter(
-      (d) => d.type === "include-strategy" && d.choice === "join"
+    const joinInfos = collectJoinHydrationInfos(planReport);
+    if (joinInfos.length === 0) return;
+    const infosByDepth = [...joinInfos].sort(
+      (a, b) => a.segments.length - b.segments.length
     );
-    if (joinDecisions.length === 0) {
-      return;
-    }
-    const joinInfos = joinDecisions.map((d) => d.context?.relation).filter((r) => typeof r === "string").map((relation) => ({ relation, prefix: `${relation}.` }));
-    if (joinInfos.length === 0) {
-      return;
-    }
-    const joinInfosWithCache = joinInfos.map((info) => ({
-      ...info,
-      cachedKeys: null
-    }));
-    if (results.length > 0) {
-      const firstRow = results.find(
-        (r) => typeof r === "object" && r !== null
-      );
-      if (firstRow) {
-        const firstRecord = firstRow;
-        const allKeys = Object.keys(firstRecord);
-        for (const info of joinInfosWithCache) {
-          info.cachedKeys = allKeys.filter((k) => k.startsWith(info.prefix));
-        }
-      }
-    }
     for (const row of results) {
       if (typeof row !== "object" || row === null) {
         continue;
       }
       const record2 = row;
-      for (const info of joinInfosWithCache) {
-        const keys = info.cachedKeys && info.cachedKeys.length > 0 ? info.cachedKeys : Object.keys(record2).filter((k) => k.startsWith(info.prefix));
-        if (keys.length === 0) continue;
-        const nestedObj = {};
-        let allNull = true;
-        for (const key of keys) {
-          const val = record2[key];
-          if (val !== void 0) {
-            nestedObj[key.slice(info.prefix.length)] = val;
-            delete record2[key];
-            if (val !== null) allNull = false;
-          }
+      const valuesByPath = /* @__PURE__ */ new Map();
+      for (const key of Object.keys(record2)) {
+        const info = findLongestJoinInfo(key, joinInfos);
+        if (!info) continue;
+        const value = record2[key];
+        let entry = valuesByPath.get(info.relationPath);
+        if (!entry) {
+          entry = { values: {}, allNull: true };
+          valuesByPath.set(info.relationPath, entry);
         }
-        record2[info.relation] = allNull ? null : nestedObj;
+        assignColumnValue(
+          entry.values,
+          key.slice(info.keyPrefixWithDot.length),
+          value
+        );
+        if (value !== null && value !== void 0) entry.allNull = false;
+        delete record2[key];
+      }
+      for (const info of infosByDepth) {
+        const entry = valuesByPath.get(info.relationPath);
+        if (!entry) continue;
+        assignNestedValue(
+          record2,
+          info.segments,
+          entry.allNull ? null : entry.values
+        );
       }
     }
   }
@@ -11474,6 +11711,7 @@ export {
   composeBeforeMutationHooks,
   composeBeforeQueryHooks,
   composeOnErrorHooks,
+  countDistinctRelationPathsByName,
   createDialectCapabilities,
   createHookManager,
   createNqlTag,
@@ -11486,6 +11724,7 @@ export {
   defineModel,
   defineSchema,
   denseRank,
+  deriveRelationPathFromIntentPath,
   detectForeignKeys,
   detectManyToMany,
   distinct,
@@ -11588,6 +11827,7 @@ export {
   normalizeSchema,
   not,
   notExists,
+  nqlRaw,
   objectToWhereIntent,
   op,
   or,