@ultimat3/entity 22.15.0 → 23.0.0

package/CLAUDE.md

@@ -87,37 +87,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   (`close()` = `AsyncGenerator.return()`), `.cursor` is advanced before the yield, no empty batch, and
   three refusals on the chain (size, `limit()` alongside, an order no cursor can carry — judged by
   exported `totalOrder`).
-- **A grouped count means one thing in both drivers, and `count-by.ts` is where that one thing is
-  written.** `countBy(column)` is the aggregate a `count()` per row is the N+1 of, so both drivers
-  call `groupColumnOf` before their statement exists and `countsFrom` after their rows are in — a
-  rule added to `pg-driver.ts` or to `memory-repo.ts` alone is exactly the drift that file exists
-  to prevent. **Groupable kinds are a closed set**: `uuid`, `text`, `char`, `boolean`, `integer`,
-  `bigint`. A `timestamptz` is a `Date`, a `jsonb` is an object and `money` is two physical columns
-  — a `Map` compares a non-primitive key by identity, so any of those would file rows under a key
-  no caller can look up again and the result would be a map that only ever answers `undefined`. The
-  refusal is `X_INVARIANT_VIOLATED` naming a column of *this* entity that is groupable, never
-  `x entity explain`: what repairs it is one edit to the call, and the entity is the only place the
-  replacement column lives. **The bound is a refusal, not a truncation.** The statement asks for
-  `MAX_GROUPS + 1` groups — the trick a page already uses when it reads one row past its limit — and
-  that extra group is what says the answer was never going to fit, so `countsFrom` throws with the
-  `andWhere(…, 'in', <values>)` that bounds it. Truncating would hand back a map that reads exactly
-  like a complete one, and a caller recounting from it would write the wrong number to every row it
-  missed. **Absent is not `0`**: a value nothing matched has no entry, because that is what
-  `group by` returns and it is the only way a caller can tell "none" from "never asked" — the
-  `?? 0` is theirs to write, and inventing it here would answer for keys the table has never seen.
-  **NULL is one group**, keyed `null`: the memory driver reads the property as `?? null` so it lands
-  where Postgres puts its NULL rows, while `0`, `''` and `false` stay the values they are. **The
-  order is applied after the rows are in, never in SQL** — a hash aggregate returns groups in
-  whatever order it built them and a `Map` filled row by row returns insertion order, so an
-  `order by` in the statement would let the two drivers disagree about a result they agree on;
-  sorting groups (never rows) costs nothing at this size and is what puts the largest bucket at the
-  front. **Both output names are fixed aliases** — `group_value` and `group_count` in
-  `countByStatement` (`pg-sql.ts`) — because an entity is free to declare a column called `count`,
-  and the un-aliased form would then return two outputs of one name; the grouped value is re-parsed
-  by the column that declared it, since `int8` arrives as a string and would otherwise key the map
-  by text where memory keys it by a `bigint`. **Nothing new to declare**: no `groupBy()` builder and
-  no error code of its own — it is a terminal on the chain that already exists, over exactly the
-  rows `count()` counts.
+- **A grouped count means one thing in both drivers, written in `count-by.ts`**: both call
+  `groupColumnOf` before the statement and `countsFrom` after the rows. Groupable kinds are a closed
+  set (`uuid`, `text`, `char`, `boolean`, `integer`, `bigint`); the bound is a REFUSAL at
+  `MAX_GROUPS + 1`, never a truncation; absent is not `0`; NULL is one group keyed `null`; the order
+  is applied after the rows are in, never in SQL; `group_value` / `group_count` are fixed aliases.
+  The refusal names a groupable column of THIS entity, never `x entity explain`.
+  The argument for each: [`docs/history/entity.md`](../../docs/history/entity.md).
 - **The codec is `@ultimat3/core`'s**, reached through `cursorFor(entity, plan, row, id)` and
   `seekFrom(entity, plan)`; **`assertSeekable` runs in `planFor`**, before a statement exists. A
   `timestamptz` sort key is refused when its `<column>$US` alias would pass 63 bytes. A cursor is bound
