@ultimat3/entity 1.2.0 → 3.0.0

package/src/type-pins.ts

@@ -0,0 +1,311 @@
+// Compile-time pins for the two type positions this package has already regressed in. Source, not
+// a `.test.ts`, on purpose: `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a
+// test file and a type-level assertion written there can never fail. Everything below is erased —
+// the module emits nothing — and a regression is a build error, which is the only kind of
+// enforcement this repo counts (axiom 3).
+
+import type { Id } from '@ultimat3/core';
+import type { MoneyValue as SchemaMoneyValue } from '@ultimat3/schema';
+import type { uuid } from './columns';
+import type { EntitySet } from './database';
+import type { Entity, EntityCore, EntityInit } from './entity';
+import type { ColumnExpr, InvariantColumns } from './expr';
+import type { Invariant, InvariantDef } from './invariants';
+import type { Table } from './query';
+import type { Repo } from './repo';
+import type { AnyColumn, IdOf, Insertable, MoneyInput, MoneyValue, RowOf } from './types';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+/**
+ * Shaped like a declared column set; only its keys and its derived row take part. A type alias,
+ * not an interface: only an alias gets the implicit index signature `ColumnMap` asks for.
+ */
+type PinColumns = {
+  readonly title: AnyColumn;
+  readonly price: AnyColumn;
+};
+
+type PinRow = RowOf<PinColumns>;
+
+/** Ambient: a type query needs a value to name, and an ambient declaration emits nothing. */
+declare const pinned: InvariantColumns<PinColumns>;
+
+/**
+ * The defect: `InvariantColumns` was `{ readonly [column: string]: ColumnExpr }`, so under
+ * `noUncheckedIndexedAccess` every `c.title` was `ColumnExpr | undefined` and every generated
+ * entity needed a `!`. Written as a property access rather than an indexed-access type, because
+ * that is the position the flag widens.
+ */
+export type PinColumnIsNotOptional = Assert<undefined extends typeof pinned.title ? false : true>;
+
+export type PinColumnIsAColumnExpr = Assert<
+  [typeof pinned.title] extends [ColumnExpr] ? true : false
+>;
+
+/** An index signature would make every string a key, so a typo would type-check. */
+export type PinUnknownColumnIsNotAKey = Assert<
+  'titel' extends keyof InvariantColumns<PinColumns> ? false : true
+>;
+
+/** `unique()` and `satisfies()` name columns as strings, so they need the same protection. */
+export type PinHelpersTakeDeclaredColumns = Assert<
+  readonly 'titel'[] extends Parameters<InvariantColumns<PinColumns>['unique']>[0] ? false : true
+>;
+
+/**
+ * `invariants` is one callback over the whole list, never an array of `(c) => …` builders: a
+ * per-element builder is a call TypeScript checks before `C` is fixed, so `C` fell back to its
+ * constraint and the mapped type above never reached the author.
+ */
+export type PinInvariantsIsOneCallback = Assert<
+  EntityInit<PinColumns>['invariants'] extends
+    | ((columns: InvariantColumns<PinColumns>) => readonly InvariantDef[])
+    | undefined
+    ? true
+    : false
+>;
+
+/**
+ * `Invariant<T>.holds` is a method, not a `readonly holds: (row: T) => boolean` property. A
+ * function-typed property is checked contravariantly, which made `Invariant<PinRow>` unassignable
+ * to `Invariant<unknown>`, `Entity<PinRow, C>` unassignable to `EntityCore`, and so every
+ * `database({ … })` call degrade to `Table<unknown>` — one position, 36 cascading errors.
+ */
+export type PinInvariantIsBivariant = Assert<
+  [Invariant<PinRow>] extends [Invariant<unknown>] ? true : false
+>;
+
+export type PinEntityIsAnEntityCore = Assert<
+  [Entity<PinRow, PinColumns>] extends [EntityCore] ? true : false
+>;
+
+export type PinEntityMapIsAnEntitySet = Assert<
+  [{ readonly post: Entity<PinRow, PinColumns> }] extends [EntitySet] ? true : false
+>;
+
+// --- Insertable: a nullable column is omissible ------------------------------
+// `nullable()` widens the type to `T | null` without setting `$optional`, so before this pin every
+// insert had to spell out `avatarKey: null, deletedAt: null` — restating an absence the column
+// declaration already carries, for values SQL was going to write as NULL either way. The demo's
+// seed could not compile without that padding, which is precisely the boilerplate this framework
+// exists to delete.
+
+declare const nullableColumn: import('./types').Column<string | null, false>;
+declare const requiredColumn: import('./types').Column<string, false>;
+
+type InsertPinColumns = {
+  readonly required: typeof requiredColumn;
+  readonly optionalByNull: typeof nullableColumn;
+};
+
+type InsertPin = import('./types').Insertable<InsertPinColumns>;
+
+/** The nullable column may be omitted entirely… */
+type _NullableIsOmissible = Assert<{ required: 'x' } extends InsertPin ? true : false>;
+
+/** …and passing `null` explicitly stays legal, so a programmatic caller need not strip keys. */
+type _NullableStillAccepted = Assert<
+  { required: 'x'; optionalByNull: null } extends InsertPin ? true : false
+>;
+
+/** A non-nullable column with no default is still required — the pin must not over-relax. */
+type _RequiredStaysRequired = Assert<{ optionalByNull: null } extends InsertPin ? false : true>;
+
+// --- The bulk write path keeps every narrowing the single-row one has ---------
+// `insertAll`/`upsertAll` are `insert` in bulk, and a bulk signature is exactly where one quietly
+// widens: `readonly Row[]` instead of `readonly Insertable<C>[]` would make every batch spell out
+// the defaults `insert` fills for one row, and a `readonly string[]` conflict target would push a
+// typo the single-row path never had to the runtime guard.
+
+type InsertPinTable = Table<RowOf<InsertPinColumns>, InsertPinColumns>;
+type ConflictTarget = Parameters<InsertPinTable['upsertAll']>[1]['onConflict'];
+
+/** A batch is `Insertable`, so a nullable column stays omissible a hundred rows at a time. */
+type _InsertAllTakesInsertables = Assert<
+  readonly { required: 'x' }[] extends Parameters<InsertPinTable['insertAll']>[0] ? true : false
+>;
+
+/** What comes back is the stored row, never the insertable the caller handed in. */
+type _InsertAllResolvesWithRows = Assert<
+  [Awaited<ReturnType<InsertPinTable['insertAll']>>] extends [readonly RowOf<InsertPinColumns>[]]
+    ? true
+    : false
+>;
+
+type _ConflictTargetTakesADeclaredColumn = Assert<
+  readonly 'required'[] extends ConflictTarget ? true : false
+>;
+
+/** The narrowing that matters: a misspelled conflict target is a compile error, not a rejection. */
+type _ConflictTargetRejectsATypo = Assert<
+  readonly 'requiredd'[] extends ConflictTarget ? false : true
+>;
+
+// --- A branded id survives the whole type chain ------------------------------
+// `uuid<PostId>()` is where the brand is declared, and every hop after it has to carry it. The
+// derivation (`TypeOf`, `RowOf`, `Insertable`) always did; the BUILDER hard-coded `Column<string>`
+// so there was nothing to carry, and `Repo`/`Table` then took `id: string`, which is where the
+// last of it went. Both halves are pinned, because fixing either one alone still lets
+// `posts.update(someUserId, …)` compile.
+
+type PostId = Id<'post'>;
+type UserId = Id<'user'>;
+
+/** The builder's own output, not a hand-written `Column<PostId, true>`. */
+type BrandedKey = ReturnType<ReturnType<typeof uuid<PostId>>['primaryKey']>;
+
+type BrandColumns = {
+  readonly id: BrandedKey;
+  readonly authorId: ReturnType<typeof uuid<UserId>>;
+  readonly title: typeof requiredColumn;
+};
+
+type BrandRow = RowOf<BrandColumns>;
+
+type _BrandSurvivesTheRow = Assert<[BrandRow['id']] extends [PostId] ? true : false>;
+
+/** The half that matters: a plain string is no longer good enough to be a post id. */
+type _RowIdIsNotAPlainString = Assert<[string] extends [BrandRow['id']] ? false : true>;
+
+/** Two entities' ids do not mix, which is the whole reason to declare one. */
+type _BrandsDoNotMix = Assert<[BrandRow['authorId']] extends [PostId] ? false : true>;
+
+/** The write path too — an insert that names the wrong entity's id is a compile error. */
+type _BrandSurvivesTheInsert = Assert<
+  [Insertable<BrandColumns>['authorId']] extends [UserId] ? true : false
+>;
+
+type _InsertRejectsAnotherBrand = Assert<
+  [PostId] extends [Insertable<BrandColumns>['authorId']] ? false : true
+>;
+
+/** `Repo` was the last hop that erased it: `findById(id: string)` accepted any entity's id. */
+type _FindByIdTakesTheBrand = Assert<
+  [Parameters<Repo<BrandRow>['findById']>[0]] extends [PostId] ? true : false
+>;
+
+type _FindByIdRejectsAnotherBrand = Assert<
+  [UserId] extends [Parameters<Repo<BrandRow>['findById']>[0]] ? false : true
+>;
+
+/**
+ * `UpsertArgs<T>.onConflict` is `readonly (keyof T & string)[]`, which is `readonly never[]` at
+ * `T = unknown` — so a typed repository must still satisfy the row-agnostic one `RelatedTable.repo`
+ * and the generated admin are written against, or narrowing the target breaks the preload seam.
+ */
+type _TypedRepoIsARowAgnosticRepo = Assert<[Repo<BrandRow>] extends [Repo<unknown>] ? true : false>;
+
+type _TableUpdateTakesTheBrand = Assert<
+  [Parameters<Table<BrandRow>['update']>[0]] extends [PostId] ? true : false
+>;
+
+type _TableDeleteRejectsAnotherBrand = Assert<
+  [UserId] extends [Parameters<Table<BrandRow>['delete']>[0]] ? false : true
+>;
+
+/**
+ * …and an unbranded entity is addressed exactly as it was. `IdOf` collapsing to `string` for
+ * every row that declared no brand is what makes this additive rather than a major version.
+ */
+type _UnbrandedIdStaysAString = Assert<
+  [string] extends [IdOf<{ readonly id: string }>] ? true : false
+>;
+
+// --- The batch iteration stays consumable both ways --------------------------
+// `inBatches()` is the one read that hands back a resource instead of a value, and both ways of
+// consuming it are language features rather than methods a call site would obviously miss:
+// `for await` needs `[Symbol.asyncIterator]`, `await using` needs `[Symbol.asyncDispose]`. Losing
+// either is a silent regression — every existing call keeps compiling, and only the loop that was
+// supposed to stop reading stops stopping.
+
+type BatchPin = ReturnType<Table<BrandRow>['inBatches']>;
+
+type _BatchIterates = Assert<
+  [BatchPin] extends [AsyncIterable<readonly BrandRow[]>] ? true : false
+>;
+
+type _BatchDisposes = Assert<[BatchPin] extends [AsyncDisposable] ? true : false>;
+
+/** Batches, never rows: yielding one row at a time is the loop this call exists to replace. */
+type _BatchYieldsBatches = Assert<[BatchPin] extends [AsyncIterable<BrandRow>] ? false : true>;
+
+type _RowAgnosticIdStaysAString = Assert<[string] extends [IdOf<unknown>] ? true : false>;
+
+// --- Money is one declaration, and the wide half is the write half -----------
+// `MoneyValue` was a third structural restatement of `Money` whose `minor` was a `bigint`, so a
+// row this package decoded satisfied neither `t.money` nor `JSON.stringify` — the shape the whole
+// framework passes around was not the shape its own driver produced. It is now an alias of
+// `@ultimat3/schema`'s declaration, which is also what `@ultimat3/money`'s `Money` is; these pins
+// are what stops the next edit from re-declaring it here and re-opening the same gap.
+
+/**
+ * Identity, not mutual assignability: `extends` ignores `readonly`, so the weaker test would pass
+ * against a mutable restatement — which is exactly the drift being pinned against.
+ */
+type Identical<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+
+type _MoneyValueIsSchemasDeclaration = Assert<Identical<MoneyValue, SchemaMoneyValue>>;
+
+/** The value type is a `number`. A `bigint` here is the regression, not a widening. */
+type _MoneyMinorIsANumber = Assert<[MoneyValue['minor']] extends [number] ? true : false>;
+
+// The shape is pinned as independent properties rather than as one literal snapshot of the whole
+// interface. The snapshot said the same thing, but every additive change had to be hand-edited
+// past it — and a pin the next reader learns to hand-edit reflexively has stopped being a check.
+// Only the key set moves when a field is added, which is the one place that decision belongs.
+
+/** No field but these three, ever: a fourth is a shape nobody declared. */
+type _MoneyHasNoOtherField = Assert<
+  [keyof MoneyValue] extends ['minor' | 'currency' | 'scale'] ? true : false
+>;
+
+/** …and none of the three may go — the pin must not pass by the type shrinking instead. */
+type _MoneyHasEveryField = Assert<
+  ['minor' | 'currency' | 'scale'] extends [keyof MoneyValue] ? true : false
+>;
+
+// Immutable, enforced, field by field: a mutable `minor` is a rounding bug with a place to hide.
+// `Pick` carries `readonly` and optionality through, so each of these is exact about one field
+// and says nothing about the others.
+
+type _MoneyMinorIsAReadonlyNumber = Assert<
+  Identical<Pick<MoneyValue, 'minor'>, { readonly minor: number }>
+>;
+
+type _MoneyCurrencyIsAReadonlyString = Assert<
+  Identical<Pick<MoneyValue, 'currency'>, { readonly currency: string }>
+>;
+
+/**
+ * `scale` is the decimal exponent `minor` counts in — `{ minor: 2, currency: 'USD', scale: 6 }` is
+ * $0.000002. Optional, and pinned optional, because a cents-only `Money` could not name a
+ * sub-cent amount at all: the AI cost path rounded a $0.00016 call up to a whole cent, 62x, and
+ * the alternative to this field was a second money type.
+ */
+type _MoneyScaleIsAReadonlyOptionalNumber = Assert<
+  Identical<Pick<MoneyValue, 'scale'>, { readonly scale?: number }>
+>;
+
+/**
+ * The additive half, and the pin that decides the semver: a value carrying no scale is still a
+ * `MoneyValue`, meaning the currency's own minor unit. Every amount already stored, serialized
+ * and asserted against in every app is that shape — so the day this fails, the change that made
+ * it fail is a breaking one and needs a major, not a fix here.
+ */
+type _MoneyWithoutAScaleIsStillMoney = Assert<
+  { readonly minor: number; readonly currency: string } extends MoneyValue ? true : false
+>;
+
+/**
+ * A writer may still hand a `bigint` — that is the additive half, and it is what lets a minor unit
+ * read straight off a `bigint` column reach an insert without a conversion at the call site.
+ */
+type _MoneyInputTakesABigInt = Assert<
+  [{ readonly minor: bigint; readonly currency: string }] extends [MoneyInput] ? true : false
+>;
+
+/** And a row value is always a legal input: read a row, write it back. */
+type _MoneyValueIsMoneyInput = Assert<[MoneyValue] extends [MoneyInput] ? true : false>;

