@ultimat3/entity 2.0.0 → 3.0.0

package/src/columns.ts

@@ -10,11 +10,20 @@ import {
   isMoneyScale,
   MAX_MONEY_SCALE,
 } from '@ultimat3/schema';
-import { BARE, column, GENERATED_UUID, makeColumn, makeTimestamp } from './column';
+import {
+  assertColumnName,
+  BARE,
+  column,
+  GENERATED_UUID,
+  makeColumn,
+  makeTimestamp,
+} from './column';
 import { invariantViolated } from './errors';
 import type {
   Column,
   ColumnMap,
+  ColumnMeta,
+  MoneyColumnNames,
   MoneyInput,
   MoneyValue,
   TimestampColumn,
@@ -64,16 +73,22 @@ const parseBrandedUuid = <T extends string>(value: unknown): T => parseUuid(valu
  * derivation — row, insert, `findById`, `update`, `delete` — so mixing two entities' ids is a
  * compile error instead of a query that silently matches nothing.
  */
-export const uuid = <T extends string = string>(): UuidColumn<T> => ({
-  ...makeColumn<T, false>({ ...BARE, kind: 'uuid' }, parseBrandedUuid, false),
+export const uuid = <T extends string = string>(): UuidColumn<T> =>
+  uuidWith({ ...BARE, kind: 'uuid' });
+
+const uuidWith = <T extends string>(meta: ColumnMeta): UuidColumn<T> => ({
+  ...makeColumn<T, false>(meta, parseBrandedUuid, false),
   // Narrower than the generic chain: a uuid key is generated when omitted, so it is the one
   // primary key an insert may leave out.
   primaryKey: () =>
     makeColumn<T, true>(
-      { ...BARE, kind: 'uuid', primaryKey: true, default: GENERATED_UUID },
+      { ...meta, primaryKey: true, default: GENERATED_UUID },
       parseBrandedUuid,
       true,
     ),
+  // Overridden for the same reason `timestamp()`'s is: `uuid().column('user_id').primaryKey()`
+  // must still be the KEY form, which is optional on insert, rather than the general one.
+  column: (name) => uuidWith<T>({ ...meta, name: assertColumnName(name) }),
 });
 
 export interface TextOptions {
@@ -294,7 +309,34 @@ const parseMoney = (value: unknown): MoneyValue => {
  * silent 10,000x reinterpretation of a value the type system, `t.money` and `@ultimat3/money` all
  * carry. `null` in the column is "no explicit scale" and decodes to an ABSENT key, never to `0`.
  */
-export const money = (): Column<MoneyValue> => column<MoneyValue>('money', parseMoney);
+export interface MoneyOptions {
+  /**
+   * Where the three columns already live, for a table this framework did not create. Named per
+   * part and merged over `<name>_minor` / `<name>_currency` / `<name>_scale`, so a legacy
+   * `amount_cents` beside a `currency` is two words rather than three.
+   *
+   * `scale: null` says the table has no scale column at all. What that costs is stated where the
+   * option is declared (`MoneyColumnNames`): every amount is then at the currency's own minor
+   * unit. What it does NOT cost is correctness — an absent scale already means exactly that.
+   */
+  readonly columns?: MoneyColumnNames;
+}
+
+export const money = (options: MoneyOptions = {}): Column<MoneyValue> =>
+  column<MoneyValue>(
+    'money',
+    parseMoney,
+    options.columns === undefined ? {} : { parts: checkedParts(options.columns) },
+  );
+
+/** Every part named goes through the same identifier rule a `.column()` does. */
+const checkedParts = (columns: MoneyColumnNames): MoneyColumnNames => ({
+  ...(columns.minor === undefined ? {} : { minor: assertColumnName(columns.minor) }),
+  ...(columns.currency === undefined ? {} : { currency: assertColumnName(columns.currency) }),
+  ...(columns.scale === undefined || columns.scale === null
+    ? { ...(columns.scale === null ? { scale: null } : {}) }
+    : { scale: assertColumnName(columns.scale) }),
+});
 
 /**
  * Money is the one column whose write type is wider than its row type — `MoneyInput` takes a

package/src/describe.ts

@@ -5,7 +5,7 @@
 // Money is the one place the projection is not one-to-one: one property becomes the two
 // physical columns that back it.
 
-import { referenceBinding, snake } from './column';
+import { columnName, moneyColumns, referenceBinding } from './column';
 import { currencyCheck, scaleCheck } from './columns';
 import type { Invariant } from './invariants';
 import type { ColumnDescription, EntityDescription, ReferenceDescription } from './registry';
@@ -13,6 +13,8 @@ import type { AnyColumn, ColumnMeta, IndexDef } from './types';
 
 export interface DescribeInput<Row> {
   readonly name: string;
+  /** The physical table. The entity's own name unless `entity(name, { table })` said otherwise. */
+  readonly table: string;
   readonly columns: readonly (readonly [string, AnyColumn])[];
   readonly primaryKey: readonly string[];
   readonly invariants: readonly Invariant<Row>[];
@@ -41,7 +43,7 @@ export const describeReferences = (
     return [
       {
         property,
-        column: snake(property),
+        column: columnName(property, meta),
         nullable: !meta.notNull,
         targetEntity: target.table,
         targetProperty: target.property,
@@ -50,15 +52,38 @@ export const describeReferences = (
     ];
   });
 
+/**
+ * The Postgres type a column becomes. `kind` is what the migration generator reads and its table
+ * falls through to the kind itself for anything it does not name (`SQL_TYPES[kind] ?? kind`), so a
+ * precise type belongs HERE, where the precision, the element and the length are still in scope —
+ * the alternative is a second copy of the column vocabulary inside `@ultimat3/db`.
+ */
+export const sqlTypeOf = (meta: ColumnMeta): string => {
+  if (meta.kind === 'numeric') {
+    return meta.precision === undefined || meta.numericScale === undefined
+      ? 'numeric'
+      : `numeric(${meta.precision}, ${meta.numericScale})`;
+  }
+  if (meta.kind === 'array') {
+    const element = meta.element?.$meta;
+    // `arrayOf` refuses an element that is not one scalar column, so this is total in practice;
+    // `text[]` is the answer that keeps a description renderable rather than throwing inside a
+    // projection, which is the one place an error has no caller to instruct.
+    return `${element === undefined ? 'text' : sqlTypeOf(element)}[]`;
+  }
+  return meta.kind;
+};
+
 const describeColumn = <Row>(
   input: DescribeInput<Row>,
   property: string,
   meta: ColumnMeta,
   reference: ReferenceDescription | undefined,
 ): readonly ColumnDescription[] => {
-  const physical = snake(property);
+  const physical = columnName(property, meta);
   if (meta.kind === 'money') {
-    const currency = `${physical}_currency`;
+    const parts = moneyColumns(property, meta);
+    const currency = parts.currency;
     const shared = {
       notNull: meta.notNull,
       primaryKey: false,
@@ -69,7 +94,7 @@ const describeColumn = <Row>(
     return [
       {
         property: `${property}Minor`,
-        column: `${physical}_minor`,
+        column: parts.minor,
         kind: 'bigint',
         check: null,
         ...shared,
@@ -85,21 +110,29 @@ const describeColumn = <Row>(
       // currency's own minor unit", which is every amount written before the column existed and
       // every ordinary price after it. A NOT NULL here would demand a scale on values that have
       // none, and `0` is not that value — it means whole units.
-      {
-        property: `${property}Scale`,
-        column: `${physical}_scale`,
-        kind: 'integer',
-        check: scaleCheck(`${physical}_scale`),
-        ...shared,
-        notNull: false,
-      },
+      //
+      // Absent entirely when the table has none: an adopted amount column predating scale is two
+      // physical columns, and describing a third would put a column in the DDL and in every
+      // statement that the table does not have.
+      ...(parts.scale === null
+        ? []
+        : [
+            {
+              property: `${property}Scale`,
+              column: parts.scale,
+              kind: 'integer',
+              check: scaleCheck(parts.scale),
+              ...shared,
+              notNull: false,
+            },
+          ]),
     ];
   }
   return [
     {
       property,
       column: physical,
-      kind: meta.kind,
+      kind: sqlTypeOf(meta),
       notNull: meta.notNull,
       primaryKey: meta.primaryKey || input.primaryKey.includes(property),
       unique: meta.unique,
@@ -114,6 +147,10 @@ const describeColumn = <Row>(
 };
 
 export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescription => {
+  const physicalOf = (property: string): string => {
+    const column = input.columns.find(([key]) => key === property)?.[1];
+    return column === undefined ? property : columnName(property, column.$meta);
+  };
   const references = new Map(
     describeReferences(input.name, input.columns).map((reference) => [
       reference.property,
@@ -122,8 +159,8 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
   );
   return {
     name: input.name,
-    table: input.name,
-    primaryKey: input.primaryKey.map((property) => snake(property)),
+    table: input.table,
+    primaryKey: input.primaryKey.map(physicalOf),
     columns: input.columns.flatMap(([property, column]) =>
       describeColumn(input, property, column.$meta, references.get(property)),
     ),

package/src/entity.ts

@@ -5,7 +5,7 @@
 
 import { systemClock } from '@ultimat3/core';
 import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
-import { bindColumn, snake } from './column';
+import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
 import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
@@ -33,6 +33,15 @@ export interface IndexInit<C extends ColumnMap> {
 
 export interface EntityInit<C extends ColumnMap> {
   readonly columns: C;
+  /**
+   * The physical table, when it is not the entity's own name. The half of adoption a column name
+   * cannot cover: `entity('user', { table: 'users', … })` reads and writes the table that is
+   * already there, and every statement, index name and foreign key follows it.
+   *
+   * The entity NAME stays the framework's key — the registry, the cache tag, `x entities describe`
+   * and every relation are keyed by it — so renaming a table never moves a cache tag or a policy.
+   */
+  readonly table?: string;
   /**
    * The tenant column, said out loud. Omitted, it is inferred from `.tenant()` or a column named
    * `orgId`, so silence never means unscoped.
@@ -117,6 +126,7 @@ export const entity = <const C extends ColumnMap>(
   const entries: readonly (readonly [string, AnyColumn])[] = Object.entries(init.columns);
   for (const [property, column] of entries) bindColumn(column, name, property);
 
+  const table = init.table === undefined ? name : assertColumnName(init.table);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
@@ -147,19 +157,22 @@ export const entity = <const C extends ColumnMap>(
           `${property} is money: name ${property}.minor or ${property}.currency`,
         );
       }
-      return snake(property);
+      return columnName(property, column.$meta);
     }
     if (!isMoney || !MONEY_PARTS.has(part)) {
       throw invariantViolated(name, property, `${property} has no part "${part}"`);
     }
-    return `${snake(property)}_${part}`;
+    const parts = moneyColumns(property, column.$meta);
+    return part === 'minor' ? parts.minor : parts.currency;
   };
 
   const columnsExpr = invariantColumns<C>(
     name,
     entries.map(([property]) => property),
   );
-  const partialWhere = softDelete ? `${snake(SOFT_DELETE_COLUMN)} is null` : undefined;
+  // Through the one resolver, so a soft-delete column the table spells differently is still the
+  // column every partial index excludes rows by.
+  const partialWhere = softDelete ? `${resolve([SOFT_DELETE_COLUMN])} is null` : undefined;
   // Called once, here, so an unknown column throws while the entity is being declared.
   const invariants: readonly Invariant<Row>[] = (init.invariants?.(columnsExpr) ?? []).map((def) =>
     bindInvariant<Row>(def, resolve, partialWhere),
@@ -169,9 +182,11 @@ export const entity = <const C extends ColumnMap>(
     ...entries.flatMap(([property, column]) => {
       const meta = column.$meta;
       if (!meta.unique && !meta.index) return [];
-      const physical = [meta.kind === 'money' ? `${snake(property)}_minor` : snake(property)];
+      const physical = [
+        meta.kind === 'money' ? moneyColumns(property, meta).minor : columnName(property, meta),
+      ];
       return [
-        { name: indexName(name, physical, meta.unique), columns: physical, unique: meta.unique },
+        { name: indexName(table, physical, meta.unique), columns: physical, unique: meta.unique },
       ];
     }),
     ...(init.indexes ?? []).map((index) => {
@@ -191,7 +206,7 @@ export const entity = <const C extends ColumnMap>(
         );
       }
       return {
-        name: indexName(name, columns, unique),
+        name: indexName(table, columns, unique),
         columns,
         unique,
         ...(index.order === undefined ? {} : { order: index.order }),
@@ -208,6 +223,7 @@ export const entity = <const C extends ColumnMap>(
   const describe = (): EntityDescription =>
     describeEntity({
       name,
+      table,
       columns: entries,
       primaryKey,
       invariants,
@@ -251,7 +267,7 @@ export const entity = <const C extends ColumnMap>(
 
   const core: EntityCore<Row, C> = {
     $name: name,
-    $table: name,
+    $table: table,
     $columns: init.columns,
     $primaryKey: primaryKey,
     $indexes: indexes,
@@ -289,7 +305,7 @@ export const entity = <const C extends ColumnMap>(
     $references: references,
   };
 
-  registerEntity({ name, tableName: name, describe, references });
+  registerEntity({ name, tableName: table, describe, references });
   // The columns land on the entity itself so `orgs.id` is a column reference; every framework
   // member is `$`-prefixed, which is why a column may be called `name`.
   return Object.assign(core, init.columns);

package/src/index.ts

@@ -4,7 +4,9 @@
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export type { BatchIterator } from './batch';
-export type { TextOptions } from './columns';
+export type { MoneyColumns } from './column';
+export { columnName, moneyColumns, snake } from './column';
+export type { MoneyOptions, TextOptions } from './columns';
 export {
   boolean,
   enumerated,
@@ -18,11 +20,18 @@ export {
   url,
   uuid,
 } from './columns';
+// The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
+// are decisions this framework made for a table it was going to create, and these are the shapes
+// a table already has (`docs`: Entities-And-Migrations, "Adopting an existing database").
+export type { DecimalOptions } from './columns-data';
+export { arrayOf, bigint, bytes, date, decimal, json } from './columns-data';
 // `crossTenantReason` stays internal: an app that could read the flag would have a second way to
 // reason about tenant scope — branch on it — next to the one way, which is entering the scope.
 export { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant';
 export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
 export { database, defaultDriver, memoryDriver } from './database';
+export type { DescribeInput } from './describe';
+export { sqlTypeOf } from './describe';
 export type { Entity, EntityCore, EntityInit, IndexInit } from './entity';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
 export type {
@@ -102,8 +111,18 @@ export type {
   UpsertArgs,
 } from './repo';
 export { memoryRepo, memoryTransactor } from './repo';
-export type { Seed, SeedContext, SeedOptions } from './seed';
-export { defineSeed, seedId } from './seed';
+export type {
+  Seed,
+  SeedContext,
+  SeedInit,
+  SeedKey,
+  SeedMetrics,
+  SeedOptions,
+  SeedRun,
+  SeedTier,
+  SeedWrite,
+} from './seed';
+export { defineSeed, isSeed, SEED_TIERS, seedId, seedTiersFor } from './seed';
 export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
 export {
   assertRowTenant,
@@ -127,6 +146,7 @@ export type {
   IdOf,
   IndexDef,
   Insertable,
+  MoneyColumnNames,
   MoneyInput,
   MoneyValue,
   OnDelete,

package/src/pg-driver.ts

@@ -25,7 +25,6 @@ import {
   upsertPlan,
 } from './bulk-write';
 import { coalesceFindById } from './coalesce';
-import { snake } from './column';
 import { countsFrom, groupColumnOf, groupValue, MAX_GROUPS } from './count-by';
 import { cursorFor, seekFrom, valueAt } from './cursor';
 import type { Driver } from './database';
@@ -33,7 +32,7 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { notFound, repoClientPinned } from './errors';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
 import { forgetPreloaded, tagSiblings } from './jit-preload';
-import { bindValues, decodeRow, type PhysicalRow } from './pg-row';
+import { bindValues, decodeRow, type PhysicalRow, physicalName } from './pg-row';
 import {
   type ConflictTarget,
   countByStatement,
@@ -133,7 +132,7 @@ export const postgresRepo = <Row>(
       ? updateStatement(
           entity,
           plan,
-          new Map([[snake(SOFT_DELETE_COLUMN), systemClock.now()]]),
+          new Map([[physicalName(entity, SOFT_DELETE_COLUMN), systemClock.now()]]),
           shapeOf({}),
           false,
         )

package/src/pg-row.ts

@@ -4,7 +4,7 @@
 // from the driver is re-parsed by the column that declared it rather than trusted — int8 arrives
 // as a string, timestamptz may arrive as one, and a silent `NaN` is worse than a loud throw.
 
-import { snake } from './column';
+import { columnName, moneyColumns } from './column';
 import { narrowMoney } from './columns';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
@@ -23,10 +23,15 @@ const MONEY_PARTS = new Set(['minor', 'currency']);
  * addressable as a predicate or a sort key (`MONEY_PARTS` below, and `cursor.ts`'s copy) — a scale
  * says which units `minor` counts, so ordering or filtering by it compares two different questions.
  */
-export const columnsOf = (property: string, column: AnyColumn): readonly string[] =>
-  column.$meta.kind === 'money'
-    ? [`${snake(property)}_minor`, `${snake(property)}_currency`, `${snake(property)}_scale`]
-    : [snake(property)];
+export const columnsOf = (property: string, column: AnyColumn): readonly string[] => {
+  if (column.$meta.kind !== 'money') return [columnName(property, column.$meta)];
+  const parts = moneyColumns(property, column.$meta);
+  // Two columns for an adopted amount that has no scale column: the list IS the projection, so a
+  // name here that the table does not have is a `42703` on the first select.
+  return parts.scale === null
+    ? [parts.minor, parts.currency]
+    : [parts.minor, parts.currency, parts.scale];
+};
 
 /**
  * A predicate or sort key names a property, never a physical column — so `orgId` becomes
@@ -44,7 +49,7 @@ export const physicalName = <Row>(entity: EntityCore<Row>, path: string): string
   }
   const isMoney = column.$meta.kind === 'money';
   if (part === undefined) {
-    if (!isMoney) return snake(property);
+    if (!isMoney) return columnName(property, column.$meta);
     throw invariantViolated(
       entity.$name,
       property,
@@ -54,7 +59,8 @@ export const physicalName = <Row>(entity: EntityCore<Row>, path: string): string
   if (!isMoney || !MONEY_PARTS.has(part)) {
     throw invariantViolated(entity.$name, property, `${property} has no part "${part}"`);
   }
-  return `${snake(property)}_${part}`;
+  const parts = moneyColumns(property, column.$meta);
+  return part === 'minor' ? parts.minor : parts.currency;
 };
 
 /** Every physical column of the entity, in declaration order. */
@@ -77,26 +83,63 @@ export const bindValues = <Row>(
     if (!Object.hasOwn(record, property)) continue;
     const value = record[property];
     if (column.$meta.kind !== 'money') {
-      bound.set(snake(property), value ?? null);
+      bound.set(columnName(property, column.$meta), bindable(column, value));
       continue;
     }
+    const parts = moneyColumns(property, column.$meta);
     const money = value as MoneyValue | null | undefined;
-    bound.set(`${snake(property)}_minor`, money?.minor ?? null);
-    bound.set(`${snake(property)}_currency`, money?.currency ?? null);
+    bound.set(parts.minor, money?.minor ?? null);
+    bound.set(parts.currency, money?.currency ?? null);
     // `?? null` and not `!== undefined`: an amount at the currency's own scale carries no key at
     // all, and that absence is what the nullable column stores. A `0` written here for it would
     // claim whole units — a 100x reinterpretation of every ordinary price.
-    bound.set(`${snake(property)}_scale`, money?.scale ?? null);
+    if (parts.scale !== null) bound.set(parts.scale, money?.scale ?? null);
   }
   return bound;
 };
 
-const moneyOf = (source: PhysicalRow, minor: string, currency: string, scale: string): unknown => {
+/**
+ * One array element, as a Postgres array literal spells it. Quoted always: an unquoted element
+ * containing a comma, a brace or a backslash is a different array, and an empty string unquoted
+ * is nothing at all.
+ */
+const arrayElement = (value: unknown): string => {
+  if (value === null || value === undefined) return 'NULL';
+  const text =
+    value instanceof Date ? value.toISOString() : typeof value === 'object' ? '' : String(value);
+  return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+};
+
+/**
+ * The value a parameter carries. Every column but one hands its row value straight over — the
+ * measured driver behaviour is that an object binds to `jsonb`, a string binds to `numeric`,
+ * `int8` and `date`, and a `Uint8Array` binds to `bytea`.
+ *
+ * An array is the one that cannot: Bun's `sql` serialises a JS array to `x,y`, which Postgres
+ * answers with `malformed array literal` (measured). What it accepts is the literal, so this is
+ * where a JS array becomes one.
+ */
+const bindable = (column: AnyColumn, value: unknown): unknown => {
+  if (value === null || value === undefined) return null;
+  // A plain object is not a bindable parameter (`X_SQL_UNSAFE`), so a `jsonb` value crosses as its
+  // TEXT and `pg-sql.ts`'s cell casts it back — see `cellCast` for why the cast is `::text::jsonb`.
+  if (column.$meta.kind === 'jsonb') return JSON.stringify(value);
+  if (column.$meta.kind !== 'array' || !Array.isArray(value)) return value;
+  return `{${value.map(arrayElement).join(',')}}`;
+};
+
+const moneyOf = (
+  source: PhysicalRow,
+  minor: string,
+  currency: string,
+  scale: string | undefined,
+): unknown => {
   const amount = source[minor];
   if (amount === null || amount === undefined) return null;
   // A column the projection left out is absent, not null — and absent must read as "no scale"
-  // exactly as a stored NULL does, so both take the same branch.
-  const declared = source[scale];
+  // exactly as a stored NULL does, so both take the same branch. So does a table that has no
+  // scale column at all, which is why the name itself may be `undefined`.
+  const declared = scale === undefined ? undefined : source[scale];
   return {
     minor: amount,
     currency: String(source[currency] ?? '').trim(),
@@ -113,10 +156,13 @@ export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Ro
   for (const [property, column] of Object.entries(entity.$columns)) {
     const [head, currency, scale] = columnsOf(property, column);
     if (head === undefined || !(head in source)) continue;
+    // Decided by the column's KIND and never by how many names came back: a money column whose
+    // table has no scale column projects two names, and reading that as a non-money column handed
+    // the caller a raw minor unit where a `Money` belongs.
     const value =
-      currency === undefined || scale === undefined
-        ? source[head]
-        : moneyOf(source, head, currency, scale);
+      column.$meta.kind === 'money' && currency !== undefined
+        ? moneyOf(source, head, currency, scale)
+        : source[head];
     if (value !== null && value !== undefined) {
       row[property] = column.$parse(value);
       continue;

package/src/pg-sql.ts

@@ -4,7 +4,7 @@
 // declared. That is the whole reason this file exists instead of a template literal per method.
 
 import { identifier, join, raw, type SqlFragment, sql } from '@ultimat3/db';
-import { snake } from './column';
+import { columnName } from './column';
 import type { EntityCore } from './entity';
 import { SOFT_DELETE_COLUMN } from './entity';
 import { allColumns, columnsOf, physicalName } from './pg-row';
@@ -111,7 +111,7 @@ const conditions = <Row>(
 ): SqlFragment => {
   const parts = plan.where.map((predicate) => predicateSql(entity, predicate));
   if (entity.$softDelete && !shape.includeDeleted) {
-    parts.push(sql`${identifier(snake(SOFT_DELETE_COLUMN))} is null`);
+    parts.push(sql`${identifier(physicalName(entity, SOFT_DELETE_COLUMN))} is null`);
   }
   if (shape.seek !== undefined) parts.push(seekSql(entity, plan.orderBy, shape.seek));
   return parts.length === 0 ? sql`true` : join(parts, ' and ');
@@ -224,6 +224,35 @@ const conflictSql = (conflict: ConflictTarget): SqlFragment => {
       )}`;
 };
 
+/**
+ * The one column that cannot be bound as itself. A `jsonb` value is a plain object, and the
+ * driver seam refuses one as a parameter (`X_SQL_UNSAFE` — `isBoundValue` takes scalars, a `Date`,
+ * a `Uint8Array` and arrays of those); so `bindValues` hands over the JSON TEXT and the cell says
+ * what to do with it.
+ *
+ * `::text::jsonb` and not `::jsonb`, and the double cast is load-bearing rather than defensive.
+ * Measured against Postgres 17.10 through Bun's `sql`: with `$1::jsonb` the server describes the
+ * parameter as `jsonb`, the client JSON-ENCODES the string it was given, and `{"a":1}` is stored
+ * as the JSON *string* `"{\"a\":1}"` — `jsonb_typeof` says `string`. Pinning the parameter to
+ * `text` first makes the client send the characters and the server parse them, which is the one
+ * spelling that stores an object.
+ */
+/** Physical names of this entity's `jsonb` columns. Resolved ONCE per statement, never per cell. */
+const jsonColumns = <Row>(entity: EntityCore<Row>): ReadonlySet<string> => {
+  const names = new Set<string>();
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (column.$meta.kind === 'jsonb') names.add(columnName(property, column.$meta));
+  }
+  return names;
+};
+
+/**
+ * `${value}`, plus the cast that column needs. The `raw()` argument is a literal written here and
+ * nowhere else — the audit point that call is stays a two-word constant, never a value.
+ */
+const cell = (json: ReadonlySet<string>, column: string, value: unknown): SqlFragment =>
+  json.has(column) ? sql`${value}${raw('::text::jsonb')}` : sql`${value}`;
+
 /**
  * One statement for any number of rows. A single row compiles to exactly the text it always did,
  * which is the point: `insertAll([row])` and `insert(row)` are one code path, so there is no
@@ -234,10 +263,13 @@ export const insertStatement = <Row>(
   rows: readonly ReadonlyMap<string, unknown>[],
   shape: InsertShape,
 ): SqlFragment => {
+  const json = jsonColumns(entity);
   const tuples = rows.map(
     (row) =>
       sql`(${join(
-        shape.columns.map((column) => (row.has(column) ? sql`${row.get(column)}` : DEFAULT_CELL)),
+        shape.columns.map((column) =>
+          row.has(column) ? cell(json, column, row.get(column)) : DEFAULT_CELL,
+        ),
       )})`,
   );
   const conflict = shape.conflict === undefined ? sql`` : conflictSql(shape.conflict);
@@ -259,10 +291,12 @@ export const updateStatement = <Row>(
   values: ReadonlyMap<string, unknown>,
   shape: ReadShape,
   returning: boolean,
-): SqlFragment =>
-  sql`update ${identifier(entity.$table)} set ${join(
-    [...values].map(([column, value]) => sql`${identifier(column)} = ${value}`),
+): SqlFragment => {
+  const json = jsonColumns(entity);
+  return sql`update ${identifier(entity.$table)} set ${join(
+    [...values].map(([column, value]) => sql`${identifier(column)} = ${cell(json, column, value)}`),
   )} where ${conditions(entity, plan, shape)}${returning ? sql` returning *` : sql``}`;
+};
 
 /** Only reached when the entity has no soft-delete column, so there is no filter to apply. */
 export const deleteStatement = <Row>(entity: EntityCore<Row>, plan: QueryPlan): SqlFragment =>