@ultimat3/entity 22.15.0 → 24.0.0

package/src/bulk-write.ts

@@ -11,6 +11,7 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError, invariantViolated } from './errors';
 import { columnsOf } from './pg-row';
 import type { RowPatch } from './types';
+import { uniqueConstraints } from './unique-constraints';
 
 /**
  * Postgres binds at most 65535 parameters in one statement and a multi-row insert spends
@@ -134,22 +135,12 @@ const crossTenantUpsert = (
   });
 
 /**
- * Every conflict target Postgres could infer an index for. Three sources, because this framework
- * has three ways to declare one unique index and a target refused for being declared the "wrong"
- * way would send its author to add a SECOND declaration of a constraint they already wrote:
- * the primary key, `unique()`/`indexes: [{ unique: true }]` (both land in `$indexes`), and
- * `invariant(name, c.unique([…]))`, which emits its `create unique index` out of `$invariants`.
- *
- * A partial unique index is excluded from all three: its predicate would have to be repeated in
- * the `on conflict` clause, which this layer does not spell. `bindInvariant` stamps that `where`
- * on a soft-deleting entity, so the same one rule covers both lists.
+ * Every conflict target Postgres could infer an index for: the primary key, and every non-partial
+ * unique the entity declares by either spelling (`unique-constraints.ts`).
  */
 const uniqueTargets = <Row>(entity: EntityCore<Row>): readonly (readonly string[])[] => [
   insertColumns(entity, entity.$primaryKey),
-  ...entity.$indexes.filter((i) => i.unique && i.where === undefined).map((i) => i.columns),
-  ...entity.$invariants
-    .filter((i) => i.kind === 'unique' && i.where === undefined)
-    .map((i) => i.columns),
+  ...uniqueConstraints(entity).map((unique) => unique.columns),
 ];
 
 const sameColumns = (left: readonly string[], right: readonly string[]): boolean =>

package/src/column.ts