package/src/types.ts

@@ -6,7 +6,15 @@
 // A column carries its TypeScript type in `$parse`, which is what lets the row type be derived
 // from the column set instead of being written a second time as a hand-maintained schema.
 
-/** Postgres types the blessed builders emit. `money` expands to `bigint` + `char(3)`. */
+/**
+ * Postgres types the builders emit. `money` expands to `bigint` + `char(3)` (+ a nullable
+ * `integer` scale); `array` expands to its element's type with `[]` after it.
+ *
+ * The four beyond the blessed set exist for ONE reason: a schema Ultimate did not generate already
+ * has them. A table with a `numeric(18,8)` rate, a `date` a rate takes effect on, a `jsonb` payload
+ * and a `bytea` blob cannot be declared at all without them, and an entity that cannot be declared
+ * is a rewrite instead of an adoption.
+ */
 export type ColumnKind =
   | 'uuid'
   | 'text'
@@ -14,8 +22,12 @@ export type ColumnKind =
   | 'boolean'
   | 'integer'
   | 'bigint'
+  | 'numeric'
   | 'timestamptz'
+  | 'date'
   | 'jsonb'
+  | 'bytea'
+  | 'array'
   | 'money';
 
 export type ColumnDefault =
@@ -28,16 +40,51 @@ export interface ReferenceOptions {
   readonly onDelete?: OnDelete;
 }
 
