@dbsp/core 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _dbsp_types from '@dbsp/types';
-import { PseudoColumnMetadata, RecursiveMetadata, RelationIR, RelationKind, AdapterCapabilities, Adapter, BaseAdapter, DDLGeneratingAdapter, ExecutingAdapter, IntrospectingAdapter, RawSqlAdapter, StreamingAdapter, TransactionalAdapter, ColumnType, WhereIntent, OnDeleteAction, ModelIR, DbCasing, QueryIntent, PlanOptions, PlanReport, RecursiveIntent, RecursivePlanOptions, RecursivePlanReport, TableIR, EnumIR, SequenceIR, AmbiguityCheckResult, DialectCapabilities, DDLFeature, DDLFeatureVersionRange, ComparisonOperator, WhereSubqueryIntent, SubqueryRefIntent, WhereAndIntent, WhereAnyIntent, WhereComparisonIntent, WhereRelationFilterIntent, RecursiveExistsOptions, WhereExistsIntent, WhereInIntent, WhereNullIntent, WhereLikeIntent, WhereNotIntent, WhereNotExistsIntent, WhereOrIntent, WhereRawExistsIntent, WhereRawNotExistsIntent, SelectIntent, IncludeIntent, AggregateIntent, OrderByIntent, SortDirection, InsertIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, Dump, SetOperationIntent, LockStrength, LockWaitPolicy, DumpMeta, JoinIntent, UnnestCteIntent, CteQueryIntent, CompileOptions, CompiledQuery, UpsertConflictTarget, UpsertConflictAction, RawCteIntent, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, IndexInfo, ExpressionIntent, WhereExpressionIntent, AggOrderByArg, RelationType as RelationType$1, Cardinality, FeatureWarning, UnsupportedFeatureBehavior, FeatureBehaviorConfig, RangeValue, WhereRangeIntent, SubqueryIncludeInfo } from '@dbsp/types';
+import { PseudoColumnMetadata, RecursiveMetadata, RelationIR, RelationKind, AdapterCapabilities, Adapter, BaseAdapter, DDLGeneratingAdapter, ExecutingAdapter, IntrospectingAdapter, RawSqlAdapter, StreamingAdapter, TransactionalAdapter, ColumnType, WhereIntent, OnDeleteAction, ModelIR, DbCasing, QueryIntent, PlanOptions, PlanReport, RecursiveIntent, RecursivePlanOptions, RecursivePlanReport, TableIR, EnumIR, SequenceIR, AmbiguityCheckResult, DialectCapabilities, DDLFeature, DDLFeatureVersionRange, ComparisonOperator, WhereSubqueryIntent, SubqueryRefIntent, WhereAndIntent, WhereAnyIntent, WhereComparisonIntent, WhereRelationFilterIntent, RecursiveExistsOptions, WhereExistsIntent, WhereInIntent, WhereNullIntent, WhereLikeIntent, WhereNotIntent, WhereNotExistsIntent, WhereOrIntent, WhereRawExistsIntent, WhereRawNotExistsIntent, SelectIntent, IncludeIntent, AggregateIntent, OrderByIntent, SortDirection, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, Dump, SetOperationIntent, LockStrength, LockWaitPolicy, DumpMeta, JoinIntent, UnnestCteIntent, CteQueryIntent, CompileOptions, CompiledQuery, MutationIntent as MutationIntent$1, UpsertConflictTarget, UpsertConflictAction, RawCteIntent, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, IndexInfo, ExpressionIntent, WhereExpressionIntent, AggOrderByArg, RelationType as RelationType$1, Cardinality, FeatureWarning, UnsupportedFeatureBehavior, FeatureBehaviorConfig, RangeValue, WhereRangeIntent, SubqueryIncludeInfo } from '@dbsp/types';
 export { Adapter, AdapterCapabilities, AdapterLogger, AdapterStreamOptions, AdjacencyTraversal, AggregateExpressionIntent, AggregateFunction, AggregateIntent, AggregateWindowFunction, AliasIncludedColumnsMode, AlterColumnOptions, AmbiguityCheckResult, ArrayOperator, BaseAdapter, CTEDefinition, Cardinality, CaseExpressionIntent, CoalesceExpressionIntent, ColumnAliasIntent, ColumnExpressionIntent, ColumnIR, ColumnType, CommonColumnType, ComparisonExpressionIntent, ComparisonOperator, CompileOnlyAdapter, CompileOptions, CompileResultWithIncludes, CompiledQuery, CompilingAdapter, CreateIndexOptions, CustomTraversal, DDLGeneratingAdapter, DbCasing, DecisionType, DeleteIntent, DialectCapabilities, DialectName, DropIndexOptions, DuckDBColumnType, Dump, DumpMeta, EdgeTableTraversal, EmitJoinClause, ExecutingAdapter, ExpressionIntent, FilterStrategy, ForeignKeyIR, IncludeIntent, IncludeStrategy, IndexColumnDef, IndexIR, IndexInfo, IndexMethod, InsertFromIntent, InsertIntent, IntrospectingAdapter, IsTypeSupported, JoinDefault, JoinIntent, LiteralExpressionIntent, LogicalOperator, MSSQLColumnType, ModelIR, MutationIntent, MySQLColumnType, NullOperator, NullsPosition, OffsetWindowFunction, OnDeleteAction, Optionality, OrderByIntent, PartitionIR, PlanDecision, PlanOptions, PlanReport, PlanWarning, PlanWarningCode, PostgresColumnType, PostgresOnlyColumnType, PseudoColumnExpressionIntent, PseudoColumnMetadata, PseudoColumnTraversal, QueryIntent, RangeOperator, RangeValue, RankingWindowFunction, RawExpressionIntent, RawSqlAdapter, RecursiveAdvancedOptions, RecursiveDedupe, RecursiveDirection, RecursiveEmitOptions, RecursiveExistsOptions, RecursiveIntent, RecursiveMetadata, RecursiveNodeIdExpr, RecursivePlanOptions, RecursivePlanReport, RecursiveTrackOptions, RecursiveTraversal, RelationColumnIntent, RelationIR, RelationKind, RelationOperator, RelationType, ResolvedIncludeStrategy, SQLiteColumnType, ScalarSubqueryIntent, SelectAggregateIntent, SelectAllIntent, SelectFieldsIntent, SelectIntent, SelectWithExpressionsIntent, SortDirection, StreamingAdapter, StringOperator, SubqueryIncludeInfo, SubqueryRefIntent, SupportedColumnTypes, TableIR, TransactionalAdapter, TruncateOptions, UpdateIntent, UpsertConflictAction, UpsertConflictTarget, UpsertFromIntent, UpsertIntent, VacuumOptions, WhereAndIntent, WhereAnyIntent, WhereComparisonIntent, WhereExistsIntent, WhereInIntent, WhereIntent, WhereLikeIntent, WhereNotExistsIntent, WhereNotIntent, WhereNullIntent, WhereOrIntent, WhereRangeIntent, WhereRelationFilterIntent, WhereSubqueryIntent, WindowFunction, WindowIntent, WindowOrderBy, getNodeIdAlias, isAdjacencyTraversal, isAggregateWindowFunction, isCoalesceExpression, isColumnAliasExpression, isCustomTraversal, isDeleteIntent, isEdgeTableTraversal, isInsertIntent, isMutationIntent, isRankingWindowFunction, isRawExpression, isRecursiveIntent, isRelationColumnExpression, isSelectAggregate, isSelectAll, isSelectFields, isSelectWithExpressions, isSubqueryRef, isUpdateIntent, isUpsertIntent, isWhereAnd, isWhereAny, isWhereComparison, isWhereExists, isWhereIn, isWhereLike, isWhereLogical, isWhereNot, isWhereNotExists, isWhereNull, isWhereOr, isWhereRange, isWhereRelationBased, isWhereRelationFilter, isWhereSubquery, isWindowIntent } from '@dbsp/types';
 import { NqlCompilerOptions } from '@dbsp/nql';
 import * as v from 'valibot';
