@ultimat3/entity 20.2.1 → 22.0.0

package/README.md

@@ -56,6 +56,51 @@ A view the columns cannot express — a joined `authorName`, a computed `excerpt
 `t.object({...})`. `t` is re-exported here, the same object `@ultimat3/schema` exports, so that file
 still imports one package: `import { entity, t } from '@ultimat3/entity'`.
 
+## A whole row is a record
+
+`posts.$schema` is the whole row as a `t` schema, and its node is branded
+(`Symbol.for('ultimate.entity')`, non-enumerable) with the entity's **record projection**. An
+action or query whose output names it — bare or wrapped — returns rows the client store adopts,
+with no `records:` option anywhere: the envelope is derived from the output schema.
+
+```ts
+import {
+  entity,
+  hasEntityRows,
+  recordProjection,
+  recordTypeForTable,
+  rowsOf,
+  t,
+  text,
+  uuid,
+} from '@ultimat3/entity';
+
+const posts = entity('posts', { columns: { id: uuid().primaryKey(), title: text() } });
+const Feed = t.object({ items: t.array(posts.$schema), featured: posts.$schema.nullable() });
+declare const answer: unknown; // what a handler returned
+
+hasEntityRows(Feed);         // true — static, memoised per node
+rowsOf(Feed, answer);        // { posts: { [recordKey]: row } } — null-prototype, same objects
+recordProjection(posts);     // { type: 'posts', table: 'posts', key, schema, persist: false }
+recordTypeForTable('posts'); // 'posts' — what a changefeed row belongs to
+```
+
+| Rule | Detail |
+|---|---|
+| Survives every wrapper | `t.array`, `t.object`, `t.record`, `t.union` keep the child node by reference; `.nullable()`, `.optional()`, `.default()`, `.describe()`, `.refine()` re-brand the copy they make |
+| A partial row is never a record | a `$view`, and any `t.object(...).pick/omit/extend`, carries no brand — it would overwrite a full record |
+| Wire shape | type → record key → row: the KEY travels, because a browser cannot compute one without importing the app's `entity()` declarations |
+| Union arms | a branded arm claims a value only when every column is an own key of it |
+| Record key | the primary key, in DECLARED order; a single key is the value itself (so it equals `$tagFor(id)`'s id), a composite one percent-encodes each part and joins on `:` |
+| Missing key | `X_RECORD_KEY_MISSING` — never keyed as `undefined`, because two keyless rows would be one record |
+| `persist` | `entity(name, { persist: true })` — default `false`; a browser keeps the records on disk (IndexedDB, per principal) only when declared. Realtime's persister reads `recordProjection(e).persist`, never the declaration |
+| `type` / `table` | the entity name (the store's key) and the physical relation (what a changefeed names); two entities over one table are `X_INVARIANT_VIOLATED` from `recordTypeForTable` |
+
+**In browser code import these from `@ultimat3/entity/record`**, never the barrel: the package
+declares no `sideEffects`, so the barrel retains ~1 MB of SQL rendering and `@ultimat3/db` a page
+never runs, while the subpath retains the projection, the key and the registry and nothing else —
+`record-bundle.test.ts` measures both.
+
 ## Blessed columns
 
 | Builder | Emits | Why it is the only way |
@@ -842,7 +887,17 @@ database from its boot code has decided to, and a library that overruled that wo
 `X_ENTITY_DUPLICATE` · `X_INVARIANT_VIOLATED` · `X_TENANCY_UNSCOPED` ·
 `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_PRELOAD_UNKNOWN_RELATION` · `X_N_PLUS_ONE_QUERY` · `X_N_PLUS_ONE_WRITE` ·
+`X_RECORD_KEY_MISSING`
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `EntityError` | any `EntityErrorCode` — `ENTITY_ERROR_CODES` | `src/entity-error.ts` |
 
 ## Boundaries
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./record": "./src/record.ts"
   },
   "files": [
     "src",
@@ -31,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/db": "20.2.1",
-    "@ultimat3/schema": "20.2.1",
-    "@ultimat3/time": "20.2.1"
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/db": "22.0.0",
+    "@ultimat3/schema": "22.0.0",
+    "@ultimat3/time": "22.0.0"
   }
 }

package/src/aggregate-decode.ts

@@ -24,7 +24,8 @@ export const decodeAggregate = (fn: AggregateFn, kind: ColumnKind, text: string)
   // whatever they fit in, while `sum('likeCount')` over a million of them does not.
   if (fn === 'sum' || fn === 'avg') return text;
   if (kind === 'timestamptz') {
-    const at = new Date(text);
+    // Epoch milliseconds (`pg-sql.ts`), so no zone and no calendar is parsed here at all.
+    const at = new Date(Number(text));
     return Number.isNaN(at.getTime()) ? null : at;
   }
   if (kind === 'integer') {

package/src/columns-data.ts

@@ -47,6 +47,32 @@ export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
 
 const DIGITS = /^-?\d+$/;
 
+/**
+ * The one spelling Postgres answers with: no leading zeros, and no `-0`. Memory stored `'007'`
+ * where Postgres returned `7`, so the same row was two values by driver. String work only — the
+ * digits never pass through a `Number`.
+ */
+const canonicalDigits = (digits: string): string => {
+  const negative = digits.startsWith('-');
+  const whole = digits.replace('-', '').replace(/^0+(?=\d)/, '');
+  return negative && whole !== '0' ? `-${whole}` : whole;
+};
+
+/**
+ * An ACCEPTED decimal in Postgres's spelling: leading zeros stripped, `-0` and `-0.00` unsigned,
+ * and a short fraction padded to the column's scale (`numeric(8, 2)` answers `7.50` for `7.5`).
+ * Never rounds — excess scale was refused above, and rounding here would widen what the column
+ * accepts. An unbounded `numeric` keeps the fraction it was given, as Postgres does.
+ */
+const canonicalDecimal = (text: string, scale: number | undefined): string => {
+  const negative = text.startsWith('-');
+  const [rawWhole = '', rawFraction = ''] = text.replace('-', '').split('.');
+  const whole = rawWhole.replace(/^0+(?=\d)/, '');
+  const fraction = scale === undefined ? rawFraction : rawFraction.padEnd(scale, '0');
+  const zero = /^0*$/.test(whole + fraction);
+  return `${negative && !zero ? '-' : ''}${whole}${fraction === '' ? '' : `.${fraction}`}`;
+};
+
 /**
  * `bigint`, whose row type is a decimal STRING. Neither alternative survives contact:
  * a JS `bigint` is what `JSON.stringify` throws on — the reason `money.minor` is a `number` — and
@@ -71,7 +97,7 @@ export const bigint = (): Column<string> =>
           );
     }
     return typeof value === 'string' && DIGITS.test(value)
-      ? value
+      ? canonicalDigits(value)
       : refuseColumn(
           'bigint',
           `expected whole digits, ${got(value)}`,
@@ -149,7 +175,7 @@ export const decimal = (options: DecimalOptions = {}): Column<string> => {
           `widen the column — decimal({ precision: ${whole + (scale ?? 0)}, scale: ${scale ?? 0} }) — and run x db gen "widen the numeric": what overflows is the digits BEFORE the point`,
         );
       }
-      return text;
+      return canonicalDecimal(text, scale);
     },
     precision === undefined || scale === undefined ? {} : { precision, numericScale: scale },
   );

package/src/columns-scalar.ts

@@ -0,0 +1,79 @@
+// Single responsibility: the three plain scalar columns — `text`, `integer`, `boolean` — each
+// refusing in `$parse` exactly what Postgres refuses at the column, so the memory driver cannot
+// store a value production answers 23514 or 22003 for. Split from `columns.ts` at its ceiling.
+
+import { charCount } from '@ultimat3/schema';
+import { column } from './column';
+import { got } from './column-values';
+import { refuseColumn } from './refuse';
+import type { Column } 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> => {
+  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.
+  if (max !== undefined && !(Number.isSafeInteger(max) && max >= 1)) {
+    refuseColumn(
+      'length',
+      `text({ max }) must be a whole number of characters, at least 1, ${got(max)}`,
+      'text({ max: 200 }) — a whole count of characters, or text() for no bound',
+    );
+  }
+  return column<string>(
+    'text',
+    (value) => {
+      if (typeof value !== 'string') {
+        return refuseColumn(
+          'type',
+          `expected a string, ${got(value)}`,
+          'String(value) at the call site when this really is text — a number column is integer(), an exact decimal is decimal(), a structured payload is json(schema)',
+        );
+      }
+      // Code points, as `char_length` counts them: the CHECK refused an over-long value in
+      // Postgres (23514) while memory stored it, so a test passed a write production refuses.
+      if (max !== undefined && charCount(value) > max) {
+        return refuseColumn(
+          'length',
+          `expected at most ${max} characters, got ${charCount(value)}`,
+          `truncate at the call site, or widen the column — text({ max: ${charCount(value)} }) — and run x db gen "widen the text"`,
+        );
+      }
+      return value;
+    },
+    max === undefined ? {} : { length: max, check: (name) => `char_length(${name}) <= ${max}` },
+  );
+};
+
+/** Postgres `integer` is int4: a safe JS integer past this range is 22003 there. */
+const INT4_MIN = -2_147_483_648;
+const INT4_MAX = 2_147_483_647;
+
+export const integer = (): Column<number> =>
+  column<number>('integer', (value) =>
+    typeof value === 'number' &&
+    Number.isSafeInteger(value) &&
+    value >= INT4_MIN &&
+    value <= INT4_MAX
+      ? value
+      : refuseColumn(
+          'type',
+          `expected a whole number in the int4 range (${INT4_MIN}..${INT4_MAX}), ${got(value)}`,
+          'Math.trunc(value) for a float and Number(value) for a numeric string — a count past int4 is bigint(), a fractional value is decimal()',
+        ),
+  );
+
+export const boolean = (): Column<boolean> =>
+  column<boolean>('boolean', (value) =>
+    typeof value === 'boolean'
+      ? value
+      : refuseColumn(
+          'type',
+          `expected a boolean, ${got(value)}`,
+          "value === 'true' at the call site for a text flag, and boolean().nullable() when the column has a third state",
+        ),
+  );

package/src/columns.ts

@@ -6,6 +6,7 @@ import { uuid as uuidV7 } from '@ultimat3/core';
 import {
   CURRENCY_CODE_PATTERN,
   isCurrencyCode,
+  isIsoDateTime,
   isMoneyScale,
   MAX_MONEY_SCALE,
 } from '@ultimat3/schema';
@@ -85,59 +86,22 @@ const uuidWith = <T extends string>(meta: ColumnMeta): UuidColumn<T> => ({
   column: (name) => uuidWith<T>({ ...meta, name: assertColumnName(name) }),
 });
 
-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> =>
-  column<string>(
-    'text',
-    (value) =>
-      typeof value === 'string'
-        ? value
-        : refuseColumn(
-            'type',
-            `expected a string, ${got(value)}`,
-            'String(value) at the call site when this really is text — a number column is integer(), an exact decimal is decimal(), a structured payload is json(schema)',
-          ),
-    options.max === undefined
-      ? {}
-      : { length: options.max, check: (name) => `char_length(${name}) <= ${options.max}` },
-  );
-
-export const integer = (): Column<number> =>
-  column<number>('integer', (value) =>
-    typeof value === 'number' && Number.isSafeInteger(value)
-      ? value
-      : refuseColumn(
-          'type',
-          `expected a safe integer, ${got(value)}`,
-          'Math.trunc(value) for a float and Number(value) for a numeric string — a count past ±2^53 is bigint(), a fractional value is decimal()',
-        ),
-  );
-
-export const boolean = (): Column<boolean> =>
-  column<boolean>('boolean', (value) =>
-    typeof value === 'boolean'
-      ? value
-      : refuseColumn(
-          'type',
-          `expected a boolean, ${got(value)}`,
-          "value === 'true' at the call site for a text flag, and boolean().nullable() when the column has a third state",
-        ),
-  );
+export type { TextOptions } from './columns-scalar';
+export { boolean, integer, text } from './columns-scalar';
 
 const parseInstant = (value: unknown): Date => {
   if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
-  if (typeof value === 'string' || typeof value === 'number') {
+  // A string must be ISO-8601 naming its own instant (`@ultimat3/schema`'s `isIsoDateTime`):
+  // `new Date('2026-03-14T09:00')` and `new Date('March 14, 2026')` resolved through the HOST's
+  // zone on insert and seed, so one row was a different instant per container `TZ`.
+  if ((typeof value === 'string' && isIsoDateTime(value)) || typeof value === 'number') {
     const parsed = new Date(value);
     if (!Number.isNaN(parsed.getTime())) return parsed;
   }
   return refuseColumn(
     'format',
-    `expected a UTC instant, ${got(value)}`,
-    'new Date(value) at the call site — timestamp() stores an instant; a calendar date with no clock is date(), and an elapsed span is integer()',
+    `expected a UTC instant — a Date, epoch milliseconds, or an ISO-8601 string with Z or an offset — ${got(value)}`,
+    "'2026-03-14T09:00:00Z' or a Date — timestamp() stores an instant, so a string must name its zone; a calendar date with no clock is date(), and an elapsed span is integer()",
   );
 };
 
@@ -156,7 +120,12 @@ export const url = (): Column<string> =>
       if (typeof value === 'string') {
         try {
           const parsed = new URL(value);
-          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') return value;
+          // The scheme is stored in its canonical LOWER case: the CHECK is `~ '^https?://'`, so
+          // `HTTPS://a.b` was stored by memory and refused by Postgres. Only the scheme is
+          // rewritten — the rest of the URL is the caller's, byte for byte.
+          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+            return value.replace(/^https?(?=:)/i, (scheme) => scheme.toLowerCase());
+          }
         } catch {
           // fall through to the shared rejection so the error names the rule
         }

