@ultimat3/entity 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -48,7 +48,15 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   sent, which is why `findById` keeps its signature and there is no `batch()` to opt into. The
   window closes before the statement goes out, so a lookup arriving mid-flight opens the next batch
   instead of joining ids already on the wire, and past `MAX_IDS_PER_STATEMENT` a batch becomes
-  several whole statements rather than one Postgres refuses for its bind count. A sequential
+  several whole statements rather than one Postgres refuses for its bind count. **No caller of a
+  batch is ever left unsettled** — every promise `coalesceFindById` returns was handed out before
+  the flush was scheduled, so `flush` settles the whole of `waiting` in a catch of its own rather
+  than only the chunk that failed, and the scheduled `flush` carries a `.catch`: a rejection there
+  has nobody left to hand it to and an unhandled one ends the Bun process. Unsettled forever is
+  strictly worse than failed — a rejection is a stack trace and a hang is a request that never
+  answers — which is why `coalesce.test.ts` races its assertions against a deadline instead of
+  letting the runner time out. `jit-preload.ts` has the same property by construction, settling
+  with an `Answer` rather than a rejection. A sequential
   `for … of` loop shares no microtask — its `await` ends the window — which is what the sibling
   preload below is for.
 - **A page batches the loop it causes, and a preloaded row is only ever served to the statement
@@ -578,6 +586,76 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   ±2^53 message, where the value is a `number`, a `bigint` or a digits-only string, the amount is
   the only fact that repairs the row, and `@ultimat3/realtime` renders the same value the same way
   for the same reason. Changing either means changing both.