@@ -240,8 +240,43 @@ export const makeColumn = <T, Optional extends boolean>(
  * the derived name is checked, because that runs once per column at `entity()` rather than on
  * every statement.
  */
+const isPhysicalName = (name: string): boolean =>
+  /^[a-z_][a-z0-9_$]*$/.test(name) && name.length <= 63;
+
+/** The nearest legal spelling of a name, so the fix hands back a value and never a placeholder. */
+const physicalSpelling = (name: string): string => {
+  const snake = name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9_$]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return (/^[a-z_]/.test(snake) ? snake : `t_${snake}`).slice(0, 63);
+};
+
+/** A name as a TypeScript literal that parses whatever it holds — it is pasted into source. */
+const asSource = (name: string): string =>
+  /^[\w-]+$/.test(name) ? `'${name}'` : JSON.stringify(name);
+
+/**
+ * The TABLE's physical name — `init.table`, or the entity name when none is declared. The same
+ * rule as a column's, and its own refusal: it used to go through `assertColumnName`, which called
+ * a table "not a physical column name" and handed back `.column('created_at')`, an edit to a
+ * column that was never the problem. The repair is at `entity(name, { table })`, and the entity
+ * NAME stays what it was — cache tags and policies key on it.
+ */
+export const assertTableName = (entityName: string, table: string): string => {
+  if (!isPhysicalName(table)) {
+    refuseColumn(
+      'table-name',
+      `"${table}" is not a physical table name: lower-case letters, digits and underscores, at most 63 of them`,
+      `entity(${asSource(entityName)}, { table: '${physicalSpelling(table)}', columns })   # table is the physical name; the entity name is unchanged`,
+    );
+  }
+  return table;
+};
+
 export const assertColumnName = (name: string): string => {
-  if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {
+  if (!isPhysicalName(name)) {
     refuseColumn(
       'column-name',
       `"${name}" is not a physical column name: lower-case letters, digits and underscores, at most 63 of them`,

package/src/columns-data.ts

@@ -58,6 +58,25 @@ const canonicalDigits = (digits: string): string => {
   return negative && whole !== '0' ? `-${whole}` : whole;
 };
 
+const INT8_MIN = -(2n ** 63n);
+const INT8_MAX = 2n ** 63n - 1n;
+
+/**
+ * Whole digits inside `int8`, in Postgres's spelling. Memory stored a 40-digit value the server
+ * answers `22003 — bigint out of range` for, so a row every app test wrote was one production
+ * refuses. The digits are never echoed: a column message reaches the log line.
+ */
+const int8 = (digits: string): string => {
+  const value = BigInt(digits);
+  return value >= INT8_MIN && value <= INT8_MAX
+    ? canonicalDigits(digits)
+    : refuseColumn(
+        'bigint',
+        'the value is past the int8 range (-2^63 to 2^63 - 1), which Postgres answers 22003 for',
+        'declare the column decimal({ precision: 40, scale: 0 }) — a numeric holds whole numbers past int8 — and run x db gen "widen the bigint to numeric"',
+      );
+};
+
 /**
  * An ACCEPTED decimal in Postgres's spelling: leading zeros stripped, `-0` and `-0.00` unsigned,
  * and a short fraction padded to the column's scale (`numeric(8, 2)` answers `7.50` for `7.5`).
@@ -86,7 +105,7 @@ const canonicalDecimal = (text: string, scale: number | undefined): string => {
  */
 export const bigint = (): Column<string> =>
   column<string>('bigint', (value) => {
-    if (typeof value === 'bigint') return value.toString();
+    if (typeof value === 'bigint') return int8(value.toString());
     if (typeof value === 'number') {
       return Number.isSafeInteger(value)
         ? String(value)
@@ -97,7 +116,7 @@ export const bigint = (): Column<string> =>
           );
     }
     return typeof value === 'string' && DIGITS.test(value)
-      ? canonicalDigits(value)
+      ? int8(value)
       : refuseColumn(
           'bigint',
           `expected whole digits, ${got(value)}`,
@@ -167,7 +186,9 @@ export const decimal = (options: DecimalOptions = {}): Column<string> => {
           `Number(value).toFixed(${scale}) at the call site decides the rounding, or widen the column to decimal({ precision: ${(precision ?? fraction) + fraction - scale}, scale: ${fraction} }) and run x db gen "widen the numeric"`,
         );
       }
-      const whole = (digits[0] ?? '').replace(/^0+(?=\d)/, '').length;
+      // A whole part of `0` is NO digit: `numeric(2, 2)` holds `0.50`, and counting the zero
+      // refused every legal value of a `numeric(p, p)` column.
+      const whole = (digits[0] ?? '').replace(/^0+/, '').length;
       if (precision !== undefined && whole > precision - (scale ?? 0)) {
         return refuseColumn(
           'numeric',

package/src/columns-scalar.ts

@@ -3,17 +3,18 @@
 // store a value production answers 23514, 22003 or 22021 (a NUL in text) for. Split from `columns.ts` at its ceiling.
 
 import { charCount } from '@ultimat3/schema';
-import { column } from './column';
+import { BARE, column } from './column';
 import { got, refuseNul } from './column-values';
 import { refuseColumn } from './refuse';
-import type { Column } from './types';
+import { makeTextColumn } from './sealed-column';
+import type { Column, TextColumn } from './types';
 
 export interface TextOptions {
   /** Emits `char_length(<column>) <= max`, so Postgres refuses an over-long string too. */
   readonly max?: number;
 }
 
-export const text = (options: TextOptions = {}): Column<string> => {
+export const text = (options: TextOptions = {}): TextColumn => {
   const { max } = options;
   // Refused where it is declared: a `NaN` or fractional max emitted `char_length(x) <= NaN` into
   // the DDL, which Postgres refuses one migration later, far from the line that wrote it.
@@ -24,8 +25,14 @@ export const text = (options: TextOptions = {}): Column<string> => {
       'text({ max: 200 }) — a whole count of characters, or text() for no bound',
     );
   }
-  return column<string>(
-    'text',
+  return makeTextColumn<string, false>(
+    {
+      ...BARE,
+      kind: 'text',
+      ...(max === undefined
+        ? {}
+        : { length: max, check: (name) => `char_length(${name}) <= ${max}` }),
+    },
     (value) => {
       if (typeof value !== 'string') {
         return refuseColumn(
@@ -45,7 +52,7 @@ export const text = (options: TextOptions = {}): Column<string> => {
       }
       return refuseNul(value);
     },
-    max === undefined ? {} : { length: max, check: (name) => `char_length(${name}) <= ${max}` },
+    false,
   );
 };
 

package/src/columns.ts

@@ -109,6 +109,9 @@ const parseInstant = (value: unknown): Date => {
 export const timestamp = (): TimestampColumn =>
   makeTimestamp<false>({ ...BARE, kind: 'timestamptz' }, parseInstant, false);
 
+/** The column's CHECK (`~ '^https?://'`), before the scheme is lower-cased. */
+const STORED_HTTP = /^https?:\/\//i;
+
 /**
  * An absolute http(s) URL, validated on write rather than on render: a bad URL stored once is
  * served to every reader, and `<img src>` fails silently in the browser.
@@ -126,7 +129,11 @@ export const url = (): Column<string> =>
           // The scheme is stored in its canonical LOWER case: the CHECK is `~ '^https?://'`, so
           // `HTTPS://a.b` was stored by memory and refused by Postgres. Only the scheme is
           // rewritten — the rest of the URL is the caller's, byte for byte.
-          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+          // And the STORED text must itself open with it: WHATWG strips leading whitespace and
+          // embedded tabs and mends `https:/a.b` before `protocol` is read, while the column keeps
+          // the caller's bytes — which the CHECK then refused as a raw 23514.
+          const http = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+          if (http && STORED_HTTP.test(value)) {
             return value.replace(/^https?(?=:)/i, (scheme) => scheme.toLowerCase());
           }
         } catch {

package/src/containment.ts

@@ -28,6 +28,15 @@ const sameElement = (left: unknown, right: unknown): boolean => {
   return left === right;
 };
 
+/**
+ * Two elements of a SQL ARRAY, equal — and a NULL element is equal to nothing, itself included.
+ * `array['a', null] @> array[null]` and `array[null] && array[null]` are both FALSE in Postgres:
+ * the element comparison is `=`, and `NULL = NULL` is unknown. Arrays only — a `jsonb` `null` is a
+ * VALUE and equals itself, which is why `jsonContains` keeps `sameElement`.
+ */
+const sameArrayElement = (left: unknown, right: unknown): boolean =>
+  !isNull(left) && !isNull(right) && sameElement(left, right);
+
 /**
  * `left @> right` for `jsonb`, to the letter of Postgres' definition — each clause below measured
  * on Postgres 16 rather than read off a summary, because three of them are easy to state wrongly:
@@ -67,7 +76,7 @@ const contains = (left: unknown, right: unknown, top: boolean): boolean => {
  * by every array, which is what Postgres answers.
  */
 export const arrayContains = (left: readonly unknown[], right: readonly unknown[]): boolean =>
-  right.every((item) => left.some((candidate) => sameElement(candidate, item)));
+  right.every((item) => left.some((candidate) => sameArrayElement(candidate, item)));
 
 /**
  * `left && right`: they share at least one element. Arrays only — `jsonb` has no `&&` — and the
@@ -75,7 +84,7 @@ export const arrayContains = (left: readonly unknown[], right: readonly unknown[
  * contained by everything.
  */
 export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[]): boolean =>
-  right.some((item) => left.some((candidate) => sameElement(candidate, item)));
+  right.some((item) => left.some((candidate) => sameArrayElement(candidate, item)));
 
 /**
  * The memory half of `col ? key`. The SQL side emits the OPERATOR, schema-qualified —
@@ -88,6 +97,10 @@ export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[
  * Three shapes, all of them Postgres': a top-level key of an object, a string ELEMENT of an array,
  * and a string value equal to the key. A number never matches — `'[1]'::jsonb ? '1'` is false
  * there, and a `String(item) === key` here would have made it true.
+ *
+ * The KEY is a string or the test matches no row, in both drivers: `pg-sql.ts` compiles any other
+ * operand to no rows rather than binding `String(key)`, which found a key named `"null"` for a
+ * `null` operand and `"1"` for the number `1`.
  */
 export const jsonHasKey = (value: unknown, key: unknown): boolean => {
   if (typeof key !== 'string' || isNull(value)) return false;

package/src/database.ts

@@ -2,11 +2,11 @@
 // writes a repository class per entity, and nobody can reach a table that is not in the set.
 
 import type { EntityCore } from './entity';
-import { memoryRepo } from './memory-repo';
+import { memoryRepo, memoryTransactor } from './memory-repo';
 import type { RelatedTables } from './preload';
 import type { Table } from './query';
 import { tableFor } from './query';
-import type { Repo } from './repo';
+import type { Repo, Transactor } from './repo';
 import { observedRepo } from './row-observer';
 
 export type EntitySet = Readonly<Record<string, EntityCore>>;
@@ -25,6 +25,12 @@ export interface Driver {
    * `reset()` eventually would. A harness therefore asks and does not assume: `driver.reset?.()`.
    */
   reset?(): void;
+  /**
+   * The transactor that undoes THIS driver's writes. Required: a seed dry run writes for real and
+   * rolls back through it, and a driver that could not undo would be found out at run time. A
+   * driver that wraps another delegates — `transactor: () => inner.transactor()`.
+   */
+  transactor(): Transactor;
 }
 
 export interface DatabaseOptions {
@@ -54,6 +60,7 @@ export const memoryDriver = (): Driver => {
     reset() {
       for (const reset of resets) reset();
     },
+    transactor: () => memoryTransactor(),
   };
 };
 

package/src/entity-error.ts

@@ -1,11 +1,19 @@
 // The entity layer's code registry, its error class, and the two refusals the declaration path
 // raises — split from `errors.ts` so a module the BROWSER loads (the record key, the projection,
-// the registry) can raise one without importing `@ultimat3/db`, which `errors.ts` needs for
-// `dbDrift`'s shell-inert fix line.
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+// the registry) can raise one without importing `@ultimat3/db`.
+import type { ErrorRetry } from '@ultimat3/core';
+import {
+  isFixShellSafe,
+  registerErrorCodes,
+  registerErrorRetry,
+  UltimateError,
+} from '@ultimat3/core';
 
-/** Codes this package declares and owns. */
-export const ENTITY_OWNED_ERROR_CODES = [
+/**
+ * Every code this package throws, and it owns each one. `X_DB_DRIFT` is `@ultimat3/db`'s and is
+ * raised there — drift is a fact about migrations.
+ */
+export const ENTITY_ERROR_CODES = [
   'X_ENTITY_DUPLICATE',
   'X_INVARIANT_VIOLATED',
   'X_TENANCY_UNSCOPED',
@@ -28,25 +36,13 @@ export const ENTITY_OWNED_ERROR_CODES = [
   'X_STATE_TRANSITION_ILLEGAL',
   'X_STATE_CONFLICT',
   'X_RECORD_KEY_MISSING',
+  'X_ENTITY_SEALED_PREDICATE',
+  'X_ENTITY_SEALED_IN_VIEW',
 ] as const;
 
-/**
- * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
- * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
- * second copy of the title is what lets the two packages disagree about what the code means.
- */
-export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
-
-/** Every code entity can throw: the ones it owns plus the one it borrows. */
-export const ENTITY_ERROR_CODES = [
-  ...ENTITY_OWNED_ERROR_CODES,
-  ...ENTITY_BORROWED_ERROR_CODES,
-] as const;
-
-export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
 
-export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
+export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_DUPLICATE: 'two entities claim the same name',
   X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
   X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
@@ -71,6 +67,9 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>>
   X_STATE_TRANSITION_ILLEGAL: 'the machine has no such transition',
   X_STATE_CONFLICT: 'the row is no longer in the state this transition named',
   X_RECORD_KEY_MISSING: 'a row reached its record key without a primary-key value',
+  X_ENTITY_SEALED_PREDICATE:
+    'a sealed column is read by a predicate, an order or a rule the database evaluates',
+  X_ENTITY_SEALED_IN_VIEW: 'a sealed column is named in a view',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the
@@ -80,6 +79,20 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
+/**
+ * How the codes here that are worth classifying are retried. Only the two sealed-column refusals:
+ * both are the app's own declaration or call, so attempt five answers what attempt one did — and
+ * left unclassified, `classifyThrown` reads them as undecided and a job spends its whole retry
+ * policy re-proving it. Listed although `terminal` is the default, for the reason core's own table
+ * gives for `X_NOT_IMPLEMENTED`. The rest of this package's codes are unclassified, as they were.
+ */
+export const ENTITY_ERROR_RETRY = {
+  X_ENTITY_SEALED_PREDICATE: 'terminal',
+  X_ENTITY_SEALED_IN_VIEW: 'terminal',
+} as const satisfies Readonly<Partial<Record<EntityErrorCode, ErrorRetry>>>;
+
+registerErrorRetry(ENTITY_ERROR_RETRY);
+
 /**
  * Base for every error this package throws. No `docs:` — `UltimateError` fills it from
  * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
@@ -100,6 +113,18 @@ export class EntityError extends UltimateError {
   }
 }
 
+/**
+ * The one command a BOUND refusal hands back — a page size, a preload ceiling, a judged write: it
+ * runs, and it names the real entity. The edit itself is code on a chain whose variable no error
+ * can know (`db.members`, not `preload_test_members`), so it is spelled in the `cause` as the call
+ * to write, never in the `fix` as though the entity name were that variable. A name a shell would
+ * read is not spliced.
+ */
+export const describeCommand = (entityName: string): string =>
+  isFixShellSafe(entityName)
+    ? `x entities describe ${entityName} --json`
+    : 'x entities list --json';
+
 /**
  * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
  * given. A literal is an entity that does not exist, and this fix then hands the reader

package/src/entity.ts

@@ -6,7 +6,7 @@
 import type { IndexMethod } from '@ultimat3/db';
 import { describeValue, type Schema } from '@ultimat3/schema';
 import { entityNow } from './clock';
-import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
+import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
 import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
@@ -19,10 +19,13 @@ import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
 import { rowSchema } from './row-schema';
+import { sealedFields } from './sealed';
+import { assertSealedDeclaration } from './sealed-declaration';
+import { sealedInView, sealedMissing } from './sealed-errors';
 import type { SearchInit, SearchSource, SearchVector } from './search';
 import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
-import type { AnyColumn, ColumnMap, ColumnMeta, IndexDef, RowOf } from './types';
+import type { AnyColumn, ColumnMap, ColumnMeta, IndexDef, RowOf, WireRow } from './types';
 import type { EntityView } from './view';
 import { viewFor } from './view';
 
@@ -123,8 +126,13 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
    * (bare or wrapped: `t.array(posts.$schema)`) is a row the client store adopts, because its node
    * carries the `recordProjection` brand. A `$view` or a `.pick()` carries none: a partial row is
    * never a record.
+   *
+   * Typed `unknown` HERE and precisely on `Entity`: the parsed value is the row WITHOUT its sealed
+   * columns (`WireRow`), which is not `Row`, and a conditional over `C` in this interface would
+   * stop every `EntityCore<Row, C>` being an `EntityCore<Row>`. A row-agnostic consumer never read
+   * the output type; the one that does holds the `entity()` result.
    */
-  readonly $schema: Schema<unknown, Row>;
+  readonly $schema: Schema<unknown, unknown>;
   /** `entity:<name>:<id>` — row-level invalidation for live queries. */
   $tagFor(id: string): string;
   /** Fills declared defaults, then validates every column. Throws on a bad value. */
@@ -149,7 +157,14 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   $references(): readonly ReferenceDescription[];
 }
 
-export type Entity<Row, C extends ColumnMap = ColumnMap> = EntityCore<Row, C> & C;
+/**
+ * What `entity()` returns. `$schema` is restated with its real output: the row as it leaves the
+ * server, without the sealed columns — so `output: users.$schema` types a client that cannot read
+ * `password`, which is the value it will not be sent. `$parse` and `$row` are the whole row.
+ */
+export type Entity<Row, C extends ColumnMap = ColumnMap> = Omit<EntityCore<Row, C>, '$schema'> & {
+  readonly $schema: Schema<unknown, WireRow<Row, C>>;
+} & C;
 
 const MONEY_PARTS = new Set(['minor', 'currency']);
 
@@ -171,7 +186,7 @@ export const entity = <const C extends ColumnMap>(
   // Both branches. The declared table was checked and the fallback — which is every entity that
   // does not rename its table — was not, so an entity NAME closed the identifier in the same way a
   // column name could: `entity('t" (x int); drop table u; --')` emitted that `drop table` verbatim.
-  const table = assertColumnName(init.table ?? name);
+  const table = assertTableName(name, init.table ?? name);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
@@ -227,10 +242,7 @@ export const entity = <const C extends ColumnMap>(
     return part === 'minor' ? parts.minor : parts.currency;
   };
 
-  const columnsExpr = invariantColumns<C>(
-    name,
-    entries.map(([property]) => property),
-  );
+  const columnsExpr = invariantColumns<C>(name, init.columns);
   // Through the one resolver, so a soft-delete column the table spells differently is still the
   // column every partial index excludes rows by.
   const partialWhere = softDelete ? `${resolve([SOFT_DELETE_COLUMN])} is null` : undefined;
@@ -341,6 +353,19 @@ export const entity = <const C extends ColumnMap>(
       declared.findIndex((other) => identity(other) === identity(index)) === position,
   );
 
+  const sealed = sealedFields({ $name: name, $table: table, $columns: init.columns });
+  assertSealedDeclaration({
+    name,
+    fields: sealed,
+    primaryKey,
+    tenantColumn,
+    indexes,
+    invariants,
+  });
+  const sealedKeys = new Set(sealed.map((field) => field.property));
+  /** The columns that leave the server: every one that is not sealed. */
+  const wireEntries = entries.filter(([property]) => !sealedKeys.has(property));
+
   const tags = [cacheTag, ...(init.tags ?? [])];
   const describe = (): EntityDescription =>
     describeEntity({
@@ -377,7 +402,11 @@ export const entity = <const C extends ColumnMap>(
       const given = raw === undefined ? defaultValue(column.$meta) : raw;
       if (given === undefined || given === null) {
         if (column.$meta.notNull) {
-          throw invariantViolated(name, property, 'is required and has no default');
+          // A required sealed column ABSENT from a row is nearly always a spread of a repository
+          // row, which does not enumerate it — so the refusal names that, and the rewrite.
+          throw given === undefined && sealedKeys.has(property)
+            ? sealedMissing(name, property)
+            : invariantViolated(name, property, 'is required and has no default');
         }
         row[property] = null;
         continue;
@@ -388,6 +417,39 @@ export const entity = <const C extends ColumnMap>(
     return row as Row;
   };
 
+  /**
+   * The row as `$schema` validates it: the sealed columns are neither required nor returned, so a
+   * handler's row — which holds their plaintext — parses to a value that does not.
+   */
+  const parseWire = (value: unknown): WireRow<Row, C> => {
+    if (sealedKeys.size === 0) return parse(value) as WireRow<Row, C>;
+    if (typeof value !== 'object' || value === null) {
+      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
+    }
+    const input = value as Readonly<Record<string, unknown>>;
+    const row: Record<string, unknown> = {};
+    for (const [property, column] of wireEntries) {
+      const raw = input[property];
+      const given = raw === undefined ? defaultValue(column.$meta) : raw;
+      if (given === undefined || given === null) {
+        if (column.$meta.notNull) {
+          throw invariantViolated(name, property, 'is required and has no default');
+        }
+        row[property] = null;
+        continue;
+      }
+      row[property] = column.$parse(given);
+    }
+    // Every wire property was validated by its own column, and no sealed one was copied.
+    return row as WireRow<Row, C>;
+  };
+
+  const schema = rowSchema<WireRow<Row, C>>(
+    { name, table, primaryKey, persist: init.persist === true, sealed: [...sealedKeys] },
+    wireEntries,
+    parseWire,
+  );
+
   const core: EntityCore<Row, C> = {
     $name: name,
     $table: table,
@@ -400,19 +462,19 @@ export const entity = <const C extends ColumnMap>(
     $softDelete: softDelete,
     $tenantColumn: tenantColumn,
     $search: search,
-    $schema: rowSchema<Row>(
-      { name, table, primaryKey, persist: init.persist === true },
-      entries,
-      parse,
-    ),
+    $schema: schema,
     get $row(): Row {
       // Type-only. Reading it means someone expected a value where a type was meant.
       throw invariantViolated(name, '$row', '$row is a type, not a value — use typeof x.$row');
     },
     $tagFor: (id) => `${cacheTag}:${id}`,
     $parse: parse,
-    $view: <K extends keyof Row & string>(keys: readonly K[]) =>
-      viewFor<Row, K>(name, init.columns, keys),
+    $view: <K extends keyof Row & string>(keys: readonly K[]) => {
+      // Before the view exists: a view is an `output`, and a sealed column is in none.
+      const named = keys.find((key) => sealedKeys.has(key));
+      if (named !== undefined) throw sealedInView(name, named);
+      return viewFor<Row, K>(name, init.columns, keys);
+    },
     $assert: (row) => assertInvariants(name, invariants, row),
     $describe: describe,
     $references: references,
@@ -429,5 +491,6 @@ export const entity = <const C extends ColumnMap>(
   });
   // The columns land on the entity itself so `orgs.id` is a column reference; every framework
   // member is `$`-prefixed, which is why a column may be called `name`.
-  return Object.assign(core, init.columns);
+  // `$schema` is restated so the result carries its real output type; it is the same object.
+  return Object.assign(core, init.columns, { $schema: schema });
 };

package/src/errors.ts

@@ -1,16 +1,14 @@
-// The entity layer's stable error codes. Each factory produces the exact command
-// that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
-// column and the generator invocation. The code registry, the class, `invariantViolated` and
-// `entityDuplicate` live in `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here.
-import { shellInertIdentifier } from '@ultimat3/db';
+// The entity layer's stable error codes. Each factory produces the exact command that fixes the
+// situation. The code registry, the class, `invariantViolated` and `entityDuplicate` live in
+// `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here. `X_DB_DRIFT` is not
+// raised here at all: drift is `@ultimat3/db`'s, factory included.
 import { EntityError } from './entity-error';
 
-export type { EntityErrorCode, EntityOwnedErrorCode } from './entity-error';
+export type { EntityErrorCode } from './entity-error';
 export {
-  ENTITY_BORROWED_ERROR_CODES,
+  describeCommand,
   ENTITY_ERROR_CODES,
   ENTITY_ERROR_TITLES,
-  ENTITY_OWNED_ERROR_CODES,
   EntityError,
   entityDuplicate,
   invariantViolated,
@@ -165,20 +163,18 @@ export const crossTenantDenied = (init: {
   });
 
 /**
- * A repository built with an explicit `client`, used while a transaction is open.
+ * A repository built with an explicit `client`, used inside a transaction that was opened on some
+ * OTHER client.
  *
- * Refused rather than resolved, because neither answer is available. `withTransaction` reserves
- * ONE connection and runs `BEGIN` on it — the ambient pool's, or a reservation of its own
- * `client:` option — while a repository pinned through `postgresDriver({ client })` sends every
- * statement straight to that client, which takes a different connection out of the pool. So the
- * write commits immediately and survives the rollback, and the read cannot see the rows the
- * transaction has already written; both are silent. Joining the transaction instead would be the
- * worse half of the same guess: a `DbTx` does not name the client it was opened on, so "is this
- * even the same database" is not a question this layer can ask, and on a sharded app the answer
- * is no.
+ * Refused rather than resolved. `withTransaction` reserves one connection and runs `BEGIN` on it,
+ * while a pinned repository sends to its own client — another connection, and on a sharded app
+ * another database — so the write would commit immediately and survive the rollback, and the read
+ * would miss rows the transaction has written; both silent. A transaction opened ON the pinned
+ * client (`tx.origin`) is the same database and the same reservation, and the repository joins it:
+ * that case never reaches here.
  *
- * The fix names the ambient seam because that is the one path a repository joins a transaction
- * through: `db()` resolves `currentTx()` first, which is exactly what a pinned client skips.
+ * The fix names the ambient seam because that is the path a repository joins the AMBIENT
+ * transaction through: `db()` resolves `currentTx()` first, which is what a pinned client skips.
  */
 export const repoClientPinned = (entityName: string): EntityError =>
   new EntityError({
@@ -187,28 +183,6 @@ export const repoClientPinned = (entityName: string): EntityError =>
     fix: `setDbClient(client) at boot and build the repository with no client: — postgresDriver() then resolves the open transaction through db() — or run this call outside withTransaction()`,
   });
 
-/**
- * The contract's pinned wording. Mirror of `@ultimat3/db`'s `dbDrift()` (`drift-errors.ts`) —
- * keep in sync; both screen through the same `shellInertIdentifier`, so the two lines are one
- * text on both sides of the tier seam, and `errors.test.ts` asserts it rather than asking.
- *
- * The column is the CATALOG's, so it is data, and `x db gen "add C"` puts it inside SHELL DOUBLE
- * QUOTES where `$(…)` and a backtick substitute before `x` is reached at all. The argument is a
- * migration DESCRIPTION, not an identifier, so no quoted form makes a hostile name safe to pass —
- * a refused one is left OUT of the command rather than escaped into it, and read off `cause`.
- */
-export const dbDrift = (tableName: string, columnName: string): EntityError =>
-  new EntityError({
-    code: 'X_DB_DRIFT',
-    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
-    fix:
-      shellInertIdentifier(columnName) === null
-        ? 'x db gen "add the column named in this error"   # its name carries a backtick, a ' +
-          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
-          'this command'
-        : `x db gen "add ${columnName}"`,
-  });
-
 export const notFound = (entityName: string, id: string): EntityError =>
   new EntityError({
     code: 'X_NOT_FOUND',