@@ -248,6 +224,35 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   after the refusal from a tenant-scoped `findById`; no DDL beyond `enumerated()`'s CHECK; a machine
   column may not be nullable; `whyNot` asks unknown → terminal → legal list.
 
+## Do not regress — sealed columns
+
+- **`sealed-repo.ts` is the ONE seam**: `memoryRepo()` and `postgresRepo()` both return through
+  `sealedRepo(entity, repo)`, which seals rows and patches going in, opens rows coming out and
+  rewrites or refuses every predicate. A driver never seals for itself; an entity with no sealed
+  column gets its repository back untouched. The cipher is core's (`scripts/seal-calls.ts`).
+- **A sealed column's `$parse` passes a sealed string and judges a plaintext**; `decodeRow` parses
+  none. `sealValue` runs the plaintext parser BEFORE sealing — nothing after can.
+- **No reading of an unsealed value.** Not sealed is `X_SEAL_INVALID`; existing plaintext is
+  expand → `backfill()` → contract (README). No `legacy` option.
+- **Purpose is `entity:<table>.<column>`, physical names** (`sealed.ts`). **Sealing is not on
+  `$describe()`**: it changes no DDL, so it must not move the drift hash — the manifest and
+  `x doctor` read `sealedFields(entity)`. Only `check`/`length` leave the description.
+- **A sealed property on a repository row is SERVER-ONLY** — own, readable, writable, NOT
+  enumerable (`serverOnly`, `sealed.ts`; set by `openRow`). Every generic serialiser omits it, which
+  is what holds a `query`'s rows, a loose `output`, a log line, an island prop, a job payload and a
+  cache tier — none of them parses a row. So ABOVE the seam a row is copied with `copyRow` /
+  `pickRow` (descriptors), never `{ ...row }`, `Object.assign({}, row)` or `out[k] = row[k]`:
+  `preload.ts`, `select()` and `touch()` in `query.ts`. `sealRow` reads each sealed property BY NAME,
+  so a row passed back whole is written whole. A required one missing on insert is `sealedMissing`
+  (`X_INVARIANT_VIOLATED`, from `$parse` and from the seam), naming the spread. `sealed.test.ts`.
+- **Nothing sealed leaves**: `$schema` (node and parsed value; typed `WireRow` on `Entity`,
+  `unknown` on `EntityCore`), `$view` (`X_ENTITY_SEALED_IN_VIEW`), `rowsOf`, the row observer, and
+  the repository row itself (above). `sealed-egress.test.ts` here and one per consuming package.
+- **Opaque: NULL tests only. `lookup`: also `eq` / `in`, `.unique()`, an unordered index.**
+  Refused at the type (`SealedKeysOf<C>` on `ReadBuilder`, `type-pins.ts`) AND at runtime
+  (`X_ENTITY_SEALED_PREDICATE`). A filtered write's FILTER refuses both kinds. Declaration rules
+  are `sealed-column.ts` (the chain) and `sealed-declaration.ts` (the entity).
+
 ## Do not regress — records and tests
 
 - **An entity row on the client is a RECORD, derived** (`row-schema.ts`, `ENTITY_BRAND` =

package/README.md

@@ -113,10 +113,121 @@ never runs, while the subpath retains the projection, the key and the registry a
 | `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too |
 
 Chain: `.primaryKey()` · `.nullable()` · `.unique()` · `.default(v)` · `.defaultNow()` ·
-`.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()` · `.column(name)`.
+`.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()` · `.column(name)` ·
+`.sealed()` (`text()` only).
 Physical names are derived from the property key (`orgId` → `org_id`); a name is written once, or
 never — `.column()` is the exception, and it exists for tables this framework did not create.
 
+## A sealed column
+
+A credential column is declared `.sealed()`. The row type stays `string`; the database never sees
+the plaintext.
+
+```ts
+import { database, entity, text, uuid } from '@ultimat3/entity';
+
+export const connections = entity('connections', {
+  columns: {
+    id: uuid().primaryKey(),
+    label: text({ max: 80 }),
+    password: text({ max: 200 }).sealed(), // opaque: read and written, never compared
+    token: text().nullable().sealed(),
+    email: text().sealed({ lookup: true }).unique(), // deterministic: equality only
+  },
+});
+
+const db = database({ connections });
+
+export async function passwordFor(email: string): Promise<string | null> {
+  const row = await db.connections.where({ email }).one();
+  return row?.password ?? null; // the plaintext — on the server, and nowhere else
+}
+```
+
+| Fact | |
+|---|---|
+| Builder | `text()` only — `text().sealed()`, in any order with `.nullable()`, `.unique()`, `.column()`. A sealed number or date does not compile |
+| Stored | `x1.<keyId>.<iv>.<ciphertext+tag>` from `@ultimat3/core`'s `seal()`, in a plain `text` column. No new SQL type; a `text({ max })` bound is checked against the plaintext before sealing and emits no CHECK |
+| Key | the master key `x secrets` manages. No key is `X_SEAL_KEY_MISSING` — the plaintext is never stored instead |
+| Purpose | derived: `entity:<table>.<column>`, physical names. Never stated, so two columns cannot share one; a value copied between sealed columns does not open. Renaming the table or the column is a re-seal — pin the name with `.column()` |
+| Both drivers | `memoryDriver()` seals too; `memoryRepo(entity, seed)` refuses a seed for a sealed entity (`insertAll` instead) |
+| The seam | `sealedRepo(entity, repo)` — both driver factories return through it, so `database()`'s handle and a hand-held `postgresRepo(entity)` agree. A driver written outside this package returns through it too |
+| Cost | the key ring is resolved ONCE per repository call, however many values it seals or opens — a 500-row page is one resolution, not a thousand |
+| Retry | `X_ENTITY_SEALED_PREDICATE` and `X_ENTITY_SEALED_IN_VIEW` are registered `terminal` (`ENTITY_ERROR_RETRY`): a job stops on its first attempt |
+
+**What leaves the server: nothing.**
+
+| Path | Sealed column |
+|---|---|
+| `entity.$schema` (an action's or query's `output`) | absent from the node and from the parsed value; the type is `WireRow` — the row without it |
+| `entity.$view([...])` | `X_ENTITY_SEALED_IN_VIEW` |
+| a record (`rowsOf`, `recordProjection`, the `persist: true` browser store) | dropped from every collected row; `projection.sealed` lists them |
+| a change reported to `setRowObserver` | dropped from `before` and `after` |
+| `decodeRow` on a write-ahead-log row | the stored string, never the plaintext (`@ultimat3/realtime` drops the property before a change leaves) |
+| a repository row serialised whole — a `query`'s rows, a loose `output`, a log line, an error's `meta`, an island prop, a job payload, a cache tier | absent: the property is **server-only** (below) |
+| `{ token: row.token }` — the secret named by hand | leaves. Naming it is the one read there is |
+| `$parse`, `$row`, the repository | the whole row, plaintext included — server code only |
+
+**A sealed property is server-only**, `As of 2026-10`: own, readable and writable, **not
+enumerable**. `row.password` is the plaintext; nothing that walks the row sees it.
+
+| | |
+|---|---|
+| Reads it | `row.password`, `const { password } = row`, `update(id, row)` and `insert(row)` with the row passed whole |
+| Does not | `JSON.stringify(row)`, `{ ...row }`, `Object.keys` / `entries` / `assign`, `structuredClone(row)` |
+| Prints it | `console.log(row)` / `Bun.inspect(row)` — log through `logger` |
+| A spread patch | `update(id, { ...row, label })` leaves the stored secret alone |
+| A spread insert, required column | `X_INVARIANT_VIOLATED` naming the column and the rewrite: `insert({ ...row, password: row.password })` |
+| A spread insert, **nullable** column | stores NULL — silent; an absent nullable column is a legal insert. Name it: `{ ...row, token: row.token }` |
+| `select({ password: true })`, `preload()` | the row keeps it, still server-only |
+
+**Testing a sealed row.** `toEqual` walks enumerable properties, so it cannot see the secret:
+`expect(row).toEqual({ …, password })` fails with an empty diff, and `expect(a).toEqual(b)` passes
+over a wrong one. Write one of:
+
+| Assertion | Compares |
+|---|---|
+| `expect(row).toEqualRow({ id, label: 'primary', password: 'hunter2' })` | every own property (`@ultimat3/testing`) |
+| `expect(row.password).toBe('hunter2')` | the one property, by name |
+| `expect(row).toMatchObject({ password: 'hunter2' })` | the named subset |
+
+`toEqualRow` compares every own property and names what differs — a server-only one by name,
+never by value. No key is needed in a test: `@ultimat3/testing/preload` installs a throwaway one
+when the app supplied none.
+
+**What the database may compare: nothing, or equality.**
+
+| Use | `.sealed()` | `.sealed({ lookup: true })` |
+|---|---|---|
+| `where` / `andWhere` `eq`, `in` | compile error; `X_ENTITY_SEALED_PREDICATE` at runtime | allowed — rewritten to the stored string |
+| `andWhere(column, 'is-null')` / `'is-not-null'` | allowed — `null` is stored as NULL, never sealed, so presence is not a secret | allowed |
+| any other operator, `orderBy`, `countBy`, an aggregate, a cursor | refused | refused |
+| `deleteWhere` / `updateWhere` **filter** | refused | refused — find the row, then write by id |
+| `.unique()`, a unique index, an upsert conflict target | refused | allowed |
+| a plain index | refused | allowed, unordered |
+| an invariant other than `unique` | refused | refused — a CHECK would read ciphertext |
+| `.default()`, `.primaryKey()`, `.tenant()`, `.references()`, `.searchable()` | refused on the chain | refused on the chain |
+
+`lookup` **reveals equality**: two rows holding one value store one string. Never for a low-entropy
+value — a boolean, a status, a PIN.
+
+**During a key rotation** a lookup value has one stored form per declared key, so equality reads
+through `in (…)` over `sealAll()` and `.unique()` holds per key. `x doctor` reports
+`X_SEAL_RESEAL_PENDING` until every row is rewritten (`update(id, { column: row.column })` seals
+under the current key) and the retired key is dropped (`x secrets rotate --drop <keyId>`).
+
+**A column that already holds plaintext is migrated, never tolerated.** A stored value that is not
+a sealed value is `X_SEAL_INVALID`, always. Expand, backfill, contract:
+
+| # | Step | Edit |
+|---|---|---|
+| 1 | expand | add `passwordSealed: text().nullable().sealed()` beside `password`; `x db gen "add sealed password"`; `x db migrate` |
+| 2 | backfill | a `backfill()` over `db.connections.andWhere('passwordSealed', 'is-null')` — only the rows still to seal — whose `handle` runs `update(row.id, { passwordSealed: row.password })` per row. Idempotent, so a replayed page is harmless |
+| 3 | switch | readers and writers use `passwordSealed` |
+| 4 | contract | delete `password`; declare `password: text().sealed().column('password_sealed')` — the purpose follows the physical name, so nothing is re-sealed; `x db gen "drop plaintext password"` |
+
+The full recipe with the `backfill()` declaration: [Entities and migrations](../../wiki/Entities-And-Migrations.md#sealing-a-column-that-already-holds-data).
+
 ## Wide columns
 
 The vocabulary an EXISTING schema needs. The blessed set above is a decision the framework made
@@ -888,7 +999,7 @@ database from its boot code has decided to, and a library that overruled that wo
 `X_TENANCY_ACTOR_MISMATCH` · `X_TENANCY_ACTOR_ORG_REQUIRED` · `X_TENANCY_CROSS_DENIED` ·
 `X_DB_DRIFT` · `X_NOT_FOUND` · `X_WRITE_UNFILTERED` · `X_PATCH_EMPTY` ·
 `X_PRELOAD_UNKNOWN_RELATION` · `X_N_PLUS_ONE_QUERY` · `X_N_PLUS_ONE_WRITE` ·
-`X_RECORD_KEY_MISSING`
+`X_RECORD_KEY_MISSING` · `X_ENTITY_SEALED_PREDICATE` · `X_ENTITY_SEALED_IN_VIEW`
 
 ### Error classes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "22.15.0",
+  "version": "23.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -32,9 +33,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/db": "22.15.0",
-    "@ultimat3/schema": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/db": "23.0.0",
+    "@ultimat3/schema": "23.0.0",
+    "@ultimat3/time": "23.0.0"
   }
 }

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/entity-error.ts

@@ -2,7 +2,8 @@
 // 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';
+import type { ErrorRetry } from '@ultimat3/core';
+import { registerErrorCodes, registerErrorRetry, UltimateError } from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const ENTITY_OWNED_ERROR_CODES = [
@@ -28,6 +29,8 @@ 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;
 
 /**
@@ -71,6 +74,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 +86,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<EntityOwnedErrorCode, 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

package/src/entity.ts

@@ -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']);
 
@@ -341,6 +356,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 +405,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 +420,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 +465,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 +494,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/index.ts

@@ -132,6 +132,11 @@ export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-o
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
 export type { RecordsByKey, RecordsByType } from './rows-of';
 export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
+// Sealed columns. `sealedFields` is what a manifest or `x doctor` reads to say which columns are
+// sealed; `sealedRepo` is the seam a driver written outside this package returns through.
+export type { SealedField } from './sealed';
+export { sealedFields } from './sealed';
+export { sealedRepo } from './sealed-repo';
 // Full-text search. The LANGUAGE set and the weights are values an app reads to build a form;
 // `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
 export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';
@@ -194,10 +199,15 @@ export type {
   RowOf,
   RowPatch,
   RowWrite,
+  SealedColumn,
+  SealedMeta,
+  SealedOptions,
   SearchWeight,
+  TextColumn,
   TimestampColumn,
   TypeOf,
   UuidColumn,
+  WireRow,
 } from './types';
 export { COLUMN_KINDS } from './types';
 // `viewFor` stays internal: a view is reached through the entity, as `posts.$view([...])`.

package/src/instant.ts

@@ -57,9 +57,88 @@ export const pgInstantMicros = (text: unknown): bigint | undefined => {
 };
 
 /**
- * The microsecond epoch of whatever a sort key is holding: a decoded row's `Date` (milliseconds,
- * so the last three digits are zero), a value already counted in microseconds, or the decimal a
- * cursor carries. `undefined` for anything else, so a caller decides rather than guessing at `0`.
+ * An instant as TEXT that names its own zone — what `toISOString()` writes and what a URL, a JSON
+ * body or a hand-kept keyset position holds: `2026-01-01T00:00:03.000Z`, `…+02:00`, `… 00:00:03+00`.
+ *
+ * The zone is REQUIRED. Postgres reads a zoneless text in the session's `TimeZone`, which this
+ * process cannot know, so such a text is not an instant here — the same rule `timestamp()` holds a
+ * written value to.
+ */
+const ISO_INSTANT_TEXT =
+  /^(\d{4,})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?\s*(Z|[+-]\d{2}(?::?\d{2})?)$/i;
+
+const MICROS_PER_MINUTE = 60_000_000n;
+
+const MICROS_PER_DAY = 86_400_000_000;
+
+/** Postgres's `MAX_TZDISP_HOUR`: a numeric offset of sixteen hours or more is an error there. */
+const MAX_OFFSET_HOURS = 15;
+
+/** `Z`, `+02`, `+02:00`, `-0430` → minutes east of UTC; `undefined` past what Postgres accepts. */
+const offsetMinutes = (zone: string): bigint | undefined => {
+  if (zone.toUpperCase() === 'Z') return 0n;
+  const digits = zone.slice(1).replace(':', '');
+  const hours = Number(digits.slice(0, 2));
+  const minutes = Number(digits.slice(2) || '0');
+  if (hours > MAX_OFFSET_HOURS || minutes >= 60) return undefined;
+  const east = BigInt(hours * 60 + minutes);
+  return zone.startsWith('-') ? -east : east;
+};
+
+/**
+ * The fraction as Postgres reads it: `strtod` of the digits, times a million, `rint` — so past six
+ * digits it ROUNDS, half to even, on the double (`.0000005` is a hair under the half and goes
+ * down), and `.9999996` is a whole second. JavaScript's `Number` is the same IEEE double.
+ */
+const fractionMicros = (digits: string | undefined): number => {
+  if (digits === undefined) return 0;
+  if (digits.length <= FRACTION_DIGITS) return Number(digits.padEnd(FRACTION_DIGITS, '0'));
+  const scaled = Number(`0.${digits}`) * 1_000_000;
+  const floor = Math.floor(scaled);
+  const above = scaled - floor;
+  if (above !== 0.5) return above > 0.5 ? floor + 1 : floor;
+  return floor % 2 === 0 ? floor : floor + 1;
+};
+
+/**
+ * The exact microsecond epoch an ISO instant text names, or `undefined` when Postgres would refuse
+ * it — no zone, a date the calendar does not have (`2026-13-45` is an error there, never the 14th
+ * of February), an offset of sixteen hours, or a time past the end of its day.
+ *
+ * Postgres's `time_overflows`: hour ≤ 24, minute ≤ 59, second ≤ 60, and the whole time of day at
+ * most 24:00:00 — so `24:00:00` is the next midnight and `:60` the next minute, while
+ * `24:00:00.000001` and `23:59:60.5` are errors.
+ */
+const isoInstantMicros = (text: string): bigint | undefined => {
+  const match = ISO_INSTANT_TEXT.exec(text);
+  if (match === null) return undefined;
+  const [, year = '', month = '', day = '', hour = '', minute = '', second = '', fraction] = match;
+  const [y = 0, m = 0, d = 0] = [year, month, day].map(Number);
+  const [h = 0, min = 0, sec = 0] = [hour, minute, second].map(Number);
+  const midnight = utcSecondMillis([y, m, d, 0, 0, 0]);
+  const built = new Date(midnight);
+  // A field the calendar rolled over was never that date: 13 months, 45 days.
+  if (built.getUTCMonth() + 1 !== m || built.getUTCDate() !== d) return undefined;
+  const fsec = fractionMicros(fraction);
+  const ofDay = ((h * 60 + min) * 60 + sec) * 1_000_000 + fsec;
+  if (h > 24 || min > 59 || sec > 60 || ofDay > MICROS_PER_DAY) return undefined;
+  const offset = offsetMinutes(match[8] ?? 'Z');
+  if (offset === undefined) return undefined;
+  const local = BigInt(midnight) * MICROS_PER_MILLI + BigInt(ofDay);
+  // The text is wall-clock time AT its offset, so the instant is that many minutes earlier.
+  return local - offset * MICROS_PER_MINUTE;
+};
+
+/**
+ * The microsecond epoch of whatever a sort key or an operand is holding: a decoded row's `Date`
+ * (milliseconds, so the last three digits are zero), a value already counted in microseconds, the
+ * decimal a cursor carries, or an ISO instant as text. `undefined` for anything else, so a caller
+ * decides rather than guessing at `0`.
+ *
+ * The ISO text is the half Postgres always had: a `"created_at" < $1` bound to
+ * `2026-01-01T00:00:03.000Z` is parsed there as an instant, while the in-memory driver compared it
+ * to the stored `Date` by CHARACTERS — so a hand-kept keyset answered an empty page two in memory
+ * and the right one in production.
  */
 export const instantMicros = (value: unknown): bigint | undefined => {
   if (typeof value === 'bigint') return value;
@@ -67,8 +146,8 @@ export const instantMicros = (value: unknown): bigint | undefined => {
     const millis = value.getTime();
     return Number.isNaN(millis) ? undefined : BigInt(millis) * MICROS_PER_MILLI;
   }
-  if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
-  return undefined;
+  if (typeof value !== 'string') return undefined;
+  return /^-?\d+$/.test(value) ? BigInt(value) : isoInstantMicros(value);
 };
 
 /**

package/src/memory-match.ts

@@ -91,6 +91,13 @@ export const sameValueOfKind = (
   right: unknown,
 ): boolean => {
   if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  // An instant handed over as ISO text is the instant it names, as Postgres parses the bound
+  // parameter: `eq` against a stored `Date` compared an object to a string and matched no row.
+  if (kind === 'timestamptz') {
+    const stored = instantMicros(left);
+    const given = instantMicros(right);
+    if (stored !== undefined && given !== undefined) return stored === given;
+  }
   if (kind === 'uuid' && typeof left === 'string' && typeof right === 'string') {
     return keyOf('uuid', left) === keyOf('uuid', right);
   }