@vibeorm/sql 5.4.0 → 5.6.0

package/dist/ast.d.ts

@@ -971,9 +971,28 @@ export type ReturningColumn = string | {
 } | {
     readonly name: string;
     readonly transform: "jsonText";
+} | CaptureReturningColumn;
+/**
+ * A row-capture RETURNING column (`$transaction(…, { capture })`, dialects with
+ * the `rowCapture` capability: PostgreSQL 18, where RETURNING names the row
+ * before the statement `old` and the row after it `new`):
+ *
+ * - `"old"` / `"new"`: `old."col"::text AS "alias"` / `new."col"::text AS "alias"`,
+ *   the value as text so every type survives exactly (`old` is all NULL for an
+ *   inserted row, `new` for a deleted one);
+ * - `"inserted"`: `(old."col" IS NULL) AS "alias"` — the arm of an `INSERT …
+ *   ON CONFLICT DO UPDATE` row, true when it was inserted (`col` must be a
+ *   column no stored row holds NULL in: a primary-key column).
+ */
+export type CaptureReturningColumn = {
+    readonly capture: "old" | "new" | "inserted";
+    readonly name: string;
+    readonly alias: string;
 };
 /** The column name a {@link ReturningColumn} exposes in the result row. */
 export declare function returningColumnName(column: ReturningColumn): string;
