@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/runtime/batch-diagnostics.js

@@ -0,0 +1,89 @@
+import { Effect } from "effect";
+import { isSqlError, isSqlErrorReason } from "effect/unstable/sql/SqlError";
+import { fieldColumnName, indexName, primaryKeyName, uniqueIndexName } from "../migrate/storage.js";
+const DRIVER_MESSAGES = new Set([
+    "PgConnection: Query failed",
+    "PgConnection: The server reported an error",
+]);
+const FRAME_PREFIX = "^\\s+at (?:(?:async |new )?(?:[\\w.$<>]+ )?(?:\\[as [\\w$]+\\] )?\\()?";
+const FRAME_LOCATION = "(?:(?:file:\\/\\/)?\\/[\\w./@%+~:-]+|node:[\\w./-]+)";
+const SOURCE_FRAME = new RegExp(`${FRAME_PREFIX}${FRAME_LOCATION}:\\d+:\\d+\\)?$`);
+function knownConstraint(entity, error) {
+    const cause = error.reason.cause;
+    const constraint = error.reason._tag === "UniqueViolation"
+        ? error.reason.constraint
+        : typeof cause === "object" && cause !== null && "constraint" in cause
+            ? cause.constraint
+            : undefined;
+    const names = [
+        primaryKeyName(entity.table),
+        primaryKeyName(entity.historyTable),
+        ...entity.manifest.properties
+            .filter((field) => field.unique)
+            .map((field) => uniqueIndexName(entity.name, field.name)),
+        ...entity.manifest.indexes
+            .filter((index) => index.unique)
+            .map((index) => indexName(entity.table, index.properties.map((name) => fieldColumnName(entity.manifest, name) ?? name))),
+    ];
+    // PostgreSQL truncates these generated ASCII identifiers to its 63-byte identifier limit.
+    return typeof constraint === "string" && names.some((name) => name.slice(0, 63) === constraint)
+        ? constraint
+        : undefined;
+}
+function causeTag(cause) {
+    if (isSqlError(cause)) {
+        return "SqlError";
+    }
+    if (isSqlErrorReason(cause)) {
+        return cause._tag;
+    }
+    return cause instanceof Error ? "Error" : "UnknownCause";
+}
+function safeCause(cause, constraint) {
+    if (!(cause instanceof Error)) {
+        return { tag: causeTag(cause), message: "[redacted database cause]", messageRedacted: true };
+    }
+    const original = cause.message;
+    const knownUniqueMessage = constraint === undefined
+        ? undefined
+        : `duplicate key value violates unique constraint "${constraint}"`;
+    const allowed = DRIVER_MESSAGES.has(original) || original === knownUniqueMessage;
+    const message = allowed ? original : "[redacted database message]";
+    const headline = `${cause.name}: ${original}`;
+    const stack = typeof cause.stack === "string" && cause.stack.startsWith(`${headline}\n`)
+        ? cause.stack.slice(headline.length + 1)
+        : "";
+    // Remove the complete (possibly multiline) original headline before keeping JS source frames.
+    // SQL, hints, parameters and arbitrary database explanations never enter this projection.
+    const frames = stack.split("\n").filter((line) => SOURCE_FRAME.test(line));
+    return {
+        tag: causeTag(cause),
+        message,
+        messageRedacted: !allowed,
+        ...(frames.length > 0 ? { stack: frames.join("\n") } : {}),
+    };
+}
+/** A safe projection of every wrapper; the original driver cause stays on the Conflict itself. */
+export function batchConflictDiagnostic(entity, error) {
+    const constraint = knownConstraint(entity, error);
+    const causeChain = [];
+    const seen = new Set();
+    let current = error;
+    while (current !== undefined && !seen.has(current)) {
+        seen.add(current);
+        causeChain.push(safeCause(current, constraint));
+        current =
+            typeof current === "object" && current !== null && "cause" in current
+                ? current.cause
+                : undefined;
+    }
+    return { sqlState: "23505", ...(constraint === undefined ? {} : { constraint }), causeChain };
+}
+/** Emit before mapping the error, so even a handler-caught conflict has a correlated diagnostic. */
+export function logBatchConflict(entity, error, scope) {
+    return Effect.logWarning("ontology.action.batch_conflict").pipe(Effect.annotateLogs({
+        ...scope,
+        entity: entity.name,
+        ...batchConflictDiagnostic(entity, error),
+    }));
+}

