@ultimat3/entity 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -29,6 +29,38 @@ 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.
+- **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,
+  each of them a place the two drivers used to disagree, `As of 2026-08`. **A decimal-string column
+  orders by its digits**: `bigint()` and `decimal()` both hand back a STRING (deliberately —
+  `JSON.stringify` throws on a `bigint` and a `number` loses digits past 2^53), so neither the
+  `number`/`number` branch nor the `bigint`/`bigint` branch fired and both fell to
+  `String(left) < String(right)` — `["10","100","2","9"]` against Postgres' `2, 9, 10, 100`, and a
+  keyset page cut where the database cuts none, since the seek compares the stored string against
+  a revived `BigInt`. The comparison is exact at any width (the fractions are padded and both sides
+  become one integer), which no `Number()` is — and `As of 2026-08` it is **`@ultimat3/core`'s
+  `compareDecimalText`**, not this file's, because the text arrives in more than one package while
+  the declared kind does not. What stays here is `DECIMAL_TEXT` (which kinds are decimal text) and
+  the decision to ask; core's function answers `undefined` for a pair that is not two plain
+  decimals, so a caller with no kinds — `@ultimat3/query`, whose `OrderKey` is a name and a
+  direction — deliberately never calls it: Postgres orders a `text` column of digits lexically, and
+  a comparator guessing "both sides look like decimals" would trade this agreement for that
+  disagreement. That residual gap is `@ultimat3/query`'s `shape-order.test.ts` `DECLARED_GAP`. **A `uuid` is a VALUE**: Postgres parses it and
+  prints it lower-cased, so `findById(UPPER)` reads the row there and answered `null` here, and
+  `update(UPPER)` was `X_NOT_FOUND` against a row that exists — `keyOf(kind, value)`
+  (`batch-read.ts`), which already carried that rule for a batched read, now spells the memory
+  store's key and its equality too. Text is NOT narrowed: lower-casing it would merge two rows
+  Postgres keeps apart. **A `LIKE` pattern uses Postgres' default escape**: `\` escapes `%`, `_`
+  or itself, so `like 'a\%b'` matches the literal `a%b` in both drivers rather than
+  `a\<anything>b` in one — and a pattern ending in the escape character is refused here as
+  Postgres refuses it (`22025`). A RUN of `%` is still one `.*`: twenty adjacent `.*` groups in an
+  anchored regex is a CPU stall on a filter value forwarded from a search box. **`in` takes a list
+  or nothing**, in both drivers and in `@ultimat3/query`: a scalar operand matches NO rows (it was
+  wrapped into a one-element list for the SQL and refused in memory — 0 rows against one driver, 1
+  against the other, from a call `andWhere(column, op, value: unknown)` compiles), and a list
+  carrying a NULL emits `(col in (…) or col is null)` — `col = null` is UNKNOWN, so the null row
+  the caller listed was the one row Postgres left out while memory included it.
 - **The Postgres driver is proved against a real Postgres, not only against a recording client.**
   `pg-driver.live.test.ts` runs the whole chain — `entity()` -> `$describe()` ->
   `generateMigration()` -> a live server -> `postgresDriver()` -> decoded row — and skips when no
@@ -48,7 +80,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
@@ -66,9 +106,15 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   calls `forgetPreloaded(entity.$name)` *before* the statement, so a row a request changed is
   re-read and never served from a page read before it. **Values, not rows**: the index is keyed by
   id and holds ids, so a page early in a long request pins its keys and not its rows, and it dies
