@dbsp/core 1.1.0 → 1.3.0

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 prepared.mapAfterMutationResult?.(result, transformed) ?? 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,63 @@ 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 isBindingFinalQuery(bundle) {
+  return bundle.query !== void 0 && (bundle.bindings?.has(bundle.query.from) ?? false);
+}
+function formatBindingRelationPath(path) {
+  return typeof path === "string" ? path : path.join(".");
+}
+function findBindingFinalRelationFilter(where) {
+  switch (where.kind) {
+    case "and":
+    case "or":
+      for (const condition of where.conditions) {
+        const found = findBindingFinalRelationFilter(condition);
+        if (found !== void 0) return found;
+      }
+      return void 0;
+    case "not":
+      return findBindingFinalRelationFilter(where.condition);
+    case "relationFilter":
+      return formatBindingRelationPath(where.relation);
+    case "exists":
+    case "notExists":
+      return where.relation;
+    case "rawExists":
+    case "rawNotExists":
+      return "raw EXISTS";
+    default:
+      return void 0;
+  }
+}
+function assertBindingFinalQueryCanUseSyntheticPlan(intent) {
+  const relationColumns = intent.select?.type === "expressions" ? intent.select.columns.filter((column) => column.kind === "relationColumn").map((column) => column.relation) : [];
+  const relationFilter = intent.where ? findBindingFinalRelationFilter(intent.where) : void 0;
+  const havingRelationFilter = intent.having ? findBindingFinalRelationFilter(intent.having) : void 0;
+  if ((intent.include?.length ?? 0) > 0 || relationColumns.length > 0 || (intent.joins?.length ?? 0) > 0 || relationFilter !== void 0 || havingRelationFilter !== void 0) {
+    throw new Error(
+      `NQL binding-final query '${intent.from}' cannot select relation columns, use includes, joins, or relation filters. Relation planning requires a physical model table, not a CTE binding.`
+    );
+  }
+}
+function createBindingFinalPlan(intent) {
+  assertBindingFinalQueryCanUseSyntheticPlan(intent);
+  return {
+    rootTable: intent.from,
+    decisions: [],
+    warnings: [],
+    ctes: [],
+    intent,
+    metadata: {
+      planningTimeMs: 0,
+      relationsAnalyzed: 0,
+      isAmbiguous: false
+    }
+  };
+}
 function nqlRaw(fragment) {
   if (typeof fragment !== "string") {
     throw new TypeError("nqlRaw() expects a string fragment");
@@ -6250,7 +6333,250 @@ function assembleNqlTemplate(strings, values) {
     sourceError: findInternalParamSourceError(query, generatedRanges)
   };
 }
-function createNqlTag(schemaDefinition, model, adapter, schemaName) {
+function hasMutationBindingBodies(bundle) {
+  return (bundle.mutationBindings?.size ?? 0) > 0;
+}
+function requireMutationBindingColumns(bundle, bindName) {
+  const columns = bundle.bindingOutputSchemas?.get(bindName)?.columns;
+  if (columns === void 0 || columns.length === 0) {
+    throw new Error(
+      `NQL mutation binding '${bindName}' cannot be materialized because its projected column schema is unavailable.`
+    );
+  }
+  return columns;
+}
+function toSnakeCaseIdentifier(identifier) {
+  if (!identifier) return identifier;
+  const leadingUnderscores = identifier.match(/^_+/)?.[0] ?? "";
+  const rest = identifier.slice(leadingUnderscores.length);
+  if (!rest) return identifier;
+  const snakeCase = rest.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").toLowerCase();
+  return leadingUnderscores + snakeCase;
+}
+function toDatabaseColumnName(column, dbCasing) {
+  return dbCasing === "snake_case" ? toSnakeCaseIdentifier(column) : column;
+}
+function toRuntimeBindingRow(bindName, row, columns, dbCasing) {
+  if (typeof row !== "object" || row === null || Array.isArray(row)) {
+    throw new Error(
+      `NQL mutation binding '${bindName}' returned a non-object row; runtime VALUES materialization requires object rows keyed by projected column name.`
+    );
+  }
+  const source = row;
+  const materialized = {};
+  for (const column of columns) {
+    const dbColumn = toDatabaseColumnName(column, dbCasing);
+    const sourceColumn = Object.hasOwn(source, column) ? column : dbColumn !== column && Object.hasOwn(source, dbColumn) ? dbColumn : void 0;
+    if (sourceColumn === void 0) {
+      throw new Error(
+        `NQL mutation binding '${bindName}' returned a row without projected column '${column}'.`
+      );
+    }
+    materialized[column] = source[sourceColumn];
+  }
+  return materialized;
+}
+function createRuntimeBinding(bundle, bindName, rows, dbCasing) {
+  const columns = requireMutationBindingColumns(bundle, bindName);
+  return {
+    columns,
+    rows: rows.map(
+      (row) => toRuntimeBindingRow(bindName, row, columns, dbCasing)
+    )
+  };
+}
+function bindingEntryIsFinal(compiledIntent, bindName, boundQuery, sourceBundle) {
+  if (compiledIntent.kind === "query") {
+    return boundQuery === compiledIntent.intent;
+  }
+  return sourceBundle.mutationBindings?.get(bindName) === compiledIntent.intent;
+}
+function orderedSequenceStepToProgramStep(step) {
+  const dependencyStep = step;
+  if (step.kind === "query") {
+    return {
+      kind: "query",
+      intent: step.query,
+      ...step.bindName !== void 0 && { bindName: step.bindName },
+      final: step.final,
+      ...dependencyStep.bindingDependencies !== void 0 && {
+        bindingDependencies: dependencyStep.bindingDependencies
+      }
+    };
+  }
+  return {
+    kind: "mutation",
+    intent: step.mutation,
+    ...step.bindName !== void 0 && { bindName: step.bindName },
+    final: step.final,
+    ...dependencyStep.bindingDependencies !== void 0 && {
+      bindingDependencies: dependencyStep.bindingDependencies
+    }
+  };
+}
+function snapshotMutationRows(rows) {
+  return rows.map((row) => {
+    if (Array.isArray(row)) {
+      return [...row];
+    }
+    if (row !== null && typeof row === "object") {
+      return { ...row };
+    }
+    return row;
+  });
+}
+function assertNqlProgramSteps(compiledIntent, steps) {
+  if (steps.length === 0) {
+    throw new Error("NQL program sequence did not contain any statements.");
+  }
+  const finalIndexes = steps.map((step, index) => step.final ? index : -1).filter((index) => index !== -1);
+  if (finalIndexes.length !== 1 || finalIndexes[0] !== steps.length - 1) {
+    throw new Error(
+      "NQL program sequence must contain exactly one final statement at the end."
+    );
+  }
+  const finalStep = steps.at(-1);
+  if (finalStep === void 0) {
+    throw new Error("NQL program sequence did not contain a final statement.");
+  }
+  if (finalStep.kind !== compiledIntent.kind || finalStep.intent !== compiledIntent.intent) {
+    throw new Error(
+      "NQL program sequence final statement does not match the compiled NQL result."
+    );
+  }
+  const seenBindNames = /* @__PURE__ */ new Set();
+  for (const step of steps) {
+    if (step.bindName === void 0) continue;
+    if (seenBindNames.has(step.bindName)) {
+      throw new Error(
+        `NQL program sequence contains duplicate binding '${step.bindName}'.`
+      );
+    }
+    seenBindNames.add(step.bindName);
+    if (!(compiledIntent.bundle.bindings?.has(step.bindName) ?? false)) {
+      throw new Error(
+        `NQL program sequence references unknown binding '${step.bindName}'.`
+      );
+    }
+  }
+}
+function createNqlProgramSteps(compiledIntent) {
+  const sourceBundle = compiledIntent.bundle;
+  if (sourceBundle.nqlProgramSequence !== void 0) {
+    const steps2 = sourceBundle.nqlProgramSequence.map(
+      orderedSequenceStepToProgramStep
+    );
+    assertNqlProgramSteps(compiledIntent, steps2);
+    return steps2;
+  }
+  const bindingEntries = [...sourceBundle.bindings ?? /* @__PURE__ */ new Map()];
+  const steps = bindingEntries.map(
+    ([bindName, boundQuery]) => {
+      const boundMutation = sourceBundle.mutationBindings?.get(bindName);
+      if (boundMutation !== void 0) {
+        return {
+          kind: "mutation",
+          intent: boundMutation,
+          bindName,
+          final: false
+        };
+      }
+      return {
+        kind: "query",
+        intent: boundQuery,
+        bindName,
+        final: false
+      };
+    }
+  );
+  const lastBindingEntry = bindingEntries.at(-1);
+  const finalIsBound = lastBindingEntry !== void 0 && bindingEntryIsFinal(
+    compiledIntent,
+    lastBindingEntry[0],
+    lastBindingEntry[1],
+    sourceBundle
+  );
+  if (finalIsBound) {
+    const lastStep = steps.at(-1);
+    if (lastStep === void 0) return steps;
+    steps[steps.length - 1] = { ...lastStep, final: true };
+    return steps;
+  }
+  if (compiledIntent.kind === "query") {
+    steps.push({
+      kind: "query",
+      intent: compiledIntent.intent,
+      final: true
+    });
+  } else {
+    steps.push({
+      kind: "mutation",
+      intent: compiledIntent.intent,
+      final: true
+    });
+  }
+  assertNqlProgramSteps(compiledIntent, steps);
+  return steps;
+}
+function renumberDumpSqlParams(sql2, offset) {
+  if (offset === 0) return sql2;
+  return sql2.replace(/\$(\d+)/g, (_match, num) => {
+    return `$${Number.parseInt(num, 10) + offset}`;
+  });
+}
+function joinDumpSequenceSql(sequence) {
+  let parameterOffset = 0;
+  return sequence.map((step) => {
+    const sql2 = renumberDumpSqlParams(step.sql, parameterOffset);
+    parameterOffset += step.params.length;
+    return sql2;
+  }).join(";\n");
+}
+function flattenDumpSequenceParams(sequence) {
+  return sequence.flatMap((step) => [...step.params]);
+}
+function filterMapByBindingDependencies(source, bindingDependencies) {
+  if (source === void 0) return /* @__PURE__ */ new Map();
+  if (bindingDependencies === void 0) return new Map(source);
+  const filtered = /* @__PURE__ */ new Map();
+  for (const bindName of bindingDependencies) {
+    const value = source.get(bindName);
+    if (value !== void 0) {
+      filtered.set(bindName, value);
+    }
+  }
+  return filtered;
+}
+function filterOptionalMapByBindingDependencies(source, bindingDependencies) {
+  const filtered = filterMapByBindingDependencies(source, bindingDependencies);
+  return filtered.size > 0 ? filtered : void 0;
+}
+function filterMapByRuntimeBindingDependencies(source, runtimeSourceBindings, bindingDependencies) {
+  if (source === void 0) return /* @__PURE__ */ new Map();
+  if (bindingDependencies === void 0 || runtimeSourceBindings === void 0 || runtimeSourceBindings.size === 0) {
+    return new Map(source);
+  }
+  const dependencies = new Set(bindingDependencies);
+  const filtered = /* @__PURE__ */ new Map();
+  for (const [bindName, value] of source) {
+    if (!runtimeSourceBindings.has(bindName) || dependencies.has(bindName)) {
+      filtered.set(bindName, value);
+    }
+  }
+  return filtered;
+}
+function filterOptionalMapByNames(source, names) {
+  if (source === void 0) return void 0;
+  const filtered = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const value = source.get(name);
+    if (value !== void 0) {
+      filtered.set(name, value);
+    }
+  }
+  return filtered.size > 0 ? filtered : void 0;
+}
+function createNqlTag(_schemaDefinition, model, adapter, schemaName, hookStore, onHookError, inTransaction) {
   return function nql(strings, ...values) {
     const assembled = assembleNqlTemplate(strings, values);
     return new NqlBuilderImpl(
@@ -6258,37 +6584,42 @@ function createNqlTag(schemaDefinition, model, adapter, schemaName) {
       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, params, hasBoundParams, sourceError, schemaDefinition, model, adapter, schemaName) {
+  hookStore;
+  onHookError;
+  inTransaction;
+  constructor(query, params, hasBoundParams, sourceError, 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}`);
@@ -6300,7 +6631,7 @@ var NqlBuilderImpl = class {
     };
     const result = nqlCompile(
       this.query,
-      this.schemaDefinition,
+      this.model,
       void 0,
       compilerOptions
     );
@@ -6309,29 +6640,63 @@ 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;
+    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();
+    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 isBindingFinalQuery(compiled.bundle) ? createBindingFinalPlan(compiled.intent) : this.planInternal();
   }
   dump(meta) {
-    const planReport = this.planInternal();
+    const compiledIntent = this.compile();
+    if (hasMutationBindingBodies(compiledIntent.bundle)) {
+      return this.dumpNqlProgramSequence(compiledIntent, meta);
+    }
+    if (compiledIntent.kind === "mutation") {
+      return this.dumpMutation(
+        this.createFinalNqlStatementBundle(compiledIntent),
+        compiledIntent.intent,
+        meta
+      );
+    }
+    const bindingFinalQuery = isBindingFinalQuery(compiledIntent.bundle);
+    const planReport = bindingFinalQuery ? createBindingFinalPlan(compiledIntent.intent) : this.planInternal();
     if (!this.adapter) {
       return {
         plan: planReport,
@@ -6340,7 +6705,8 @@ var NqlBuilderImpl = class {
         ...meta !== void 0 && { meta }
       };
     }
-    const compiled = this.adapter.compile(planReport);
+    const finalBundle = this.createFinalNqlStatementBundle(compiledIntent);
+    const compiled = bindingFinalQuery || hasNqlBindings(finalBundle) ? this.adapter.compile(finalBundle, this.nqlBundleCompileOptions()) : this.adapter.compile(planReport);
     try {
       return this.adapter.createDump(planReport, compiled, meta);
     } catch (err) {
@@ -6368,15 +6734,342 @@ 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 }
+    };
+  }
+  createNqlStatementBundle(statement, bindings, runtimeBindings, sourceBundle, bindingDependencies) {
+    const statementBindings = filterMapByRuntimeBindingDependencies(
+      bindings,
+      sourceBundle.mutationBindings,
+      bindingDependencies
+    );
+    const statementRuntimeBindings = filterMapByBindingDependencies(
+      runtimeBindings,
+      bindingDependencies
+    );
+    const emittedBindingNames = /* @__PURE__ */ new Set([
+      ...statementBindings.keys(),
+      ...statementRuntimeBindings.keys()
+    ]);
+    const statementBindingOutputSchemas = filterOptionalMapByNames(
+      sourceBundle.bindingOutputSchemas,
+      emittedBindingNames
+    );
+    const statementMutationBindings = filterOptionalMapByBindingDependencies(
+      sourceBundle.mutationBindings,
+      bindingDependencies
+    );
+    return {
+      ...statement,
+      ...statementBindings.size > 0 && { bindings: statementBindings },
+      ...statementBindingOutputSchemas !== void 0 && {
+        bindingOutputSchemas: statementBindingOutputSchemas
+      },
+      ...statementMutationBindings !== void 0 && {
+        mutationBindings: statementMutationBindings
+      },
+      ...statementRuntimeBindings.size > 0 && {
+        runtimeBindings: statementRuntimeBindings
+      }
+    };
+  }
+  createFinalNqlStatementBundle(compiledIntent) {
+    const finalStep = createNqlProgramSteps(compiledIntent).at(-1);
+    if (compiledIntent.kind === "query") {
+      return this.createNqlStatementBundle(
+        { query: compiledIntent.intent },
+        compiledIntent.bundle.bindings ?? /* @__PURE__ */ new Map(),
+        compiledIntent.bundle.runtimeBindings ?? /* @__PURE__ */ new Map(),
+        compiledIntent.bundle,
+        finalStep?.bindingDependencies
+      );
+    }
+    return this.createNqlStatementBundle(
+      { mutation: compiledIntent.intent },
+      compiledIntent.bundle.bindings ?? /* @__PURE__ */ new Map(),
+      compiledIntent.bundle.runtimeBindings ?? /* @__PURE__ */ new Map(),
+      compiledIntent.bundle,
+      finalStep?.bindingDependencies
+    );
+  }
+  runMutationStatement(adapter, bundle, intent, inTransaction) {
+    const hasReturning = (intent.returning?.length ?? 0) > 0;
+    return runMutationWithHooks({
+      table: intent.table,
+      intent,
+      hookStore: this.hookStore,
+      onHookError: this.onHookError,
+      schemaName: this._schemaName,
+      inTransaction,
+      prepare: () => {
+        const compiled = adapter.compile(
+          bundle,
+          this.mutationCompileOptions()
+        );
+        return {
+          sql: compiled.sql,
+          parameters: compiled.parameters,
+          execute: async () => {
+            const hookRows = await adapter.execute(compiled);
+            const rawRows = snapshotMutationRows(hookRows);
+            return {
+              rawRows,
+              hookRows,
+              transformedRows: hookRows
+            };
+          },
+          getAfterMutationResult: (result) => hasReturning ? result.hookRows : [],
+          mapAfterMutationResult: (result, transformedRows) => ({
+            rawRows: result.rawRows,
+            hookRows: result.hookRows,
+            transformedRows: [...transformedRows]
+          }),
+          returnAfterMutationResult: hasReturning
+        };
+      }
+    });
+  }
+  async executeNqlProgramSequence(compiledIntent, adapter) {
+    if (!supportsTransactions(adapter)) {
+      throw new ExecutionError({
+        operation: "nql",
+        reason: "NQL programs with mutation bindings require adapter transaction support",
+        fix: "Use an adapter that implements transaction(fn), such as the PostgreSQL adapter."
+      });
+    }
+    return adapter.transaction(async (txAdapter) => {
+      const sourceBundle = compiledIntent.bundle;
+      const priorBindings = /* @__PURE__ */ new Map();
+      const runtimeBindings = /* @__PURE__ */ new Map();
+      const steps = createNqlProgramSteps(compiledIntent);
+      let finalRows = [];
+      for (const step of steps) {
+        if (step.kind === "mutation") {
+          if ((step.intent.returning?.length ?? 0) === 0 && step.bindName) {
+            throw new Error(
+              `NQL mutation binding '${step.bindName}' cannot execute without a RETURNING projection.`
+            );
+          }
+          const statementBundle = this.createNqlStatementBundle(
+            { mutation: step.intent },
+            priorBindings,
+            runtimeBindings,
+            sourceBundle,
+            step.bindingDependencies
+          );
+          const rows = await this.runMutationStatement(
+            txAdapter,
+            statementBundle,
+            step.intent,
+            true
+          );
+          if (step.bindName) {
+            runtimeBindings.set(
+              step.bindName,
+              createRuntimeBinding(
+                sourceBundle,
+                step.bindName,
+                rows.rawRows,
+                txAdapter.dbCasing
+              )
+            );
+          }
+          if (step.final) {
+            finalRows = rows.transformedRows;
+          }
+        } else if (step.final) {
+          const statementBundle = this.createNqlStatementBundle(
+            { query: step.intent },
+            priorBindings,
+            runtimeBindings,
+            sourceBundle,
+            step.bindingDependencies
+          );
+          const compiled = txAdapter.compile(
+            statementBundle,
+            this.nqlBundleCompileOptions()
+          );
+          finalRows = await txAdapter.execute(compiled);
+        }
+        if (step.bindName) {
+          const boundQuery = sourceBundle.bindings?.get(step.bindName);
+          if (boundQuery !== void 0) {
+            priorBindings.set(step.bindName, boundQuery);
+          }
+        }
+      }
+      return finalRows;
+    });
+  }
+  dumpNqlProgramSequence(compiledIntent, meta) {
+    const adapter = this.requireAdapter("dump");
+    const sourceBundle = compiledIntent.bundle;
+    const priorBindings = /* @__PURE__ */ new Map();
+    const runtimeBindings = /* @__PURE__ */ new Map();
+    const sequence = [];
+    const steps = createNqlProgramSteps(compiledIntent);
+    for (const step of steps) {
+      if (step.kind === "mutation") {
+        const statementBundle = this.createNqlStatementBundle(
+          { mutation: step.intent },
+          priorBindings,
+          runtimeBindings,
+          sourceBundle,
+          step.bindingDependencies
+        );
+        const compiled = adapter.compile(
+          statementBundle,
+          this.mutationCompileOptions()
+        );
+        sequence.push({
+          kind: "mutation",
+          ...step.bindName !== void 0 && { bindName: step.bindName },
+          sql: compiled.sql,
+          params: compiled.parameters
+        });
+        if (step.bindName !== void 0) {
+          runtimeBindings.set(step.bindName, {
+            columns: requireMutationBindingColumns(sourceBundle, step.bindName),
+            rows: []
+          });
+        }
+      } else {
+        const statementBundle = this.createNqlStatementBundle(
+          { query: step.intent },
+          priorBindings,
+          runtimeBindings,
+          sourceBundle,
+          step.bindingDependencies
+        );
+        const compiled = adapter.compile(
+          statementBundle,
+          this.nqlBundleCompileOptions()
+        );
+        sequence.push({
+          kind: "query",
+          ...step.bindName !== void 0 && { bindName: step.bindName },
+          sql: compiled.sql,
+          params: compiled.parameters
+        });
+      }
+      if (step.bindName !== void 0) {
+        const boundQuery = sourceBundle.bindings?.get(step.bindName);
+        if (boundQuery !== void 0) {
+          priorBindings.set(step.bindName, boundQuery);
+        }
+      }
+    }
+    const finalStep = steps.at(-1);
+    if (finalStep?.kind === "query") {
+      const planReport = isBindingFinalQuery(compiledIntent.bundle) ? createBindingFinalPlan(finalStep.intent) : this.planInternal();
+      const dumpMeta2 = {
+        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 {
+        plan: planReport,
+        sql: joinDumpSequenceSql(sequence),
+        params: flattenDumpSequenceParams(sequence),
+        meta: dumpMeta2,
+        sequence
+      };
+    }
+    if (finalStep?.kind !== "mutation") {
+      throw new Error(
+        "NQL program sequence did not contain a final statement."
+      );
+    }
+    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: joinDumpSequenceSql(sequence),
+      parameters: flattenDumpSequenceParams(sequence),
+      intent: finalStep.intent,
+      meta: dumpMeta,
+      sequence
+    };
+  }
+  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 (hasMutationBindingBodies(compiledIntent.bundle)) {
+      return this.executeNqlProgramSequence(compiledIntent, adapter);
+    }
+    if (compiledIntent.kind === "mutation") {
+      return (await this.runMutationStatement(
+        adapter,
+        this.createFinalNqlStatementBundle(compiledIntent),
+        compiledIntent.intent,
+        this.inTransaction
+      )).transformedRows;
+    }
+    if (isBindingFinalQuery(compiledIntent.bundle)) {
+      const compiled2 = adapter.compile(
+        this.createFinalNqlStatementBundle(compiledIntent),
+        this.nqlBundleCompileOptions()
+      );
+      return adapter.execute(compiled2);
+    }
     const planReport = this.planInternal();
-    const compiled = this.adapter.compile(planReport);
-    return this.adapter.execute(compiled);
+    const finalBundle = this.createFinalNqlStatementBundle(compiledIntent);
+    const compiled = hasNqlBindings(finalBundle) ? adapter.compile(finalBundle, this.nqlBundleCompileOptions()) : adapter.compile(planReport);
+    return adapter.execute(compiled);
+  }
+  async run() {
+    await this.all();
   }
   async first() {
     const rows = await this.all();
@@ -9151,7 +9844,10 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
     schemaDefinition,
     model,
     adapter,
-    schemaName
+    schemaName,
+    hookStore,
+    onHookError,
+    inTransaction
   );
   const mutationOpts = {
     model,
@@ -10271,6 +10967,8 @@ var POSTGRESQL_CAPABILITIES = {
   supportsJsonType: true,
   supportsJsonOperators: true,
   // PG: ->, ->>, @>, <@, ?, #>, #>>
+  supportsRowLevelLocks: true,
+  supportsLockWaitPolicies: true,
   supportsSchemas: true,
   // Include Strategy Capabilities (CORE-006)
   supportsLateralJoin: true,
@@ -10315,6 +11013,9 @@ var MYSQL_CAPABILITIES = {
   supportsJsonType: true,
   supportsJsonOperators: false,
   // MySQL uses JSON_EXTRACT() functions, not operators
+  // Coarse PostgreSQL-shaped lock flags; revisit MySQL with per-strength caps.
+  supportsRowLevelLocks: false,
+  supportsLockWaitPolicies: false,
   supportsSchemas: true,
   // MySQL uses database as schema
   // Include Strategy Capabilities (CORE-006)
@@ -10345,6 +11046,8 @@ var SQLITE_CAPABILITIES = {
   // SQLite 3.38+ (JSON1 extension)
   supportsJsonOperators: false,
   // SQLite uses json_extract() functions
+  supportsRowLevelLocks: false,
+  supportsLockWaitPolicies: false,
   supportsSchemas: false,
   // SQLite uses ATTACH for multiple databases
   // Include Strategy Capabilities (CORE-006)
@@ -10373,6 +11076,8 @@ var DUCKDB_CAPABILITIES = {
   supportsJsonType: true,
   supportsJsonOperators: false,
   // DuckDB uses json_extract() style
+  supportsRowLevelLocks: false,
+  supportsLockWaitPolicies: false,
   supportsSchemas: true,
   // Include Strategy Capabilities (CORE-006)
   supportsLateralJoin: true,
@@ -10402,6 +11107,9 @@ var MSSQL_CAPABILITIES = {
   // SQL Server 2016+
   supportsJsonOperators: false,
   // MSSQL uses JSON_VALUE/JSON_QUERY functions
+  // Coarse PostgreSQL-shaped lock flags; revisit MSSQL hints with per-strength caps.
+  supportsRowLevelLocks: false,
+  supportsLockWaitPolicies: false,
   supportsSchemas: true,
   // Include Strategy Capabilities (CORE-006)
   supportsLateralJoin: true,
@@ -10459,6 +11167,8 @@ function createDialectCapabilities(overrides, options) {
     supportsRangeTypes: false,
     supportsJsonType: false,
     supportsJsonOperators: false,
+    supportsRowLevelLocks: false,
+    supportsLockWaitPolicies: false,
     supportsSchemas: false,
     supportsLateralJoin: false,
     supportsJsonAgg: false,