+/** Is this RETURNING column a row-capture column ({@link CaptureReturningColumn})? */
+export declare function isCaptureReturningColumn(column: ReturningColumn): column is CaptureReturningColumn;
 export type InsertStatement = {
     readonly kind: "insert";
     readonly table: TableRef;
@@ -1084,6 +1103,14 @@ export type OnConflictClause = OnConflictUpdate | OnConflictDoNothing;
 export type UpdateStatement = {
     readonly kind: "update";
     readonly table: TableRef;
+    /** The target's alias; required with {@link UpdateStatement.from}, where two relations are in scope. */
+    readonly alias?: string;
+    /**
+     * A joined source: `UPDATE … FROM` on PostgreSQL/SQLite (its `on` AND-ed
+     * before `where`), `UPDATE … JOIN … ON` on MySQL. A
+     * {@link SourceColumnRef} set value reads its columns.
+     */
+    readonly from?: UpdateSource;
     /**
      * Column → parameter value, or an atomic {@link SetOperation}. As a
      * {@link ChainStep} only (statement-maxx lane C3), a value may be a
@@ -1208,6 +1235,23 @@ export declare function stepColumnRef(params: {
     step: string;
     column: string;
 }): StepColumnRef;
+/** The joined relation of an {@link UpdateStatement}: its table, alias and join condition. */
+export type UpdateSource = {
+    readonly table: TableRef;
+    readonly alias: string;
+    readonly on: SqlExpr;
+};
+/** An UPDATE set value read from the joined source's `column` (`UPDATE … FROM`). */
+export type SourceColumnRef = {
+    readonly __sourceColumn: true;
+    readonly column: string;
+};
+/** Read `column` of an {@link UpdateStatement}'s joined source as a set value. */
+export declare function sourceColumnRef(params: {
+    column: string;
+}): SourceColumnRef;
+/** Is this UPDATE set value a {@link SourceColumnRef}? */
+export declare function isSourceColumnRef(value: unknown): value is SourceColumnRef;
 /** Is this INSERT … SELECT cell a {@link StepColumnRef}? */
 export declare function isStepColumnRef(value: unknown): value is StepColumnRef;
 /**
@@ -1330,6 +1374,41 @@ export type ChainResult = {
      * it instead of counting result rows (effect `writeTally`).
      */
     readonly tally?: ChainTally;
+    /**
+     * Row capture ({@link ChainCapture}): per captured data-modifying step, its
+     * row count and its distinct before and after images, on every result row
+     * (uncorrelated scalar subqueries, evaluated once). Needs the dialect's
+     * `rowCapture` capability. Rendered after every other result column, so
+     * their bound limits come last.
+     */
+    readonly capture?: readonly ChainCapture[];
+};
+/**
+ * One captured step of a chain ({@link ChainResult.capture}). Result columns,
+ * `<alias>` being this entry's alias:
+ *
+ * - `<alias>_n`: `(SELECT count(*) FROM "step")`;
+ * - `<alias>_i` (with `inserted`): the rows whose arm marker is true;
+ * - `<alias>_b` / `<alias>_a` (with `before` / `after`): `(SELECT
+ *   array_agg("__vibe_i")::text FROM (SELECT DISTINCT ARRAY["c0", "c1"] AS
+ *   "__vibe_i" FROM "step" LIMIT $n) AS "__vibe_d")` — a two-dimensional text
+ *   array literal of at most `limit` distinct images, NULL when the step
+ *   returned no row. A before image skips the rows whose arm marker is true.
+ *
+ * `before` / `after` name columns the step RETURNS (its
+ * {@link CaptureReturningColumn} aliases), in image order. `limit` is bound once.
+ */
+export type ChainCapture = {
+    readonly step: string;
+    readonly alias: string;
+    /** The step's `"inserted"` arm-marker column, for an `INSERT … ON CONFLICT DO UPDATE` step. */
+    readonly inserted?: string;
+    /** With `inserted`: images of inserted rows only — `after` reads the rows whose marker is true. */
+    readonly insertedOnly?: true;
+    readonly before?: readonly string[];
+    readonly after?: readonly string[];
+    /** The most distinct images one image column returns: a positive safe integer, bound as a parameter. */
+    readonly limit: number;
 };
 /**
  * Fail the statement when `step` returned no row; `token` names the veto in the

package/dist/dialects/diagnostics.d.ts

@@ -1,20 +1,30 @@
 import type { SqlDialect } from "../dialect.ts";
 import type { RenderedQuery } from "../render.ts";
-import type { SqlStatement } from "../ast.ts";
+import type { SqlStatement, TableRef } from "../ast.ts";
 import type { PostgresExplainOptions, PostgresWorkloadQuery } from "./postgres-diagnostics.ts";
 /** Fixed, parameterless diagnostics whose text never varies. */
 export type FixedDiagnosticQuery = "postgresJsonWire" | "sqliteTriggers";
+/** One table of row capture's readiness read: the table as write statements name it, and the columns capture returns. */
+export type CaptureReadinessTable = {
+    readonly table: TableRef;
+    readonly columns: readonly string[];
+};
 /**
  * Fixed diagnostic queries; execution and result interpretation belong to callers.
  *
- * Three variants, discriminated by `query`:
+ * Four variants, discriminated by `query`:
  *  - a fixed transport/catalog probe,
+ *  - row capture's readiness read over the tables of one spec,
  *  - `postgresExplain`, which wraps another statement (EPIC 5),
  *  - a read-only PostgreSQL workload/catalog read (EPIC 5).
  */
 export type DiagnosticStatement = {
     readonly kind: "diagnostic";
     readonly query: FixedDiagnosticQuery;
+} | {
+    readonly kind: "diagnostic";
+    readonly query: "postgresCaptureReadiness";
+    readonly tables: readonly CaptureReadinessTable[];
 } | {
     readonly kind: "diagnostic";
     readonly query: "postgresExplain";
@@ -34,10 +44,22 @@ export declare function renderDiagnostic(params: {
     dialect: SqlDialect;
     query: FixedDiagnosticQuery;
 }): RenderedQuery;
-/** True for the two fixed probes; everything else is an EPIC 5 PostgreSQL diagnostic. */
+/** True for the fixed probes; everything else is the capture readiness read or an EPIC 5 PostgreSQL diagnostic. */
 export declare function isFixedDiagnostic(params: {
     query: DiagnosticStatement["query"];
 }): params is {
     query: FixedDiagnosticQuery;
 };
+/**
+ * Row capture's readiness read (PostgreSQL): the server version, and for each
+ * captured table what would make its `RETURNING` change a write's outcome.
+ * One statement with one JSON parameter, bound as text and cast by the server
+ * (bun:sql re-encodes a parameter it resolves as JSON); `to_regclass` resolves
+ * each table from the same quoted name the write statements use
+ * (schema-qualified when the model has a namespace, else through `search_path`).
+ */
+export declare function renderCaptureReadiness(params: {
+    dialect: SqlDialect;
+    tables: readonly CaptureReadinessTable[];
+}): RenderedQuery;
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/index.d.ts

@@ -40,8 +40,8 @@ export type { ResultDecoder, ResultReadDecoder, ResultParameterEncoder, ResultSc
  * lives in this package; see the root sql-catalog.md for the reviewable surface.
  */
 export { compileExclusion, renderExclusionSetup, renderExclusionDdl, renderExclusionCatalog, renderExclusionProbe } from "./exclusion.ts";
-export type { AdvisoryLockKey, AdvisoryLockStatement, AdvisoryLocksStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, DateTruncation, CountSubquery, ScalarSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyRows, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, TableRef, UpdateStatement, } from "./ast.ts";
-export { ADVISORY_LOCK_RESULT_COLUMN, CHAIN_VETO_PREFIX, CHAIN_VETO_TOKEN_PATTERN, SQL_DEFAULT_CELL, SQL_KEEP_CELL, chainVetoToken, dbNowMarker, excludedRef, isDbNowMarker, isExcludedRef, isJsonParamCell, isListSetOperation, isSetOperation, isSqlDefaultCell, isSqlKeepCell, isStepColumnRef, jsonParamCell, returningColumnName, stepColumnRef, } from "./ast.ts";
+export type { AdvisoryLockKey, AdvisoryLockStatement, AdvisoryLocksStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainCapture, CaptureReturningColumn, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, DateTruncation, CountSubquery, ScalarSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyRows, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, SourceColumnRef, UpdateSource, TableRef, UpdateStatement, } from "./ast.ts";
+export { ADVISORY_LOCK_RESULT_COLUMN, CHAIN_VETO_PREFIX, CHAIN_VETO_TOKEN_PATTERN, SQL_DEFAULT_CELL, SQL_KEEP_CELL, chainVetoToken, dbNowMarker, excludedRef, isDbNowMarker, isExcludedRef, isJsonParamCell, isListSetOperation, isSetOperation, isSqlDefaultCell, isSqlKeepCell, isStepColumnRef, isSourceColumnRef, sourceColumnRef, isCaptureReturningColumn, jsonParamCell, returningColumnName, stepColumnRef, } from "./ast.ts";
 export type { AdvisoryLockFunctions, AdvisoryLockModeFunctions, RowLockSyntax, EmptyInsertSyntax, SqlDialect, } from "./dialect.ts";
 export { ADVISORY_KEY_BOUNDS, describeRowLock, renderAdvisoryLock, renderAdvisoryLocks, renderRowLockClause } from "./locks.ts";
 export { JSON_TRANSPORT, projectionOutputName } from "./json-transport.ts";
@@ -76,7 +76,7 @@ export type { RlsContextStatement, RlsDisableStatement, RlsDropPolicyStatement,
 export { containsPattern, endsWithPattern, escapeGlobPattern, escapeLikePattern, startsWithPattern, strictMatchCollationPrefilter, strictMatchPattern } from "./like.ts";
 export { RLS_READINESS_SQL, NATIVE_RLS_PROBE_POLICY, renderRlsReadinessQuery, renderRlsProbeTable, renderRlsPolicyPath } from "./dialects/postgres-rls-readiness.ts";
 export type { RlsReadinessQuery } from "./dialects/postgres-rls-readiness.ts";
-export { isFixedDiagnostic, renderDiagnostic } from "./dialects/diagnostics.ts";
+export { isFixedDiagnostic, renderCaptureReadiness, renderDiagnostic } from "./dialects/diagnostics.ts";
 export { sqliteColumnClauses } from "./dialects/sqlite-table-definition.ts";
 export type { SqliteColumnClause } from "./dialects/sqlite-table-definition.ts";
 export { parsePostgresTypeName, renderPostgresTypeName, renderPostgresTypeIdentity } from "./dialects/postgres-type-identity.ts";
@@ -92,7 +92,7 @@ export { renderMigrationInventory, renderSqliteColumnInventory, renderSqliteFore
 export { renderMigrationObjectBatch, renderMigrationObjectQuery, renderCheckProbe, renderMigrationNamespace, renderMigrationServerVersion, renderMigrationDependencies, renderMysqlObjectMembers, renderMysqlObjectBatch, renderMysqlObjectMembersBatch } from "./dialects/migration-objects.ts";
 export type { MigrationObjectBatch, MysqlObjectBatch } from "./dialects/migration-objects.ts";
 export type { SqliteIntrospectionPragma } from "./dialects/migration-inventory.ts";
-export type { DiagnosticStatement, FixedDiagnosticQuery } from "./dialects/diagnostics.ts";
+export type { CaptureReadinessTable, DiagnosticStatement, FixedDiagnosticQuery } from "./dialects/diagnostics.ts";
 export { POSTGRES_DIAGNOSTIC_SQL, POSTGRES_WORKLOAD_LIMITS, renderPostgresExplain, renderPostgresWorkload, } from "./dialects/postgres-diagnostics.ts";
 export type { PostgresExplainOptions, PostgresWorkloadQuery } from "./dialects/postgres-diagnostics.ts";
 export { renderColumnStateQuery, renderConstraintStateQuery, renderIndexStateQuery, renderMigrationSessionRead, renderMigrationSessionRestore, renderMigrationSessionSet, renderRelationStateQuery, } from "./dialects/postgres-migration.ts";

package/dist/index.js

@@ -2894,12 +2894,24 @@ function isExcludedRef(value) {
   return typeof value === "object" && value !== null && value.__excluded === true;
 }
 function returningColumnName(column) {
-  return typeof column === "string" ? column : column.name;
+  return typeof column === "string" ? column : ("capture" in column) ? column.alias : column.name;
+}
+function isCaptureReturningColumn(column) {
+  return typeof column !== "string" && "capture" in column;
 }
 var ADVISORY_LOCK_RESULT_COLUMN = "acquired";
 function stepColumnRef(params) {
   return { __stepColumn: true, step: params.step, column: params.column };
 }
+function sourceColumnRef(params) {
+  return Object.freeze({ __sourceColumn: true, column: params.column });
+}
+function isSourceColumnRef(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const candidate = value;
+  return candidate.__sourceColumn === true && typeof candidate.column === "string" && Object.keys(value).length === 2;
+}
 function isStepColumnRef(value) {
   return typeof value === "object" && value !== null && value.__stepColumn === true;
 }
@@ -3652,7 +3664,7 @@ function renderSqliteJsonEquality(params) {
 }
 
 // packages/sql/src/dialects/diagnostics.ts
-import { unsupportedCapability as unsupportedCapability24 } from "@vibeorm/schema";
+import { assertSqlNamespace as assertSqlNamespace2, unsupportedCapability as unsupportedCapability24 } from "@vibeorm/schema";
 var QUERIES = Object.freeze({
   postgresJsonWire: { dialect: "postgres", text: `SELECT '{"__vibeorm":1}'::jsonb AS "probe"` },
   sqliteTriggers: { dialect: "sqlite", text: "SELECT name, tbl_name, sql FROM sqlite_master WHERE type = 'trigger'" }
@@ -3665,7 +3677,23 @@ function renderDiagnostic(params) {
   return { text: query.text, values: [], returning: "none" };
 }
 function isFixedDiagnostic(params) {
-  return params.query === "postgresJsonWire" || params.query === "sqliteTriggers";
+  return Object.hasOwn(QUERIES, params.query);
+}
+var CAPTURE_READINESS_SQL = `SELECT pg_catalog.current_setting('server_version_num') AS "serverVersionNum", t."entry" AS "entry", c.oid IS NOT NULL AS "found", EXISTS (SELECT 1 FROM pg_catalog.pg_rewrite r WHERE r.ev_class = c.oid) AS "rules", COALESCE(pg_catalog.row_security_active(c.oid), false) AS "rowSecurity", (SELECT pg_catalog.array_agg(k.name)::text FROM pg_catalog.json_array_elements_text(t."columns") AS k(name) WHERE NOT EXISTS (SELECT 1 FROM pg_catalog.pg_attribute a WHERE a.attrelid = c.oid AND a.attname = k.name AND a.attnum > 0 AND NOT a.attisdropped)) AS "missing", (SELECT pg_catalog.array_agg(k.name)::text FROM pg_catalog.json_array_elements_text(t."columns") AS k(name) JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid AND a.attname = k.name AND a.attnum > 0 AND NOT a.attisdropped WHERE NOT pg_catalog.has_column_privilege(c.oid, a.attnum, 'SELECT')) AS "unreadable" FROM pg_catalog.json_to_recordset(%TABLES%::text::json) AS t("entry" integer, "table" text, "columns" json) LEFT JOIN pg_catalog.pg_class c ON c.oid = pg_catalog.to_regclass(t."table") ORDER BY t."entry"`;
+function renderCaptureReadiness(params) {
+  const { dialect, tables } = params;
+  if (dialect.name !== "postgres") {
+    throw unsupportedCapability24({ dialect: dialect.name, feature: "postgresCaptureReadiness", hint: "row capture reads RETURNING old/new, PostgreSQL 18 or newer" });
+  }
+  const entries = tables.map((entry, index) => {
+    const { name, namespace } = entry.table;
+    if (namespace !== undefined)
+      assertSqlNamespace2({ namespace, dialect: dialect.name });
+    const relation = dialect.quoteIdent({ name });
+    return { entry: index, table: namespace === undefined ? relation : `${dialect.quoteIdent({ name: namespace })}.${relation}`, columns: [...entry.columns] };
+  });
+  const collector = new ParamCollector(dialect);
+  return { text: CAPTURE_READINESS_SQL.replace("%TABLES%", collector.add(JSON.stringify(entries))), values: collector.values, returning: "none" };
 }
 
 // packages/sql/src/dialects/postgres-diagnostics.ts
@@ -4090,7 +4118,7 @@ function renderRlsPolicyPath(params) {
 }
 
 // packages/sql/src/render.ts
-import { assertSqlNamespace as assertSqlNamespace2, internalError as internalError4, unsupportedCapability as unsupportedCapability28 } from "@vibeorm/schema";
+import { assertSqlNamespace as assertSqlNamespace3, internalError as internalError4, unsupportedCapability as unsupportedCapability28 } from "@vibeorm/schema";
 
 // packages/sql/src/like.ts
 function escapeLikePattern(params) {
@@ -4128,6 +4156,8 @@ function renderStatement(params) {
     case "diagnostic": {
       if (isFixedDiagnostic(statement))
         return renderDiagnostic({ dialect, query: statement.query });
+      if (statement.query === "postgresCaptureReadiness")
+        return renderCaptureReadiness({ dialect, tables: statement.tables });
       if (statement.query === "postgresExplain") {
         return renderPostgresExplain({
           dialect,
@@ -4246,7 +4276,7 @@ function renderProjection(params) {
 }
 function renderTable(dialect, table) {
   if (table.namespace !== undefined)
-    assertSqlNamespace2({ namespace: table.namespace, dialect: dialect.name });
+    assertSqlNamespace3({ namespace: table.namespace, dialect: dialect.name });
   const relation = dialect.quoteIdent({ name: table.name });
   const name = table.namespace === undefined ? relation : `${dialect.quoteIdent({ name: table.namespace })}.${relation}`;
   if (table.alias === undefined)
@@ -4934,20 +4964,37 @@ function applyReturning(params) {
     return { suffix: "", status: "none" };
   }
   if (!dialect.capabilities.returning) {
+    const capture = requested.find(isCaptureReturningColumn);
+    if (capture !== undefined)
+      renderCaptureReturning({ dialect, column: capture });
     return { suffix: "", status: "omitted" };
   }
+  const read = (name) => params.qualify === undefined ? name : `${params.qualify}.${name}`;
   const columns = requested.map((column) => {
     if (typeof column === "string")
-      return dialect.quoteIdent({ name: column });
+      return read(dialect.quoteIdent({ name: column }));
+    if ("capture" in column)
+      return renderCaptureReturning({ dialect, column });
     if ("transform" in column) {
       const name = dialect.quoteIdent({ name: column.name });
-      return `${dialect.jsonTextProjection({ expression: name })} AS ${name}`;
+      return `${dialect.jsonTextProjection({ expression: read(name) })} AS ${name}`;
     }
     const name = dialect.quoteIdent({ name: column.name });
-    return `${textProjection({ dialect, expression: name })} AS ${name}`;
+    return `${textProjection({ dialect, expression: read(name) })} AS ${name}`;
   }).join(", ");
   return { suffix: ` RETURNING ${columns}`, status: "native" };
 }
+function renderCaptureReturning(params) {
+  const { dialect, column } = params;
+  if (!dialect.capabilities.rowCapture) {
+    throw unsupportedCapability28({ dialect: dialect.name, feature: "row capture (RETURNING old./new.)", hint: "row capture needs PostgreSQL 18 or later; the runtime refuses $transaction({ capture }) on this dialect" });
+  }
+  const name = dialect.quoteIdent({ name: column.name });
+  const alias = dialect.quoteIdent({ name: column.alias });
+  if (column.capture === "inserted")
+    return `(old.${name} IS NULL) AS ${alias}`;
+  return `${textProjection({ dialect, expression: `${column.capture}.${name}` })} AS ${alias}`;
+}
 function renderKeyTableJoin(params) {
   const { dialect, join, collector } = params;
   const postgresMember = (member) => member.kind === "citext" || member.kind === "text" || member.kind === "integer";
@@ -5367,6 +5414,18 @@ function renderUpdate(params) {
   if (assignments.length === 0) {
     throw internalError4({ message: "update must set at least one column" });
   }
+  const source = statement.from;
+  if (source !== undefined) {
+    if (statement.alias === undefined || statement.alias === source.alias)
+      throw internalError4({ message: "UPDATE \u2026 FROM needs distinct target and source aliases" });
+    const target = dialect.quoteIdent({ name: statement.alias });
+    const joined = dialect.quoteIdent({ name: source.alias });
+    const assign = () => renderAssignments({ dialect, entries: assignments, collector, selfRef: target, source: joined, ...dialect.name === "mysql" ? { qualifyWrite: target } : {}, ...params.earlier === undefined ? {} : { steps: params.earlier } });
+    const where = () => statement.where === undefined ? "" : ` AND ${renderExpr({ dialect, expr: statement.where, collector })}`;
+    const text = dialect.name === "mysql" ? `UPDATE ${renderTable(dialect, statement.table)} AS ${target} JOIN ${renderTable(dialect, source.table)} AS ${joined} ON ${renderExpr({ dialect, expr: source.on, collector })} SET ${assign()}${statement.where === undefined ? "" : ` WHERE ${renderExpr({ dialect, expr: statement.where, collector })}`}` : `UPDATE ${renderTable(dialect, statement.table)} AS ${target} SET ${assign()} FROM ${renderTable(dialect, source.table)} AS ${joined} WHERE ${renderExpr({ dialect, expr: source.on, collector })}${where()}`;
+    const returning = applyReturning({ dialect, requested: statement.returning, ...dialect.name === "postgres" ? { qualify: target } : {} });
+    return { text: text + returning.suffix, values: collector.values, returning: returning.status };
+  }
   const setSql = renderAssignments({ dialect, entries: assignments, collector, ...params.earlier === undefined ? {} : { steps: params.earlier } });
   let text = `UPDATE ${renderTable(dialect, statement.table)} SET ${setSql}`;
   if (statement.where !== undefined) {
@@ -5386,6 +5445,11 @@ function renderAssignments(params) {
   return entries.map(([name, value]) => {
     const column = dialect.quoteIdent({ name });
     const read = selfRef === undefined ? column : `${selfRef}.${column}`;
+    if (isSourceColumnRef(value)) {
+      if (params.source === undefined)
+        throw internalError4({ message: `an UPDATE set value reads the joined source's column ${value.column}, but the statement joins no source` });
+      return `${column} = ${params.source}.${dialect.quoteIdent({ name: value.column })}`;
+    }
     if (isStepColumnRef(value)) {
       if (params.steps === undefined || !params.steps.has(value.step)) {
         throw internalError4({ message: `an UPDATE set value reads step "${value.step}", which is not an earlier chain step` });
@@ -5429,7 +5493,7 @@ function renderAssignments(params) {
       return `${column} = ${read} || ${collector.add(value.value)}`;
     }
     return `${column} = ${collector.add(value)}`;
-  }).join(", ");
+  }).map((assignment) => params.qualifyWrite === undefined ? assignment : `${params.qualifyWrite}.${assignment}`).join(", ");
 }
 function renderDelete(params) {
   const { dialect, statement, collector } = params;
@@ -5464,8 +5528,18 @@ function renderChain(params) {
     defined.add(step.name);
   }
   const result = statement.result;
+  const captures = result.capture ?? [];
+  if (captures.length > 0 && !dialect.capabilities.rowCapture) {
+    throw unsupportedCapability28({ dialect: dialect.name, feature: "row capture (RETURNING old./new.)", hint: "row capture needs PostgreSQL 18 or later; the runtime refuses $transaction({ capture }) on this dialect" });
+  }
+  for (const alias of captureAliases({ captures })) {
+    if (result.columns.includes(alias) || alias === result.verdict?.alias || alias === result.tally?.alias) {
+      throw internalError4({ message: `chain capture alias "${alias}" collides with a result column` });
+    }
+  }
   if (result.rowsFrom.length === 0 && result.columns.length === 0 && result.tally !== undefined && result.verdict === undefined) {
-    return { text: `WITH ${steps.join(", ")} SELECT ${renderTallyColumn({ dialect, result, defined, collector })}`, values: collector.values, returning: "none" };
+    const tally = renderTallyColumn({ dialect, result, defined, collector });
+    return { text: `WITH ${steps.join(", ")} SELECT ${[tally, ...renderChainCaptures({ dialect, captures, defined, collector })].join(", ")}`, values: collector.values, returning: "none" };
   }
   if (result.rowsFrom.length === 0 || result.columns.length === 0) {
     throw internalError4({ message: "a chain result needs at least one source step and one column" });
@@ -5475,9 +5549,11 @@ function renderChain(params) {
       throw internalError4({ message: `chain result reads undefined step "${name}"` });
   }
   const columnList = result.columns.map((name) => dialect.quoteIdent({ name })).join(", ");
-  const union = result.rowsFrom.map((name) => `SELECT ${columnList} FROM ${dialect.quoteIdent({ name })}`).join(" UNION ALL ");
+  const guarded = result.verdict !== undefined || result.tally !== undefined || result.veto !== undefined && result.veto.length > 0;
+  const armCapture = guarded || captures.length === 0 ? "" : `, ${renderChainCaptures({ dialect, captures, defined, collector }).join(", ")}`;
+  const union = result.rowsFrom.map((name) => `SELECT ${columnList}${armCapture} FROM ${dialect.quoteIdent({ name })}`).join(" UNION ALL ");
   let select = union;
-  if (result.verdict !== undefined || result.tally !== undefined || result.veto !== undefined && result.veto.length > 0) {
+  if (guarded) {
     const extra = [];
     for (const alias of [result.verdict?.alias, result.tally?.alias]) {
       if (alias !== undefined && result.columns.includes(alias)) {
@@ -5492,6 +5568,7 @@ function renderChain(params) {
     if (result.tally !== undefined || result.veto !== undefined && result.veto.length > 0) {
       extra.push(renderTallyColumn({ dialect, result, defined, collector }));
     }
+    extra.push(...renderChainCaptures({ dialect, captures, defined, collector }));
     select = `SELECT ${[...projected, ...extra].join(", ")} FROM (SELECT 1) AS ${dialect.quoteIdent({ name: CHAIN_ONE_ALIAS })}` + ` LEFT JOIN (${union}) AS ${rows} ON TRUE`;
   }
   return { text: `WITH ${steps.join(", ")} ${select}`, values: collector.values, returning: "none" };
@@ -5511,6 +5588,47 @@ function renderChainStep(params) {
       return renderDelete({ dialect, statement, collector }).text;
   }
 }
+function captureAliases(params) {
+  const out = [];
+  for (const entry of params.captures) {
+    out.push(`${entry.alias}_n`);
+    if (entry.inserted !== undefined)
+      out.push(`${entry.alias}_i`);
+    if (entry.before !== undefined && entry.before.length > 0)
+      out.push(`${entry.alias}_b`);
+    if (entry.after !== undefined && entry.after.length > 0)
+      out.push(`${entry.alias}_a`);
+  }
+  return out;
+}
+function renderChainCaptures(params) {
+  const { dialect, captures, defined, collector } = params;
+  const quote = (name) => dialect.quoteIdent({ name });
+  const out = [];
+  for (const entry of captures) {
+    if (!defined.has(entry.step))
+      throw internalError4({ message: `chain capture reads undefined step "${entry.step}"` });
+    const step = quote(entry.step);
+    const marker = entry.inserted === undefined ? undefined : quote(entry.inserted);
+    out.push(`(SELECT count(*) FROM ${step}) AS ${quote(`${entry.alias}_n`)}`);
+    if (marker !== undefined)
+      out.push(`(SELECT count(*) FROM ${step} WHERE ${marker}) AS ${quote(`${entry.alias}_i`)}`);
+    const before = entry.before ?? [];
+    const after = entry.after ?? [];
+    if (before.length === 0 && after.length === 0)
+      continue;
+    if (!Number.isSafeInteger(entry.limit) || entry.limit < 1)
+      throw internalError4({ message: `chain capture "${entry.alias}" needs a positive integer limit` });
+    const limit = collector.add(entry.limit);
+    const item = quote("__vibe_i");
+    const image = (columns, filter) => `(SELECT array_agg(${item})::text FROM (SELECT DISTINCT ARRAY[${columns.map(quote).join(", ")}] AS ${item} FROM ${step}${filter} LIMIT ${limit}) AS ${quote("__vibe_d")})`;
+    if (before.length > 0)
+      out.push(`${image(before, marker === undefined ? "" : ` WHERE NOT ${marker}`)} AS ${quote(`${entry.alias}_b`)}`);
+    if (after.length > 0)
+      out.push(`${image(after, marker !== undefined && entry.insertedOnly === true ? ` WHERE ${marker}` : "")} AS ${quote(`${entry.alias}_a`)}`);
+  }
+  return out;
+}
 function renderSelectCell(params) {
   const { dialect, value, collector } = params;
   if (isJsonParamCell(value))
@@ -6311,6 +6429,7 @@ export {
   extractSqliteGeneratedColumn,
   float32Codec,
   getSqlDialect,
+  isCaptureReturningColumn,
   isDbNowMarker,
   isExcludedRef,
   isFixedDiagnostic,
@@ -6321,6 +6440,7 @@ export {
   isReusableSqlCommand,
   isReusableSqlQuery,
   isSetOperation,
+  isSourceColumnRef,
   isSqlBindingCollector,
   isSqlCommand,
   isSqlDefaultCell,
@@ -6353,6 +6473,7 @@ export {
   registerSqlHandleCheck,
   renderAdvisoryLock,
   renderAdvisoryLocks,
+  renderCaptureReadiness,
   renderCheckProbe,
   renderColumnStateQuery,
   renderConstraintOwnedIndexDrop,
@@ -6439,6 +6560,7 @@ export {
   sealSqlInputScope,
   shortestFloat32,
   snapshotSqlValue,
+  sourceColumnRef,
   sql,
   sqlInputContract,
   sqlParamContract,
@@ -6458,4 +6580,4 @@ export {
   toPgArrayLiteral
 };
 
-//# debugId=11C29D1889ACA76B64756E2164756E21
+//# debugId=FBE116988ABE557464756E2164756E21