+- **A seed is replayable by construction, and `insert` is the verb that makes it so** — decided
+  2026-08. `defineSeed`'s context offered `insert` and nothing else, and a plain insert meant two
+  different things to the two drivers: the memory repository overwrites by primary key, Postgres
+  raises `23505`. So a seed replayed twice passed every test in this repo and killed the SECOND
+  boot of any container on a durable store, which is why both tracked apps had (or needed) a
+  hand-written `Driver` decorator over `insert`. `SeedContext.insert` now writes one
+  `upsertAll(rows, { onConflict: entity.$primaryKey, onMatch: 'nothing' })` per call. Four
+  properties, none optional. **`'nothing'`, never `'update'`**: `upsertPlan` refuses an updating
+  upsert whose target omits the tenant column (`X_TENANCY_UNSCOPED`), and a tenant-scoped entity
+  whose only unique keys are global — `posts` in the reference app — has no legal updating target
+  at all; `'nothing'` also skips the uneven-batch and nothing-to-set refusals, which a fixture
+  graph would otherwise have to satisfy. **One statement per call**, so the per-row `insert` loop
+  this replaced is no longer the N+1 of its own bulk form. **The metrics are the driver's answer**,
+  not a count of the input: `upsertAll` under `'nothing'` resolves with the rows it actually wrote,
+  so `skipped` is the replay, observed. **A generated primary key the row does not name is
+  refused** — `uuid().primaryKey()` carries `GENERATED_UUID`, so `$parse` fills it with a fresh
+  uuid, the conflict target matches nothing and run five leaves five copies; it is the one
+  duplication no other rule in this package can see.
+- **`upsert(entity, { by }, values)` is the second verb, and it exists because only the SEED AUTHOR
+  knows the natural key.** A seed writing into a table whose ids already exist — `banks` keyed by
+  `value`, `users` by `email`, `exchange_rates` by `(base, target, effective_on)` — cannot choose a
+  primary key, so keying replay on `$primaryKey` would be keying it on something Postgres does not
+  enforce. It reads first so an unchanged row can answer `'skipped'` with no statement, then writes
+  through ONE `on conflict … do update`: the read is for the report, never for the decision, or two
+  containers booting at once would race between the two. **`createdAt` is preserved on a match** —
+  the row handed to the update omits it, so `namedProperties` leaves it out of the `set` — because
+  a replay must not move when a row first arrived.
+- **The environment guard is the CLI's, not `run()`'s.** `seedTiersFor(environment, requested)` is
+  the one table (`reference` everywhere, `dev` everywhere but production) and `x db seed` is what
+  refuses. `run()` stays permissive on purpose: `dummy/social-media-clone/apps/web/api/index.ts`
+  seeds its own production demo database from its boot code and says out loud that this is an app
+  decision (axiom 8) — a library refusal would break it. A seed declares its tier as DATA, the way
+  a `backfill()` declares its environments.
+- **One resolver decides a physical name, and it is `columnName(property, meta)`** — decided
+  2026-08 with `entity(name, { table })` and `.column(name)`. Before them, `snake(property)` was
+  called in nine places and `$table` was the entity name, so a schema this framework did not
+  generate could not be declared at all: adoption meant a rewrite. Every projection now reads the
+  resolver — the DDL (`describe.ts`), the binding and the decoder (`pg-row.ts`), the predicate and
+  sort resolver, the index names, the invariant SQL, the soft-delete clause in `pg-sql.ts` and
+  `pg-driver.ts`. **A second `snake(property)` anywhere is a statement naming a column the table
+  does not have**, and the first table that proves it is somebody's production database. It is
+  additive by construction: with no override the resolver IS `snake(property)`.
+- **The entity NAME and the TABLE are different things.** The name stays the framework's key — the
+  registry, the cache tag (`entity:account`), `$tagFor`, every relation and every policy — and the
+  table is physical. Renaming a table must never move a cache tag. Index names are the TABLE's,
+  because an index is a physical object.
+- **Money's three columns are per-part and `scale: null` is a real answer.** `money({ columns })`
+  merges over `<base>_minor`/`<base>_currency`/`<base>_scale` one part at a time, so a table that
+  renamed one does not restate the other two. `scale: null` says the table has no scale column at
+  all — the ordinary shape of an amount written before scale existed — and then `columnsOf`
+  projects TWO names, `bindValues` writes two, and `decodeRow` folds two. That last one is why
+  `decodeRow` branches on `$meta.kind === 'money'` and not on how many names came back: reading a
+  two-column amount as a non-money column handed the caller a raw minor unit where a `Money` goes.
+- **A `jsonb` value is bound as TEXT and cast back, `::text::jsonb`** — and the double cast is
+  load-bearing, not defensive. The driver seam refuses a plain object as a parameter
+  (`X_SQL_UNSAFE`; `isBoundValue` takes scalars, `Date`, `Uint8Array` and arrays of those). With
+  `$1::jsonb` the server describes the parameter as `jsonb`, Bun's `sql` JSON-ENCODES the string it
+  was handed, and `{"a":1}` is stored as the JSON *string* — `jsonb_typeof` says `string`
+  (measured, Postgres 17.10). Pinning the parameter to `text` first makes the client send the
+  characters and the server parse them. An ARRAY is the other value that cannot cross as itself:
+  Bun serialises a JS array to `x,y`, which Postgres answers with `malformed array literal`, so
+  `bindValues` writes the `{…}` literal with every element quoted.
+- **The wide column types were chosen from what a driver actually returns, not from what reads
+  well.** `int8` is a string from Bun's `sql` and a `bigint` from PGlite; `numeric` is a string
+  from both; `date` is a `Date` at midnight UTC from both; `bytea` is a `Buffer` from one and a
+  `Uint8Array` from the other. Every one of those is normalised in `$parse` to a single row type,
+  because a row that means two things by driver is the drift this package's two-driver split exists
+  to refuse. `bigint()` and `decimal()` are STRINGS for the same reason `money.minor` is a
+  `number`: `JSON.stringify` throws on a bigint, and a `number` loses digits exactly where a legacy
+  `int8` key lives.
 - Never throw a bare `Error` — use `errors.ts`.
 - Tests restore the process-global registry in `afterAll` (`clearRegistry()`): a leaked registry
   breaks an unrelated package's tests, as it did in `@ultimat3/policy`.
@@ -587,7 +665,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | File | Job |
 |---|---|
 | `types.ts` | `Column`, `RowOf`, `Insertable`, `IdOf` — the type derivation |