-/** The single value a money column puts on the row. Two physical columns back it. */
-export interface MoneyValue {
-  readonly minor: bigint;
-  readonly currency: string;
+/**
+ * The single value a money column puts on the row. Two physical columns back it.
+ *
+ * An **alias** of `@ultimat3/schema`'s declaration, which is also what `@ultimat3/money`'s `Money`
+ * is — so a row this package decodes IS a `Money`, assignable to `add()`, `formatMoney()` and
+ * `<Money>` without a cast. It used to be a third, structurally different interface whose `minor`
+ * was a `bigint`, and that was a live defect rather than a stylistic one: `JSON.stringify` throws
+ * on a bigint, so returning a row with a money column from an action crashed the response, and
+ * `t.money` — the schema node that becomes the OpenAPI contract — rejected the framework's own row.
+ */
+import type { MoneyValue } from '@ultimat3/schema';
+
+export type { MoneyValue };
+
+/**
+ * What a writer may hand a money column. An integer `number` is the value type; a `bigint` is
+ * accepted so a minor unit read straight off a `bigint` column (hand-written SQL, a backfill)
+ * needs no conversion at the call site. A float throws, and so does a `bigint` past
+ * `Number.MAX_SAFE_INTEGER` — see `parseMinor` in `columns.ts`.
+ */
+/**
+ * The physical columns behind a money property, when they are not `<name>_minor`,
+ * `<name>_currency` and `<name>_scale`. Named per part and merged over those defaults, so a table
+ * that renamed one column does not have to restate the other two.
+ */
+export interface MoneyColumnNames {
+  readonly minor?: string;
+  readonly currency?: string;
+  /**
+   * `null` says this table has NO scale column — the ordinary shape of a money column written
+   * before scale existed. Every amount in it is then at the currency's own minor unit, which is
+   * what an absent scale already means, so nothing is lost but the ability to store a sub-cent one.
+   */
+  readonly scale?: string | null;
 }
 
-/** What a writer may hand a money column. An integer `number` widens; a float throws. */
 export interface MoneyInput {
   readonly minor: bigint | number;
   readonly currency: string;
+  /**
+   * Carried through the write, never invented: `undefined` means the currency's own minor unit and
+   * `0` means whole units, and the two must not collapse. `null` is accepted because that is what
+   * the `<name>_scale` column holds for an amount that declared none.
+   */
+  readonly scale?: number | null;
 }
 
 /**
@@ -52,7 +99,20 @@ export interface ColumnMeta {
   readonly index: boolean;
   /** Presence of a tenant column is what turns tenancy on. See `tenancy.ts`. */
   readonly tenant: boolean;
+  /**
+   * The physical column, when it is not `snake(property)`. The whole of what makes an existing
+   * table addressable: `githubLogin` on a row, `gh_login` in every statement, decided once here
+   * and read through `columnName()` by every projection.
+   */
+  readonly name?: string;
   readonly length?: number;
+  /** `numeric(precision, scale)` — both, or neither. A bare `numeric` is unbounded on purpose. */
+  readonly precision?: number;
+  readonly numericScale?: number;
+  /** The element column of an `array`, which carries the element's own kind and `$parse`. */
+  readonly element?: AnyColumn;
+  /** Where money's three physical columns live, when the table already named them. */
+  readonly parts?: MoneyColumnNames;
   readonly values?: readonly string[];
   readonly default?: ColumnDefault;
   readonly onUpdate?: ColumnDefault;
@@ -80,16 +140,32 @@ export interface Column<T, Optional extends boolean = false> {
   tenant(): Column<T, Optional>;
   references(target: () => AnyColumn, options?: ReferenceOptions): Column<T, Optional>;
   default(value: T): Column<T, true>;
+  /**
+   * The physical column name, when the table does not spell it `snake(property)`. Name it LAST in
+   * a chain: this link returns the general column, so a builder's own methods (`defaultNow()`,
+   * a uuid key's narrowed `primaryKey()`) are declared before it — `uuid()` and `timestamp()`
+   * override it to keep theirs, and nothing else has any.
+   */
+  column(name: string): Column<T, Optional>;
 }
 
-/** A uuid primary key is generated (v7) when omitted, which is why it narrows to `true`. */
-export interface UuidColumn<Optional extends boolean = false> extends Column<string, Optional> {
-  primaryKey(): Column<string, true>;
+/**
+ * A uuid primary key is generated (v7) when omitted, which is why it narrows to `true`.
+ *
+ * `T` is the declared id type: `uuid<PostId>()` carries the brand from here to the row, the
+ * insert and every repository signature, so a `PostId` cannot be passed where a `UserId` is
+ * wanted. It defaults to `string`, so an unbranded declaration reads exactly as it did.
+ */
+export interface UuidColumn<T extends string = string, Optional extends boolean = false>
+  extends Column<T, Optional> {
+  primaryKey(): Column<T, true>;
+  column(name: string): UuidColumn<T, Optional>;
 }
 
 export interface TimestampColumn<Optional extends boolean = false> extends Column<Date, Optional> {
   defaultNow(): TimestampColumn<true>;
   onUpdateNow(): TimestampColumn<Optional>;
+  column(name: string): TimestampColumn<Optional>;
 }
 
 export type AnyColumn = Column<unknown, boolean>;
@@ -98,6 +174,18 @@ export type ColumnMap = Readonly<Record<string, AnyColumn>>;
 
 export type TypeOf<C> = C extends Column<infer T, boolean> ? T : never;
 
+/**
+ * How a row is addressed: the type its own `id` column declared, or `string` when the entity is
+ * keyed by something else (a composite key, or an unbranded uuid).
+ *
+ * This is where a brand used to die. `RowOf` and `Insertable` carry it through the derivation
+ * without help, but `Repo.findById(id: string)` and `Table.update(id: string, …)` erased it at
+ * the last hop — so `posts.update(someUserId, …)` type-checked and Postgres returned nothing.
+ * `IdOf<Row>` collapses to `string` for every unbranded entity, so nothing that compiled before
+ * stops compiling.
+ */
+export type IdOf<Row> = Row extends { readonly id: infer I extends string } ? I : string;
+
 /** The row type a column set describes. This derivation is why the package exists. */
 export type RowOf<C extends ColumnMap> = {
   readonly [K in keyof C]: TypeOf<C[K]>;
@@ -107,14 +195,28 @@ type DefaultedKeys<C extends ColumnMap> = {
   [K in keyof C]-?: C[K]['$optional'] extends true ? K : never;
 }[keyof C];
 
+/**
+ * A `.nullable()` column is omissible too, and that is not a convenience — it is the difference
+ * between declaring a fact and restating an absence. `nullable()` widens the type to `T | null`
+ * without setting `$optional`, so every insert had to spell out `avatarKey: null, deletedAt: null`
+ * for columns whose whole meaning is "there may be nothing here", and SQL was going to write NULL
+ * either way. That is boilerplate the declaration already contains.
+ *
+ * Omitting it and passing `null` stay equivalent, deliberately: a caller building a row
+ * programmatically should not have to strip keys to avoid a type error.
+ */
+type NullableKeys<C extends ColumnMap> = {
+  [K in keyof C]-?: null extends TypeOf<C[K]> ? K : never;
+}[keyof C];
+
 /** Money is the one column whose write shape is wider than its row shape. */
 type InputOf<T> = T extends MoneyValue ? MoneyInput : T;
 
-/** What an insert must supply: every column except the ones carrying a default. */
+/** What an insert must supply: every column that is neither defaulted nor nullable. */
 export type Insertable<C extends ColumnMap> = {
-  readonly [K in Exclude<keyof C, DefaultedKeys<C>>]: InputOf<TypeOf<C[K]>>;
+  readonly [K in Exclude<keyof C, DefaultedKeys<C> | NullableKeys<C>>]: InputOf<TypeOf<C[K]>>;
 } & {
-  readonly [K in DefaultedKeys<C>]?: InputOf<TypeOf<C[K]>>;
+  readonly [K in DefaultedKeys<C> | NullableKeys<C>]?: InputOf<TypeOf<C[K]>>;
 };
 
 export interface IndexDef {

package/src/view.ts

@@ -3,7 +3,7 @@
 // already describe. Values are validated by the entity's own column parsers; an unknown key is a
 // declaration-time failure, not a surprise on the first request.
 
-import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
 import { invariantViolated } from './errors';
 import type { AnyColumn, ColumnMap } from './types';
 
@@ -50,7 +50,13 @@ export const viewFor = <Row, K extends keyof Row & string>(
 
   const parse = (value: unknown): Pick<Row, K> => {
     if (typeof value !== 'object' || value === null) {
-      throw invariantViolated(entityName, 'view', `expected an object, got ${String(value)}`);
+      // Shape, never content — the same renderer `columns.ts` uses, for the same reason: a
+      // view issue is folded into `X_BODY_INVALID` and reaches the caller and the log line.
+      throw invariantViolated(
+        entityName,
+        'view',
+        `expected an object, got ${describeValue(value)}`,
+      );
     }
     const input = value as Readonly<Record<string, unknown>>;
     const projected = {} as Record<K, unknown>;