@ultimat3/entity 13.0.0 → 15.0.0

package/CLAUDE.md

@@ -33,6 +33,23 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `pg-driver-bulk.live.test.ts`, `pg-driver-tenancy.live.test.ts`). A method with only the first is
   unproven against Postgres itself; a method with only the second is unproven against memory. Both
   are the bar, not either one.
+- **Money's write shape is wider than its row shape, and both drivers narrow it at the WRITE
+  METHOD'S entry — `As of 2026-08-25`.** `MoneyInput` lets a writer hand a `bigint` minor unit read
+  straight off a `bigint` column; `MoneyValue` is what a row holds, because `JSON.stringify` refuses
+  a `bigint` and money crosses every wire this framework projects. `RowWrite<Row>` is the type that
+  says so at `Repo.insert`/`insertAll`/`upsertAll`, which took the ROW type instead — so the
+  widening this package documents, narrows and stores correctly was a **compile error at the only
+  call an app makes**, `postgresRepo()` being exported, and it was the last two entries on
+  `scripts/lib/test-typecheck-pins.ts`. `narrowRow` (`columns.ts`) is the narrowing, called at each
+  entry rather than deep inside `bindValues`/`write`, and the POSITION is the rule. `entity.$assert`
+  and `upsertPlan` both run before a statement exists, so an invariant reading `total.minor` was
+  handed the caller's `bigint` and never the `number` the row would hold — it rejected rows both
+  drivers then stored correctly. And it decides whether a refusal costs a row: Bun's client binds a
+  `bigint` verbatim (measured), so a minor unit past ±2^53 narrowed any later is INSERTed,
+  committed, and only then refused by the decode of its own `returning *` — a row the app wrote and
+  can never read. `pg-money-write.live.test.ts` is the proof, because only a real table can see
+  that; `money-write-parity.test.ts` pins both drivers together, and `type-pins.ts` fails the build
+  if those three writes stop taking `RowWrite` or start answering with it.
 - **What a PREDICATE means is decided by the column's declared KIND, and `memory-match.ts` is
   where that one meaning is written.** The database decides by the column's type, so a driver
   deciding by the JS `typeof` of the value in hand is answering a different question — four rules,
@@ -776,8 +793,28 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **Every framework member on an entity is `$`-prefixed** — the columns are `Object.assign`ed onto
   the core, so an unprefixed member would make `view`, `name` or `tenant` an illegal column name.
   `$view`, never `view`; no free `view(entity, keys)` either — one way to write a projection.
-- **Invariants run twice**: in the app on write AND as a Postgres CHECK/UNIQUE via `toSql()`. An
-  untranslatable JS predicate reports `kind: 'assert'`, `sql: null` — never a pretend CHECK.
+- **Invariants run twice, and only ONE side of the pair is rendered here.** In the app on write
+  (`assertInvariants`), and as a Postgres CHECK/UNIQUE emitted by `@ultimat3/db` —
+  `constraintNameFor`, `declaredChecks`, `declaredIndexes` (`invariant-ddl.ts`), reading
+  `$describe()`. An untranslatable JS predicate reports `kind: 'assert'`, `sql: null` — never a
+  pretend CHECK. **This package rendered a second copy of that DDL until 2026-08-25**
+  (`toSql`/`invariantsToSql`/`constraintName`, reachable through `entity.$migration()`), and the
+  copy is the argument: nothing but its own tests ever called it, so nobody noticed it passed the
+  entity NAME where the table belongs — `entity('account', { table: 'legacy_accounts' })` rendered
+  `ALTER TABLE "account" ADD CONSTRAINT "account_…_check"`, a relation Postgres answers `42P01` for
+  and a constraint name no migration has ever written. All four are deleted; `$migration()` was on
+  `EntityCore`, so this is a breaking change to a documented member. Never render constraint DDL
+  here again — the entity's job is to DESCRIBE the rule, and `<table>_<name>_<check|key>` now has
+  exactly one source.
+- **`InvariantDescription.columns` is projected, `As of 2026-08-25`** — the physical names the rule
+  reads, for every kind, straight off `Invariant.columns`. Same argument as `onDelete`, `generated`
+  and `default` on `ColumnDescription`: `@ultimat3/db` is tier 1 and cannot import this package, so
+  a fact this projection drops is a fact the generator must recover from a rendering. It was
+  recovering it — `uniqueColumns()` split a `unique` rule's `sql` on commas and re-validated each
+  part — which is the shape that made `posts_org_id_created_at_idx` read back as the single column
+  `"org_id_created_at"`. `snapshotOf` derives from `declaredChecks`/`declaredIndexes` and not from
+  this record, so the field changes no snapshot and nothing regenerates
+  (`describe-invariant.test.ts` pins both halves).
 - **And the two halves must AGREE, term by term** (`expr.ts`). A rule the app accepts and the CHECK
   refuses is not a stricter database: the write comes back as a raw constraint error instead of
   `X_INVARIANT_VIOLATED`, which is the framework's own invariant bypassed on the way out. Two