package/dist/runtime/batch.d.ts

@@ -0,0 +1,52 @@
+import { Effect } from "effect";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { ActionRejected, Conflict, NotFound, type ScopeViolated } from "../errors.js";
+import type { BatchResult, BatchReturning, StoredValues } from "../runtime.js";
+import { type EntityModel, type FieldModel } from "./model.js";
+import { type PreparedWrite } from "./records.js";
+import { type WriteContext, type WriteGuard } from "./writes.js";
+export declare const BATCH_MAX_ROWS = 200;
+export declare const BATCH_MAX_BYTES: number;
+export declare const ACTION_MAX_BATCH_ROWS = 500;
+/** The pinned PostgreSQL driver's signed Int16 count caps bindings at 32,767. */
+export declare const BATCH_MAX_PARAMETERS = 30000;
+/** Includes bound values and an allowance for their SQL placeholders. */
+export declare const BATCH_MAX_STATEMENT_BYTES: number;
+export type BatchOperation = "create" | "update" | "upsert";
+export type BatchError = ActionRejected | Conflict | NotFound | ScopeViolated | SqlError;
+export interface BatchInput {
+    readonly records: ReadonlyArray<StoredValues | {
+        readonly id: string;
+        readonly values: StoredValues;
+    }>;
+    readonly returning?: BatchReturning;
+    readonly on?: ReadonlyArray<string>;
+}
+interface PlannedRow {
+    readonly index: number;
+    readonly id: string;
+    readonly create: PreparedWrite;
+    readonly patch: PreparedWrite;
+}
+export interface BatchPlan {
+    readonly operation: BatchOperation;
+    readonly returning: BatchReturning;
+    readonly rows: ReadonlyArray<PlannedRow>;
+    readonly keys: ReadonlyArray<FieldModel>;
+    readonly distinctReferences: number;
+}
+export interface BatchContext extends WriteContext {
+    /** Set only after a prior write's savepoint succeeded. */
+    readonly attributionInitialized: boolean;
+}
+/** One UTF-8 JSON encoding defines the public byte bound, including IDs and conflict fields. */
+export declare function batchInputBytes(input: BatchInput): number;
+/** All authored-value validation finishes before a record mutation can execute. */
+export declare function planBatch(entity: EntityModel, operation: BatchOperation, input: BatchInput): Effect.Effect<BatchPlan, ActionRejected | NotFound>;
+/**
+ * Executes one set of mutations; the caller owns its single savepoint and edit publication. With a
+ * guard, updated records must be inside its `change` scope before and after, created ones inside
+ * its `create` scope.
+ */
+export declare function executeBatch(context: BatchContext, entity: EntityModel, plan: BatchPlan, guard?: WriteGuard): Effect.Effect<BatchResult, BatchError>;
+export {};

package/dist/runtime/batch.js