@@ -3153,9 +3153,9 @@ type QueryHookContext = {
 };
 /** Union of all mutation intent types */
 /** Union of all mutation intent types */
-type MutationIntent = InsertIntent | UpdateIntent | BatchUpdateIntent | DeleteIntent | UpsertIntent;
+type MutationIntent = InsertIntent | InsertFromIntent | UpdateIntent | BatchUpdateIntent | DeleteIntent | UpsertIntent | UpsertFromIntent;
 /** Mutation operation types */
-type MutationOperation = 'insert' | 'update' | 'batchUpdate' | 'delete' | 'upsert';
+type MutationOperation = 'insert' | 'insert_from' | 'update' | 'batchUpdate' | 'delete' | 'upsert' | 'upsert_from';
 /**
  * Context passed to mutation hooks (beforeMutation/afterMutation).
  * Frozen via Object.freeze — hooks must return new objects to modify.
@@ -4635,12 +4635,9 @@ interface MutationDump {
     /** Bound parameter values */
     readonly parameters: readonly unknown[];
     /** The mutation intent */
-    readonly intent: InsertIntent | UpdateIntent | BatchUpdateIntent | DeleteIntent | UpsertIntent;
+    readonly intent: MutationIntent$1;
     /** Optional metadata */
-    readonly meta?: {
-        readonly schema?: string;
-        readonly compiledAt?: Date;
-    };
+    readonly meta?: DumpMeta;
 }
 /** Shared base options for all mutation builders */
 type MutationBaseOpts = {
@@ -4684,11 +4681,7 @@ declare abstract class MutationBuilderBase<T, TIntent extends InsertIntent | Upd
     protected requireAdapter(operation: string): Adapter;
     dump(extraOptions?: CompileOptions): MutationDump;
     execute(): Promise<T>;
-    private executeWithoutHooks;
-    private executeWithHooks;
-    private executeWithHooksInner;
-    /** Extract cardinality and data from mutation intent */
-    private extractIntentData;
+    private prepareMutationExecution;
 }
 /**
  * Builder for INSERT operations.
@@ -4933,14 +4926,16 @@ declare class UpsertBuilder<T = void> extends MutationBuilderBase<T, UpsertInten
 interface NqlBuilder<T> {
     /** Execute query and return all results */
     all(): Promise<T[]>;
