@dbsp/core 1.0.5 → 1.2.0

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,
@@ -5446,6 +5453,122 @@ var LightweightModelIR = class {
 };
 
 // src/dx/mutation-builders.ts
+function compileMutationIntent(adapter, intent, options) {
+  switch (intent.type) {
+    case "insert":
+      return adapter.compileInsert(intent, options);
+    case "insert_from":
+      return adapter.compileInsertFrom(intent, options);
+    case "update":
+      return adapter.compileUpdate(intent, options);
+    case "batchUpdate":
+      return adapter.compileBatchUpdate(intent, options);
+    case "delete":
+      return adapter.compileDelete(intent, options);
+    case "upsert":
+      return adapter.compileUpsert(intent, options);
+    case "upsert_from":
+      return adapter.compileUpsertFrom(intent, options);
+  }
+  const _exhaustive = intent;
+  throw new Error(
+    `Unsupported mutation type: ${_exhaustive.type}`
+  );
+}
+async function runMutationWithHooks(opts) {
+  if (!opts.hookStore || !hasHooks(opts.hookStore)) {
+    const prepared = opts.prepare(opts.intent);
+    return prepared.execute();
+  }
+  return withReentrancyGuard(
+    opts.hookStore,
+    (store) => runMutationWithHooksInner(opts, store)
+  );
+}
+async function runMutationWithHooksInner(opts, store) {
+  const { intent } = opts;
+  const operation = intent.type;
+  const startTime = Date.now();
+  const { cardinality, data } = extractMutationIntentData(intent);
+  let ctx = Object.freeze({
+    table: opts.table,
+    operation,
+    intent,
+    cardinality,
+    data,
+    ...opts.schemaName !== void 0 ? { schemaName: opts.schemaName } : {},
+    ...opts.inTransaction ? { inTransaction: true } : {}
+  });
+  try {
+    if (store.beforeMutation.length > 0) {
+      ctx = await runBeforeMutationHooks(
+        store.beforeMutation,
+        ctx,
+        opts.onHookError
+      );
+    }
+    const prepared = opts.prepare(intent);
+    const duration = Date.now() - startTime;
+    const result = await prepared.execute();
+    if (store.afterMutation.length > 0) {
+      const afterCtx = Object.freeze({
+        ...ctx,
+        sql: prepared.sql,
+        parameters: prepared.parameters,
+        duration
+      });
+      const transformed = await runAfterMutationHooks(
+        store.afterMutation,
+        afterCtx,
+        [...prepared.getAfterMutationResult?.(result) ?? []],
+        opts.onHookError
+      );
+      if (prepared.returnAfterMutationResult) {
+        return transformed;
+      }
+    }
+    return result;
+  } catch (error) {
+    if (store.onError.length > 0) {
+      const errorCtx = {
+        table: opts.table,
+        operation,
+        error,
+        intent,
+        phase: "beforeMutation",
+        ...opts.schemaName !== void 0 ? { schemaName: opts.schemaName } : {}
+      };
+      const transformed = await runOnErrorHooks(store.onError, errorCtx);
+      throw transformed;
+    }
+    throw error;
+  }
+}
+function extractMutationIntentData(intent) {
+  if (intent.type === "insert" || intent.type === "upsert") {
+    const values = intent.values;
+    return {
+      cardinality: values.length > 1 ? "bulk" : "single",
+      data: values.length > 1 ? values : values[0]
+    };
+  }
+  if (intent.type === "update") {
+    return {
+      cardinality: "single",
+      data: intent.set
+    };
+  }
+  if (intent.type === "batchUpdate") {
+    return {
+      cardinality: "bulk",
+      data: intent.updates
+    };
+  }
+  if (intent.type === "insert_from" || intent.type === "upsert_from") {
+    return { cardinality: "bulk", data: void 0 };
+  }
+  return { cardinality: "single", data: void 0 };
+}
 var MutationBuilderBase = class {
   table;
   model;
@@ -5500,11 +5623,15 @@ var MutationBuilderBase = class {
       Object.keys(compileOptions).length > 0 ? compileOptions : void 0
     );
     const meta = {
-      compiledAt: /* @__PURE__ */ new Date()
+      compiledAt: /* @__PURE__ */ new Date(),
+      ...this.schemaName !== void 0 && { schema: this.schemaName },
+      ...extraOptions?.queryName !== void 0 && {
+        queryName: extraOptions.queryName
+      },
+      ...extraOptions?.correlationId !== void 0 && {
+        correlationId: extraOptions.correlationId
+      }
     };
-    if (this.schemaName !== void 0) {
-      meta.schema = this.schemaName;
-    }
     return {
       sql: compiled.sql,
       parameters: compiled.parameters,
@@ -5514,129 +5641,38 @@ var MutationBuilderBase = class {
   }
   async execute() {
     const adapter = this.requireAdapter(this.operationName);
-    if (!this.hookStore || !hasHooks(this.hookStore)) {
-      return this.executeWithoutHooks(adapter);
-    }
-    return this.executeWithHooks(adapter);
-  }
-  async executeWithoutHooks(adapter) {
     const intent = this.buildIntent();
-    const compileOptions = this.schemaName ? { schemaName: this.schemaName } : void 0;
-    const compiled = this.compileIntent(adapter, intent, compileOptions);
-    if (this.returningColumns && this.returningColumns.length > 0) {
-      const result = await adapter.execute(compiled);
-      return result;
-    }
-    await adapter.execute(compiled);
-    return void 0;
-  }
-  async executeWithHooks(adapter) {
-    const store = this.hookStore;
-    if (!store) throw new Error("executeWithHooks called without hookStore");
-    return withReentrancyGuard(
-      store,
-      (s) => this.executeWithHooksInner(adapter, s)
-    );
-  }
-  async executeWithHooksInner(adapter, store) {
-    const intent = this.buildIntent();
-    const operation = intent.type;
-    const startTime = Date.now();
-    const { cardinality, data } = this.extractIntentData(intent);
-    let ctx = Object.freeze({
+    return runMutationWithHooks({
       table: this.table,
-      operation,
       intent,
-      cardinality,
-      data,
-      ...this.schemaName !== void 0 ? { schemaName: this.schemaName } : {},
-      ...this.inTransaction ? { inTransaction: true } : {}
+      hookStore: this.hookStore,
+      onHookError: this.onHookError,
+      schemaName: this.schemaName,
+      inTransaction: this.inTransaction,
+      prepare: (preparedIntent) => this.prepareMutationExecution(adapter, preparedIntent)
     });
-    try {
-      if (store.beforeMutation.length > 0) {
-        ctx = await runBeforeMutationHooks(
-          store.beforeMutation,
-          ctx,
-          this.onHookError
-        );
-      }
-      const compileOptions = this.schemaName ? { schemaName: this.schemaName } : void 0;
-      const compiled = this.compileIntent(adapter, intent, compileOptions);
-      const duration = Date.now() - startTime;
-      if (this.returningColumns && this.returningColumns.length > 0) {
-        const result = await adapter.execute(compiled);
-        const afterCtx = Object.freeze({
-          ...ctx,
-          sql: compiled.sql,
-          parameters: compiled.parameters,
-          duration
-        });
-        if (store.afterMutation.length > 0) {
-          const transformed = await runAfterMutationHooks(
-            store.afterMutation,
-            afterCtx,
-            result,
-            this.onHookError
-          );
-          return transformed;
-        }
-        return result;
-      }
-      await adapter.execute(compiled);
-      if (store.afterMutation.length > 0) {
-        const afterCtx = Object.freeze({
-          ...ctx,
-          sql: compiled.sql,
-          parameters: compiled.parameters,
-          duration
-        });
-        await runAfterMutationHooks(
-          store.afterMutation,
-          afterCtx,
-          [],
-          this.onHookError
-        );
-      }
-      return void 0;
-    } catch (error) {
-      if (store.onError.length > 0) {
-        const errorCtx = {
-          table: this.table,
-          operation,
-          error,
-          intent,
-          phase: "beforeMutation",
-          ...this.schemaName !== void 0 ? { schemaName: this.schemaName } : {}
-        };
-        const transformed = await runOnErrorHooks(store.onError, errorCtx);
-        throw transformed;
-      }
-      throw error;
-    }
   }
-  /** Extract cardinality and data from mutation intent */
-  extractIntentData(intent) {
-    if (intent.type === "insert" || intent.type === "upsert") {
-      const values = intent.values;
-      return {
-        cardinality: values.length > 1 ? "bulk" : "single",
-        data: values.length > 1 ? values : values[0]
-      };
-    }
-    if (intent.type === "update") {
-      return {
-        cardinality: "single",
-        data: intent.set
-      };
-    }
-    if (intent.type === "batchUpdate") {
-      const updates = intent.updates;
+  prepareMutationExecution(adapter, intent) {
+    const compileOptions = this.schemaName ? { schemaName: this.schemaName } : void 0;
+    const compiled = this.compileIntent(adapter, intent, compileOptions);
+    if (this.returningColumns && this.returningColumns.length > 0) {
       return {
-        cardinality: "bulk",
-        data: updates
+        sql: compiled.sql,
+        parameters: compiled.parameters,
+        execute: () => adapter.execute(compiled),
+        getAfterMutationResult: (result) => result,
+        returnAfterMutationResult: true
       };
     }
-    return { cardinality: "single", data: void 0 };
+    return {
+      sql: compiled.sql,
+      parameters: compiled.parameters,
+      execute: async () => {
+        await adapter.execute(compiled);
+        return void 0;
+      },
+      getAfterMutationResult: () => []
+    };
   }
 };
 var InsertBuilder = class _InsertBuilder extends MutationBuilderBase {
@@ -5696,7 +5732,7 @@ var InsertBuilder = class _InsertBuilder extends MutationBuilderBase {
     return intent;
   }
   compileIntent(adapter, intent, options) {
-    return adapter.compileInsert(intent, options);
+    return compileMutationIntent(adapter, intent, options);
   }
 };
 var UpdateBuilder = class _UpdateBuilder extends MutationBuilderBase {
@@ -5851,10 +5887,7 @@ var UpdateBuilder = class _UpdateBuilder extends MutationBuilderBase {
     return intent;
   }
   compileIntent(adapter, intent, options) {
-    if (intent.type === "batchUpdate") {
-      return adapter.compileBatchUpdate(intent, options);
-    }
-    return adapter.compileUpdate(intent, options);
+    return compileMutationIntent(adapter, intent, options);
   }
 };
 var DeleteBuilder = class _DeleteBuilder extends MutationBuilderBase {
@@ -5941,7 +5974,7 @@ var DeleteBuilder = class _DeleteBuilder extends MutationBuilderBase {
     return intent;
   }
   compileIntent(adapter, intent, options) {
-    return adapter.compileDelete(intent, options);
+    return compileMutationIntent(adapter, intent, options);
   }
 };
 var UpsertBuilder = class _UpsertBuilder extends MutationBuilderBase {
@@ -6073,7 +6106,7 @@ var UpsertBuilder = class _UpsertBuilder extends MutationBuilderBase {
     return intent;
   }
   compileIntent(adapter, intent, options) {
-    return adapter.compileUpsert(intent, options);
+    return compileMutationIntent(adapter, intent, options);
   }
 };
 
@@ -6126,80 +6159,192 @@ 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 hasNqlBindings(bundle) {
+  return (bundle.bindings?.size ?? 0) > 0;
+}
+function assertNoMutationBindingBodies(bundle) {
+  const mutationBindings = bundle.mutationBindings;
+  if (!mutationBindings || mutationBindings.size === 0) {
+    return;
   }
-  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;
+  const bindNames = [...mutationBindings.keys()].map((name) => `'${name}'`).join(", ");
+  throw new Error(
+    `NQL tag programs cannot use mutation bodies in | bind clauses (${bindNames}); writable binding CTEs are disabled for tag execution (#173). Use a read-only bind before a single final mutation, or execute the mutation explicitly.`
+  );
+}
+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;
+  }
+  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 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] ?? "");
+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, hookStore, onHookError, inTransaction) {
+  return function nql(strings, ...values) {
+    const assembled = assembleNqlTemplate(strings, values);
     return new NqlBuilderImpl(
-      query,
+      assembled.query,
+      assembled.params,
+      assembled.hasBoundParams,
+      assembled.sourceError,
       schemaDefinition,
       model,
       adapter,
-      schemaName
+      schemaName,
+      hookStore,
+      onHookError,
+      inTransaction
     );
   };
 }
 var NqlBuilderImpl = class {
-  _intent;
+  _compiled;
   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) {
+  hookStore;
+  onHookError;
+  inTransaction;
+  constructor(query, params, hasBoundParams, sourceError, schemaDefinition, model, adapter, schemaName, hookStore, onHookError, inTransaction) {
     this.query = query;
+    this.params = params;
+    this.hasBoundParams = hasBoundParams;
+    this.sourceError = sourceError;
     this.schemaDefinition = schemaDefinition;
     this.model = model;
     this.adapter = adapter;
     this._schemaName = schemaName;
+    this.hookStore = hookStore;
+    this.onHookError = onHookError;
+    this.inTransaction = inTransaction;
   }
   compile() {
-    if (this._intent) {
-      return this._intent;
+    if (this._compiled) {
+      return this._compiled;
+    }
+    if (this.sourceError !== void 0) {
+      throw new Error(`NQL compilation failed: ${this.sourceError}`);
     }
-    const compilerOptions = extractPseudoColumnKeywords(this.model);
+    const compilerOptions = {
+      ...extractPseudoColumnKeywords(this.model) ?? {},
+      params: this.params,
+      [NQL_INTERNAL_COMPILER_OPTIONS]: { allowInternalParams: true }
+    };
     const result = nqlCompile(
       this.query,
       this.schemaDefinition,
@@ -6208,28 +6353,57 @@ var NqlBuilderImpl = class {
     );
     if (!result.success) {
       const errors = result.errors?.map((e) => e.message).join(", ") ?? "Unknown error";
-      throw new Error(`NQL compilation failed: ${errors}`);
-    }
-    if (result.ast?.mutation && !result.ast?.query) {
-      throw new Error(
-        "INSERT/UPDATE/DELETE/UPSERT not yet supported via the nql`...` tagged template. Use orm.insert(table, data) / orm.update(table, set) / orm.delete(table) / orm.upsert(table, data) instead. Tracking: https://github.com/oorabona/db-semantic-planner/issues/113"
-      );
+      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?.query) {
+    const bundle = result.ast;
+    if (!bundle) {
       throw new Error("NQL compilation failed: no query AST produced");
     }
-    this._intent = result.ast.query;
-    return this._intent;
+    assertNoMutationBindingBodies(bundle);
+    if (bundle.query) {
+      this._compiled = {
+        kind: "query",
+        bundle,
+        intent: bundle.query
+      };
+      return this._compiled;
+    }
+    if (bundle.mutation) {
+      this._compiled = {
+        kind: "mutation",
+        bundle,
+        intent: bundle.mutation
+      };
+      return this._compiled;
+    }
+    throw new Error("NQL compilation failed: no query AST produced");
   }
   toIntentIR() {
-    return this.compile();
+    return this.compile().intent;
+  }
+  planInternal() {
+    const compiled = this.compile();
+    if (compiled.kind === "mutation") {
+      throw new Error(
+        "NQL mutations do not have execution plans; use dump() for SQL and parameters."
+      );
+    }
+    return plan(compiled.intent, this.model);
   }
   plan() {
-    const intent = this.compile();
-    return plan(intent, this.model);
+    return this.planInternal();
   }
   dump(meta) {
-    const planReport = this.plan();
+    const compiledIntent = this.compile();
+    if (compiledIntent.kind === "mutation") {
+      return this.dumpMutation(
+        compiledIntent.bundle,
+        compiledIntent.intent,
+        meta
+      );
+    }
+    const planReport = this.planInternal();
     if (!this.adapter) {
       return {
         plan: planReport,
@@ -6238,7 +6412,10 @@ var NqlBuilderImpl = class {
         ...meta !== void 0 && { meta }
       };
     }
-    const compiled = this.adapter.compile(planReport);
+    const compiled = hasNqlBindings(compiledIntent.bundle) ? this.adapter.compile(
+      compiledIntent.bundle,
+      this.nqlBundleCompileOptions()
+    ) : this.adapter.compile(planReport);
     try {
       return this.adapter.createDump(planReport, compiled, meta);
     } catch (err) {
@@ -6266,15 +6443,88 @@ var NqlBuilderImpl = class {
       throw err;
     }
   }
-  async all() {
+  requireAdapter(operation) {
     if (!this.adapter) {
+      throw new ExecutionError({
+        operation,
+        reason: "Adapter not configured",
+        fix: "Pass adapter option when creating ORM: createOrm({ model, adapter })"
+      });
+    }
+    return this.adapter;
+  }
+  mutationCompileOptions(extraOptions) {
+    return {
+      model: this.model,
+      ...this._schemaName !== void 0 && { schemaName: this._schemaName },
+      ...extraOptions
+    };
+  }
+  nqlBundleCompileOptions() {
+    return {
+      model: this.model,
+      ...this._schemaName !== void 0 && { schemaName: this._schemaName }
+    };
+  }
+  dumpMutation(bundle, intent, meta) {
+    const adapter = this.requireAdapter("dump");
+    const compiled = adapter.compile(bundle, this.mutationCompileOptions(meta));
+    const dumpMeta = {
+      compiledAt: /* @__PURE__ */ new Date(),
+      ...this._schemaName !== void 0 && { schema: this._schemaName },
+      ...meta?.queryName !== void 0 && { queryName: meta.queryName },
+      ...meta?.correlationId !== void 0 && {
+        correlationId: meta.correlationId
+      }
+    };
+    return {
+      sql: compiled.sql,
+      parameters: compiled.parameters,
+      intent,
+      meta: dumpMeta
+    };
+  }
+  async all() {
+    const adapter = this.adapter;
+    if (!adapter) {
       throw new Error(
         "Cannot execute query: no adapter configured. Pass an adapter to createOrm() or use .toIntentIR() / .plan() for debugging."
       );
     }
-    const planReport = this.plan();
-    const compiled = this.adapter.compile(planReport);
-    return this.adapter.execute(compiled);
+    const compiledIntent = this.compile();
+    if (compiledIntent.kind === "mutation") {
+      const hasReturning = (compiledIntent.intent.returning?.length ?? 0) > 0;
+      return runMutationWithHooks({
+        table: compiledIntent.intent.table,
+        intent: compiledIntent.intent,
+        hookStore: this.hookStore,
+        onHookError: this.onHookError,
+        schemaName: this._schemaName,
+        inTransaction: this.inTransaction,
+        prepare: () => {
+          const compiled2 = adapter.compile(
+            compiledIntent.bundle,
+            this.mutationCompileOptions()
+          );
+          return {
+            sql: compiled2.sql,
+            parameters: compiled2.parameters,
+            execute: () => adapter.execute(compiled2),
+            getAfterMutationResult: (result) => hasReturning ? result : [],
+            returnAfterMutationResult: hasReturning
+          };
+        }
+      });
+    }
+    const planReport = this.planInternal();
+    const compiled = hasNqlBindings(compiledIntent.bundle) ? adapter.compile(
+      compiledIntent.bundle,
+      this.nqlBundleCompileOptions()
+    ) : adapter.compile(planReport);
+    return adapter.execute(compiled);
+  }
+  async run() {
+    await this.all();
   }
   async first() {
     const rows = await this.all();
@@ -6661,8 +6911,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 +7133,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
+        );
       }
     }
   }
@@ -8914,7 +9299,10 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
     schemaDefinition,
     model,
     adapter,
-    schemaName
+    schemaName,
+    hookStore,
+    onHookError,
+    inTransaction
   );
   const mutationOpts = {
     model,
@@ -11474,6 +11862,7 @@ export {
   composeBeforeMutationHooks,
   composeBeforeQueryHooks,
   composeOnErrorHooks,
+  countDistinctRelationPathsByName,
   createDialectCapabilities,
   createHookManager,
   createNqlTag,
@@ -11486,6 +11875,7 @@ export {
   defineModel,
   defineSchema,
   denseRank,
+  deriveRelationPathFromIntentPath,
   detectForeignKeys,
   detectManyToMany,
   distinct,
@@ -11588,6 +11978,7 @@ export {
   normalizeSchema,
   not,
   notExists,
+  nqlRaw,
   objectToWhereIntent,
   op,
   or,