-| `column.ts` / `columns.ts` | the chain + property-key binding; the blessed builders; `narrowMoney`, the one write-side narrowing both drivers run |
+| `column.ts` / `columns.ts` | the chain + property-key binding; the blessed builders; `columnName`/`moneyColumns`, the ONE physical-name resolver; `narrowMoney`, the one write-side narrowing both drivers run |
+| `columns-data.ts` | the wide vocabulary an existing schema needs: `json`, `decimal`, `date`, `bigint`, `bytes`, `arrayOf` |
 | `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; bind + `toSql()` DDL |
 | `entity.ts` / `describe.ts` | `entity()`, `$row`; the `EntityDescription` projection |
 | `view.ts` | `$view(keys)` — the row projection an action names as its `output` |
@@ -607,6 +686,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `registry.ts` | duplicate detection, `describeEntities()` for the manifest, `references()` per entry |
 | `relations.ts` | `relationMap()`/`relationsFor()`/`relationNamed()` — the FKs as a named `belongsTo`/`hasMany` map |
 | `n-plus-one.ts` | a repeated statement → the error whose `fix` is the preload or bulk call that ends it |
+| `seed.ts` | `defineSeed` — the replayable fixture graph: `insert` (the seed's own ids), `upsert` (a natural key), the sentinel reads, and the tier table `x db seed` refuses from |
 | `type-pins.ts` | compile-time assertions `tsc` checks — the column proxy, `Invariant` variance, the branded id |
 
 ## Commands

package/README.md

@@ -67,8 +67,58 @@ still imports one package: `import { entity, t } from '@ultimat3/entity'`.
 | `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too |
 
 Chain: `.primaryKey()` · `.nullable()` · `.unique()` · `.default(v)` · `.defaultNow()` ·