@@ -997,7 +1034,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `columns-data.ts` | the wide vocabulary an existing schema needs: `json`, `decimal`, `date`, `bigint`, `bytes`, `arrayOf` |
 | `array-element.ts` | which element kinds `arrayOf()` refuses, and the one-line edit that repairs each |
 | `refuse.ts` | `refuseColumn`/`refuseInvariant` — the refusals raised before any entity exists, each carrying the EDIT that repairs it |
-| `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; bind + `toSql()` DDL |
+| `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; `bindInvariant` resolves property paths to physical names. No DDL — that is `@ultimat3/db`'s `invariant-ddl.ts` |
 | `entity.ts` / `describe.ts` | `entity()`, `$row`; the `EntityDescription` projection |
 | `index-name.ts` | what an index is CALLED — the predicate/direction/method discriminator and the 63-byte bound |
 | `search.ts` | the generated `tsvector` a `.searchable()` column set derives: the closed language list, the weights, the expression |

package/README.md

@@ -61,7 +61,7 @@ still imports one package: `import { entity, t } from '@ultimat3/entity'`.
 |---|---|---|
 | `uuid()`, `uuid<PostId>()` | `uuid`; `.primaryKey()` defaults to v7 | time-ordered keys keep the pk index append-friendly; the optional brand is declared once and survives to every signature |
 | `timestamp()` | `timestamptz` | UTC storage is not a per-table decision; there is no naive variant |
-| `money()` | `<name>_minor bigint` + `<name>_currency char(3)` + `<name>_scale integer null` | never a float, never one implied currency. The row value is `@ultimat3/schema`'s `MoneyValue` — the same declaration `@ultimat3/money`'s `Money` is — so a decoded row goes straight to `add()`/`formatMoney()`. A writer may hand a `bigint`; a stored minor unit past ±2^53 is refused on read, never rounded. `scale` is the decimal exponent `minor` counts in when it is not the currency's own (`{ minor: 2, currency: 'USD', scale: 6 }` is $0.000002); NULL in the column means "the currency's own minor unit" and round-trips as an ABSENT key, never as `0` |
+| `money()` | `<name>_minor bigint` + `<name>_currency char(3)` + `<name>_scale integer null` | never a float, never one implied currency. The row value is `@ultimat3/schema`'s `MoneyValue` — the same declaration `@ultimat3/money`'s `Money` is — so a decoded row goes straight to `add()`/`formatMoney()`. A writer may hand a `bigint` — `Insertable` says so on a table, `RowWrite<Row>` at a repository, and every whole-row write narrows it at its own entry, before an invariant or a statement sees it; a minor unit past ±2^53 is refused there and on read, never rounded. `scale` is the decimal exponent `minor` counts in when it is not the currency's own (`{ minor: 2, currency: 'USD', scale: 6 }` is $0.000002); NULL in the column means "the currency's own minor unit" and round-trips as an ABSENT key, never as `0` |
 | `enumerated(v)` | `text` + CHECK | a variant is a one-line migration, not `ALTER TYPE` |
 | `tz(zones)`, `locale(tags)` | `text` + CHECK, `Intl`-validated at declaration | an offset is not a time zone |
 | `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too |
@@ -142,9 +142,13 @@ Nothing is checked at runtime: a brand has no witness, `$parse` still validates
 One declaration, two enforcement points: the app checks it on every write, and the migration
 emits it. A bulk import or a `psql` session hits the same rule.
 
+The DDL is `@ultimat3/db`'s — one renderer, reading `$describe()`, so what `x db gen` writes is the
+only spelling there is. On a table this migration creates the check is an inline clause; on one that
+already exists it is the `alter table` beside it.
+
 ```sql
