@ultimat3/entity 22.15.0 → 23.0.0

package/src/sealed-repo.ts

@@ -0,0 +1,235 @@
+// Single responsibility: the ONE seam a sealed column crosses. A repository wrapped here seals the
+// sealed properties of every row and patch on the way in, opens them on the way out, and rewrites
+// or refuses every predicate that names one — so both drivers store ciphertext and neither knows
+// it. Both driver factories return through this, which is why the typed handle and a hand-held
+// `postgresRepo()` cannot disagree. An entity with no sealed column gets its repository back as is.
+
+import type { AggregateFn } from './aggregate';
+import { namedColumns } from './plan';
+import type { FindManyArgs, Repo, UpsertArgs } from './repo';
+import type { SealedField, SealedSource, SealKeys } from './sealed';
+import {
+  lookupCandidates,
+  openValue,
+  sealedFields,
+  sealKeysOnce,
+  sealValue,
+  serverOnly,
+} from './sealed';
+import type { SealedUse } from './sealed-errors';
+import { sealedLookupValue, sealedMissing, sealedPredicate } from './sealed-errors';
+import type { Predicate } from './tenancy';
+
+type Loose = Readonly<Record<string, unknown>>;
+
+const isRecord = (value: unknown): value is Loose => typeof value === 'object' && value !== null;
+
+/**
+ * A row or a patch with its sealed properties sealed. Only a STRING is sealed: `null` clears the
+ * column, `undefined` leaves it alone, and anything else is not a value this column holds — it is
+ * passed on untouched so the driver's own `$parse` refuses it in the words it always uses.
+ *
+ * Each sealed property is read BY NAME and carried explicitly, because the copy below is a spread
+ * and a repository row does not enumerate one: `insert(row)` and `update(id, row)` with a row
+ * passed back whole write exactly what the row holds, a `null` included.
+ *
+ * `inserting` says the values are a whole ROW: a required sealed column it lacks is refused here,
+ * in words that name the spread that usually lost it. The typed handle refuses the same row with
+ * the same error one step earlier (`entity.$parse`); this is the hand-held repository's.
+ */
+const sealRow = async <T>(
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  values: T,
+  keys: SealKeys,
+  inserting = false,
+): Promise<T> => {
+  if (!isRecord(values)) return values;
+  const sealed: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = Object.hasOwn(values, field.property) ? values[field.property] : undefined;
+    if (typeof value === 'string') sealed[field.property] = await sealValue(field, value, keys);
+    else if (value !== undefined) sealed[field.property] = value;
+    else if (inserting && field.required) throw sealedMissing(entity.$name, field.property);
+  }
+  // A copy, never the caller's object: the row they hold keeps the plaintext they wrote.
+  return { ...values, ...sealed } as T;
+};
+
+/**
+ * A stored row with its sealed properties opened. A projection that left one out leaves it out.
+ * Opened means SERVER-ONLY (`serverOnly`): the plaintext is read by name and enumerated by nothing,
+ * so the row a repository answers can be serialised whole and the secret stays here.
+ */
+const openRow = async <T>(fields: readonly SealedField[], row: T, keys: SealKeys): Promise<T> => {
+  if (!isRecord(row)) return row;
+  const opened: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = Object.hasOwn(row, field.property) ? row[field.property] : undefined;
+    if (typeof value === 'string') opened[field.property] = await openValue(field, value, keys);
+  }
+  return serverOnly(fields, row, opened) as T;
+};
+
+const openRows = <T>(
+  fields: readonly SealedField[],
+  rows: readonly T[],
+  keys: SealKeys,
+): Promise<T[]> => Promise.all(rows.map((row) => openRow(fields, row, keys)));
+
+/**
+ * One predicate, as the database can answer it.
+ *
+ * A NULL test passes through for EVERY sealed column: `null` is never sealed — it is stored as
+ * NULL in a nullable `text` column — so whether a value is present is a fact the schema already
+ * publishes, and it is what lets a backfill visit only the rows still to be sealed. Past that an
+ * opaque column answers nothing, and a lookup column answers equality: `eq` and `in` are rewritten
+ * to the stored strings the value seals to — one per declared key, so a rotation in progress still
+ * finds the rows written before it.
+ */
+const rewrite = async (
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  predicate: Predicate,
+  keys: SealKeys,
+): Promise<Predicate> => {
+  const field = fields.find((one) => one.property === predicate.column);
+  if (field === undefined) return predicate;
+  const { op, value } = predicate;
+  if (op === 'is-null' || op === 'is-not-null') return predicate;
+  if (!field.lookup) throw sealedPredicate(entity.$name, field.property, 'a filter', false);
+  // A stored value is ciphertext or NULL, so anything but a string or a NULL would reach the driver
+  // and match nothing — indistinguishable from "no such row". Refused instead.
+  const sealable = (one: unknown): boolean =>
+    typeof one === 'string' || one === null || one === undefined;
+  if ((op === 'eq' || op === 'in') && !(Array.isArray(value) ? value : [value]).every(sealable)) {
+    throw sealedLookupValue(entity.$name, field.property, op === 'in' ? 'list' : 'value');
+  }
+  if (op === 'eq') {
+    if (typeof value !== 'string') return predicate;
+    const candidates = await lookupCandidates(field, value, keys);
+    const [only] = candidates;
+    return candidates.length === 1 && only !== undefined
+      ? { ...predicate, value: only }
+      : { ...predicate, op: 'in', value: candidates };
+  }
+  if (op === 'in' && Array.isArray(value)) {
+    const lists = await Promise.all(
+      value.map((one: unknown) =>
+        typeof one === 'string' ? lookupCandidates(field, one, keys) : [one],
+      ),
+    );
+    return { ...predicate, value: lists.flat() };
+  }
+  throw sealedPredicate(entity.$name, field.property, 'a filter', true);
+};
+
+/** A column named where no rewrite exists: an order, a group, an aggregate, a write's filter. */
+const refuseNamed = (
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  properties: readonly string[],
+  use: SealedUse,
+  lookupAllowed = false,
+): void => {
+  for (const property of properties) {
+    const field = fields.find((one) => one.property === property);
+    if (field === undefined || (lookupAllowed && field.lookup)) continue;
+    throw sealedPredicate(entity.$name, field.property, use, field.lookup);
+  }
+};
+
+const readArgs = async <A extends FindManyArgs>(
+  entity: SealedSource,
+  fields: readonly SealedField[],
+  args: A | undefined,
+  keys: SealKeys,
+): Promise<A | undefined> => {
+  if (args === undefined) return args;
+  refuseNamed(
+    entity,
+    fields,
+    (args.orderBy ?? []).map((key) => key.column),
+    'an order',
+  );
+  if (args.where === undefined) return args;
+  const where = await Promise.all(args.where.map((one) => rewrite(entity, fields, one, keys)));
+  return { ...args, where };
+};
+
+/**
+ * `repo`, sealing. Every method stays `async` and rejects rather than throws, as the contract
+ * requires. Written as a spread over the inner repository so a member this file does not know —
+ * `MemoryRepo.reset()` — survives it.
+ */
+export const sealedRepo = <Row, R extends Repo<Row>>(entity: SealedSource, repo: R): R => {
+  const fields = sealedFields(entity);
+  if (fields.length === 0) return repo;
+  const filterOf = (filter: unknown): readonly string[] =>
+    namedColumns(filter).map(([property]) => property);
+
+  // Every method takes its own ring: one resolution per repository call, however many values.
+  const sealing: Repo<Row> = {
+    async findById(id, options) {
+      const row = await repo.findById(id, options);
+      return row === null ? null : openRow(fields, row, sealKeysOnce());
+    },
+    async findMany(args) {
+      const keys = sealKeysOnce();
+      const page = await repo.findMany(await readArgs(entity, fields, args, keys));
+      return { rows: await openRows(fields, page.rows, keys), nextCursor: page.nextCursor };
+    },
+    async insert(values, options) {
+      const keys = sealKeysOnce();
+      const stored = await repo.insert(await sealRow(entity, fields, values, keys, true), options);
+      return openRow(fields, stored, keys);
+    },
+    async insertAll(rows, options) {
+      const keys = sealKeysOnce();
+      const sealed = await Promise.all(rows.map((row) => sealRow(entity, fields, row, keys, true)));
+      return openRows(fields, await repo.insertAll(sealed, options), keys);
+    },
+    async upsertAll(rows, args: UpsertArgs<Row>) {
+      // A conflict target is a uniqueness comparison, so it is a lookup column's or nobody's.
+      refuseNamed(entity, fields, args.onConflict, 'an upsert conflict target', true);
+      const keys = sealKeysOnce();
+      const sealed = await Promise.all(rows.map((row) => sealRow(entity, fields, row, keys, true)));
+      return openRows(fields, await repo.upsertAll(sealed, args), keys);
+    },
+    async update(id, patch, options) {
+      const keys = sealKeysOnce();
+      const stored = await repo.update(id, await sealRow(entity, fields, patch, keys), options);
+      return openRow(fields, stored, keys);
+    },
+    delete: (id, options) => repo.delete(id, options),
+    // A filtered write's filter is refused for every sealed column, lookup included: its shape is
+    // one value per column, and during a rotation a lookup value has one stored form PER KEY.
+    async deleteWhere(filter, options) {
+      refuseNamed(entity, fields, filterOf(filter), "a filtered write's filter");
+      return repo.deleteWhere(filter, options);
+    },
+    async updateWhere(filter, patch, options) {
+      refuseNamed(entity, fields, filterOf(filter), "a filtered write's filter");
+      return repo.updateWhere(
+        filter,
+        await sealRow(entity, fields, patch, sealKeysOnce()),
+        options,
+      );
+    },
+    async count(args) {
+      return repo.count(await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+    async countBy(column, args) {
+      refuseNamed(entity, fields, [column], 'a grouped count');
+      return repo.countBy(column, await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+    async aggregate(fn: AggregateFn, column, args) {
+      refuseNamed(entity, fields, [column], 'an aggregate');
+      return repo.aggregate(fn, column, await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+    async approximateCount(args) {
+      return repo.approximateCount(await readArgs(entity, fields, args, sealKeysOnce()));
+    },
+  };
+  return { ...repo, ...sealing };
+};

package/src/sealed.ts

@@ -0,0 +1,194 @@
+// Single responsibility: which columns of an entity are sealed, and the two conversions a value
+// crosses on — plaintext to the stored string on a write, the stored string back on a read. The
+// cipher is `@ultimat3/core`'s `seal()` / `open()`; this file only decides WHAT is sealed, under
+// which purpose. `sealed-repo.ts` is the one caller on the row path.
+
+import type { SealKeyRing } from '@ultimat3/core';
+import { openText, resolveSealKeys, seal, sealAll } from '@ultimat3/core';
+import { columnName } from './column';
+import type { AnyColumn, ColumnMap } from './types';
+
+/** The slice of an entity this reads, so the declaration path can ask before `entity()` returns. */
+export interface SealedSource {
+  readonly $name: string;
+  readonly $table: string;
+  readonly $columns: ColumnMap;
+}
+
+export interface SealedField {
+  /** Property key on the row. */
+  readonly property: string;
+  /** Physical column — half of the purpose, and what `x doctor` names. */
+  readonly column: string;
+  /**
+   * `entity:<table>.<column>`, derived and never stated: two columns cannot share one by accident,
+   * so a value copied from one sealed column into another does not open there. PHYSICAL names —
+   * the ones a migration renames — so renaming the table or the column is a re-seal.
+   */
+  readonly purpose: string;
+  readonly lookup: boolean;
+  /** NOT NULL — and a sealed column takes no default, so a row to insert must carry it. */
+  readonly required: boolean;
+  /**
+   * The column's own parser, which judges a PLAINTEXT — `text({ max })` included. Run before a
+   * value is sealed, because nothing after that point can: the driver only ever sees the sealed
+   * string, which is longer than any bound the author wrote.
+   */
+  readonly parse: (value: unknown) => unknown;
+}
+
+export const sealedPurpose = (table: string, column: string): string => `entity:${table}.${column}`;
+
+const describeField = (table: string, property: string, column: AnyColumn): SealedField[] => {
+  const sealed = column.$meta.sealed;
+  if (sealed === undefined) return [];
+  const physical = columnName(property, column.$meta);
+  return [
+    {
+      property,
+      column: physical,
+      purpose: sealedPurpose(table, physical),
+      lookup: sealed.lookup,
+      required: column.$meta.notNull,
+      parse: column.$parse,
+    },
+  ];
+};
+
+const fields = new WeakMap<ColumnMap, readonly SealedField[]>();
+
+/**
+ * Every sealed column of the entity, in declaration order — empty for almost every entity, and
+ * that is the fast path: a repository over one with none is returned untouched. Memoised on the
+ * column map, which is the declaration itself and outlives nothing it should not.
+ */
+export const sealedFields = (entity: SealedSource): readonly SealedField[] => {
+  const known = fields.get(entity.$columns);
+  if (known !== undefined) return known;
+  const found = Object.entries(entity.$columns).flatMap(([property, column]) =>
+    describeField(entity.$table, property, column),
+  );
+  fields.set(entity.$columns, found);
+  return found;
+};
+
+/**
+ * The key ring for ONE repository call, resolved the first time a value needs it and shared by
+ * every value after. A 500-row page with two sealed columns is a thousand values and one ring —
+ * not a thousand reads of the environment or the key file. Lazy, so a call that seals and opens
+ * nothing needs no key at all; per call and never longer, so a rotation is seen by the next one.
+ */
+export type SealKeys = () => Promise<SealKeyRing>;
+
+export const sealKeysOnce = (): SealKeys => {
+  let ring: Promise<SealKeyRing> | undefined;
+  return () => {
+    ring ??= resolveSealKeys();
+    return ring;
+  };
+};
+
+/**
+ * The stored form of one value: validated as the plaintext it is, then sealed. A lookup column
+ * seals deterministically so equality survives. `async`, so a refused value rejects like every
+ * other repository failure rather than throwing at the call.
+ */
+export const sealValue = async (
+  field: SealedField,
+  plaintext: string,
+  keys: SealKeys,
+): Promise<string> => {
+  const checked = field.parse(plaintext);
+  return seal(typeof checked === 'string' ? checked : plaintext, {
+    purpose: field.purpose,
+    deterministic: field.lookup,
+    keys: await keys(),
+  });
+};
+
+/**
+ * The plaintext of one stored value. A stored string that is not a sealed value is
+ * `X_SEAL_INVALID`, always: there is no reading of an unsealed row, so a column sealed after rows
+ * were written is migrated by expand, `backfill()`, contract — never by tolerating the old rows.
+ */
+export const openValue = async (
+  field: SealedField,
+  stored: string,
+  keys: SealKeys,
+): Promise<string> => openText(stored, { purpose: field.purpose, keys: await keys() });
+
+/**
+ * Every stored string a lookup may match `plaintext` against: one per declared key. Outside a
+ * rotation that is one string; while a retired key is still declared it is two, so the rows
+ * written before the rotation are still found.
+ */
+export const lookupCandidates = async (
+  field: SealedField,
+  plaintext: string,
+  keys: SealKeys,
+): Promise<readonly string[]> => sealAll(plaintext, { purpose: field.purpose, keys: await keys() });
+
+type Loose = Readonly<Record<string, unknown>>;
+
+/**
+ * A copy of `row` whose sealed properties are SERVER-ONLY: own, readable and writable —
+ * `row.password` is the plaintext and the row type does not change — but NOT ENUMERABLE. So
+ * `JSON.stringify`, an object spread, `Object.keys`/`entries`, `structuredClone` and every
+ * serialiser built on them leave the property behind, which is what keeps a row handed whole to a
+ * `query`, an island prop, a log line, a job payload or a cache tier from carrying the secret out.
+ * Fail closed: a path nobody listed omits it too, and an explicit `row.password` is the only read.
+ *
+ * `opened` wins over the stored value; a property the row does not have is not invented, and a
+ * NULL is hidden like a value — whether a secret is set is not for the wire either.
+ */
+export const serverOnly = <T extends Loose>(
+  fields: readonly SealedField[],
+  row: T,
+  opened: Loose = {},
+): T => {
+  const out: Record<string, unknown> = { ...row };
+  for (const { property } of fields) {
+    if (!Object.hasOwn(row, property)) continue;
+    Object.defineProperty(out, property, {
+      value: Object.hasOwn(opened, property) ? opened[property] : row[property],
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out as T;
+};
+
+/**
+ * A copy of a row that KEEPS what `serverOnly` set — `{ ...row }` would drop every sealed property,
+ * which is the point of it everywhere a row leaves and wrong where server code only wants its own
+ * object. Enumerable properties stay enumerable, so this is a spread for every other entity.
+ */
+export const copyRow = <T extends object>(row: T): T =>
+  Object.defineProperties({}, Object.getOwnPropertyDescriptors(row)) as T;
+
+/**
+ * `keys` of a row, each as the row holds it: a projection that NAMES a sealed column still answers
+ * it server-only. Assigning the value instead would re-create it enumerable, and a row that names
+ * the secret would be the one repository row that serialises it. A key the row lacks is present
+ * and `undefined`, as an assignment would leave it.
+ */
+export const pickRow = <T extends object, K extends keyof T & string>(
+  row: T,
+  keys: readonly K[],
+): Pick<T, K> => {
+  const picked = {};
+  for (const key of keys) {
+    Object.defineProperty(
+      picked,
+      key,
+      Object.getOwnPropertyDescriptor(row, key) ?? {
+        value: undefined,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      },
+    );
+  }
+  return picked as Pick<T, K>;
+};

package/src/type-pins.ts

@@ -5,15 +5,25 @@
 // enforcement this repo counts (axiom 3).
 
 import type { Id } from '@ultimat3/core';
-import type { MoneyValue as SchemaMoneyValue } from '@ultimat3/schema';
+import type { Schema, MoneyValue as SchemaMoneyValue } from '@ultimat3/schema';
 import type { uuid } from './columns';
 import type { EntitySet } from './database';
 import type { Entity, EntityCore, EntityInit } from './entity';
 import type { ColumnExpr, InvariantColumns } from './expr';
 import type { Invariant, InvariantDef } from './invariants';
-import type { Table } from './query';
+import type { ReadBuilder, Table } from './query';
 import type { Repo } from './repo';
-import type { AnyColumn, IdOf, Insertable, MoneyInput, MoneyValue, RowOf } from './types';
+import type {
+  AnyColumn,
+  IdOf,
+  Insertable,
+  MoneyInput,
+  MoneyValue,
+  RowOf,
+  SealedColumn,
+  TextColumn,
+  WireRow,
+} from './types';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -345,3 +355,99 @@ type _RepoBatchWritesTakeABigIntMinor = Assert<
 type _RepoAnswersTheValueType = Assert<
   [Awaited<ReturnType<Repo<PinMoneyRow>['insert']>>] extends [PinMoneyRow] ? true : false
 >;
+
+// --- Sealed columns (plan 101, slice 03) ---------------------------------------------------------
+// The row keeps `string`; the wire schema loses the column; a predicate naming it does not compile.
+
+declare const sealedPin: Entity<RowOf<SealedPinColumns>, SealedPinColumns>;
+type SealedPinColumns = {
+  readonly id: ReturnType<typeof uuid>;
+  readonly label: TextColumn;
+  readonly password: SealedColumn<string, false, false>;
+  readonly email: SealedColumn<string, false, true>;
+};
+type SealedPinRow = RowOf<SealedPinColumns>;
+declare const sealedTable: Table<SealedPinRow, SealedPinColumns>;
+
+/** The server row is the whole row, plaintext included. */
+export type _SealedRowKeepsTheColumn = Assert<
+  SealedPinRow['password'] extends string ? true : false
+>;
+
+/** `$schema` parses to the row WITHOUT its sealed columns — what an `output` sends. */
+type SealedWire = WireRow<SealedPinRow, SealedPinColumns>;
+export type _SealedWireDropsBoth = Assert<
+  'password' extends keyof SealedWire ? false : 'email' extends keyof SealedWire ? false : true
+>;
+export type _SealedWireKeepsTheRest = Assert<'label' extends keyof SealedWire ? true : false>;
+export type _SealedSchemaIsTheWireRow = Assert<
+  (typeof sealedPin)['$schema'] extends Schema<unknown, SealedWire> ? true : false
+>;
+/** …and an entity with no sealed column keeps `Row` itself, not a mapped copy. */
+export type _UnsealedWireIsTheRow = Assert<
+  WireRow<PinRow, PinColumns> extends PinRow
+    ? PinRow extends WireRow<PinRow, PinColumns>
+      ? true
+      : false
+    : false
+>;
+
+/** A sealed entity is still an `EntityCore`, so `database()` and every driver take it. */
+export type _SealedEntityIsACore = Assert<
+  typeof sealedPin extends EntityCore<SealedPinRow, SealedPinColumns> ? true : false
+>;
+export type _SealedEntityIsInASet = Assert<
+  { readonly x: typeof sealedPin } extends EntitySet ? true : false
+>;
+
+type WhereFilter = Parameters<(typeof sealedTable)['where']>[0];
+/** An opaque column is absent from the filter; a lookup column and a plain one are present. */
+export type _OpaqueIsNotFilterable = Assert<'password' extends keyof WhereFilter ? false : true>;
+export type _LookupIsFilterable = Assert<'email' extends keyof WhereFilter ? true : false>;
+export type _PlainIsFilterable = Assert<'label' extends keyof WhereFilter ? true : false>;
+
+type AndWhereColumn = Parameters<(typeof sealedTable)['andWhere']>[0];
+export type _OpaqueIsNotAPredicate = Assert<'password' extends AndWhereColumn ? false : true>;
+export type _LookupIsAPredicate = Assert<'email' extends AndWhereColumn ? true : false>;
+/** …but a NULL test names any column: presence is not sealed. The overload is the first one. */
+declare const nullTested: ReturnType<typeof nullTest>;
+declare function nullTest(): ReturnType<(typeof sealedTable)['andWhere']>;
+export type _NullTestTakesAnOpaqueColumn = Assert<
+  (typeof sealedTable)['andWhere'] extends (column: 'password', op: 'is-null') => typeof nullTested
+    ? true
+    : false
+>;
+
+type OrderColumn = Parameters<(typeof sealedTable)['orderBy']>[0];
+/** Neither kind orders: ciphertext has no order worth asking for. */
+export type _SealedDoesNotOrder = Assert<
+  'password' extends OrderColumn ? false : 'email' extends OrderColumn ? false : true
+>;
+export type _PlainOrders = Assert<'label' extends OrderColumn ? true : false>;
+
+/** `.sealed()` is `text()`'s: no other builder has it, so a sealed number does not compile. */
+export type _OnlyTextSeals = Assert<
+  'sealed' extends keyof TextColumn
+    ? 'sealed' extends keyof ReturnType<typeof uuid>
+      ? false
+      : true
+    : false
+>;
+/** It survives the links that may precede it, and keeps its marker across the ones that follow. */
+export type _SealedAfterNullable = Assert<
+  ReturnType<TextColumn['nullable']> extends { sealed: unknown } ? true : false
+>;
+export type _MarkerSurvivesNullable = Assert<
+  ReturnType<SealedColumn<string, false, true>['nullable']>['$sealed'] extends 'lookup'
+    ? true
+    : false
+>;
+
+/**
+ * A sealed table is still a `ReadBuilder<Row>`: `backfill({ source })`, `preload` and every other
+ * consumer that names the chain without the columns takes it. The refusal is in the PARAMETERS,
+ * which a method compares bivariantly, so the narrower chain is assignable to the wider one.
+ */
+export type _SealedTableIsAReadBuilder = Assert<
+  typeof sealedTable extends ReadBuilder<SealedPinRow> ? true : false
+>;

package/src/types.ts

@@ -155,6 +155,27 @@ export interface ColumnMeta {
    * indexes by a data key.
    */
   readonly machine?: StateMachine;
+  /**
+   * Presence is what makes this column SEALED: stored as `@ultimat3/core`'s `seal()` output, opened
+   * on read, absent from every schema that leaves the server. `sealed-repo.ts` is the one reader
+   * that seals and opens; everything else reads it to refuse (`sealed-declaration.ts`).
+   */
+  readonly sealed?: SealedMeta;
+}
+
+/** What `.sealed(options)` declared, resolved. */
+export interface SealedMeta {
+  /** Deterministic seal: equality in `where` and `.unique()` are allowed, and nothing else. */
+  readonly lookup: boolean;
+}
+
+export interface SealedOptions<Lookup extends boolean = boolean> {
+  /**
+   * Seal deterministically so the column can be matched by equality (`where`, `in`, `.unique()`).
+   * It REVEALS EQUALITY: two rows holding the same value store the same string. Never for a
+   * low-entropy value — a boolean, a status, a PIN.
+   */
+  readonly lookup?: Lookup;
 }
 
 /**
@@ -230,6 +251,85 @@ export interface TimestampColumn<Optional extends boolean = false> extends Colum
   column(name: string): TimestampColumn<Optional>;
 }
 
+/**
+ * `text()`'s own column: the one that may be sealed, because a sealed value is a string and no
+ * other kind has a use for it. `nullable()`, `unique()`, `default()` and `column()` keep the
+ * builder, so `.sealed()` reads the same wherever it sits among them.
+ */
+export interface TextColumn<T extends string | null = string, Optional extends boolean = false>
+  extends Column<T, Optional> {
+  nullable(): TextColumn<T | null, Optional>;
+  unique(): TextColumn<T, Optional>;
+  default(value: T): TextColumn<T, true>;
+  column(name: string): TextColumn<T, Optional>;
+  /**
+   * Seal this column under the app's master key: the row still reads `string`, the database holds
+   * `x1.<keyId>.<iv>.<ciphertext>`, and no view, `$schema`, record or predicate carries it.
+   * `.sealed({ lookup: true })` allows equality at the cost of revealing it.
+   */
+  sealed<const Lookup extends boolean = false>(
+    options?: SealedOptions<Lookup>,
+  ): SealedColumn<T, Optional, Lookup>;
+}
+
+/**
+ * A sealed column. `$sealed` is the phantom the typed handle reads: `'opaque'` is refused in every
+ * predicate, `'lookup'` in everything but equality. It is a real string at runtime too.
+ */
+export interface SealedColumn<
+  T extends string | null = string,
+  Optional extends boolean = false,
+  Lookup extends boolean = false,
+> extends Column<T, Optional> {
+  readonly $sealed: Lookup extends true ? 'lookup' : 'opaque';
+  nullable(): SealedColumn<T | null, Optional, Lookup>;
+  /** `lookup` only: uniqueness over ciphertext needs equal values to seal equal. */
+  unique(): SealedColumn<T, Optional, Lookup>;
+  column(name: string): SealedColumn<T, Optional, Lookup>;
+}
+
+/** The columns no predicate may name, and the ones only equality may. Read by `query.ts`. */
+export type OpaqueKeys<C extends ColumnMap> = {
+  [K in keyof C]-?: C[K] extends { readonly $sealed: 'opaque' } ? K : never;
+}[keyof C];
+export type SealedKeys<C extends ColumnMap> = {
+  [K in keyof C]-?: C[K] extends { readonly $sealed: string } ? K : never;
+}[keyof C];
+
+/**
+ * Which keys the typed chain refuses: `opaque` in every predicate, `sealed` (opaque and lookup
+ * both) in an order or a group. A pair rather than the column map itself, so `ReadBuilder` stays
+ * row-shaped and a `select()` or a `preload()` carries it along unchanged.
+ */
+export interface SealedKeySet {
+  readonly opaque: PropertyKey;
+  readonly sealed: PropertyKey;
+}
+
+/** The default: an entity with no sealed column, and every row-agnostic consumer. */
+export interface NoSealedKeys {
+  readonly opaque: never;
+  readonly sealed: never;
+}
+
+export interface SealedKeysOf<C extends ColumnMap> {
+  readonly opaque: OpaqueKeys<C>;
+  readonly sealed: SealedKeys<C>;
+}
+
+/** A filter's shape: the row without the columns no predicate may name. */
+export type Filterable<Row, S extends SealedKeySet> = [S['opaque']] extends [never]
+  ? Row
+  : Omit<Row, S['opaque']>;
+
+/**
+ * The row as it leaves the server: without its sealed columns. `[…] extends [never]` so an entity
+ * with none — and every row-agnostic `EntityCore` — keeps `Row` itself, not a mapped copy of it.
+ */
+export type WireRow<Row, C extends ColumnMap> = [SealedKeys<C>] extends [never]
+  ? Row
+  : Omit<Row, SealedKeys<C>>;
+
 export type AnyColumn = Column<unknown, boolean>;
 
 export type ColumnMap = Readonly<Record<string, AnyColumn>>;