@dbsp/core 1.2.0 → 1.4.0

package/dist/index.js

@@ -5524,7 +5524,7 @@ async function runMutationWithHooksInner(opts, store) {
         opts.onHookError
       );
       if (prepared.returnAfterMutationResult) {
-        return transformed;
+        return prepared.mapAfterMutationResult?.(result, transformed) ?? transformed;
       }
     }
     return result;
@@ -6163,20 +6163,77 @@ import {
   NqlLexer,
   compile as nqlCompile
 } from "@dbsp/nql";
-import { NQL_INTERNAL_COMPILER_OPTIONS } from "@dbsp/types/internal";
+import {
+  getTrustedNqlRelationFilterFields,
+  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;
+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":
+      if (getTrustedNqlRelationFilterFields(where) !== void 0) {
+        return void 0;
+      }
+      return formatBindingRelationPath(where.relation);
+    case "exists":
+    case "notExists":
+      return where.relation;
+    case "rawExists":
+    case "rawNotExists":
+      return "raw EXISTS";
+    default:
+      return void 0;
   }
-  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 assertBindingFinalQueryCanUseSyntheticPlan(intent) {
+  const relationColumns = intent.select?.type === "expressions" ? intent.select.columns.flatMap((column) => {
+    if (column.kind !== "relationColumn") return [];
+    const trusted = getTrustedNqlRelationFilterFields(column);
+    if (trusted?.selectedColumn !== void 0 && trusted.cardinality === "one") {
+      return [];
+    }
+    return [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") {
@@ -6289,7 +6346,250 @@ function assembleNqlTemplate(strings, values) {
     sourceError: findInternalParamSourceError(query, generatedRanges)
   };
 }
-function createNqlTag(schemaDefinition, model, adapter, schemaName, hookStore, onHookError, inTransaction) {
+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(
@@ -6297,7 +6597,6 @@ function createNqlTag(schemaDefinition, model, adapter, schemaName, hookStore, o
       assembled.params,
       assembled.hasBoundParams,
       assembled.sourceError,
-      schemaDefinition,
       model,
       adapter,
       schemaName,
@@ -6313,19 +6612,17 @@ var NqlBuilderImpl = class {
   params;
   hasBoundParams;
   sourceError;
-  schemaDefinition;
   model;
   _schemaName;
   adapter;
   hookStore;
   onHookError;
   inTransaction;
-  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;
@@ -6347,7 +6644,7 @@ var NqlBuilderImpl = class {
     };
     const result = nqlCompile(
       this.query,
-      this.schemaDefinition,
+      this.model,
       void 0,
       compilerOptions
     );
@@ -6360,7 +6657,6 @@ var NqlBuilderImpl = class {
     if (!bundle) {
       throw new Error("NQL compilation failed: no query AST produced");
     }
-    assertNoMutationBindingBodies(bundle);
     if (bundle.query) {
       this._compiled = {
         kind: "query",
@@ -6392,18 +6688,28 @@ var NqlBuilderImpl = class {
     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 compiledIntent = this.compile();
+    if (hasMutationBindingBodies(compiledIntent.bundle)) {
+      return this.dumpNqlProgramSequence(compiledIntent, meta);
+    }
     if (compiledIntent.kind === "mutation") {
       return this.dumpMutation(
-        compiledIntent.bundle,
+        this.createFinalNqlStatementBundle(compiledIntent),
         compiledIntent.intent,
         meta
       );
     }
-    const planReport = this.planInternal();
+    const bindingFinalQuery = isBindingFinalQuery(compiledIntent.bundle);
+    const planReport = bindingFinalQuery ? createBindingFinalPlan(compiledIntent.intent) : this.planInternal();
     if (!this.adapter) {
       return {
         plan: planReport,
@@ -6412,10 +6718,8 @@ var NqlBuilderImpl = class {
         ...meta !== void 0 && { meta }
       };
     }
-    const compiled = hasNqlBindings(compiledIntent.bundle) ? this.adapter.compile(
-      compiledIntent.bundle,
-      this.nqlBundleCompileOptions()
-    ) : 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) {
@@ -6466,6 +6770,268 @@ var NqlBuilderImpl = class {
       ...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));
@@ -6492,35 +7058,27 @@ var NqlBuilderImpl = class {
       );
     }
     const compiledIntent = this.compile();
+    if (hasMutationBindingBodies(compiledIntent.bundle)) {
+      return this.executeNqlProgramSequence(compiledIntent, adapter);
+    }
     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
-          };
-        }
-      });
+      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 = hasNqlBindings(compiledIntent.bundle) ? adapter.compile(
-      compiledIntent.bundle,
-      this.nqlBundleCompileOptions()
-    ) : adapter.compile(planReport);
+    const finalBundle = this.createFinalNqlStatementBundle(compiledIntent);
+    const compiled = hasNqlBindings(finalBundle) ? adapter.compile(finalBundle, this.nqlBundleCompileOptions()) : adapter.compile(planReport);
     return adapter.execute(compiled);
   }
   async run() {
@@ -10422,6 +10980,8 @@ var POSTGRESQL_CAPABILITIES = {
   supportsJsonType: true,
   supportsJsonOperators: true,
   // PG: ->, ->>, @>, <@, ?, #>, #>>
+  supportsRowLevelLocks: true,
+  supportsLockWaitPolicies: true,
   supportsSchemas: true,
   // Include Strategy Capabilities (CORE-006)
   supportsLateralJoin: true,
@@ -10466,6 +11026,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)
@@ -10496,6 +11059,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)
@@ -10524,6 +11089,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,
@@ -10553,6 +11120,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,
@@ -10610,6 +11180,8 @@ function createDialectCapabilities(overrides, options) {
     supportsRangeTypes: false,
     supportsJsonType: false,
     supportsJsonOperators: false,
+    supportsRowLevelLocks: false,
+    supportsLockWaitPolicies: false,
     supportsSchemas: false,
     supportsLateralJoin: false,
     supportsJsonAgg: false,