@vibeorm/sql 5.3.0 → 5.5.0

package/dist/ast.d.ts

@@ -868,10 +868,21 @@ export type SelectStatement = {
  * The lock a locking read takes: one strength, one wait policy. Both members
  * are REQUIRED here — defaulting happens once, in the query builder, so the
  * rendered SQL is a function of the AST alone.
+ *
+ * `of` narrows the lock to named FROM items (`FOR UPDATE OF "Parent"`). The
+ * join relation strategy needs it: its statement also reads child rows through
+ * `LEFT JOIN LATERAL` subqueries, and an unnarrowed clause is refused by
+ * postgres ("FOR UPDATE is not allowed with aggregate functions", from the
+ * children's `json_agg`). With `of` naming the statement's own table only the
+ * parent rows are locked. Each name must be the statement's table alias, or its
+ * unqualified table name when it has no alias — the only FROM item the AST
+ * names; the renderer refuses anything else. Dialects without a locking-read
+ * clause render nothing, as for a lock without `of`.
  */
 export type RowLock = {
     readonly strength: RowLockStrength;
     readonly wait: RowLockWaitPolicy;
+    readonly of?: readonly string[];
 };
 /**
  * Sentinel VALUES cell: render the `DEFAULT` keyword instead of a placeholder
@@ -960,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;
@@ -1319,6 +1349,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, 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, 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,7 +2894,10 @@ 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) {
@@ -2960,6 +2963,12 @@ function renderRowLockClause(params) {
       hint: `${dialect.name} can express: ${Object.keys(syntax.wait).join(", ")}`
     });
   }
+  if (lock.of !== undefined) {
+    if (lock.of.length === 0)
+      throw internalError({ message: "a row lock's `of` list cannot be empty" });
+    const tables = lock.of.map((name) => dialect.quoteIdent({ name })).join(", ");
+    return `${strengthText} OF ${tables}${waitText}`;
+  }
   return `${strengthText}${waitText}`;
 }
 var ADVISORY_KEY_BOUNDS = Object.freeze({
@@ -3646,7 +3655,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'" }
@@ -3659,7 +3668,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
@@ -4084,7 +4109,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) {
@@ -4122,6 +4147,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,
@@ -4240,7 +4267,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)
@@ -4928,11 +4955,16 @@ 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 columns = requested.map((column) => {
     if (typeof column === "string")
       return 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}`;
@@ -4942,6 +4974,17 @@ function applyReturning(params) {
   }).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";
@@ -5136,6 +5179,13 @@ function renderSelect(params) {
     text += ` OFFSET ${statement.offset}`;
   }
   if (statement.rowLock !== undefined) {
+    const target = statement.table.alias ?? statement.table.name;
+    if (statement.rowLock.of !== undefined && statement.rowLock.of.some((name) => name !== target)) {
+      throw internalError4({ message: `a row lock's \`of\` list may name only the statement's own table "${target}"` });
+    }
+    if (statement.rowLock.of !== undefined && (statement.fromSelect !== undefined || statement.keyPage !== undefined)) {
+      throw internalError4({ message: "a row lock's `of` list cannot name a derived table" });
+    }
     const clause = renderRowLockClause({ dialect, lock: statement.rowLock });
     if (clause !== null)
       text += ` ${clause}`;
@@ -5451,8 +5501,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" });
@@ -5462,9 +5522,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)) {
@@ -5479,6 +5541,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" };
@@ -5498,6 +5561,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))
@@ -6298,6 +6402,7 @@ export {
   extractSqliteGeneratedColumn,
   float32Codec,
   getSqlDialect,
+  isCaptureReturningColumn,
   isDbNowMarker,
   isExcludedRef,
   isFixedDiagnostic,
@@ -6340,6 +6445,7 @@ export {
   registerSqlHandleCheck,
   renderAdvisoryLock,
   renderAdvisoryLocks,
+  renderCaptureReadiness,
   renderCheckProbe,
   renderColumnStateQuery,
   renderConstraintOwnedIndexDrop,
@@ -6445,4 +6551,4 @@ export {
   toPgArrayLiteral
 };
 
-//# debugId=A6FF0AC9CFF5903864756E2164756E21
+//# debugId=98E9DEF83EE89CED64756E2164756E21