-`.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()`. Physical names are
-derived from the property key (`orgId` → `org_id`); a name is written once, or never.
+`.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()` · `.column(name)`.
+Physical names are derived from the property key (`orgId` → `org_id`); a name is written once, or
+never — `.column()` is the exception, and it exists for tables this framework did not create.
+
+## Wide columns
+
+The vocabulary an EXISTING schema needs. The blessed set above is a decision the framework made
+for a table it was going to create; these are the shapes a table already has, `As of 2026-08`.
+
+| Builder | Emits | Row type, and why |
+|---|---|---|
+| `json(schema)` | `jsonb` | the schema is **required**: a `json()` returning `unknown` is the `any` hole this framework forbids, and a column is the worst place for one — the value arrives from the database as often as from a caller. The object is bound as an object, never as JSON text |
+| `decimal({ precision, scale })` | `numeric(p, s)` | a `string`, the exact digits. Money is the one decimal with an opinion (integer minor units + a currency); this is every other one, and a value with more decimal places than the column stores is refused rather than rounded |
+| `date()` | `date` | `@ultimat3/time`'s `PlainDate` — a calendar date, no time, no zone. `effective_on` is the date a rate applies, and as a `timestamptz` it is a different date on either side of midnight for half the planet |
+| `bigint()` | `bigint` | a decimal `string`. A JS `bigint` is what `JSON.stringify` throws on and a `number` loses digits past 2^53 — which is exactly where a legacy `int8` key lives. Both driver spellings (a string from Bun's `sql`, a `bigint` from PGlite) arrive as one |
+| `bytes()` | `bytea` | a plain `Uint8Array`, normalised: Bun's `sql` returns a `Buffer` and PGlite a `Uint8Array`, and the two do not serialise alike |
+| `arrayOf(column)` | `<element>[]` | `readonly T[]`, each member parsed by the element column it was given. Money and nested arrays are refused — an element is one scalar column |
+
+## Adopting an existing table
+
+Three overrides, and together they are what makes a schema Ultimate did not generate declarable
+at all. Nothing here changes what an entity without them emits.
+
+```ts
+import { date, entity, money, text, uuid } from '@ultimat3/entity';
+
+export const accounts = entity('account', {
+  table: 'legacy_accounts',
+  columns: {
+    id: uuid().primaryKey().column('account_id'),
+    githubLogin: text({ max: 40 }).column('gh_login'),
+    balance: money({ columns: { minor: 'amount_cents', currency: 'currency', scale: null } }),
+    openedOn: date().column('opened_on'),
+  },
+});
+```
+
+| Override | What follows it |
+|---|---|
+| `entity(name, { table })` | every statement, index name and foreign key. The entity NAME stays the framework's key — the registry, the cache tag (`entity:account`), `x entities describe` and every relation are keyed by it, so renaming a table never moves a cache tag or a policy |
+| `.column(name)` | the DDL, the binding, the decoder, the predicate, the sort key, the cursor. Name it LAST in a chain — the link returns the general column, and only `uuid()` and `timestamp()` keep their own methods across it |
+| `money({ columns })` | per part, merged over `<name>_minor` / `<name>_currency` / `<name>_scale`, so a table that renamed one does not restate the other two. `scale: null` says the table has no scale column: every amount is then at the currency's own minor unit, which is what an absent scale already means |
+
+A physical name is checked where it is written — lower-case letters, digits and underscores, at
+most the 63 bytes Postgres truncates at — because it is spliced into every statement as an
+identifier.
+
+**What is not adoptable yet**, `As of 2026-08`: a `numeric` money column with no currency column
+beside it (`money()` is two columns by construction — declare it `decimal()` and keep the currency
+in the app), a Postgres `enum` TYPE (`enumerated()` emits a CHECK, not a `CREATE TYPE`), a
+composite type, and a live query over a renamed column — `@ultimat3/realtime` rebuilds a row from
+the physical names alone and would deliver `ghLogin` where the repository says `githubLogin`.
 
 ## Branded ids
 
@@ -514,9 +564,30 @@ the enforcement.
 
 ## Seeds
 
-`defineSeed('dev', async ({ insert, id }) => …)`. `id('post:tenancy')` is a UUID v5 of the label,
-so the same fixture graph gets the same ids on every machine. Rows go through the columns and
-the invariants, which makes a seed a test of the schema as well.
+`defineSeed(name, build, { tier })` — the fixture graph, written once and **replayed anywhere**: a
+second run writes nothing and raises nothing, against Postgres as well as against memory. Rows go
+through the columns and the invariants either way, which makes a seed a test of the schema as well.
+`x db seed [<name>]` is what applies it.
+
+Two write verbs, because only the author knows which key identifies a row:
+
+| Context member | Use it when | A replay |
+|---|---|---|
+| `insert(entity, rows)` | the seed chose the ids — `id('post:tenancy')` is a UUID v5 of the label, so the same graph gets the same ids on every machine | one `on conflict … do nothing` statement per call; a stored row is left alone and counted `skipped` |
+| `upsert(entity, { by, preserve? }, values)` | the table owns the id and only a natural key identifies the row | reads first, so an unchanged row is `'skipped'` with no statement; otherwise one `on conflict … do update`, which settles the race between two containers booting at once |
+| `exists(entity, where?)` / `count(entity, where?)` | bulk volume data, where the FILE is the unit of idempotency | the sentinel returns early and nothing is written |
+| `deleteWhere(entity, where)` | a scoped wipe before a regenerate | **refused on a soft-deleting entity**: the stamp keeps the row's unique key and no replay can clear it |
+| `id`, `now`, `environment`, `tier`, `dryRun`, `metrics` | — | `now` is one instant per run; `metrics` is `{ inserted, updated, skipped }` and `run()` returns it |
+
+Rules worth knowing before the first seed: `upsert` never overwrites `createdAt` (`preserve` names
+other columns to spare); `upsert` on a tenant-scoped entity needs the tenant column inside `by`,
+exactly as `upsertAll` does, while `insert` needs nothing because `do nothing` writes nothing to a
+row it does not own; and `insert` refuses a row that leaves a `uuid().primaryKey()` unnamed —
+`$parse` would fill it with a fresh uuid and every replay would insert one more copy.
+
+`tier` is `'dev'` (the default, fixture data) or `'reference'` (data the app is wrong without,
+which ships to production). The refusal is the CLI's, never `run()`'s: an app that seeds its own
+database from its boot code has decided to, and a library that overruled that would break it.
 
 ## Errors
 

package/package.json

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

package/src/coalesce.ts

@@ -81,7 +81,10 @@ const openBatch = (
   // mid-flight opens the next batch instead of joining ids already on the wire.
   queueMicrotask(() => {
     if (batches.get(key) === batch) batches.delete(key);
-    void flush(batch);
+    // `flush` settles every caller itself, so a rejection escaping it has nobody left to hand it
+    // to — and an unhandled rejection ends the Bun process, which turns one bad batch into the
+    // whole node. Nothing is swallowed here that a caller was not already given.
+    void flush(batch).catch(() => undefined);
   });
   return batch;
 };
@@ -89,23 +92,34 @@ const openBatch = (
 const flush = async (batch: Batch): Promise<void> => {
   const waiting = [...batch.pending.values()];
   batch.pending.clear();
-  // One statement at a time: a batch wide enough to split must not take the pool with it.
-  for (const chunk of statementChunks(waiting)) {
-    try {
-      const answers = await batch.load(chunk.map((entry) => entry.id));
-      for (const entry of chunk) {
-        const answer = answers.get(entry.key);
-        // An id the statement did not answer for is a row that is not there — `findById`'s `null`,
-        // never a rejection, and never another caller's row.
-        if (answer === undefined) entry.settle(null);
-        else if ('error' in answer) entry.fail(answer.error);
-        else entry.settle(answer.row);
+  try {
+    // One statement at a time: a batch wide enough to split must not take the pool with it.
+    for (const chunk of statementChunks(waiting)) {
+      try {
+        const answers = await batch.load(chunk.map((entry) => entry.id));
+        for (const entry of chunk) {
+          const answer = answers.get(entry.key);
+          // An id the statement did not answer for is a row that is not there — `findById`'s
+          // `null`, never a rejection, and never another caller's row.
+          if (answer === undefined) entry.settle(null);
+          else if ('error' in answer) entry.fail(answer.error);
+          else entry.settle(answer.row);
+        }
+      } catch (error) {
+        // The statement failed, so everyone in it gets the failure the single statement would
+        // have handed them. Every one was returned to a caller, so none goes unhandled.
+        for (const entry of chunk) entry.fail(error);
       }
-    } catch (error) {
-      // The statement failed, so everyone in it gets the failure the single statement would have
-      // handed them. Every one of these promises was returned to a caller, so none goes unhandled.
-      for (const entry of chunk) entry.fail(error);
     }
+  } catch (error) {
+    // Every promise in `waiting` was handed to a caller before this batch was ever scheduled, so
+    // anything escaping the loop above — `statementChunks` itself, or whatever a later edit puts
+    // beside it — would leave them awaiting a row that can no longer arrive. Unsettled forever is
+    // strictly worse than failed: a rejection is a stack trace, a hang is a request that never
+    // answers. Failing an entry an earlier chunk already settled is a no-op, so this is safe over
+    // the whole list. `jit-preload.ts` gets the same property by construction, settling with an
+    // `Answer` rather than a rejection; this path has a real promise per caller and cannot.
+    for (const entry of waiting) entry.fail(error);
   }
 };
 

package/src/column.ts

@@ -7,11 +7,51 @@
 // physical name even though two schema modules import each other in a cycle.
 
 import { invariantViolated } from './errors';
-import type { AnyColumn, Column, ColumnDefault, ColumnMeta, TimestampColumn } from './types';
+import type {
+  AnyColumn,
+  Column,
+  ColumnDefault,
+  ColumnMeta,
+  MoneyColumnNames,
+  TimestampColumn,
+} from './types';
 
 export const snake = (value: string): string =>
   value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
 
+/**
+ * The physical column, decided in ONE place: what `.column()` declared, else `snake(property)`.
+ *
+ * Every projection reads it here — the DDL, the binding, the decoder, the invariant resolver, the
+ * index names — because a second `snake(property)` anywhere is a statement naming a column the
+ * table does not have, and the first table that proves it is somebody's production database.
+ */
+export const columnName = (property: string, meta: ColumnMeta): string =>
+  meta.name ?? snake(property);
+
+/** Money's three physical columns, resolved. `scale: null` is a table that has no scale column. */
+export interface MoneyColumns {
+  readonly minor: string;
+  readonly currency: string;
+  readonly scale: string | null;
+}
+
+/**
+ * Per part, merged over the `<base>_minor` / `<base>_currency` / `<base>_scale` defaults — so a
+ * table that renamed one of the three does not have to restate the other two, and `.column()`
+ * moves the base for all of them at once.
+ */
+export const moneyColumns = (property: string, meta: ColumnMeta): MoneyColumns => {
+  const base = columnName(property, meta);
+  const declared: MoneyColumnNames = meta.parts ?? {};
+  return {
+    minor: declared.minor ?? `${base}_minor`,
+    currency: declared.currency ?? `${base}_currency`,
+    // `undefined` takes the default; `null` is the caller saying the column is not there at all.
+    scale: declared.scale === undefined ? `${base}_scale` : declared.scale,
+  };
+};
+
 export const GENERATED_UUID: ColumnDefault = { kind: 'generated', by: 'uuid-v7' };
 export const GENERATED_NOW: ColumnDefault = { kind: 'generated', by: 'now' };
 
@@ -49,7 +89,7 @@ export const bindColumn = (column: AnyColumn, table: string, property: string):
         'build a new column instead of sharing one between entities',
     );
   }
-  const binding: Binding = { table, property, name: snake(property) };
+  const binding: Binding = { table, property, name: columnName(property, column.$meta) };
   bindings.set(column, binding);
   return binding;
 };
@@ -135,8 +175,30 @@ export const makeColumn = <T, Optional extends boolean>(
     ),
 
   default: (value) => makeColumn<T, true>({ ...meta, default: literal(value) }, parse, true),
+
+  column: (name) =>
+    makeColumn<T, Optional>({ ...meta, name: assertColumnName(name) }, parse, optional),
 });
 