-  with the request like every other per-ctx store here. **Declining is the old behaviour**: no
-  request in scope, an id no page indexed, a key that resolved to nothing — the caller reads the
-  statement it always read. `MAX_IDS_PER_STATEMENT` bounds the preload exactly as it bounds a
+  with the request like every other per-ctx store here. **And the store itself is BOUNDED**
+  (`MAX_SIBLING_KEYS`, four statements' worth), `As of 2026-08`: "dies with the request" is a job's
+  whole attempt, `MAX_IDS_PER_STATEMENT` bounded the statement and nothing bounded the store, and
+  1,000 pages x 1,000 distinct keys measured **159.3 MB retained** against a 2.7 MB control — ~2 GB
+  on a 12M-row `backfill()`, an OOM in the worker on the DEFAULT configuration, since `jitPreload`
+  defaults to true and `backfill()` names no driver option. Oldest page first, for both maps: the
+  key index AND the bucket, which holds rows and is therefore the worse of the two.
+  **Declining is the old behaviour**: no request in scope, an id no page indexed, a key that
+  resolved to nothing, a key the bound evicted — the caller reads the statement it always read. `MAX_IDS_PER_STATEMENT` bounds the preload exactly as it bounds a
   batch. What both share — the scope key, `keyOf`, the one `in` statement — lives in
   `batch-read.ts` so the two can never disagree about when a shared statement is legal.
   **One switch, where the driver is built**: `postgresDriver({ jitPreload: false })` /
@@ -274,7 +320,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   rendered from it.** The resolved records are the source; `ColumnDescription.references` spells
   `"<table>.<column>"` out of one for the migration generator, which is in tier 1 and cannot
   import this package. Never parse that string back — it carries physical names and a traversal
-  reads row *properties*, so the parse would be a second, lossy resolver. `references()` is a
+  reads row *properties*, so the parse would be a second, lossy resolver. **`onDelete` rides
+  beside it, on both `ColumnDescription` and `ReferenceDescription`, `As of 2026-08-19`**: the flat
+  string has no room for a rule and neither record had a field for one, so a declared
+  `{ onDelete: 'cascade' }` type-checked and reached no SQL for three majors — `@ultimat3/db` emits
+  it now, and it can only see what the projection carries. Read off the resolved reference, never
+  off `meta` a second time: a rule with no key is not a thing. `references()` is a
   method, not a field: a thunk may point at an entity two modules of an import cycle have not
   finished evaluating. `relationMap()` memoises the whole-registry derivation against
   `registryGeneration()`, which every registration bumps — a schema module imported late must
@@ -360,6 +411,16 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
     the three callers want three answers and the wrong one is invisible in the result. The soft
     delete inside `removal()` passes `false` too — both its callers read a count through
     `execute()`, so its rows were never readable by anyone.
+- **Every instant the write path stamps comes from `ctx.clock`, through `entityNow()`**
+  (`clock.ts`, `As of 2026-08`). `defaultNow()`, `touch()`'s `onUpdateNow()`, the soft-delete stamp
+  in BOTH drivers and a seed's `now` each read `systemClock` directly, so a frozen test clock drove
+  nothing the entity layer wrote — `createdAt`, `updatedAt` and `deletedAt` were the wall clock
+  however the ctx was built, and a test could only assert a range where it wanted a value. The read
+  path still reads no clock at all, which is what makes IT drivable (`@ultimat3/query`'s CLAUDE.md
+  says so in as many words); this is the write half of the same property. Outside a request there
+  is no ctx and the system clock IS the answer — a script, a worker boot and a seed take that
+  branch exactly as before. Never read `systemClock` on the write path again: five sites is how the
+  four stamps of one write ended up able to disagree.
 - **`touch()` in `query.ts` is the ONE place `onUpdateNow()` columns are stamped**, for
   `update(id, patch)` and `updateWhere(filter, patch)` alike — a second copy is how one of them
   ends up writing a stale `updatedAt`. It returns an empty patch untouched, so whether
@@ -578,6 +639,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`.
@@ -586,12 +717,15 @@ 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 |
+| `types.ts` | `Column`, `RowOf`, `Insertable`, `IdOf` — the type derivation. `COLUMN_KINDS` is the runtime array `ColumnKind` DERIVES from (the shape core's `PRIMITIVE_KINDS` uses), so a package answering "one case per kind" reads a real list rather than spelling its own |
+| `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` |
 | `query.ts` / `database.ts` | chainable read to a cursor page; `database()` + `Driver` |
+| `clock.ts` | `entityNow()` — the ONE clock read on the write path, `ctx.clock` else the system's |
+| `memory-match.ts` | what a `Predicate` means in the memory driver: compare/equal/LIKE, by the column's kind. The decimal comparison itself is `@ultimat3/core`'s `compareDecimalText` |
 | `repo.ts` / `tenancy.ts` | `Repo<T>` + `memoryDriver`'s repo, tx rollback; `QueryPlan` + `scopedPlan()` for a read and `assertRowTenant()` for a write — one actor-derived tenant guard, both halves |
 | `cross-tenant.ts` | `crossTenant(reason, fn)` — the capability-gated scope that lifts it |
 | `plan.ts` / `cursor.ts` | the plan both drivers execute; the one keyset cursor codec |
@@ -607,6 +741,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
 
@@ -331,6 +381,13 @@ database({ orgs, posts }, { driver: postgresDriver() });   // production
 | For | tests, `x dev` before the first migration | production |
 | Transaction | `memoryTransactor()` — undo closures | `postgresTransactor()` — real `BEGIN`/`COMMIT` |
 | `reset()` | empties every repository it built | not implemented — the rows are the app's |
+| A predicate | `memory-match.ts`, by the column's declared KIND | the SQL `pg-sql.ts` compiles |
+
+Both answer the same predicate the same way, and the kind is what decides — never the JS type of
+the value: `bigint()`/`decimal()` hold decimal STRINGS and order by their digits (`2, 9, 10, 100`),
+a `uuid` compares case-insensitively because Postgres compares it as a value, `\` escapes a `%` or
+a `_` inside a `like`, and `in` takes a list or nothing (a scalar matches no rows; a list carrying
+a `null` also matches the NULL rows, which `col = null` never does).
 
 `database()` called with no driver takes the process default, and `defaultDriver()` is that same
 object — the one seam a test harness needs, `As of 2026-08`:
@@ -514,9 +571,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": "4.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": "4.0.0",
+    "@ultimat3/db": "4.0.0",
+    "@ultimat3/schema": "4.0.0",
+    "@ultimat3/time": "4.0.0"
   }
 }

package/src/bulk-write.ts

@@ -5,10 +5,12 @@
 // reads the same answer rather than a second copy of the rule.
 
 import { keyOf } from './batch-read';
+import { columnFor } from './column';
 import { valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError, invariantViolated } from './errors';
 import { columnsOf } from './pg-row';
+import type { RowPatch } from './types';
 
 /**
  * Postgres binds at most 65535 parameters in one statement and a multi-row insert spends
@@ -36,7 +38,7 @@ const owns = (row: unknown, property: string): boolean =>
  */
 export const namedProperties = <Row>(
   entity: EntityCore<Row>,
-  rows: readonly Partial<Row>[],
+  rows: readonly RowPatch<Row>[],
 ): readonly string[] =>
   Object.keys(entity.$columns).filter((property) => rows.some((row) => owns(row, property)));
 
@@ -46,7 +48,7 @@ export const insertColumns = <Row>(
   properties: readonly string[],
 ): readonly string[] =>
   properties.flatMap((property) => {
-    const column = entity.$columns[property];
+    const column = columnFor(entity.$columns, property);
     return column === undefined ? [] : columnsOf(property, column);
   });
 
@@ -180,13 +182,13 @@ const sameColumns = (left: readonly string[], right: readonly string[]): boolean
  */
 export const upsertPlan = <Row>(
   entity: EntityCore<Row>,
-  rows: readonly Partial<Row>[],
+  rows: readonly RowPatch<Row>[],
   onConflict: readonly string[],
   onMatch: 'update' | 'nothing',
 ): UpsertPlan => {
   if (onConflict.length === 0) throw noConflictTarget(entity.$name);
   for (const property of onConflict) {
-    if (entity.$columns[property] === undefined) {
+    if (columnFor(entity.$columns, property) === undefined) {
       throw invariantViolated(
         entity.$name,
         'upsertAll',
@@ -252,10 +254,10 @@ const cellKey = (kind: string, value: unknown): string | undefined => {
 export const conflictKeyOf = <Row>(
   entity: EntityCore<Row>,
   on: readonly string[],
-  row: Partial<Row>,
+  row: RowPatch<Row>,
 ): string | undefined => {
   const cells = on.map((property) =>
-    cellKey(entity.$columns[property]?.$meta.kind ?? '', valueAt(row, property)),
+    cellKey(columnFor(entity.$columns, property)?.$meta.kind ?? '', valueAt(row, property)),
   );
   return cells.some((cell) => cell === undefined) ? undefined : JSON.stringify(cells);
 };
@@ -270,7 +272,7 @@ export const conflictKeyOf = <Row>(
 export const conflictKeys = <Row>(
   entity: EntityCore<Row>,
   plan: UpsertPlan,
-  rows: readonly Partial<Row>[],
+  rows: readonly RowPatch<Row>[],
 ): readonly (string | undefined)[] => {
   const keys = rows.map((row) => conflictKeyOf(entity, plan.on, row));
   if (plan.set.length === 0) return keys;

package/src/clock.ts

@@ -0,0 +1,18 @@
+// Single responsibility: the instant the entity layer WRITES. One reader of the clock, so
+// `defaultNow()`, `onUpdateNow()`, the soft-delete stamp and a seed's `now` are one value from one
+// source — and a second `systemClock.now()` anywhere on the write path is a timestamp no test can
+// drive and no two of these four can agree with.
+
+import { systemClock, tryUseContext } from '@ultimat3/core';
+
+/**
+ * `ctx.clock`, and the system clock outside every request.
+ *
+ * The READ path reads no clock at all, which is what makes it drivable (`@ultimat3/query`'s
+ * CLAUDE.md says so in as many words). The write path read `systemClock` directly at five sites, so
+ * a frozen test clock drove nothing the entity layer stamped: `createdAt`, `updatedAt` and
+ * `deletedAt` all came from the wall clock however the ctx was built, and a test asserting on one
+ * had to assert a range instead of a value. Outside a request there is no ctx and the system clock
+ * IS the answer — a script, a worker boot and a seed all take that branch, exactly as before.
+ */
+export const entityNow = (): Date => (tryUseContext()?.clock ?? systemClock).now();

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,66 @@
 // 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,
+  ColumnMap,
+  ColumnMeta,
+  MoneyColumnNames,
+  TimestampColumn,
+} from './types';
+
+/**
+ * The column a NAME resolves to, or `undefined` — the ONE read of a column map by a name that came
+ * from outside it.
+ *
+ * `columns[property]` alone walks `Object.prototype`: an app's column map is a plain object
+ * literal, so `columns['constructor']` answers the `Object` FUNCTION, every `=== undefined` guard
+ * downstream passes, and the next `.$meta.kind` is a bare `TypeError` where the caller was owed
+ * `X_INVARIANT_VIOLATED` naming the columns that do exist. The name is caller data on every path
+ * that reaches here — a predicate column, a sort key, an `onConflict` target, a `select` list — so
+ * the discriminator lives in one place. Same read `tenancy.ts` already does for the tenant column.
+ */
+export const columnFor = (columns: ColumnMap, property: string): AnyColumn | undefined =>
+  Object.hasOwn(columns, property) ? columns[property] : undefined;
 
 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 +104,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 +190,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 +232,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),
 });