package/src/entity-error.ts

@@ -0,0 +1,126 @@
+// The entity layer's code registry, its error class, and the two refusals the declaration path
+// raises — split from `errors.ts` so a module the BROWSER loads (the record key, the projection,
+// the registry) can raise one without importing `@ultimat3/db`, which `errors.ts` needs for
+// `dbDrift`'s shell-inert fix line.
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const ENTITY_OWNED_ERROR_CODES = [
+  'X_ENTITY_DUPLICATE',
+  'X_INVARIANT_VIOLATED',
+  'X_TENANCY_UNSCOPED',
+  'X_TENANCY_ACTOR_MISMATCH',
+  'X_TENANCY_ACTOR_ORG_REQUIRED',
+  'X_TENANCY_CROSS_DENIED',
+  'X_NOT_FOUND',
+  'X_WRITE_UNFILTERED',
+  'X_PATCH_EMPTY',
+  'X_PRELOAD_UNKNOWN_RELATION',
+  'X_N_PLUS_ONE_QUERY',
+  'X_N_PLUS_ONE_WRITE',
+  'X_REPO_CLIENT_PINNED',
+  'X_AGGREGATE_UNSUPPORTED',
+  'X_AGGREGATE_MIXED_CURRENCY',
+  'X_APPROXIMATE_COUNT_FILTERED',
+  'X_SEARCH_UNDECLARED',
+  'X_SEARCH_IN_MEMORY',
+  'X_STATE_UNDECLARED',
+  'X_STATE_TRANSITION_ILLEGAL',
+  'X_STATE_CONFLICT',
+  'X_RECORD_KEY_MISSING',
+] as const;
+
+/**
+ * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
+ * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
+ * second copy of the title is what lets the two packages disagree about what the code means.
+ */
+export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
+
+/** Every code entity can throw: the ones it owns plus the one it borrows. */
+export const ENTITY_ERROR_CODES = [
+  ...ENTITY_OWNED_ERROR_CODES,
+  ...ENTITY_BORROWED_ERROR_CODES,
+] as const;
+
+export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
+export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
+
+export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
+  X_ENTITY_DUPLICATE: 'two entities claim the same name',
+  X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
+  X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
+  // "call", not "query": the same code covers a predicate that names another tenant and a row or
+  // patch that writes one, because they are one mistake made in two places.
+  X_TENANCY_ACTOR_MISMATCH: "a call named a tenant other than the actor's",
+  X_TENANCY_ACTOR_ORG_REQUIRED: 'the acting actor carries no tenant',
+  X_TENANCY_CROSS_DENIED: 'a cross-tenant read was entered without the capability',
+  X_NOT_FOUND: 'no row for that id',
+  X_WRITE_UNFILTERED: 'a filtered write named no filter columns',
+  X_PATCH_EMPTY: 'a filtered update named no columns to write',
+  X_PRELOAD_UNKNOWN_RELATION: 'no relation of that name on this entity',
+  X_N_PLUS_ONE_QUERY: 'a read repeated once per row',
+  X_N_PLUS_ONE_WRITE: 'a write repeated once per row',
+  X_REPO_CLIENT_PINNED: 'a repository pinned to its own client cannot join the open transaction',
+  X_AGGREGATE_UNSUPPORTED: 'that column has no aggregate both drivers can answer alike',
+  X_AGGREGATE_MIXED_CURRENCY: 'an amount was aggregated across currencies',
+  X_APPROXIMATE_COUNT_FILTERED: 'an estimate was asked of a filtered chain',
+  X_SEARCH_UNDECLARED: 'this entity has no searchable column',
+  X_SEARCH_IN_MEMORY: 'the in-memory driver cannot answer a full-text match',
+  X_STATE_UNDECLARED: 'that column declares no state machine',
+  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',
+};
+
+// Registered at module load, unconditionally, in one call. Without this the registry humanises the
+// code and every surface renders a title this package never wrote; with a presence guard, a second
+// package claiming one of these codes would silently win instead of throwing X_ERROR_CODE_DUPLICATE.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+/**
+ * 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
+ * code, never one per code, because `wiki/` is the framework's only public documentation surface
+ * and a code lives there in a TABLE ROW, which has no anchor. The
+ * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
+ * included, on every refusal it has ever raised.
+ */
+export class EntityError extends UltimateError {
+  override readonly name = 'EntityError';
+
+  constructor(init: { code: EntityErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+    });
+  }
+}
+
+/**
+ * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
+ * given. A literal is an entity that does not exist, and this fix then hands the reader
+ * `x entities describe column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
+ * refusal raised before any entity exists belongs in `refuse.ts`, where the caller supplies the
+ * edit; `refuse.test.ts` fails on a literal here.
+ */
+export const invariantViolated = (
+  entityName: string,
+  invariantName: string,
+  message: string,
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.${invariantName}: ${message}`,
+    fix: `x entities describe ${entityName} --json   # shows the invariant and its SQL CHECK`,
+  });
+
+export const entityDuplicate = (name: string, existingTable: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_DUPLICATE',
+    cause: `entity "${name}" is already registered for table "${existingTable}"`,
+    fix: `x entities list --json   # then rename one of the two entity({ name }) declarations`,
+  });