-ALTER TABLE "posts" ADD CONSTRAINT "posts_post_like_count_non_negative_check" CHECK (like_count >= 0);
-CREATE UNIQUE INDEX "posts_post_slug_unique_per_org_key" ON "posts" ("org_id", "slug");
+alter table "posts" add constraint "posts_post_like_count_non_negative_check" check (like_count >= 0);
+create unique index "posts_post_slug_unique_per_org_key" on "posts" ("org_id", "slug");
 ```
 
 A rule written as a JS predicate — `c.slug.matches(isValidSlug)`, `c.satisfies(fn, [...])` —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "13.0.0",
+  "version": "15.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "13.0.0",
-    "@ultimat3/db": "13.0.0",
-    "@ultimat3/schema": "13.0.0",
-    "@ultimat3/time": "13.0.0"
+    "@ultimat3/core": "15.0.0",
+    "@ultimat3/db": "15.0.0",
+    "@ultimat3/schema": "15.0.0",
+    "@ultimat3/time": "15.0.0"
   }
 }

package/src/columns.ts

@@ -27,6 +27,7 @@ import type {
   MoneyColumnNames,
   MoneyInput,
   MoneyValue,
+  RowWrite,
   TimestampColumn,
   UuidColumn,
 } from './types';
@@ -387,6 +388,22 @@ export const narrowMoney = <Row>(columns: ColumnMap, row: Row): Row => {
   return (narrowed ?? row) as Row;
 };
 
+/**
+ * The same narrowing at a write METHOD'S entry, typed honestly: what a caller may spell in,
+ * the row the entity declares out.
+ *
+ * `narrowMoney` is `<Row>(columns, row: Row): Row` — sound for `bindValues`, whose input and
+ * output are both a patch, and a lie for a full row that arrived as `RowWrite<Row>`, which is
+ * exactly the position `Repo.insert`/`insertAll`/`upsertAll` are in. Narrowing here rather than at
+ * `bindValues` is also what makes an `assert` invariant judge the value the row will HOLD instead
+ * of the spelling a caller happened to use: `entity.$assert` runs before the statement exists, so
+ * a rule reading `total.minor` saw the caller's `bigint` in both drivers and the stored `number`
+ * nowhere. The `as` is the one assertion this file is for — every money property is a `MoneyValue`
+ * once `narrowMoney` has returned, and `parseMinor` threw for anything that could not become one.
+ */
+export const narrowRow = <Row>(columns: ColumnMap, values: RowWrite<Row>): Row =>
+  narrowMoney(columns, values) as Row;
+
 /**
  * The CHECK that stops a psql session writing a currency the app would refuse — the app's own
  * bound, projected into SQL rather than restated in it.

package/src/describe.ts

@@ -170,6 +170,9 @@ const describeColumn = <Row>(
       primaryKey: meta.primaryKey || input.primaryKey.includes(property),
       unique: meta.unique,
       hasDefault: meta.default !== undefined,
+      // The value beside the boolean: `@ultimat3/db` renders it, and without it the generator
+      // could only infer two expressions and dropped every other default without saying so.
+      ...(meta.default === undefined ? {} : { default: meta.default }),
       check: meta.check?.(physical) ?? null,
       // Rendered from the resolved record, so the string a migration reads and the record a
       // traversal reads can never disagree about what a `references()` points at.
@@ -205,12 +208,15 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
       // entity without a search vector moves.
       ...(input.search == null ? [] : [describeSearchColumn(input.search)]),
     ],
+    // `columns` rides along whole: the generator needs the list a `unique` names, and recovering
+    // it by splitting `sql` is reading this package's own rendering back. See InvariantDescription.
     invariants: input.invariants.map((inv) => ({
       name: inv.name,
       kind: inv.kind,
       message: inv.message,
       sql: inv.sql,
       where: inv.where ?? null,
+      columns: inv.columns,
     })),
     // Projected whole, never reduced to the name: the generator spells the column list from this
     // and a name cannot be parsed back into one. See `IndexDescription`.

package/src/entity.ts

@@ -15,7 +15,7 @@ import type { Expr, InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
-import { assertInvariants, bindInvariant, invariantsToSql } from './invariants';
+import { assertInvariants, bindInvariant } from './invariants';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
 import type { SearchInit, SearchSource, SearchVector } from './search';
@@ -124,8 +124,10 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   $view<K extends keyof Row & string>(keys: readonly K[]): EntityView<Row, K>;
   /** Runs every invariant. Called by the repository on insert and update. */
   $assert(row: Row): void;
-  /** The CHECK/UNIQUE statements the migration emits for this entity. */
-  $migration(): string;
+  // No `$migration()`. The CHECK/UNIQUE statements an entity contributes are `@ultimat3/db`'s to
+  // render, off `$describe()`, beside the columns, indexes and foreign keys they have to be
+  // ordered against — a fragment of a migration is not one, and the one here named the wrong
+  // relation for three majors because nothing but its own test ever read it.
   $describe(): EntityDescription;
   /**
    * The foreign keys this entity declares, resolved — one record per `references()`, both ends
@@ -414,7 +416,6 @@ export const entity = <const C extends ColumnMap>(
     $view: <K extends keyof Row & string>(keys: readonly K[]) =>
       viewFor<Row, K>(name, init.columns, keys),
     $assert: (row) => assertInvariants(name, invariants, row),
-    $migration: () => invariantsToSql(name, invariants),
     $describe: describe,
     $references: references,
   };

package/src/index.ts

@@ -75,14 +75,7 @@ export {
   stateUndeclared,
 } from './feature-errors';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
-export {
-  assertInvariants,
-  constraintName,
-  invariant,
-  invariantsToSql,
-  MAX_ASSERTED_ROWS,
-  toSql,
-} from './invariants';
+export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
 export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
@@ -193,6 +186,7 @@ export type {
   ReferenceOptions,
   RowOf,
   RowPatch,
+  RowWrite,
   SearchWeight,
   TimestampColumn,
   TypeOf,

package/src/invariants.ts

@@ -69,28 +69,13 @@ export const bindInvariant = <T>(
   };
 };
 
-export const constraintName = (
-  table: string,
-  inv: { readonly name: string; readonly kind: InvariantKind },
-): string => `${table}_${inv.name}_${inv.kind === 'unique' ? 'key' : 'check'}`;
-
-/** The DDL the migration emits. One statement, terminated, ready to diff. */
-export const toSql = <T>(table: string, inv: Invariant<T>): string | null => {
-  if (inv.sql === null) return null;
-  const name = constraintName(table, inv);
-  if (inv.kind === 'check') {
-    return `ALTER TABLE "${table}" ADD CONSTRAINT "${name}" CHECK (${inv.sql});`;
-  }
-  const where = inv.where === undefined ? '' : ` WHERE ${inv.where}`;
-  const columns = inv.columns.map((column) => `"${column}"`).join(', ');
-  return `CREATE UNIQUE INDEX "${name}" ON "${table}" (${columns})${where};`;
-};
-
-export const invariantsToSql = <T>(table: string, invariants: readonly Invariant<T>[]): string =>
-  invariants
-    .map((inv) => toSql(table, inv))
-    .filter((statement): statement is string => statement !== null)
-    .join('\n');
+// The DDL an invariant becomes is NOT rendered here. `@ultimat3/db` owns it — `constraintNameFor`,
+// `declaredChecks` and `declaredIndexes` (`invariant-ddl.ts`), reading `$describe()` — and this
+// package rendered a second copy of the same fact until 2026-08-25. The copy is what made the case
+// for one renderer: it was reachable only through `entity.$migration()`, which passed the entity
+// NAME where the table belongs, so `entity('account', { table: 'legacy_accounts' })` rendered
+// `ALTER TABLE "account" ADD CONSTRAINT "account_seats_non_negative_check" …` — a relation that
+// does not exist and a constraint name no migration ever wrote. Never re-render it here.
 
 /**
  * Whether any rule here can only be judged in the app. This is what decides whether a FILTERED

package/src/memory-repo.ts

@@ -11,7 +11,7 @@ import { foldAggregate } from './aggregate-fold';
 import { keyOf } from './batch-read';
 import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
 import { entityNow } from './clock';
-import { narrowMoney } from './columns';
+import { narrowRow } from './columns';
 import { countsFrom, groupColumnOf } from './count-by';
 import { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
@@ -21,6 +21,7 @@ import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions, Transactor, Tx } from './repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
+import type { RowWrite } from './types';
 
 const field = (row: unknown, property: string): unknown =>
   typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
@@ -113,11 +114,19 @@ export const memoryRepo = <Row>(
     return { plan, found: rowsOf(plan, args) };
   };
 
-  const write = (given: Row, options: RepoOptions | undefined, operation: string): Row => {
+  /** Money's write shape narrowed once per batch, at the method the caller reached. */
+  const narrowed = (batch: readonly RowWrite<Row>[]): readonly Row[] =>
+    batch.map((row) => narrowRow<Row>(entity.$columns, row));
+
+  const write = (
+    given: RowWrite<Row>,
+    options: RepoOptions | undefined,
+    operation: string,
+  ): Row => {
     // `MoneyInput` lets a writer hand a `bigint`; a stored row holds the value type. The Postgres
-    // driver narrows in `bindValues` and reads its answer back through `returning *`, so without
-    // this an in-memory row would be the one row in the framework `JSON.stringify` refuses.
-    const row = narrowMoney(entity.$columns, given);
+    // driver narrows at the same position — its write methods' entry — so without this an
+    // in-memory row would be the one row in the framework `JSON.stringify` refuses.
+    const row = narrowRow<Row>(entity.$columns, given);
     // Beside `$assert`, and before the row lands: a write is judged by the tenant it names as well
     // as by the invariants it declares, and the Postgres driver runs the same pair in `writeRows`.
     // `update` reaches here with the STORED row merged under its patch, so a patch that moves a row
@@ -184,11 +193,15 @@ export const memoryRepo = <Row>(
       return write(values, options, 'insert');
     },
 
-    async insertAll(batch, options) {
+    async insertAll(given, options) {
       // The whole batch is judged before any of it lands: Postgres refuses the statement as one,
       // so a row an invariant rejects — or one naming a tenant this actor may not write — must not
       // leave the rows before it stored here either. `write` re-checks both per row; this loop is
       // what makes the batch all-or-nothing, which is the half a per-row check cannot give.
+      //
+      // Narrowed FIRST, so what this loop judges is what `write` will store: `$assert` was handed
+      // the caller's `bigint` minor unit here and the narrowed `number` one call later.
+      const batch = narrowed(given);
       for (const row of batch) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
         entity.$assert(row);
@@ -196,10 +209,12 @@ export const memoryRepo = <Row>(
       return batch.map((row) => write(row, options, 'insertAll'));
     },
 
-    async upsertAll(batch, args) {
+    async upsertAll(given, args) {
       // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
       // colliding row is skipped and never reaches `write()`, so checking only what lands would
-      // let a row naming another tenant through whenever it happened to collide.
+      // let a row naming another tenant through whenever it happened to collide. Narrowed first
+      // for the reason `insertAll` above is, and before `conflictKeyOf` reads a target too.
+      const batch = narrowed(given);
       for (const row of batch) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
         entity.$assert(row);

package/src/pg-driver.ts

@@ -28,6 +28,7 @@ import {
 import { entityNow } from './clock';
 import { coalesceFindById } from './coalesce';
 import { moneyColumns } from './column';
+import { narrowRow } from './columns';
 import { countsFrom, groupColumnOf, groupValue, MAX_GROUPS } from './count-by';
 import { cursorFor, seekFrom, valueAt } from './cursor';
 import type { Driver } from './database';
@@ -58,6 +59,7 @@ import { deletePlan, idPlan, readPlan, updatePlan } from './plan';
 import type { FindManyArgs, Repo, Transactor, UpsertArgs } from './repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
+import type { RowWrite } from './types';
 
 export interface PostgresDriverOptions {
   /**
@@ -121,6 +123,11 @@ export const postgresRepo = <Row>(
   const idOf = (row: Row): string =>
     entity.$primaryKey.map((property) => String(valueAt(row, property))).join('');
 
+  /** Where a batch stops being wide — before `writeRows` or `upsertPlan` read a row. `narrowRow`
+   *  says why the position matters, and `memoryRepo` narrows at the same one. */
+  const narrowed = (batch: readonly RowWrite<Row>[]): readonly Row[] =>
+    batch.map((row) => narrowRow<Row>(entity.$columns, row));
+
   const one = async (plan: QueryPlan, args: FindManyArgs): Promise<Row | null> => {
     const [found] = await client().query<PhysicalRow>(
       selectStatement(entity, plan, shapeOf(args), 1),
@@ -255,21 +262,24 @@ export const postgresRepo = <Row>(
     },
 
     async insert(values) {
-      const [written] = await writeRows('insert', [values], undefined);
-      // `returning *` is the row Postgres actually stored, defaults included.
-      return written ?? values;
+      const row = narrowRow<Row>(entity.$columns, values);
+      const [written] = await writeRows('insert', [row], undefined);
+      // `returning *` is the row Postgres actually stored, defaults included. The fallback is the
+      // NARROWED row: handing the caller's back would answer with a `bigint` minor unit.
+      return written ?? row;
     },
 
     async insertAll(batch) {
-      return writeRows('insertAll', batch, undefined);
+      return writeRows('insertAll', narrowed(batch), undefined);
     },
 
     async upsertAll(batch, args: UpsertArgs<Row>) {
-      const plan = upsertPlan(entity, batch, args.onConflict, args.onMatch ?? 'update');
+      const rows = narrowed(batch);
+      const plan = upsertPlan(entity, rows, args.onConflict, args.onMatch ?? 'update');
       // Refused here, not by the server: a batch that repeats a conflict target is `21000` in
       // Postgres and a silent overwrite in memory, and the two drivers have to mean one thing.
-      conflictKeys(entity, plan, batch);
-      return writeRows('upsertAll', batch, {
+      conflictKeys(entity, plan, rows);
+      return writeRows('upsertAll', rows, {
         columns: insertColumns(entity, plan.on),
         set: insertColumns(entity, plan.set),
       });

package/src/registry.ts

@@ -6,7 +6,7 @@
 import type { IndexMethod } from '@ultimat3/db';
 import { entityDuplicate } from './errors';
 import type { InvariantKind } from './invariants';
-import type { OnDelete } from './types';
+import type { ColumnDefault, OnDelete } from './types';
 
 export interface ColumnDescription {
   readonly property: string;
@@ -34,6 +34,16 @@ export interface ColumnDescription {
    * field that is not on this projection reaches no DDL at all.
    */
   readonly generated?: string;
+  /**
+   * The declared default, when there is one — the VALUE, not merely `hasDefault`'s boolean.
+   *
+   * Same reason as `onDelete` and `generated`: `@ultimat3/db` is tier 1 and cannot import this
+   * package, so a fact that is not on this projection reaches no DDL. `hasDefault` alone let the
+   * generator infer only `gen_random_uuid()` and `now()`; every other default was dropped in
+   * silence, and a regenerated `examples/dummy` lost nine of them. Absent on a column declaring
+   * none, so a description written before this existed reads the same and nothing regenerates.
+   */
+  readonly default?: ColumnDefault;
 }
 
 /**
@@ -64,6 +74,18 @@ export interface InvariantDescription {
   /** `null` for an `assert`: a JS predicate the database was never told about. */
   readonly sql: string | null;
   readonly where: string | null;
+  /**
+   * The physical columns this rule reads — the same list `Invariant.columns` holds, for every
+   * kind, never narrowed to `unique`.
+   *
+   * Same reason as `onDelete`, `generated` and `default` on `ColumnDescription`: `@ultimat3/db` is
+   * tier 1 and cannot import this package, so a fact absent here is a fact the generator has to
+   * recover from a rendering. Without it `uniqueColumns()` split a `unique` rule's `sql` on commas
+   * and re-validated each part as an identifier — a comma-split of text this package joined, which
+   * is the shape `parseIndexName` failed at when `posts_org_id_created_at_idx` became the single
+   * column `"org_id_created_at"`. Carried, so the split has nothing left to do.
+   */
+  readonly columns: readonly string[];
 }
 
 /**

package/src/repo.ts

@@ -9,7 +9,7 @@
 
 import type { AggregateFn } from './aggregate';
 import type { Predicate, SortKey } from './tenancy';
-import type { IdOf, RowPatch } from './types';
+import type { IdOf, RowPatch, RowWrite } from './types';
 
 export interface Tx {
   readonly id: string;
@@ -80,11 +80,16 @@ export interface Page<T> {
  * The id parameters are `IdOf<T>`, not `string`: an entity that declared `uuid<PostId>()` is
  * addressed by a `PostId` and by nothing else. `IdOf<unknown>` and `IdOf<{ id: string }>` are
  * both `string`, so a row-agnostic consumer sees the signature it always saw.
+ *
+ * The whole-row writes take `RowWrite<T>` and the filtered ones `RowPatch<T>`, which are one
+ * statement in two shapes: money's write type is wider than its row type, and every one of these
+ * five entry points narrows it — `narrowRow` — before anything reads the row. Taking `T` here made
+ * the documented `bigint` minor unit unspellable at the only call an app makes.
  */
 export interface Repo<T = unknown> {
   findById(id: IdOf<T>, options?: FindByIdOptions): Promise<T | null>;
   findMany(args?: FindManyArgs): Promise<Page<T>>;
-  insert(values: T, options?: RepoOptions): Promise<T>;
+  insert(values: RowWrite<T>, options?: RepoOptions): Promise<T>;
   /**
    * Many rows, one statement — the bulk form a per-row `insert` loop is the N+1 of. Resolves with
    * the rows as stored, defaults included, in the order given; an empty batch writes nothing and
@@ -92,13 +97,13 @@ export interface Repo<T = unknown> {
    * Past Postgres's bind count the batch becomes several statements, so wrap it in
    * `withTransaction` when all-or-nothing matters.
    */
-  insertAll(rows: readonly T[], options?: RepoOptions): Promise<readonly T[]>;
+  insertAll(rows: readonly RowWrite<T>[], options?: RepoOptions): Promise<readonly T[]>;
   /**
    * `insertAll` that resolves a collision instead of failing on it. Resolves with the rows this
    * call actually wrote — under `onMatch: 'nothing'` a row already stored is skipped and absent,
    * which is what `returning *` says on the Postgres side.
    */
-  upsertAll(rows: readonly T[], args: UpsertArgs<T>): Promise<readonly T[]>;
+  upsertAll(rows: readonly RowWrite<T>[], args: UpsertArgs<T>): Promise<readonly T[]>;
   update(id: IdOf<T>, patch: RowPatch<T>, options?: RepoOptions): Promise<T>;
   delete(id: IdOf<T>, options?: RepoOptions): Promise<void>;
   /**

package/src/type-pins.ts

@@ -309,3 +309,39 @@ type _MoneyInputTakesABigInt = Assert<
 
 /** And a row value is always a legal input: read a row, write it back. */
 type _MoneyValueIsMoneyInput = Assert<[MoneyValue] extends [MoneyInput] ? true : false>;
+
+/** A row with the one column whose write type is wider than its row type, and nothing else. */
+type PinMoneyRow = { readonly id: string; readonly price: MoneyValue };
+
+type PinWideMoneyRow = {
+  readonly id: string;
+  readonly price: { readonly minor: bigint; readonly currency: string };
+};
+
+/**
+ * The pin the two above needed all along. `MoneyInput` declares the widening and could never
+ * enforce it end to end: `Repo.insert` took the ROW type, so the one call an app makes refused the
+ * value those lines call legal — a compile error at `postgresRepo().insert(...)`, which is exported
+ * and therefore public API, while both drivers narrowed it correctly at runtime. Pinned at `Repo`
+ * rather than at `RowWrite`, because a mapped type is only worth having where it is spent.
+ */
+type _RepoInsertTakesABigIntMinor = Assert<
+  [PinWideMoneyRow] extends [Parameters<Repo<PinMoneyRow>['insert']>[0]] ? true : false
+>;
+
+/** Every whole-row write, not just the single one — three entry points, one shape. */
+type _RepoBatchWritesTakeABigIntMinor = Assert<
+  [readonly PinWideMoneyRow[]] extends [Parameters<Repo<PinMoneyRow>['insertAll']>[0]] &
+    [Parameters<Repo<PinMoneyRow>['upsertAll']>[0]]
+    ? true
+    : false
+>;
+
+/**
+ * And the half that must NOT widen: what a repository answers with is the row type. `minor` stays
+ * a `number` because money crosses every wire this framework projects and `JSON.stringify` refuses
+ * a `bigint` — the widening is the caller's spelling, never the row's.
+ */
+type _RepoAnswersTheValueType = Assert<
+  [Awaited<ReturnType<Repo<PinMoneyRow>['insert']>>] extends [PinMoneyRow] ? true : false
+>;

package/src/types.ts

@@ -281,6 +281,23 @@ export type Insertable<C extends ColumnMap> = {
   readonly [K in DefaultedKeys<C> | NullableKeys<C>]?: InputOf<TypeOf<C[K]>>;
 };
 
+/**
+ * A whole row as a WRITER may spell it — the row's own type, or money's wider write shape.
+ *
+ * `Insertable` says this at the `database()` seam, where the columns are still in hand;
+ * `Repo.insert`/`insertAll`/`upsertAll` reach the same rows one layer down with only `Row`, and
+ * they took `Row` itself — so the `bigint` minor unit `MoneyInput` documents, `narrowMoney` exists
+ * to narrow and both drivers already store correctly was a compile error at the one entry point a
+ * caller uses. `postgresRepo()` is exported, so that caller is public API, not an internal detour.
+ *
+ * `Row[K]` stays in the union rather than being replaced by `InputOf<Row[K]>`, for the reason
+ * `RowPatch` below states: a conditional type over an unresolved `Row` never reduces, so `Row`
+ * would stop being assignable to its own write shape and every internal caller would redden.
+ */
+export type RowWrite<Row> = {
+  readonly [K in keyof Row]: Row[K] | InputOf<Row[K]>;
+};
+
 /**
  * A patch or a filter: every property optional, **and every property allowed to be present and
  * `undefined`**.