@@ -0,0 +1,534 @@
+import { Effect, Schema } from "effect";
+import { ActionRejected, Conflict, NotFound } from "../errors.js";
+import { ACTION_ATTRIBUTION_TABLE, quoteIdentifier } from "../migrate/storage.js";
+import { InvalidValues, StoredRecordMismatch } from "./errors.js";
+import { diffRecords } from "./history.js";
+import { uuidv7 } from "./ids.js";
+import { entityModel } from "./model.js";
+import { normalizeId } from "./reads.js";
+import { bindValue, decodeRecord, isRecordId, prepareWrite, selectList, } from "./records.js";
+import { Aliases, columnOf, Params } from "./statement.js";
+import { scopeCondition, scopeViolated, } from "./writes.js";
+import { validate } from "./validation.js";
+export const BATCH_MAX_ROWS = 200;
+export const BATCH_MAX_BYTES = 2 * 1024 * 1024;
+export const ACTION_MAX_BATCH_ROWS = 500;
+/** The pinned PostgreSQL driver's signed Int16 count caps bindings at 32,767. */
+export const BATCH_MAX_PARAMETERS = 30_000;
+/** Includes bound values and an allowance for their SQL placeholders. */
+export const BATCH_MAX_STATEMENT_BYTES = 4 * 1024 * 1024;
+const summaryFields = new WeakMap();
+const KeyOrderRow = Schema.Struct({ index: Schema.Int, duplicates: Schema.Int });
+function rejected(message, indices, fields) {
+    return new ActionRejected({
+        message,
+        batch: { indices: [...indices], ...(fields === undefined ? {} : { fields: [...fields] }) },
+    });
+}
+/** One UTF-8 JSON encoding defines the public byte bound, including IDs and conflict fields. */
+export function batchInputBytes(input) {
+    return Buffer.byteLength(JSON.stringify({ records: input.records, ...(input.on ? { on: input.on } : {}) }));
+}
+function unsupportedFields(entity, values) {
+    return Object.keys(values).filter((name) => {
+        const field = entity.fieldsByName.get(name);
+        const link = entity.links.get(name);
+        return (values[name] !== undefined &&
+            (field?.storage === "blob" || link?.via === "join" || link?.via === "inverse-key"));
+    });
+}
+function conflictFields(entity, on) {
+    return Effect.suspend(() => {
+        const fields = on.map((name) => entity.fieldsByName.get(name));
+        const uniqueProperty = on.length === 1 && fields[0]?.property?.definition.unique === true;
+        const declaredIndex = entity.manifest.indexes.find((index) => index.unique &&
+            index.properties.length === on.length &&
+            index.properties.every((name) => on.includes(name)));
+        if (on.length === 0 ||
+            new Set(on).size !== on.length ||
+            fields.some((field) => field?.source !== "property") ||
+            (!uniqueProperty && declaredIndex === undefined)) {
+            return Effect.die(new InvalidValues({
+                entity: entity.name,
+                message: `upsertMany needs declared ordinary properties forming a unique key of ${entity.name}.`,
+                issues: [
+                    {
+                        path: ["on"],
+                        message: "Expected a declared unique property or compound unique index",
+                    },
+                ],
+            }));
+        }
+        // Equivalent conflict-key permutations must acquire unique-index locks in the same order.
+        const canonical = declaredIndex?.properties ?? on;
+        return Effect.succeed(canonical.map((name) => entity.fieldsByName.get(name)));
+    });
+}
+function prepareBatchWrite(entity, values, mode, index) {
+    return prepareWrite(entity, values, mode).pipe(Effect.catchDefect((defect) => {
+        if (!(defect instanceof InvalidValues)) {
+            return Effect.die(defect);
+        }
+        const indexed = new InvalidValues({
+            entity: defect.entity,
+            message: `Invalid ${entity.name} values at batch index ${index}.`,
+            issues: defect.issues.map((issue) => ({
+                ...issue,
+                path: ["records", index, ...issue.path],
+            })),
+        });
+        Object.defineProperty(indexed, "cause", { value: defect, enumerable: false });
+        return Effect.die(indexed);
+    }));
+}
+/** All authored-value validation finishes before a record mutation can execute. */
+export function planBatch(entity, operation, input) {
+    return Effect.gen(function* () {
+        const returning = input.returning ?? "records";
+        if (returning !== "records" && returning !== "summary") {
+            return yield* rejected("Unknown batch returning mode.", []);
+        }
+        const keys = operation === "upsert" ? yield* conflictFields(entity, input.on ?? []) : [];
+        const rows = [];
+        const updateIds = new Map();
+        const references = new Set();
+        for (const [index, entry] of input.records.entries()) {
+            const update = entry;
+            const values = operation === "update" ? update.values : entry;
+            const unsupported = unsupportedFields(entity, values);
+            if (unsupported.length > 0) {
+                return yield* rejected("Batch writes do not support blob or collection assignments.", [index], unsupported);
+            }
+            if (operation === "upsert") {
+                const missing = keys.filter((field) => values[field.name] === undefined || values[field.name] === null);
+                if (missing.length > 0) {
+                    return yield* Effect.die(new InvalidValues({
+                        entity: entity.name,
+                        message: "Every upsertMany record needs non-null conflict key values.",
+                        issues: missing.map((field) => ({
+                            path: [index, field.name],
+                            message: `${field.name} is required`,
+                        })),
+                    }));
+                }
+            }
+            const id = operation === "update" ? normalizeId(update.id) : uuidv7();
+            if (operation === "update") {
+                if (!isRecordId(id)) {
+                    return yield* missingRecord(entity, id, [index], ["id"]);
+                }
+                const indices = updateIds.get(id) ?? [];
+                indices.push(index);
+                updateIds.set(id, indices);
+            }
+            const create = yield* prepareBatchWrite(entity, values, operation === "update" ? "update" : "create", index);
+            const patch = operation === "upsert"
+                ? yield* prepareBatchWrite(entity, Object.fromEntries(Object.entries(values).filter(([name]) => !keys.some((key) => key.name === name))), "update", index)
+                : create;
+            for (const reference of create.references) {
+                references.add(`${reference.link.target}:${normalizeId(reference.id)}`);
+            }
+            rows.push({ index, id, create, patch });
+        }
+        const duplicates = [...updateIds.values()].filter((indices) => indices.length > 1).flat();
+        if (duplicates.length > 0) {
+            return yield* rejected("A batch cannot update a record more than once.", duplicates.sort((a, b) => a - b), ["id"]);
+        }
+        return { operation, returning, rows, keys, distinctReferences: references.size };
+    });
+}
+function missingRecord(entity, id, indices, fields) {
+    return new NotFound({
+        entity: entity.name,
+        id,
+        message: `A required ${entity.label.toLowerCase()} record does not exist.`,
+        batch: { indices: [...indices], ...(fields ? { fields: [...fields] } : {}) },
+    });
+}
+/** Chunk by protocol parameters and encoded statement weight; chunks share one savepoint. */
+function chunks(rows, width, valueBytes) {
+    return Effect.gen(function* () {
+        const result = [];
+        let current = [];
+        let bytes = 0;
+        for (const row of rows) {
+            const rowBytes = valueBytes(row) + width * 48;
+            if (width > BATCH_MAX_PARAMETERS || rowBytes > BATCH_MAX_STATEMENT_BYTES) {
+                return yield* rejected("A batch row exceeds the SQL statement resource limit.", []);
+            }
+            if (current.length > 0 &&
+                ((current.length + 1) * width > BATCH_MAX_PARAMETERS ||
+                    bytes + rowBytes > BATCH_MAX_STATEMENT_BYTES)) {
+                result.push(current);
+                current = [];
+                bytes = 0;
+            }
+            current.push(row);
+            bytes += rowBytes;
+        }
+        if (current.length > 0) {
+            result.push(current);
+        }
+        return result;
+    });
+}
+function writeBytes(write) {
+    return Buffer.byteLength(JSON.stringify(write.columns.map(({ field, value }) => bindValue(field, value))));
+}
+function selectedFields(entity, returning) {
+    if (returning === "records") {
+        return entity.fields;
+    }
+    const fields = summaryFields.get(entity) ??
+        entity.fields.filter((field) => field.source !== "system" || field.name === "id");
+    summaryFields.set(entity, fields);
+    return fields;
+}
+/** Summary mode needs history values, but never decodes a projected row as a complete record. */
+function decodeBatchRow(entity, row, returning) {
+    return decodeRecord(entity, row, selectedFields(entity, returning));
+}
+function requireBatchReferences(context, plan) {
+    return Effect.gen(function* () {
+        const targets = new Map();
+        for (const row of plan.rows) {
+            for (const reference of row.create.references) {
+                const ids = targets.get(reference.link.target) ?? new Map();
+                const id = normalizeId(reference.id);
+                const positions = ids.get(id) ?? { indices: new Set(), fields: new Set() };
+                positions.indices.add(row.index);
+                positions.fields.add(reference.link.name);
+                ids.set(id, positions);
+                targets.set(reference.link.target, ids);
+            }
+        }
+        for (const name of [...targets.keys()].sort()) {
+            const entity = entityModel(context.model, name);
+            const ids = targets.get(name);
+            const wanted = [...ids.keys()].sort();
+            const malformed = wanted.find((id) => !isRecordId(id));
+            if (malformed !== undefined) {
+                const positions = ids.get(malformed);
+                return yield* missingRecord(entity, malformed, [...positions.indices], [...positions.fields]);
+            }
+            for (const part of yield* chunks(wanted, 1, (id) => id.length)) {
+                const params = new Params();
+                const placeholders = part.map((id) => params.add(id, "uuid"));
+                const rows = yield* context.run(`SELECT "t0"."id"::text AS "id" FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+                    `WHERE "t0"."id" IN (${placeholders.join(", ")}) ORDER BY "t0"."id" FOR KEY SHARE OF "t0"`, params);
+                const found = new Set(rows.map((row) => row.id));
+                const missing = part.filter((id) => !found.has(id));
+                if (missing.length > 0) {
+                    const positions = missing.map((id) => ids.get(id));
+                    return yield* missingRecord(entity, missing[0], [...new Set(positions.flatMap((position) => [...position.indices]))].sort((a, b) => a - b), [...new Set(positions.flatMap((position) => [...position.fields]))].sort());
+                }
+            }
+        }
+    });
+}
+function keyValue(row, field) {
+    return row.create.columns.find((column) => column.field.name === field.name).value;
+}
+/** PostgreSQL casts, equality and collation define duplicate keys; JS string encodings do not. */
+function requireDistinctKeys(context, entity, plan) {
+    return Effect.gen(function* () {
+        const params = new Params();
+        const input = plan.rows.map((row) => Object.fromEntries([
+            ["index", row.index],
+            ...plan.keys.map((field, index) => [`k${index}`, keyValue(row, field)]),
+        ]));
+        const keyNames = plan.keys.map((_, index) => quoteIdentifier(`k${index}`));
+        const definitions = plan.keys.map((field, index) => `${keyNames[index]} ${field.sqlType}`);
+        const rows = yield* context.run(`SELECT "index", count(*) OVER (PARTITION BY ${keyNames.join(", ")})::integer AS "duplicates" ` +
+            `FROM jsonb_to_recordset(${params.add(JSON.stringify(input), "jsonb")}) AS "input" ` +
+            `("index" integer, ${definitions.join(", ")}) ORDER BY ${keyNames.join(", ")}`, params);
+        const decoded = validate(Schema.Array(KeyOrderRow), rows);
+        if (!decoded.ok) {
+            return yield* Effect.die(new StoredRecordMismatch({
+                entity: entity.name,
+                message: "The database returned an invalid batch key ordering projection.",
+            }));
+        }
+        const indices = decoded.value
+            .filter((row) => Number(row.duplicates) > 1)
+            .map((row) => Number(row.index))
+            .sort((a, b) => a - b);
+        if (indices.length > 0) {
+            return yield* rejected("The batch contains duplicate conflict keys.", indices, plan.keys.map((field) => field.name));
+        }
+        const byIndex = new Map(plan.rows.map((row) => [row.index, row]));
+        return decoded.value.map((row) => byIndex.get(row.index));
+    });
+}
+function createRows(context, entity, plan) {
+    return Effect.gen(function* () {
+        const records = new Map();
+        const fields = entity.fields.filter((field) => field.source !== "system");
+        const sorted = plan.operation === "upsert"
+            ? plan.rows
+            : [...plan.rows].sort((left, right) => left.id.localeCompare(right.id));
+        for (const part of yield* chunks(sorted, fields.length + 2, (row) => writeBytes(row.create))) {
+            const params = new Params();
+            const principal = params.add(context.scope.principalId, "uuid");
+            const values = part.map((row) => {
+                const columns = new Map(row.create.columns.map((column) => [column.field.name, column.value]));
+                const placeholders = [
+                    params.add(row.id, "uuid"),
+                    ...fields.map((field) => params.add(bindValue(field, columns.get(field.name)), field.sqlType)),
+                ];
+                return `(${placeholders.join(", ")})`;
+            });
+            const columns = fields.map((field) => quoteIdentifier(field.column));
+            const inputColumns = ['"id"', ...columns];
+            const targetColumns = [
+                '"id"',
+                '"created_at"',
+                '"updated_at"',
+                '"created_by"',
+                '"updated_by"',
+                ...columns,
+            ];
+            const selected = [
+                '"input"."id"',
+                "now()",
+                "now()",
+                principal,
+                principal,
+                ...columns.map((column) => `"input".${column}`),
+            ];
+            const conflict = plan.operation === "upsert"
+                ? ` ON CONFLICT (${plan.keys.map((field) => quoteIdentifier(field.column)).join(", ")}) DO NOTHING`
+                : "";
+            const order = plan.operation === "upsert"
+                ? plan.keys.map((field) => columnOf("input", field.column)).join(", ")
+                : '"input"."id"';
+            const rows = yield* context.run(`INSERT INTO ${quoteIdentifier(entity.table)} AS "t0" ` +
+                `(${targetColumns.join(", ")}) SELECT ${selected.join(", ")} ` +
+                `FROM (VALUES ${values.join(", ")}) AS "input" (${inputColumns.join(", ")}) ` +
+                `ORDER BY ${order}${conflict} RETURNING ${selectList(entity, "t0", selectedFields(entity, plan.returning))}`, params);
+            const byId = new Map(part.map((row) => [row.id, row.index]));
+            for (const row of rows) {
+                const record = yield* decodeBatchRow(entity, row, plan.returning);
+                records.set(byId.get(record.id), record);
+            }
+        }
+        return records;
+    });
+}
+/**
+ * Locks the existing records the batch updates. With a check, a record outside its scope is not
+ * found (the before-check): it is locked and reported rather than skipped, so that an upsert does
+ * not take it for a record that disappeared.
+ */
+function lockRows(context, entity, plan, pending, check) {
+    return Effect.gen(function* () {
+        const records = new Map();
+        const outside = [];
+        const sorted = plan.operation === "upsert"
+            ? pending
+            : [...pending].sort((left, right) => left.id.localeCompare(right.id));
+        const width = plan.operation === "upsert" ? plan.keys.length + 1 : 2;
+        for (const part of yield* chunks(sorted, width, (row) => writeBytes(row.create))) {
+            const params = new Params();
+            const keys = plan.operation === "upsert" ? plan.keys : [entity.fieldsByName.get("id")];
+            const values = part.map((row) => `(${params.add(row.index, "integer")}, ${keys
+                .map((field) => params.add(field.name === "id" ? row.id : bindValue(field, keyValue(row, field)), field.sqlType))
+                .join(", ")})`);
+            const keyNames = keys.map((_, index) => quoteIdentifier(`k${index}`));
+            const condition = keys
+                .map((field, index) => `${columnOf("t0", field.column)} = "input".${keyNames[index]}`)
+                .join(" AND ");
+            const order = keys.map((field) => columnOf("t0", field.column)).join(", ");
+            const inside = check === undefined
+                ? ""
+                : `(${scopeOnT0(context, entity, params, check)}) IS TRUE AS "__inside", `;
+            const rows = yield* context.run(`SELECT "input"."index" AS "__batch_index", ${inside}` +
+                `${selectList(entity, "t0", selectedFields(entity, plan.returning))} ` +
+                `FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+                `JOIN (VALUES ${values.join(", ")}) AS "input" ("index", ${keyNames.join(", ")}) ON ${condition} ` +
+                `ORDER BY ${order} FOR UPDATE OF "t0"`, params);
+            for (const row of rows) {
+                const { __inside: inside, ...selected } = row;
+                records.set(Number(row.__batch_index), yield* decodeBatchRow(entity, check === undefined ? row : selected, plan.returning));
+                if (check !== undefined && inside !== true) {
+                    outside.push(pending.find((candidate) => candidate.index === Number(row.__batch_index)));
+                }
+            }
+        }
+        if (outside.length > 0) {
+            const indices = outside.map((row) => row.index).sort((a, b) => a - b);
+            return yield* missingRecord(entity, String(records.get(indices[0]).id), indices, ["id"]);
+        }
+        const missing = pending.filter((row) => !records.has(row.index));
+        if (missing.length > 0) {
+            if (plan.operation === "upsert") {
+                return yield* new Conflict({
+                    entity: entity.name,
+                    message: "A conflicting upsert record disappeared before it could be locked.",
+                    batch: {
+                        indices: missing.map((row) => row.index),
+                        fields: plan.keys.map((field) => field.name),
+                    },
+                });
+            }
+            return yield* missingRecord(entity, missing[0].id, missing.map((row) => row.index), ["id"]);
+        }
+        return records;
+    });
+}
+/** Presence flags support heterogeneous patches in one set mutation without filling omissions. */
+function updateRows(context, entity, plan, pending, before) {
+    return Effect.gen(function* () {
+        const records = new Map();
+        const names = new Set(pending.flatMap((row) => row.patch.columns.map(({ field }) => field.name)));
+        const fields = entity.fields.filter((field) => names.has(field.name));
+        if (fields.length === 0) {
+            return records;
+        }
+        const sorted = [...pending].sort((left, right) => String(before.get(left.index).id).localeCompare(String(before.get(right.index).id)));
+        for (const part of yield* chunks(sorted, fields.length * 2 + 2, (row) => writeBytes(row.patch))) {
+            const params = new Params();
+            const principal = params.add(context.scope.principalId, "uuid");
+            const values = part.map((row) => {
+                const columns = new Map(row.patch.columns.map((column) => [column.field.name, column.value]));
+                const fieldsSql = fields.flatMap((field) => [
+                    params.add(columns.has(field.name), "boolean"),
+                    params.add(columns.has(field.name) ? bindValue(field, columns.get(field.name)) : null, field.sqlType),
+                ]);
+                return `(${params.add(before.get(row.index).id, "uuid")}, ${fieldsSql.join(", ")})`;
+            });
+            const inputColumns = fields.flatMap((_, index) => [`"has${index}"`, `"v${index}"`]);
+            const assignments = fields.map((field, index) => `${quoteIdentifier(field.column)} = CASE WHEN "input"."has${index}" ` +
+                `THEN "input"."v${index}" ELSE ${columnOf("t0", field.column)} END`);
+            const changed = fields.map((field, index) => `("input"."has${index}" AND ${columnOf("t0", field.column)} IS DISTINCT FROM "input"."v${index}")`);
+            const rows = yield* context.run(`UPDATE ${quoteIdentifier(entity.table)} AS "t0" SET ${assignments.join(", ")}, ` +
+                `"updated_at" = now(), "updated_by" = ${principal} ` +
+                `FROM (VALUES ${values.join(", ")}) AS "input" ("id", ${inputColumns.join(", ")}) ` +
+                `WHERE "t0"."id" = "input"."id" AND (${changed.join(" OR ")}) ` +
+                `RETURNING ${selectList(entity, "t0", selectedFields(entity, plan.returning))}`, params);
+            const byId = new Map(part.map((row) => [before.get(row.index).id, row.index]));
+            for (const row of rows) {
+                const record = yield* decodeBatchRow(entity, row, plan.returning);
+                records.set(byId.get(record.id), record);
+            }
+        }
+        return records;
+    });
+}
+function recordBatchEdits(context, entity, edits) {
+    return Effect.gen(function* () {
+        if (edits.length === 0) {
+            return;
+        }
+        if (context.scope.execution !== undefined && !context.attributionInitialized) {
+            const params = new Params();
+            yield* context.run(`INSERT INTO "${ACTION_ATTRIBUTION_TABLE}" (action_id, execution) VALUES (` +
+                `${params.add(context.scope.actionId, "uuid")}, ` +
+                `${params.add(JSON.stringify(context.scope.execution), "jsonb")}) ON CONFLICT DO NOTHING`, params);
+        }
+        for (const part of yield* chunks(edits, 7, (edit) => Buffer.byteLength(JSON.stringify(edit.changes)))) {
+            const params = new Params();
+            const values = part.map((edit) => `(${[
+                params.add(uuidv7(), "uuid"),
+                params.add(edit.id, "uuid"),
+                params.add(context.scope.action, "text"),
+                params.add(context.scope.actionId, "uuid"),
+                params.add(edit.kind, "text"),
+                params.add(context.scope.principalId, "uuid"),
+                "now()",
+                params.add(JSON.stringify(edit.changes), "jsonb"),
+            ].join(", ")})`);
+            yield* context.run(`INSERT INTO ${quoteIdentifier(entity.historyTable)} ` +
+                '("id", "record_id", "action", "action_id", "kind", "principal_id", "at", "changes") ' +
+                `VALUES ${values.join(", ")}`, params);
+        }
+        context.edits.push(...edits);
+    });
+}
+/** The scope condition on the table aliased `t0` of a statement, with aliases of its own. */
+function scopeOnT0(context, entity, params, check) {
+    const aliases = new Aliases();
+    aliases.take(); // t0
+    return scopeCondition(context, entity, params, aliases, "t0", check);
+}
+/**
+ * The after-check of the records a batch wrote: fails with ScopeViolated, naming the batch indices,
+ * unless every record is inside the scope as the batch left it.
+ */
+function requireBatchInScope(context, entity, written, check) {
+    return Effect.gen(function* () {
+        if (check === undefined || written.size === 0) {
+            return;
+        }
+        const params = new Params();
+        const scope = scopeOnT0(context, entity, params, check);
+        const values = [...written].map(([index, record]) => `(${params.add(index, "integer")}, ${params.add(record.id, "uuid")})`);
+        const rows = yield* context.run(`SELECT "input"."index" AS "index" FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+            `JOIN (VALUES ${values.join(", ")}) AS "input" ("index", "id") ON "t0"."id" = "input"."id" ` +
+            `WHERE (${scope}) IS NOT TRUE ORDER BY "input"."index"`, params);
+        if (rows.length > 0) {
+            return yield* scopeViolated(entity, check, undefined, {
+                indices: rows.map((row) => Number(row.index)),
+            });
+        }
+    });
+}
+/**
+ * Executes one set of mutations; the caller owns its single savepoint and edit publication. With a
+ * guard, updated records must be inside its `change` scope before and after, created ones inside
+ * its `create` scope.
+ */
+export function executeBatch(context, entity, plan, guard) {
+    return Effect.gen(function* () {
+        const sortedRows = plan.operation === "upsert" ? yield* requireDistinctKeys(context, entity, plan) : plan.rows;
+        const orderedPlan = { ...plan, rows: sortedRows };
+        yield* requireBatchReferences(context, plan);
+        const created = plan.operation === "update"
+            ? new Map()
+            : yield* createRows(context, entity, orderedPlan);
+        const pending = sortedRows.filter((row) => !created.has(row.index));
+        // A new READ COMMITTED statement observes insertions that DO NOTHING waited for.
+        const before = pending.length === 0
+            ? new Map()
+            : yield* lockRows(context, entity, plan, pending, guard?.change);
+        const updated = pending.length === 0
+            ? new Map()
+            : yield* updateRows(context, entity, plan, pending, before);
+        yield* requireBatchInScope(context, entity, created, guard?.create);
+        yield* requireBatchInScope(context, entity, updated, guard?.change);
+        const edits = [];
+        // Published with the edits: recordBatchEdits runs in the batch's savepoint.
+        const snapshots = context.snapshots === undefined ? undefined : [];
+        const items = plan.rows.map((row) => {
+            const record = created.get(row.index) ?? updated.get(row.index) ?? before.get(row.index);
+            const status = created.has(row.index)
+                ? "created"
+                : updated.has(row.index)
+                    ? "updated"
+                    : "unchanged";
+            if (status !== "unchanged") {
+                snapshots?.push({
+                    entity: entity.name,
+                    id: record.id,
+                    before: status === "created" ? undefined : before.get(row.index),
+                    after: record,
+                });
+                edits.push({
+                    entity: entity.name,
+                    id: record.id,
+                    kind: status === "created" ? "create" : "update",
+                    changes: diffRecords(entity, status === "created" ? undefined : before.get(row.index), record),
+                });
+            }
+            return { index: row.index, status, record };
+        });
+        yield* recordBatchEdits(context, entity, edits);
+        context.snapshots?.push(...(snapshots ?? []));
+        const counts = {
+            created: created.size,
+            updated: updated.size,
+            unchanged: before.size - updated.size,
+        };
+        return plan.returning === "summary" ? counts : { ...counts, items };
+    });
+}