@ultimat3/entity 22.15.0 → 23.0.0

package/src/memory-repo.ts

@@ -15,12 +15,14 @@ import { narrowRow } from './columns';
 import { countsFrom, groupColumnOf } from './count-by';
 import { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
-import { notFound } from './errors';
+import { invariantViolated, notFound } from './errors';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
 import { compareByKind, matchesPredicate } from './memory-match';
 import { uniqueClash, uniqueViolation } from './memory-unique';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions, Transactor, Tx } from './repo';
+import { sealedFields } from './sealed';
+import { sealedRepo } from './sealed-repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
 import type { RowWrite } from './types';
@@ -95,6 +97,15 @@ export const memoryRepo = <Row>(
   /** The same key, from the id a caller named rather than from a row it has in hand. */
   const idStoreKey = (id: unknown, operation: string): string =>
     keyOf(kindOf(entity, singleKeyOf(entity, operation)) ?? '', id);
+  // Seed rows are stored as given, and sealing is asynchronous: a seeded sealed entity would hold
+  // plaintext every read then refuses to open. Refused here, with the call that seals.
+  if (seed.length > 0 && sealedFields(entity).length > 0) {
+    throw invariantViolated(
+      entity.$name,
+      'seed',
+      'declares a sealed column, and memoryRepo(entity, seed) stores seed rows unsealed — pass no seed and write them with insertAll(rows)',
+    );
+  }
   const rows = new Map<string, Row>(seed.map((row) => [storeKey(row), row]));
 
   const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
@@ -193,7 +204,7 @@ export const memoryRepo = <Row>(
 
   // Every method is async: a repository call that fails must reject, never throw
   // synchronously, or half the call sites would need two error paths.
-  return {
+  const repo: MemoryRepo<Row> = {
     async findById(id, options) {
       const { found } = select(
         { ...options, where: [{ column: singleKeyOf(entity, 'findById'), op: 'eq', value: id }] },
@@ -414,6 +425,9 @@ export const memoryRepo = <Row>(
       for (const row of seed) rows.set(storeKey(row), row);
     },
   };
+  // The memory driver seals too: it stores what Postgres would, so a test that passes here is not
+  // passing over plaintext production never holds.
+  return sealedRepo<Row, MemoryRepo<Row>>(entity, repo);
 };
 
 let txCounter = 0;

package/src/pg-driver.ts

@@ -53,6 +53,7 @@ import {
 } from './pg-write-sql';
 import { deletePlan, idPlan, readPlan, updatePlan } from './plan';
 import type { FindManyArgs, Repo, UpsertArgs } from './repo';
+import { sealedRepo } from './sealed-repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
 import type { RowWrite } from './types';
@@ -205,7 +206,7 @@ export const postgresRepo = <Row>(
     return written;
   };
 
-  return {
+  const repo: Repo<Row> = {
     async findById(id, options) {
       const op = 'findById';
       const plan = idPlan(entity, id, options, op);
@@ -471,6 +472,8 @@ export const postgresRepo = <Row>(
       return Number.isFinite(estimate) && estimate >= 0 ? estimate : null;
     },
   };
+  // The one sealing seam, shared with `memoryRepo()`: sealed on the way in, opened on the way out.
+  return sealedRepo(entity, repo);
 };
 
 /**

package/src/pg-row.ts

@@ -185,7 +185,10 @@ export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Ro
         ? moneyOf(source, head, currency, scale)
         : source[head];
     if (value !== null && value !== undefined) {
-      row[property] = column.$parse(value);
+      // A sealed column's stored value is not the author's to parse: it goes up as it is, and the
+      // sealing seam opens it — so a row somebody left in the clear is `X_SEAL_INVALID` there
+      // rather than whatever the plaintext parser thinks of its length here.
+      row[property] = column.$meta.sealed === undefined ? column.$parse(value) : value;
       continue;
     }
     if (column.$meta.notNull) {

package/src/preload.ts

@@ -13,6 +13,7 @@ import type { EntityCore } from './entity';
 import { EntityError } from './errors';
 import type { Relation } from './relations';
 import type { Repo } from './repo';
+import { copyRow } from './sealed';
 import type { Predicate } from './tenancy';
 
 /** The other side of a relation: the entity, and where its rows live. */
@@ -170,7 +171,8 @@ export const preloaded = async <Source, Row>(
   );
   // A copy per row: the in-memory driver hands back the row it stores, and attaching to that one
   // would write a relation into the table itself.
-  const attached = rows.map((row) => ({ ...row }) as Record<string, unknown>);
+  // `copyRow`, never a spread: a spread drops every server-only (sealed) property of the row.
+  const attached = rows.map((row) => copyRow(row as object) as Record<string, unknown>);
   for (const { relation, kind, keys, index } of resolved) {
     for (const [position, row] of attached.entries()) {
       const key = keys[position];

package/src/query.ts

@@ -15,10 +15,21 @@ import { preloaded } from './preload';
 import type { Relation } from './relations';
 import { relationNamed } from './relations';
 import type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
+import { copyRow, pickRow } from './sealed';
 import { SEARCH_PROPERTY } from './search';
 import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
 import { transitionRow } from './transition';
-import type { ColumnMap, IdOf, Insertable, MoneyValue, RowPatch } from './types';
+import type {
+  ColumnMap,
+  Filterable,
+  IdOf,
+  Insertable,
+  MoneyValue,
+  NoSealedKeys,
+  RowPatch,
+  SealedKeySet,
+  SealedKeysOf,
+} from './types';
 
 /**
  * What a preloaded relation adds to a row. `unknown` because the name is a string resolved at
@@ -27,10 +38,24 @@ import type { ColumnMap, IdOf, Insertable, MoneyValue, RowPatch } from './types'
  */
 export type Preloaded<Name extends string> = { readonly [K in Name]: unknown };
 
-export interface ReadBuilder<Row> {
+/**
+ * `S` names the entity's sealed columns, so naming one in a filter or an order is a COMPILE error
+ * and not only `X_ENTITY_SEALED_PREDICATE` at runtime. It defaults to none.
+ */
+export interface ReadBuilder<Row, S extends SealedKeySet = NoSealedKeys> {
   /** Equality on the columns given. `where({ orgId })` is what satisfies the tenancy guard. */
-  where(filter: RowPatch<Row>): ReadBuilder<Row>;
-  andWhere(column: keyof Row & string, op: Operator, value: unknown): ReadBuilder<Row>;
+  where(filter: RowPatch<Filterable<Row, S>>): ReadBuilder<Row, S>;
+  // NULL is never sealed, so its tests take ANY column. First: `Parameters<…>` reads the last.
+  andWhere(
+    column: keyof Row & string,
+    op: 'is-null' | 'is-not-null',
+    value?: unknown,
+  ): ReadBuilder<Row, S>;
+  andWhere(
+    column: Exclude<keyof Row & string, S['opaque']>,
+    op: Operator,
+    value: unknown,
+  ): ReadBuilder<Row, S>;
   /**
    * Full-text search over the entity's generated `tsvector` — every `.searchable()` column at
    * once, one GIN index, one predicate. `posts.where({ orgId }).search(input.q).limit(20).page()`.
@@ -47,14 +72,17 @@ export interface ReadBuilder<Row> {
    * stays the one the caller declared. An entity with no searchable column is `X_SEARCH_UNDECLARED`
    * and the in-memory driver is `X_SEARCH_IN_MEMORY` — never a different answer from the two.
    */
-  search(term: string): ReadBuilder<Row>;
-  orderBy(column: keyof Row & string, direction?: SortDirection): ReadBuilder<Row>;
-  limit(rows: number): ReadBuilder<Row>;
+  search(term: string): ReadBuilder<Row, S>;
+  orderBy(
+    column: Exclude<keyof Row & string, S['sealed']>,
+    direction?: SortDirection,
+  ): ReadBuilder<Row, S>;
+  limit(rows: number): ReadBuilder<Row, S>;
   /** The cursor from the previous page. */
-  after(cursor: string | null): ReadBuilder<Row>;
+  after(cursor: string | null): ReadBuilder<Row, S>;
   select<K extends keyof Row & string>(
     fields: { readonly [P in K]: true },
-  ): ReadBuilder<Pick<Row, K>>;
+  ): ReadBuilder<Pick<Row, K>, S>;
   /**
    * One relation, read for the whole page in one extra `where <key> in (…)` and attached to every
    * row under its own name — the eager form of the batching a point lookup does for itself, and
@@ -66,7 +94,7 @@ export interface ReadBuilder<Row> {
    * author" never reads like "nobody preloaded the author". Attached after the projection: a
    * `select()` narrows the columns, never the relations.
    */
-  preload<Name extends string>(relation: Name): ReadBuilder<Row & Preloaded<Name>>;
+  preload<Name extends string>(relation: Name): ReadBuilder<Row & Preloaded<Name>, S>;
   /**
    * Every row the chain matches, `size` at a time and one statement per batch — the terminal a
    * `for await` consumes instead of holding a whole table in memory. A batch is the page `page()`
@@ -106,7 +134,9 @@ export interface ReadBuilder<Row> {
    * Refused rather than answered: a column whose values a map cannot be keyed by (a timestamp, a
    * jsonb, money), and a chain matching more distinct values than one statement should answer with.
    */
-  countBy<K extends keyof Row & string>(column: K): Promise<ReadonlyMap<Row[K], number>>;
+  countBy<K extends Exclude<keyof Row & string, S['sealed']>>(
+    column: K,
+  ): Promise<ReadonlyMap<Row[K], number>>;
   /**
    * The four SQL aggregates, over exactly the rows `count()` counts — the chain's filters, its
    * tenancy and its soft-delete visibility, never its page. "Total spend this month" is
@@ -147,7 +177,8 @@ export interface ReadBuilder<Row> {
   plan(): QueryPlan;
 }
 
-export interface Table<Row, C extends ColumnMap = ColumnMap> extends ReadBuilder<Row> {
+export interface Table<Row, C extends ColumnMap = ColumnMap>
+  extends ReadBuilder<Row, SealedKeysOf<C>> {
   /**
    * Move one row through the state machine `column` declares, in ONE statement.
    *
@@ -285,7 +316,8 @@ const builder = <Source, Row>(
         ],
       }),
 
-    andWhere: (column, op, value) => next({ where: [...state.where, { column, op, value }] }),
+    andWhere: (column: string, op: Operator, value?: unknown) =>
+      next({ where: [...state.where, { column, op, value }] }),
 
     // Refused HERE as well as at the statement, because this is the line the author wrote: a chain
     // over an entity that declares nothing searchable can never produce a match, and the repair is
@@ -318,12 +350,8 @@ const builder = <Source, Row>(
         entity,
         repo,
         { ...state, select: keys },
-        (row) => {
-          const source = pick(row);
-          const picked = {} as Pick<Row, K>;
-          for (const key of keys) picked[key] = source[key];
-          return picked;
-        },
+        // By DESCRIPTOR, never by assignment: a sealed column named here stays server-only.
+        (row) => pickRow(pick(row) as Row & object, keys),
         related,
       );
     },
@@ -425,7 +453,8 @@ const touch = <Row, Patch>(entity: EntityCore<Row>, patch: Patch): Patch => {
   for (const [property, column] of Object.entries(entity.$columns)) {
     if (column.$meta.onUpdate !== undefined) stamped[property] = entityNow();
   }
-  return Object.assign({}, patch, stamped);
+  // `copyRow`, never `Object.assign({}, patch)`: a row passed back whole keeps its sealed properties.
+  return Object.assign(copyRow(patch as object), stamped) as Patch;
 };
 
 // Every write is `async`, matching the repository contract: a failing call rejects and never
@@ -437,7 +466,11 @@ export const tableFor = <Row, C extends ColumnMap>(
   /** How this table reaches another — `database()` passes it; a table built by hand has none. */
   related?: RelatedTables,
 ): Table<Row, C> => ({
-  ...builder<Row, Row>(entity, repo, EMPTY, (row) => row, related),
+  // One cast: `sealed-repo.ts` refuses at runtime, `SealedKeysOf<C>` is the same rule as a type.
+  ...(builder<Row, Row>(entity, repo, EMPTY, (row) => row, related) as ReadBuilder<
+    Row,
+    SealedKeysOf<C>
+  >),
   insert: async (values, options) => repo.insert(entity.$parse(values), options),
   insertAll: async (rows, options) =>
     repo.insertAll(

package/src/record-projection.ts

@@ -31,6 +31,12 @@ export interface RecordProjection {
    * default `false`. Realtime's persister reads it here, never off the declaration.
    */
   readonly persist: boolean;
+  /**
+   * The row's SEALED properties — the ones `schema` omits. `rowsOf` drops them from every row it
+   * collects, so a record never carries one whatever object the handler returned. Empty for almost
+   * every entity.
+   */
+  readonly sealed: readonly string[];
 }
 
 /** What `entity()` hands the projection: everything but the row node, which the schema builds. */
@@ -39,14 +45,23 @@ export interface ProjectionIdentity {
   readonly table: string;
   readonly primaryKey: readonly string[];
   readonly persist: boolean;
+  /** Absent means none: a projection built before sealing existed reads the same. */
+  readonly sealed?: readonly string[];
 }
 
 /** Built once per `entity()`, frozen: the brand, `recordProjection` and `rowsOf` share one object. */
 export const createProjection = (
-  { name, table, primaryKey, persist }: ProjectionIdentity,
+  { name, table, primaryKey, persist, sealed }: ProjectionIdentity,
   schema: SchemaNode,
 ): RecordProjection =>
-  Object.freeze({ type: name, table, key: recordKeyOf(name, primaryKey), schema, persist });
+  Object.freeze({
+    type: name,
+    table,
+    key: recordKeyOf(name, primaryKey),
+    schema,
+    persist,
+    sealed: Object.freeze([...(sealed ?? [])]),
+  });
 
 /**
  * The projection a schema node is branded with, or `undefined`. Own and non-enumerable: an

package/src/row-observer.ts

@@ -18,6 +18,7 @@ import { currentTx, expectedQueryLoop } from '@ultimat3/db';
 import type { EntityCore } from './entity';
 import { MAX_PAGE_SIZE } from './plan';
 import type { Repo, RepoOptions, UpsertArgs } from './repo';
+import { sealedFields } from './sealed';
 import type { IdOf, RowPatch } from './types';
 
 export type RowChangeOp = 'insert' | 'update' | 'delete';
@@ -183,6 +184,20 @@ const beforeAllOf = async <Row>(
  */
 export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Repo<Row> {
   const name = entity.$name;
+  const sealed = sealedFields(entity).map((field) => field.property);
+
+  /**
+   * A reported row WITHOUT its sealed properties. This wrapper sits above the sealing seam, so the
+   * rows it holds carry plaintext — and a change is what a live query delivers to a subscriber. A
+   * sealed column leaves the server through no path, so it is not on a change either.
+   */
+  const reported = (row: unknown): Readonly<Record<string, unknown>> | null => {
+    const record = asRecord(row);
+    if (record === null || sealed.length === 0) return record;
+    return Object.fromEntries(
+      Object.entries(record).filter(([property]) => !sealed.includes(property)),
+    );
+  };
 
   /**
    * Reported at COMMIT. The write may sit in a transaction — the caller's `options.tx`, or the
@@ -209,8 +224,8 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
     const change: RowChange = {
       entity: name,
       op,
-      before: asRecord(before),
-      after: asRecord(after),
+      before: reported(before),
+      after: reported(after),
       ...(write === undefined ? {} : { write }),
     };
     afterCommit(options, () => observer.onChange(change));

package/src/rows-of.ts

@@ -74,12 +74,24 @@ const fits = (projection: RecordProjection, value: Readonly<Record<string, unkno
 
 type Found = Map<string, Map<string, Row>>;
 
+/**
+ * The row as a RECORD: without its sealed properties. The handler's own object is what reaches
+ * here — it holds the plaintext — and a record goes to a browser store, so the copy is made at the
+ * one place every record is collected. An entity with none keeps the same object, as before.
+ */
+const withoutSealed = (projection: RecordProjection, row: Row): Row => {
+  if (projection.sealed.length === 0) return row;
+  return Object.fromEntries(
+    Object.entries(row).filter(([property]) => !projection.sealed.includes(property)),
+  );
+};
+
 const collect = (found: Found, projection: RecordProjection, row: Row): void => {
   const byKey = found.get(projection.type) ?? new Map<string, Row>();
   found.set(projection.type, byKey);
   const key = projection.key(row);
   // First sighting wins: one record shown twice in a response is one record, not two writes.
-  if (!byKey.has(key)) byKey.set(key, row);
+  if (!byKey.has(key)) byKey.set(key, withoutSealed(projection, row));
 };
 
 const walk = (node: SchemaNode, value: unknown, found: Found, inUnion: boolean): void => {

package/src/sealed-column.ts

@@ -0,0 +1,119 @@
+// Single responsibility: `text()`'s two builders — the text column, which keeps `.sealed()` across
+// the links that may precede it, and the sealed column that link returns. What a sealed column may
+// NOT be is refused here, where the chain was written; what an ENTITY may not do with one is
+// `sealed-declaration.ts`.
+
+import { isSealed } from '@ultimat3/core';
+import { makeColumn } from './column';
+import { refuseSealed, sealedUniqueOpaque } from './sealed-errors';
+import type { Column, ColumnMeta, SealedColumn, SealedOptions, TextColumn } from './types';
+
+type Text = string | null;
+
+/**
+ * A sealed column's parser. Inside a driver the value is already the sealed string — longer than
+ * any `max`, and not the author's to validate — so it passes; everywhere else it is the plaintext
+ * and the column's own parser judges it, `max` included.
+ */
+const sealedParse =
+  <T extends Text>(parse: (value: unknown) => T) =>
+  (value: unknown): T =>
+    isSealed(value) ? (value as T) : parse(value);
+
+export const makeSealedColumn = <T extends Text, Optional extends boolean, Lookup extends boolean>(
+  meta: ColumnMeta,
+  parse: (value: unknown) => T,
+  optional: Optional,
+): SealedColumn<T, Optional, Lookup> => {
+  const base = makeColumn<T, Optional>(meta, parse, optional);
+  const lookup = meta.sealed?.lookup === true;
+  const again = <U extends Text>(next: Column<U, Optional>): SealedColumn<U, Optional, Lookup> =>
+    makeSealedColumn<U, Optional, Lookup>(next.$meta, next.$parse, optional);
+  return {
+    ...base,
+    // The runtime twin of the phantom: one cast, where a boolean becomes the literal it implies.
+    $sealed: (lookup ? 'lookup' : 'opaque') as SealedColumn<T, Optional, Lookup>['$sealed'],
+    nullable: () => again(base.nullable()),
+    column: (name) => again(base.column(name)),
+    unique: () => {
+      // Uniqueness is the database comparing ciphertexts, so it needs equal values to seal equal.
+      if (!lookup) throw sealedUniqueOpaque();
+      return again(base.unique());
+    },
+    default: () =>
+      refuseSealed(
+        'given a default',
+        'a default is a literal in the DDL, so the database would store it as plaintext',
+        'text().sealed() with no .default(…) — supply the value in the insert, where it is sealed',
+      ),
+    primaryKey: () =>
+      refuseSealed(
+        'a primary key',
+        'a key is compared, ordered and referenced by the database, which holds ciphertext',
+        'uuid().primaryKey() for the key, and text().sealed() for the secret beside it',
+      ),
+    tenant: () =>
+      refuseSealed(
+        'the tenant column',
+        'every query filters on the tenant, and a sealed value cannot be filtered on',
+        'uuid().tenant() for the tenant, and text().sealed() for the secret beside it',
+      ),
+    references: () =>
+      refuseSealed(
+        'a foreign key',
+        'the database joins on the stored value, which is ciphertext',
+        'uuid().references(() => other.id) for the key, and text().sealed() for the secret',
+      ),
+    searchable: () =>
+      refuseSealed(
+        'searchable',
+        'the search vector is generated by the database from the stored value, which is ciphertext',
+        'text().searchable() on a column that is not sealed — a secret is not search text',
+      ),
+  };
+};
+
+/** What `.sealed(options)` turns the declared meta into. */
+const sealedMeta = (meta: ColumnMeta, options: SealedOptions): ColumnMeta => {
+  if (meta.default !== undefined) {
+    refuseSealed(
+      'given a default',
+      'a default is a literal in the DDL, so the database would store it as plaintext',
+      'text().sealed() with no .default(…) — supply the value in the insert, where it is sealed',
+    );
+  }
+  const lookup = options.lookup === true;
+  if (meta.unique && !lookup) throw sealedUniqueOpaque();
+  // `check` and `length` go: they are `char_length(col) <= max`, and the column now holds a sealed
+  // string longer than any plaintext bound. The bound still holds where it can — in `$parse`,
+  // against the plaintext, before it is sealed. Any OTHER check has no such home, so it is refused
+  // rather than dropped: the rule would vanish from the DDL with nothing to say it went.
+  if (meta.check !== undefined && meta.length === undefined) {
+    refuseSealed(
+      'given a CHECK',
+      'a CHECK runs in the database against the stored value, which is ciphertext',
+      'text().sealed() with no CHECK — validate the plaintext in the action input schema',
+    );
+  }
+  const { check: _check, length: _length, ...rest } = meta;
+  return { ...rest, sealed: { lookup } };
+};
+
+export const makeTextColumn = <T extends Text, Optional extends boolean>(
+  meta: ColumnMeta,
+  parse: (value: unknown) => T,
+  optional: Optional,
+): TextColumn<T, Optional> => {
+  const base = makeColumn<T, Optional>(meta, parse, optional);
+  const again = <U extends Text, O extends boolean>(next: Column<U, O>): TextColumn<U, O> =>
+    makeTextColumn<U, O>(next.$meta, next.$parse, next.$optional);
+  return {
+    ...base,
+    nullable: () => again(base.nullable()),
+    unique: () => again(base.unique()),
+    default: (value) => again(base.default(value)),
+    column: (name) => again(base.column(name)),
+    sealed: (options = {}) =>
+      makeSealedColumn(sealedMeta(meta, options), sealedParse(parse), optional),
+  };
+};

package/src/sealed-declaration.ts

@@ -0,0 +1,64 @@
+// Single responsibility: what an ENTITY may not do with a sealed column, refused while it is being
+// declared. The column chain refuses what it can see (`sealed-column.ts`); these are the rules that
+// need the whole entity — a composite key, the tenant, an index, an invariant — and each one is the
+// database comparing a value it only holds as ciphertext.
+
+import { invariantViolated } from './entity-error';
+import type { SealedField } from './sealed';
+import { sealedPredicate } from './sealed-errors';
+import type { IndexDef } from './types';
+
+export interface SealedDeclaration {
+  readonly name: string;
+  readonly fields: readonly SealedField[];
+  /** Property keys. */
+  readonly primaryKey: readonly string[];
+  readonly tenantColumn: string | null;
+  /** Physical columns, as `IndexDef` and `Invariant` carry them. */
+  readonly indexes: readonly IndexDef[];
+  readonly invariants: readonly { readonly kind: string; readonly columns: readonly string[] }[];
+}
+
+export const assertSealedDeclaration = (input: SealedDeclaration): void => {
+  const { name, fields } = input;
+  if (fields.length === 0) return;
+  for (const field of fields) {
+    if (input.primaryKey.includes(field.property)) {
+      throw invariantViolated(
+        name,
+        field.property,
+        'is sealed and in the primary key — a key is compared and ordered by the database, which holds ciphertext; key the entity by a uuid() and keep the secret beside it',
+      );
+    }
+    if (input.tenantColumn === field.property) {
+      throw invariantViolated(
+        name,
+        field.property,
+        'is sealed and the tenant column — every query filters on the tenant, and a sealed value cannot be filtered on',
+      );
+    }
+  }
+  const byColumn = new Map(fields.map((field) => [field.column, field]));
+  for (const index of input.indexes) {
+    for (const column of index.columns) {
+      const field = byColumn.get(column);
+      // An index over a lookup column is the point of one: it is what makes the equality fast,
+      // and a unique one is `.unique()` spelled on the entity.
+      if (field === undefined || (field.lookup && index.order === undefined)) continue;
+      throw sealedPredicate(name, field.property, 'an index', field.lookup);
+    }
+  }
+  for (const invariant of input.invariants) {
+    for (const column of invariant.columns) {
+      const field = byColumn.get(column);
+      if (field === undefined) continue;
+      if (invariant.kind === 'unique') {
+        if (!field.lookup) throw sealedPredicate(name, field.property, 'a uniqueness rule', false);
+        continue;
+      }
+      // A CHECK runs in the database against the stored string, and the app-side half runs inside
+      // the driver against the same one — neither ever sees the plaintext the rule was written for.
+      throw sealedPredicate(name, field.property, 'an invariant', field.lookup);
+    }
+  }
+};

package/src/sealed-errors.ts

@@ -0,0 +1,112 @@
+// The two refusals a sealed column raises: named where the database would have to read it, and
+// named in a view. Split from `errors.ts` for `feature-errors.ts`'s reason — the codes and titles
+// stay in `entity-error.ts`. Imports `entity-error.ts`, never `errors.ts`: `entity()` raises these
+// while it is being declared, and that path is one a browser bundle evaluates.
+
+import { EntityError } from './entity-error';
+
+/**
+ * What the caller was doing with the column, as the cause words it. A closed list so every site
+ * says the same thing about the same use, and so the fix can tell an order from an equality.
+ */
+export type SealedUse =
+  | 'a filter'
+  | 'an order'
+  | 'a grouped count'
+  | 'an aggregate'
+  | "a filtered write's filter"
+  | 'an upsert conflict target'
+  | 'an index'
+  | 'a uniqueness rule'
+  | 'an invariant';
+
+/**
+ * A sealed column where the DATABASE would have to compare it. It holds ciphertext: an opaque
+ * column seals with a fresh IV, so two equal values never match and nothing can be found by it;
+ * a `lookup` column seals deterministically, so equality — and only equality — means something.
+ *
+ * Two fixes, because they are two different mistakes: asking an opaque column anything is repaired
+ * by declaring `lookup` (and the fix says what that costs), while asking a lookup column for an
+ * order or a range has no declaration that repairs it.
+ */
+export const sealedPredicate = (
+  entityName: string,
+  column: string,
+  use: SealedUse,
+  lookup: boolean,
+): EntityError =>
+  // The opaque refusal FIRST: it is the one an author meets first, and the first literal in a
+  // factory is what `x errors explain` prints.
+  !lookup
+    ? new EntityError({
+        code: 'X_ENTITY_SEALED_PREDICATE',
+        cause: `${entityName}.${column} is sealed and was named in ${use} — the database holds ciphertext sealed with a fresh IV, so no two values match and nothing there can find, order or group by it`,
+        fix: `find the row by another column, or declare ${entityName}.${column} as text().sealed({ lookup: true }) to allow equality in where() and .unique() — equal plaintexts then store as visibly equal ciphertexts, so never for a low-entropy value, and rows already stored must be written again before they match`,
+      })
+    : new EntityError({
+        code: 'X_ENTITY_SEALED_PREDICATE',
+        cause: `${entityName}.${column} is sealed for lookup and was named in ${use} that is not an equality — the database holds ciphertext, and a deterministic seal preserves equality and nothing else: no order, no range, no like`,
+        fix: `match it by equality — where({ ${column}: value }) or andWhere('${column}', 'in', values) — and order or range by a column that is not sealed`,
+      });
+
+/**
+ * An equality on a lookup column whose operand is not a string. The column stores ciphertext or
+ * NULL, so a number or an object would match no row — the same answer as "nobody has it". The
+ * value itself is never echoed: it is the secret's plaintext, or close to it.
+ */
+export const sealedLookupValue = (
+  entityName: string,
+  column: string,
+  shape: 'value' | 'list',
+): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_SEALED_PREDICATE',
+    cause: `${entityName}.${column} is sealed for lookup and was matched against a ${shape === 'list' ? 'list holding a value' : 'value'} that is not a string — the column holds sealed strings or NULL, so the filter could only ever match nothing`,
+    fix: `pass the plaintext as a string — where({ ${column}: String(value) }) — or null to ask for the rows where ${entityName}.${column} is NULL`,
+  });
+
+/**
+ * A row to insert that lacks a required sealed column. The driver would refuse it anyway ("is
+ * required and has no default"), but in words that send the reader to the entity — and the usual
+ * cause is one line above the call: a repository row does not ENUMERATE a sealed property, so
+ * `{ ...row }` leaves it behind. The rewrite names it, which is the one way to copy a secret.
+ */
+export const sealedMissing = (entityName: string, column: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.${column}: is required, sealed, and missing from the row to insert — a row read from the repository does not enumerate a sealed column, so a spread ({ ...row }) or an Object.assign copy leaves it behind`,
+    fix: `{ ...row, ${column}: row.${column} }   # in the ${entityName} insert()/insertAll()/upsertAll() call: a sealed column is copied by name, never by spread`,
+  });
+
+/** A sealed column listed in `$view([...])`. A view is what leaves the server. */
+export const sealedInView = (entityName: string, column: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_SEALED_IN_VIEW',
+    cause: `${entityName}.$view([...]) names ${column}, which is sealed — a view is an action's output, an OpenAPI schema and an MCP tool result, and a sealed column leaves the server through none of them`,
+    fix: `remove '${column}' from the $view([...]) list — server code reads it off the row; a caller that must be shown it gets its own field on a t.object output, set by the handler`,
+  });
+
+/**
+ * `.unique()` on a column sealed without `lookup`, refused on the chain — before any entity holds
+ * the column, so there is no entity to name and the fix is the rewritten chain.
+ */
+export const sealedUniqueOpaque = (): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_SEALED_PREDICATE',
+    cause:
+      'column.sealed: a sealed column cannot be unique without lookup — uniqueness is the database comparing ciphertexts, and an opaque seal draws a fresh IV, so two equal values never collide',
+    fix: 'text().sealed({ lookup: true }).unique() — equal plaintexts then store as visibly equal ciphertexts, so never for a low-entropy value',
+  });
+
+/**
+ * A link a sealed column cannot take — a default, a key, the tenant, a foreign key, a search
+ * source. Raised on the chain, before any entity exists, so the caller supplies the EDIT, exactly
+ * as `refuse.ts` has it; it constructs the error itself so `fix-scan.ts` reads each call's fix.
+ */
+export const refuseSealed = (link: string, why: string, fix: string): never => {
+  throw new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `column.sealed: a sealed column cannot be ${link} — ${why}`,
+    fix,
+  });
+};