@segmentstream-cloud/ontology 0.25.0 → 0.26.0

package/README.md

@@ -253,6 +253,84 @@ export default defineOntology({
   `InvalidOntology` with every diagnostic when the definition has errors. Entities,
   actions and select options need a description.
 
+## Batch writes in actions
+
+Stored entity handles expose `createMany(records, options?)`,
+`updateMany([{ id, values }], options?)`, and `upsertMany({ on, records, returning? })`
+inside authored action handlers. The action remains the permission and commit
+boundary; a batch does not run other authored actions for its rows.
+
+For example, an action can write sales plan lines by a declared compound unique
+key:
+
+```ts
+const PlanLine = entity("planLine", {
+  id: "ent_plan_line",
+  label: "Plan line",
+  plural: "Plan lines",
+  title: "planCode",
+  description: "A sales plan decision for a period.",
+  properties: {
+    planCode: p.text({ description: "The plan code." }),
+    period: p.date({ description: "The period start." }),
+    target: p.number({ description: "The agreed target." }),
+  },
+  indexes: [{ properties: ["planCode", "period"], unique: true }],
+}).actions((self) => ({
+  setTargets: action({
+    description: "Set targets for several plan lines together.",
+    input: Schema.Struct({
+      lines: Schema.Array(Schema.Struct(self.properties)),
+    }),
+    handler: ({ input }) =>
+      self.upsertMany({
+        on: ["planCode", "period"],
+        records: input.lines,
+        returning: "summary",
+      }),
+  }),
+}));
+```
+
+Both result modes return `{ created, updated, unchanged }`, whose counts sum to
+the input length. The default, `returning: "records"`, also returns `items` in
+input order: `{ index, status, record }`, with `status` equal to `"created"`,
+`"updated"`, or `"unchanged"`. `returning: "summary"` omits `items`; the enclosing
+action still returns its normal `edits`. These types are exported as
+`BatchRecordResult<Record>`, `BatchSummaryResult`, and `BatchResult<Record>`.
+
+Creates retain normal defaults and validation. Updates patch distinct IDs:
+omitted fields remain unchanged, and explicit `null` follows the property's
+nullability. An unchanged patch preserves timestamps and attribution and adds no
+history or replication work. Upsert keys must be a nonempty list of ordinary
+properties matching a declared unique property or compound unique index. Each
+input explicitly supplies non-null key values and enough values to create a
+record; existing records receive only supplied non-key fields. Duplicate IDs or
+upsert keys fail the batch.
+
+Batch values support ordinary properties and stored `rel.one` assignments. Blob
+and `rel.many` assignments are rejected; use the existing single-record methods
+for those fields. Warehouse-backed and platform-owned built-in entities are not
+batch write targets. `OntologyWrites` exposes the same operations with an
+explicit `entity` and snake_case field names; entity handles convert authored
+camelCase names and select values.
+
+Each call accepts at most 200 records and 2 MiB of UTF-8 JSON input, including
+record values, update IDs, and upsert key fields. One action may attempt at most
+500 rows across nonempty batch calls, including failed calls its handler catches.
+Empty input returns zero counts and, in record mode, empty `items`, without SQL.
+Every nonempty batch uses one savepoint inside the action transaction. A failure
+rolls back all of that batch's records, history, replication references, and
+edits; a handler may catch it and continue. A later uncaught action failure also
+rolls back earlier successful batches.
+
+Existing `ActionRejected`, `Conflict`, and `NotFound` errors may include
+`batch: { indices, fields? }`: zero-based input positions and safe wire field
+names. Batch calls are never automatically retried. Checkpoint a loader only
+after confirmed action success; replay after a lost response is safe only when
+the complete action is explicitly idempotent, including its other writes and
+side effects. Generic upsert alone does not establish that guarantee.
+
 ## Permissions
 
 A permission is `<entity>:<verb>`. The verbs are `read`, the generated `create`, `update`,

package/dist/entity.d.ts

@@ -3,10 +3,10 @@ import { Effect, type Schema } from "effect";
 import type { Measures } from "./measure.js";
 import type { WarehouseSource } from "./source.js";
 import type { Actions } from "./action.js";
-import type { Conflict, NotFound } from "./errors.js";
+import type { ActionRejected, Conflict, NotFound } from "./errors.js";
 import { type AnyProperty } from "./property.js";
 import type { AnyRelationship, ManyRelationship, OneRelationship } from "./relationship.js";
-import { OntologyReads, OntologyWrites, type FindOptions, type GetOptions, type UpsertResult } from "./runtime.js";
+import { OntologyReads, OntologyWrites, type BatchOptions, type BatchRecordResult, type BatchResult, type BatchSummaryResult, type FindOptions, type GetOptions, type UpsertResult } from "./runtime.js";
 export declare const EntityTypeId: unique symbol;
 export type Properties = {
     readonly [name: string]: AnyProperty;
@@ -98,6 +98,33 @@ export type UpdateValues<P, R> = Simplify<{
 } & {
     readonly [K in ManyKeys<R>]?: ReadonlyArray<string>;
 }>;
+type BlobKeys<P> = {
+    [K in keyof P]-?: NonNullable<ValueOf<P[K]>> extends BlobValue ? K : never;
+}[keyof P] & string;
+type UnsupportedBatchKeys<P, R> = BlobKeys<P> | ManyKeys<R>;
+/** Create values for a batch: ordinary properties and stored `rel.one` assignments only. */
+export type BatchCreateValues<P, R> = Simplify<Omit<CreateValues<P, R>, UnsupportedBatchKeys<P, R>> & {
+    readonly [K in UnsupportedBatchKeys<P, R>]?: never;
+}>;
+/** Patch values for a batch. Blob and collection assignments use single-record methods. */
+export type BatchUpdateValues<P, R> = Simplify<Omit<UpdateValues<P, R>, UnsupportedBatchKeys<P, R>> & {
+    readonly [K in UnsupportedBatchKeys<P, R>]?: never;
+}>;
+/** Ordinary declared properties accepted as upsert keys; unique declarations are checked at runtime. */
+export type BatchKey<P> = Exclude<keyof P & string, BlobKeys<P>>;
+/** Upsert inputs must explicitly supply non-null values for every selected conflict key. */
+export type BatchUpsertValues<P, R, K extends BatchKey<P>> = Simplify<Omit<BatchCreateValues<P, R>, K> & {
+    readonly [Key in K]: NonNullable<WriteValueOf<P[Key]>>;
+}>;
+export interface BatchUpdateRecord<P, R> {
+    readonly id: string;
+    readonly values: BatchUpdateValues<P, R>;
+}
+interface EntityUpsertManyInput<P, R, K extends BatchKey<P>> extends BatchOptions {
+    readonly on: readonly [K, ...K[]];
+    readonly records: ReadonlyArray<BatchUpsertValues<P, R, NoInfer<K>>>;
+}
+type BatchWriteError = ActionRejected | Conflict | NotFound;
 /**
  * Fields an index may cover: declared properties, system properties and `rel.one` relationships
  * between stored entities.
@@ -172,6 +199,30 @@ export interface Entity<Name extends string = string, P extends Properties = Pro
     create(values: CreateValues<P, R>): Effect.Effect<EntityRecord<P, R>, Conflict | NotFound, OntologyWrites>;
     update(record: RecordRef, values: UpdateValues<P, R>): Effect.Effect<EntityRecord<P, R>, Conflict | NotFound, OntologyWrites>;
     upsertBy(property: UniqueKeys<P>, values: CreateValues<P, R>): Effect.Effect<UpsertResult<EntityRecord<P, R>>, Conflict | NotFound, OntologyWrites>;
+    /** Atomically create records. Defaults to returning one record result per input, in order. */
+    createMany(records: ReadonlyArray<BatchCreateValues<P, R>>, options: {
+        readonly returning: "summary";
+    }): Effect.Effect<BatchSummaryResult, BatchWriteError, OntologyWrites>;
+    createMany(records: ReadonlyArray<BatchCreateValues<P, R>>, options?: {
+        readonly returning?: "records";
+    }): Effect.Effect<BatchRecordResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    createMany(records: ReadonlyArray<BatchCreateValues<P, R>>, options?: BatchOptions): Effect.Effect<BatchResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    /** Atomically patch distinct record IDs; values equal to the locked record remain unchanged. */
+    updateMany(records: ReadonlyArray<BatchUpdateRecord<P, R>>, options: {
+        readonly returning: "summary";
+    }): Effect.Effect<BatchSummaryResult, BatchWriteError, OntologyWrites>;
+    updateMany(records: ReadonlyArray<BatchUpdateRecord<P, R>>, options?: {
+        readonly returning?: "records";
+    }): Effect.Effect<BatchRecordResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    updateMany(records: ReadonlyArray<BatchUpdateRecord<P, R>>, options?: BatchOptions): Effect.Effect<BatchResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    /** Atomically insert or patch by a declared unique property or compound unique index. */
+    upsertMany<const K extends BatchKey<P>>(input: EntityUpsertManyInput<P, R, K> & {
+        readonly returning: "summary";
+    }): Effect.Effect<BatchSummaryResult, BatchWriteError, OntologyWrites>;
+    upsertMany<const K extends BatchKey<P>>(input: EntityUpsertManyInput<P, R, K> & {
+        readonly returning?: "records";
+    }): Effect.Effect<BatchRecordResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    upsertMany<const K extends BatchKey<P>>(input: EntityUpsertManyInput<P, R, K>): Effect.Effect<BatchResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
     delete(record: RecordRef): Effect.Effect<void, Conflict | NotFound, OntologyWrites>;
     link(relationship: ManyKeys<R>, record: RecordRef, target: RecordRef): Effect.Effect<void, NotFound, OntologyWrites>;
     unlink(relationship: ManyKeys<R>, record: RecordRef, target: RecordRef): Effect.Effect<void, NotFound, OntologyWrites>;

package/dist/entity.js

@@ -19,6 +19,34 @@ export function entity(name, definition) {
             measures: definition.measures ?? {},
         };
     }
+    const batchFromWire = (result) => "items" in result
+        ? {
+            ...result,
+            items: result.items.map((item) => ({
+                ...item,
+                record: recordFromWire(item.record, definition),
+            })),
+        }
+        : result;
+    const createMany = ((records, options) => withWrites((runtime) => runtime.createMany({
+        entity: toSnakeCase(name),
+        records: records.map((values) => valuesToWire(values, definition)),
+        ...(options?.returning === undefined ? {} : { returning: options.returning }),
+    })).pipe(Effect.map(batchFromWire)));
+    const updateMany = ((records, options) => withWrites((runtime) => runtime.updateMany({
+        entity: toSnakeCase(name),
+        records: records.map(({ id, values }) => ({
+            id,
+            values: valuesToWire(values, definition),
+        })),
+        ...(options?.returning === undefined ? {} : { returning: options.returning }),
+    })).pipe(Effect.map(batchFromWire)));
+    const upsertMany = ((input) => withWrites((runtime) => runtime.upsertMany({
+        entity: toSnakeCase(name),
+        on: input.on.map(toSnakeCase),
+        records: input.records.map((values) => valuesToWire(values, definition)),
+        ...(input.returning === undefined ? {} : { returning: input.returning }),
+    })).pipe(Effect.map(batchFromWire)));
     const handle = {
         [EntityTypeId]: EntityTypeId,
         name,
@@ -26,6 +54,9 @@ export function entity(name, definition) {
         properties: definition.properties,
         relationships: definition.relationships ?? {},
         ref: p.ref(name),
+        createMany,
+        updateMany,
+        upsertMany,
         get: (record, options) => withReads((runtime) => runtime.get({
             entity: toSnakeCase(name),
             id: idOf(record),

package/dist/errors.d.ts

@@ -1,6 +1,16 @@
 import { Schema } from "effect";
+/** Safe batch failure locations: zero-based input indices and wire field names. */
+export declare const BatchErrorDetails: Schema.Struct<{
+    readonly indices: Schema.$Array<Schema.Int>;
+    readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+export type BatchErrorDetails = typeof BatchErrorDetails.Type;
 declare const ActionRejected_base: Schema.Class<ActionRejected, Schema.TaggedStruct<"ActionRejected", {
     readonly message: Schema.String;
+    readonly batch: Schema.optionalKey<Schema.Struct<{
+        readonly indices: Schema.$Array<Schema.Int>;
+        readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * An action refused the request for a business reason. The message is written for the caller and is
@@ -23,6 +33,10 @@ declare const Conflict_base: Schema.Class<Conflict, Schema.TaggedStruct<"Conflic
     readonly entity: Schema.String;
     readonly message: Schema.String;
     readonly property: Schema.optionalKey<Schema.String>;
+    readonly batch: Schema.optionalKey<Schema.Struct<{
+        readonly indices: Schema.$Array<Schema.Int>;
+        readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
 }>, import("effect/Cause").YieldableError>;
 /** The write conflicts with existing data, for example a duplicate value of a unique property. */
 export declare class Conflict extends Conflict_base {
@@ -31,6 +45,10 @@ declare const NotFound_base: Schema.Class<NotFound, Schema.TaggedStruct<"NotFoun
     readonly entity: Schema.String;
     readonly id: Schema.String;
     readonly message: Schema.String;
+    readonly batch: Schema.optionalKey<Schema.Struct<{
+        readonly indices: Schema.$Array<Schema.Int>;
+        readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
 }>, import("effect/Cause").YieldableError>;
 /** The record does not exist. */
 export declare class NotFound extends NotFound_base {

package/dist/errors.js

@@ -1,10 +1,16 @@
 import { Schema } from "effect";
+/** Safe batch failure locations: zero-based input indices and wire field names. */
+export const BatchErrorDetails = Schema.Struct({
+    indices: Schema.Array(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+    fields: Schema.optionalKey(Schema.Array(Schema.String)),
+});
 /**
  * An action refused the request for a business reason. The message is written for the caller and is
  * returned to them.
  */
 export class ActionRejected extends Schema.TaggedError()("ActionRejected", {
     message: Schema.String,
+    batch: Schema.optionalKey(BatchErrorDetails),
 }) {
 }
 /**
@@ -22,6 +28,7 @@ export class Conflict extends Schema.TaggedError()("Conflict", {
     entity: Schema.String,
     message: Schema.String,
     property: Schema.optionalKey(Schema.String),
+    batch: Schema.optionalKey(BatchErrorDetails),
 }) {
 }
 /** The record does not exist. */
@@ -29,5 +36,6 @@ export class NotFound extends Schema.TaggedError()("NotFound", {
     entity: Schema.String,
     id: Schema.String,
     message: Schema.String,
+    batch: Schema.optionalKey(BatchErrorDetails),
 }) {
 }

package/dist/index.d.ts

@@ -13,8 +13,8 @@ export type { EntityPermissions, JsonSchemaObject, MemberOptions, OntologyConfig
 export { Diagnostic, DIAGNOSTIC_CODES, formatDiagnostics, InvalidOntology } from "./diagnostics.js";
 export type { DiagnosticCode } from "./diagnostics.js";
 export { entity, isEntity } from "./entity.js";
-export type { ActionsBuilder, AnyEntity, AnyStoredEntity, CreateValues, DraftEntity, Entity, EntityDefinition, EntityRecord, IndexDefinition, IndexField, NoActions, Properties, RecordRef, Relationships, SystemFields, UpdateValues, } from "./entity.js";
-export { ActionRejected, Conflict, NotFound, PermissionDenied } from "./errors.js";
+export type { ActionsBuilder, AnyEntity, AnyStoredEntity, BatchCreateValues, BatchKey, BatchUpdateRecord, BatchUpdateValues, BatchUpsertValues, CreateValues, DraftEntity, Entity, EntityDefinition, EntityRecord, IndexDefinition, IndexField, NoActions, Properties, RecordRef, Relationships, SystemFields, UpdateValues, } from "./entity.js";
+export { ActionRejected, BatchErrorDetails, Conflict, NotFound, PermissionDenied, } from "./errors.js";
 export type { ActionError } from "./errors.js";
 export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, isValueMatched, MANIFEST_VERSION, manifestHash, ModelMeasureManifest, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
 export { SYSTEM_PROPERTIES } from "./names.js";
@@ -34,7 +34,7 @@ export type { Role, RoleOptions } from "./role.js";
 export { DEFAULT_SIGN_IN_POLICY, SIGN_IN_METHODS, SIGN_IN_POLICIES } from "./sign-in.js";
 export type { SignInCheck, SignInMethod, SignInOptions, SignInPolicy } from "./sign-in.js";
 export { OntologyReads, OntologyRuntime, OntologyWrites } from "./runtime.js";
-export type { FieldCondition, OntologyRuntimeService, FindOptions, GetOptions, Principal, RecordWhere, StoredRecord, StoredValues, UpsertResult, } from "./runtime.js";
+export type { BatchOptions, BatchRecordResult, BatchResult, BatchReturning, BatchSummaryResult, CreateManyInput, FieldCondition, OntologyRuntimeService, FindOptions, GetOptions, Principal, RecordWhere, StoredRecord, StoredValues, UpsertResult, UpdateManyInput, UpsertManyInput, } from "./runtime.js";
 export { User } from "./user.js";
 export { AgentChannel, AgentChat } from "./agent-chat.js";
 export type { AgentMessage } from "./agent-chat.js";

package/dist/index.js

@@ -6,7 +6,7 @@ export { action, isAction } from "./action.js";
 export { CONNECTION_ERROR_REASONS, CONNECTION_KEY, CONNECTION_METHODS, connection, ConnectionError, Connections, ConnectionTransport, isConnection, MAXIMUM_CONNECTION_BODY_BYTES, } from "./connection.js";
 export { Diagnostic, DIAGNOSTIC_CODES, formatDiagnostics, InvalidOntology } from "./diagnostics.js";
 export { entity, isEntity } from "./entity.js";
-export { ActionRejected, Conflict, NotFound, PermissionDenied } from "./errors.js";
+export { ActionRejected, BatchErrorDetails, Conflict, NotFound, PermissionDenied, } from "./errors.js";
 export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, isValueMatched, MANIFEST_VERSION, manifestHash, ModelMeasureManifest, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
 export { SYSTEM_PROPERTIES } from "./names.js";
 export { check, defineOntology } from "./ontology.js";

package/dist/runtime/batch-diagnostics.d.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import type { EntityModel } from "./model.js";
+interface CauseDiagnostic {
+    readonly tag: string;
+    readonly message: string;
+    readonly messageRedacted: boolean;
+    readonly stack?: string;
+}
+/** A safe projection of every wrapper; the original driver cause stays on the Conflict itself. */
+export declare function batchConflictDiagnostic(entity: EntityModel, error: SqlError): {
+    causeChain: CauseDiagnostic[];
+    constraint?: string | undefined;
+    sqlState: string;
+};
+/** Emit before mapping the error, so even a handler-caught conflict has a correlated diagnostic. */
+export declare function logBatchConflict(entity: EntityModel, error: SqlError, scope: {
+    readonly operation: string;
+    readonly action: string;
+    readonly actionId: string;
+}): Effect.Effect<void>;
+export {};

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,48 @@
+import { Effect } from "effect";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { ActionRejected, Conflict, NotFound } 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 } 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 | 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. */
+export declare function executeBatch(context: BatchContext, entity: EntityModel, plan: BatchPlan): Effect.Effect<BatchResult, BatchError>;
+export {};