+    /** Execute query or mutation and discard any returned rows */
+    run(): Promise<void>;
     /** Execute query and return first result or null */
     first(): Promise<T | null>;
     /** Get the IntentIR for debugging */
-    toIntentIR(): QueryIntent;
+    toIntentIR(): QueryIntent | MutationIntent$1;
     /** Get the execution plan */
     plan(): PlanReport;
-    /** Get full dump (plan + SQL + params) */
-    dump(meta?: DumpMetaInput): Dump;
+    /** Get full dump. Mutations return MutationDump without a plan. */
+    dump(meta?: DumpMetaInput): Dump | MutationDump;
 }
 /**
  * NQL template tag function type.
@@ -4984,7 +4979,7 @@ declare function nqlRaw(fragment: string): NqlRawFragment;
  * @param schemaName - Optional schema name for multi-tenant queries
  * @returns NQL template tag function
  */
-declare function createNqlTag(schemaDefinition: unknown, model: ModelIR, adapter?: Adapter<unknown>, schemaName?: string): NqlTag;
+declare function createNqlTag(schemaDefinition: unknown, model: ModelIR, adapter?: Adapter<unknown>, schemaName?: string, hookStore?: HookStore, onHookError?: HookErrorHandler, inTransaction?: boolean): NqlTag;
 /**
  * Extract pseudo-column keywords from model configuration.
  * Collects all configured roles and recursive keywords from all tables'

package/dist/index.js

@@ -5453,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;
@@ -5507,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,
@@ -5521,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 {
@@ -5703,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 {
@@ -5858,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 {
@@ -5948,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 {
@@ -6080,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);
   }
 };
 
@@ -6139,6 +6165,19 @@ import {
 } 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;
+  }
+  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");
@@ -6250,7 +6289,7 @@ function assembleNqlTemplate(strings, values) {
     sourceError: findInternalParamSourceError(query, generatedRanges)
   };
 }
-function createNqlTag(schemaDefinition, model, adapter, schemaName) {
+function createNqlTag(schemaDefinition, model, adapter, schemaName, hookStore, onHookError, inTransaction) {
   return function nql(strings, ...values) {
     const assembled = assembleNqlTemplate(strings, values);
     return new NqlBuilderImpl(
@@ -6261,22 +6300,27 @@ function createNqlTag(schemaDefinition, model, adapter, schemaName) {
       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, params, hasBoundParams, sourceError, 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;
@@ -6285,10 +6329,13 @@ var NqlBuilderImpl = class {
     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}`);
@@ -6309,28 +6356,53 @@ var NqlBuilderImpl = class {
       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(
-        "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"
-      );
-    }
-    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 intent = this.compile();
-    return plan(intent, this.model);
+    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() {
     return this.planInternal();
   }
   dump(meta) {
+    const compiledIntent = this.compile();
+    if (compiledIntent.kind === "mutation") {
+      return this.dumpMutation(
+        compiledIntent.bundle,
+        compiledIntent.intent,
+        meta
+      );
+    }
     const planReport = this.planInternal();
     if (!this.adapter) {
       return {
@@ -6340,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) {
@@ -6368,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 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 = this.adapter.compile(planReport);
-    return this.adapter.execute(compiled);
+    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();
@@ -9151,7 +9299,10 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
     schemaDefinition,
     model,
     adapter,
-    schemaName
+    schemaName,
+    hookStore,
+    onHookError,
+    inTransaction
   );
   const mutationOpts = {
     model,