package/src/entity.ts

@@ -3,9 +3,8 @@
 // (the typed db handle, migrations, cache tags, the admin UI, the manifest) is projected from
 // this one call.
 
-import { renderThrowable } from '@ultimat3/core';
 import type { IndexMethod } from '@ultimat3/db';
-import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
+import { describeValue, type Schema } from '@ultimat3/schema';
 import { entityNow } from './clock';
 import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
@@ -16,8 +15,10 @@ import { invariantColumns } from './expr';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
+import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
+import { rowSchema } from './row-schema';
 import type { SearchInit, SearchSource, SearchVector } from './search';
 import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
@@ -84,6 +85,12 @@ export interface EntityInit<C extends ColumnMap> {
   readonly search?: SearchInit;
   /** Extra cache tags this entity participates in, beyond its own. */
   readonly tags?: readonly string[];
+  /**
+   * Whether a browser keeps this entity's records on disk (IndexedDB, keyed by principal) so they
+   * survive a reload and an offline start. Default `false`: a record is private data by default,
+   * and disk is a decision. Read off `recordProjection(entity).persist` by realtime's persister.
+   */
+  readonly persist?: boolean;
 }
 
 /**
@@ -111,8 +118,13 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   readonly $search: SearchVector | null;
   /** Phantom: `type Post = typeof posts.$row`. Reading it at runtime throws. */
   readonly $row: Row;