+/**
+ * A physical name is spliced into DDL and into every statement as a quoted identifier, so it is
+ * checked where it is written rather than trusted there: an empty name produces `""`, and a name
+ * carrying a quote or a newline is the one value in a column declaration that could close the
+ * identifier. `[a-z_][a-z0-9_$]*`, which is what an unquoted Postgres identifier may be, and the
+ * bound is the same 63 bytes the server truncates at — a longer one silently addresses a
+ * different column.
+ */
+export const assertColumnName = (name: string): string => {
+  if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {
+    throw invariantViolated(
+      'column',
+      'column-name',
+      `"${name}" is not a physical column name: lower-case letters, digits and underscores, at most 63 of them`,
+    );
+  }
+  return name;
+};
+
 export const column = <T>(
   kind: ColumnMeta['kind'],
   parse: (value: unknown) => T,
@@ -155,4 +217,7 @@ export const makeTimestamp = <Optional extends boolean>(
   ...makeColumn<Date, Optional>(meta, parse, optional),
   defaultNow: () => makeTimestamp({ ...meta, default: GENERATED_NOW }, parse, true),
   onUpdateNow: () => makeTimestamp({ ...meta, onUpdate: GENERATED_NOW }, parse, optional),
+  // Overridden so `timestamp().column('created').defaultNow()` still has `defaultNow` — the
+  // general link returns the general column, and a builder with methods of its own keeps them.
+  column: (name) => makeTimestamp({ ...meta, name: assertColumnName(name) }, parse, optional),
 });