-  /** The Standard Schema the columns already describe — forms and actions hand input to it. */
-  readonly $schema: StandardSchemaV1<unknown, Row>;
+  /**
+   * The whole row as a `t` schema — forms and actions hand input to it, and an output naming it
+   * (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.
+   */
+  readonly $schema: Schema<unknown, Row>;
   /** `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. */
@@ -388,25 +400,11 @@ export const entity = <const C extends ColumnMap>(
     $softDelete: softDelete,
     $tenantColumn: tenantColumn,
     $search: search,
-    $schema: {
-      '~standard': {
-        version: 1,
-        vendor: 'ultimate',
-        validate: (value) => {
-          try {
-            return { value: parse(value) };
-          } catch (error) {
-            // `renderThrowable`, never `error instanceof Error ? error.message : String(error)`:
-            // both halves of that read the caught value directly. `instanceof` consults
-            // `getPrototypeOf` and `String()` runs the value's own coercion, so a `Proxy` or a
-            // null-prototype throwable raised a SECOND, uncatchable `TypeError` out of the
-            // validator — where a rejection belongs. A column parser is app-reachable and an
-            // app's `$parse` may throw anything at all.
-            return { issues: [{ message: renderThrowable(error) }] };
-          }
-        },
-      },
-    },
+    $schema: rowSchema<Row>(
+      { name, table, primaryKey, persist: init.persist === true },
+      entries,
+      parse,
+    ),
     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');
@@ -420,7 +418,15 @@ export const entity = <const C extends ColumnMap>(
     $references: references,
   };
 
-  registerEntity({ name, tableName: table, describe, references });
+  registerEntity({
+    name,
+    tableName: table,
+    persist: init.persist === true,
+    projection: recordProjection(core),
+    core: core as EntityCore<unknown>,
+    describe,
+    references,
+  });
   // 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);