package/src/columns-data.ts

@@ -0,0 +1,205 @@
+// The column builders an EXISTING schema needs. `columns.ts` holds the opinionated set — one way
+// to store an id, an instant, money — and every one of them is a decision this framework made for
+// a table it was going to create. These are the shapes a table already has: a `jsonb` payload, a
+// `numeric(18,8)` rate, a calendar `date`, an `int8` id past 2^53, a `bytea` blob, a `text[]`.
+//
+// Two rules run through all of them. A value crossing the driver is parsed by the column that
+// declared it, because the two drivers disagree about what they hand back (`int8` is a string from
+// Bun's `sql` and a `bigint` from PGlite — measured); and nothing here is an `any` hole, so `json()`
+// takes a schema and validates through it.
+
+import { describeValue, formatIssues, type StandardSchemaV1, validate } from '@ultimat3/schema';
+import { isPlainDate, type PlainDate, plainDateUtc } from '@ultimat3/time';
+import { column } from './column';
+import { invariantViolated } from './errors';
+import type { AnyColumn, Column, ColumnMeta } from './types';
+
+const reject = (rule: string, detail: string): never => {
+  throw invariantViolated('column', rule, detail);
+};
+
+/** The rejected value as its SHAPE, never its content — `columns.ts` explains why at length. */
+const got = (value: unknown): string => `got ${describeValue(value)}`;
+
+/**
+ * A `jsonb` column whose CONTENTS are validated. The schema is required and that is the point: a
+ * `json()` returning `unknown` is the `any` hole this framework forbids, and a column is the worst
+ * place for one — the value arrives from the DATABASE as often as from a caller, so the row type
+ * would be a claim nothing ever checked.
+ *
+ * The object is bound as an object, never as a string: a JSON string parameter is stored as a JSON
+ * *string* by Postgres (measured — `'{"a":1}'` comes back as the text, not the object), so
+ * stringifying here would change the value's type in the table.
+ */
+export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
+  column<T>('jsonb', (value) => {
+    const result = validate(schema, value);
+    if (result.issues === undefined) return result.value;
+    // The ISSUES, never the value: `formatIssues` renders path + message, and a column rejection
+    // reaches the caller and the log line where a value has no key left to redact.
+    return reject(
+      'json',
+      `does not match the column's schema — ${formatIssues(result.issues).join('; ')}`,
+    );
+  });
+
+const DIGITS = /^-?\d+$/;
+
+/**
+ * `bigint`, whose row type is a decimal STRING. Neither alternative survives contact:
+ * a JS `bigint` is what `JSON.stringify` throws on — the reason `money.minor` is a `number` — and
+ * a `number` silently loses digits past 2^53, which is precisely the range a legacy `int8` key or
+ * a snowflake id lives in. A string holds every value the column can and crosses every wire this
+ * framework generates.
+ *
+ * Both driver spellings arrive here and leave as one: Bun's `sql` returns `int8` as a string and
+ * PGlite returns a `bigint`, and a row that meant two things by driver is the drift this package
+ * exists to refuse.
+ */
+export const bigint = (): Column<string> =>
+  column<string>('bigint', (value) => {
+    if (typeof value === 'bigint') return value.toString();
+    if (typeof value === 'number') {
+      return Number.isSafeInteger(value)
+        ? String(value)
+        : reject(
+            'bigint',
+            `${String(value)} is past ±2^53, where a JS number is no longer exact — pass the digits as a string`,
+          );
+    }
+    return typeof value === 'string' && DIGITS.test(value)
+      ? value
+      : reject('bigint', `expected whole digits, ${got(value)}`);
+  });
+
+export interface DecimalOptions {
+  /** Emits `numeric(precision, scale)`. Both, or neither — a bare `numeric` is unbounded. */
+  readonly precision?: number;
+  readonly scale?: number;
+}
+
+/**
+ * `numeric(p, s)`, whose row type is the exact decimal STRING Postgres returns. Money is the one
+ * decimal this framework has an opinion about (integer minor units plus a currency, always); this
+ * is every other one — a tax rate, an FX rate, a measurement — where the precision is the column's
+ * and no JS number holds it.
+ *
+ * It is deliberately NOT arithmetic-friendly. A framework that handed back a float here would be
+ * the float-money bug with a different name, and one that shipped a decimal type would be shipping
+ * a numeric tower: the honest thing a driver already does is give you the digits.
+ */
+export const decimal = (options: DecimalOptions = {}): Column<string> => {
+  const { precision, scale } = options;
+  if ((precision === undefined) !== (scale === undefined)) {
+    reject('numeric', 'precision and scale are declared together — numeric(18, 8), or neither');
+  }
+  if (precision !== undefined && scale !== undefined) {
+    if (!Number.isInteger(precision) || precision < 1 || precision > 1000) {
+      reject('numeric', `precision must be 1..1000, ${got(precision)}`);
+    }
+    if (!Number.isInteger(scale) || scale < 0 || scale > precision) {
+      reject('numeric', `scale must be 0..precision, ${got(scale)}`);
+    }
+  }
+  const shape = /^-?\d+(\.\d+)?$/;
+  return column<string>(
+    'numeric',
+    (value) => {
+      const text = typeof value === 'number' ? decimalOfNumber(value) : value;
+      if (typeof text !== 'string' || !shape.test(text)) {
+        return reject('numeric', `expected a decimal number, ${got(value)}`);
+      }
+      const digits = text.replace('-', '').split('.');
+      const fraction = digits[1]?.length ?? 0;
+      if (scale !== undefined && fraction > scale) {
+        return reject(
+          'numeric',
+          `${text} has ${fraction} decimal places and the column stores ${scale} — Postgres would round it, silently`,
+        );
+      }
+      if (
+        precision !== undefined &&
+        (digits[0] ?? '').replace(/^0+(?=\d)/, '').length > precision - (scale ?? 0)
+      ) {
+        return reject('numeric', `${text} does not fit numeric(${precision}, ${scale ?? 0})`);
+      }
+      return text;
+    },
+    precision === undefined || scale === undefined ? {} : { precision, numericScale: scale },
+  );
+};
+
+/**
+ * A float is accepted only where it is exactly representable as written — anything else is the
+ * rounding this column exists to refuse, and refusing it at the write is the only place the caller
+ * still knows what they meant.
+ */
+const decimalOfNumber = (value: number): string =>
+  Number.isFinite(value) ? String(value) : 'not-a-number';
+
+/**
+ * A `date`: a calendar date, with no time and therefore no zone. The row type is
+ * `@ultimat3/time`'s `PlainDate`, which is why this is not `timestamp()` with the clock zeroed —
+ * `effective_on` is the date a rate applies, and stored as an instant it is a different date on
+ * either side of midnight for half the planet.
+ *
+ * A driver hands a `date` column back as a `Date` at UTC midnight (measured: Bun's `sql` and
+ * PGlite both), so that is the one conversion here, by its own name. The value written is the
+ * string: binding a `Date` to a `date` parameter fails outright on a server whose client zone has
+ * no name Postgres knows (`time zone "gmt-0500" not recognized`, measured on 17.10).
+ */
+export const date = (): Column<PlainDate> =>
+  column<PlainDate>('date', (value) => {
+    if (value instanceof Date) {
+      return Number.isNaN(value.getTime())
+        ? reject('date', `expected a calendar date, ${got(value)}`)
+        : plainDateUtc(value);
+    }
+    return isPlainDate(value)
+      ? value
+      : reject('date', `expected a YYYY-MM-DD calendar date, ${got(value)}`);
+  });
+
+/**
+ * `bytea`. The row type is a plain `Uint8Array` and both drivers are normalised into one: Bun's
+ * `sql` returns a `Buffer`, PGlite a `Uint8Array`, and the two serialise differently
+ * (`{"type":"Buffer","data":[…]}` against `{"0":…}`) — so a row read through one driver and the
+ * same row read through the other would not be the same object on any wire.
+ */
+export const bytes = (): Column<Uint8Array> =>
+  column<Uint8Array>('bytea', (value) => {
+    if (!(value instanceof Uint8Array)) {
+      return reject('bytea', `expected bytes, ${got(value)}`);
+    }
+    // Already the plain form: the overwhelmingly common case, and it costs one prototype read.
+    return Object.getPrototypeOf(value) === Uint8Array.prototype ? value : new Uint8Array(value);
+  });
+
+/**
+ * `<element>[]` — a Postgres array of a SCALAR column. The element is a column, so its own
+ * `$parse` decides every member: `arrayOf(text({ max: 40 }))` refuses a 41-character tag exactly
+ * where a `text()` column would.
+ *
+ * Money and arrays of arrays are refused rather than approximated: money is three physical columns
+ * and cannot be one array element, and a nested array has no unambiguous literal form.
+ */
+export const arrayOf = <T>(element: Column<T>): Column<readonly T[]> => {
+  const kind = element.$meta.kind;
+  if (kind === 'money' || kind === 'array') {
+    reject(
+      'array',
+      `arrayOf(${kind}) has no single column behind it — an array element is one scalar column`,
+    );
+  }
+  return column<readonly T[]>(
+    'array',
+    (value) => {
+      if (!Array.isArray(value)) return reject('array', `expected an array, ${got(value)}`);
+      return value.map((member) => element.$parse(member));
+    },
+    { element: element as AnyColumn },
+  );
+};
+
+/** The element's own kind, for the projections that need the physical type. */
+export const elementMeta = (meta: ColumnMeta): ColumnMeta | undefined => meta.element?.$meta;