@ultimat3/entity 29.3.2 → 30.0.0

package/src/row-security-settings.ts

@@ -0,0 +1,20 @@
+// Single responsibility: the tenant every transaction carries when the database enforces row
+// security — the same `tenant:` the repository already scopes by, handed to `@ultimat3/db`'s
+// transaction-settings seam. A `crossTenant()` scope sets `x.cross`; no actor tenant sets nothing.
+
+import { tryUseContext } from '@ultimat3/core';
+import type { LocalSettings } from '@ultimat3/db';
+import { crossTenantReason } from './cross-tenant';
+
+/**
+ * Read once per root transaction, at its BEGIN. Two limits, stated: a `crossTenant()` opened INSIDE
+ * an open transaction does not reach that transaction (its settings were fixed at BEGIN), and a
+ * raw `set_config('x.cross', 'on', true)` in the app's own process lifts the guard — this layer
+ * catches forgetting, not hostile SQL already running inside the process.
+ */
+export function rowSecuritySettings(): LocalSettings | undefined {
+  if (crossTenantReason() !== undefined) return { 'x.cross': 'on' };
+  const orgId = tryUseContext()?.actor.orgId;
+  if (orgId === undefined || orgId === null || orgId === '') return undefined;
+  return { 'x.tenant': String(orgId) };
+}

package/src/sealed-repo.ts

@@ -232,5 +232,20 @@ export const sealedRepo = <Row, R extends Repo<Row>>(entity: SealedSource, repo:
       return repo.approximateCount(await readArgs(entity, fields, args, sealKeysOnce()));
     },
   };
+  // A bucket is an instant and a sum is arithmetic: neither has a meaning over ciphertext.
+  const series = repo.series?.bind(repo);
+  if (series !== undefined) {
+    sealing.series = async (spec, args) => {
+      const named = spec.value === 'count' ? [spec.on] : [spec.on, spec.value.sum];
+      refuseNamed(entity, fields, named, 'an aggregate');
+      return series(spec, await readArgs(entity, fields, args, sealKeysOnce()));
+    };
+  }
+  // Opened before `fn` sees it: a callback is a caller, and `lockKey` hands it no row to open.
+  const inner = repo.lock?.bind(repo);
+  if (inner !== undefined) {
+    sealing.lock = (id, fn, options) =>
+      inner(id, async (row, tx) => fn(await openRow(fields, row, sealKeysOnce()), tx), options);
+  }
   return { ...repo, ...sealing };
 };

package/src/seed.ts

@@ -5,6 +5,7 @@
 
 import { createHash } from 'node:crypto';
 import { type Environment, resolveEnvironment } from '@ultimat3/core';
+import { overwrittenBy } from './bulk-write';
 import { entityNow } from './clock';
 import type { Driver } from './database';
 import { memoryDriver } from './database';
@@ -12,7 +13,8 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError } from './errors';
 import type { Tx } from './repo';
 import type { Predicate } from './tenancy';
-import type { ColumnMap, Insertable } from './types';
+import { stampedColumns, touch } from './touch';
+import type { ColumnMap, Insertable, RowPatch } from './types';
 
 /** Framework namespace for seed labels. Fixed forever: changing it moves every seeded id. */
 const NAMESPACE = 'a3c1f0d6-5c2b-4a3e-9f1b-6d4e7c8a9b02';
@@ -201,6 +203,12 @@ const sameCell = (left: unknown, right: unknown): boolean => {
   return left === right;
 };
 
+/** A soft-deleting entity's row its delete has stamped — what a plain read reads as absent. */
+const isStamped = (row: unknown): boolean => {
+  const stamp = cellOf(row, SOFT_DELETE_COLUMN);
+  return stamp !== null && stamp !== undefined;
+};
+
 const equalityPredicates = <Row>(where: Partial<Row>): readonly Predicate[] =>
   Object.entries(where).map(([column, value]): Predicate => ({ column, op: 'eq', value }));
 
@@ -253,6 +261,16 @@ const withoutPreserved = <Row>(row: Row, preserve: readonly string[]): Row => {
   return copy as Row;
 };
 
+/** What a replay overwrites: the columns the seed named and the `onUpdateNow()` ones, never `preserve`. */
+const seedOverwrites = <Row>(
+  entity: EntityCore<Row>,
+  values: unknown,
+  preserve: readonly string[],
+): readonly (keyof Row & string)[] =>
+  [...overwrittenBy(entity, [values as RowPatch<Row>]), ...stampedColumns(entity)].filter(
+    (property) => !preserve.includes(property),
+  ) as (keyof Row & string)[];
+
 export const defineSeed = (
   name: string,
   build: (context: SeedContext) => Promise<void>,
@@ -300,8 +318,20 @@ export const defineSeed = (
             const where = Object.fromEntries(
               key.by.map((property) => [property, cellOf(row, property)]),
             );
-            const found = await repo.findMany({ where: equalityPredicates(where), limit: 1 });
+            // `includeDeleted`: a stamped row is still the row the key names. Read without it, it
+            // was absent, the write landed on it with `deleted_at` spared, and every replay said
+            // `'inserted'` for a row nobody can see. A soft delete is a decision a seed replayed on
+            // every boot does not undo — skipped, as `insert`'s do-nothing conflict skips it.
+            const found = await repo.findMany({
+              where: equalityPredicates(where),
+              limit: 1,
+              includeDeleted: true,
+            });
             const stored = found.rows[0];
+            if (stored !== undefined && entity.$softDelete && isStamped(stored)) {
+              metrics.skipped += 1;
+              return 'skipped';
+            }
             const preserve: readonly string[] = key.preserve ?? [CREATED_AT_COLUMN];
             // Only what the CALLER named, and never a key the table generates: `$parse` fills a
             // fresh uuid and a `defaultNow()` into `row`, which no stored row can equal — so a
@@ -336,11 +366,17 @@ export const defineSeed = (
               return outcome;
             }
             const write: SeedWrite = stored === undefined ? 'inserted' : 'updated';
-            await repo.upsertAll([stored === undefined ? row : withoutPreserved(row, preserve)], {
-              ...undo,
-              onConflict: key.by,
-              onMatch: 'update',
-            });
+            // What the caller named, as `db.*.upsertAll` does: `$parse` filled the rest, and a
+            // re-run must not reset a column this seed never mentioned to its default.
+            await repo.upsertAll(
+              [touch(entity, stored === undefined ? row : withoutPreserved(row, preserve))],
+              {
+                ...undo,
+                onConflict: key.by,
+                onMatch: 'update',
+                overwrites: seedOverwrites(entity, values, preserve),
+              },
+            );
             metrics[write === 'inserted' ? 'inserted' : 'updated'] += 1;
             return write;
           },

package/src/series-unsupported.ts

@@ -0,0 +1,11 @@
+// The refusal a hand-written `Repo` answers `series` with. It is optional on the contract so such a
+// driver still compiles, which is exactly why the typed handle has to say so — as `lock` does.
+
+import { EntityError } from './entity-error';
+
+export const seriesUnsupported = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_SERIES_UNSUPPORTED',
+    cause: `${entityName}.series() reached a repository that does not implement it: a hand-written driver, which the contract lets omit it`,
+    fix: 'database(entities, { driver: postgresDriver() })   # both shipped drivers answer series; a hand-written Repo implements series(spec, args)',
+  });

package/src/table-locks.ts

@@ -0,0 +1,41 @@
+// Single responsibility: `lock` and `lockKey` on the typed handle. The refusal lives here because
+// the repository contract lets a hand-written driver omit both, so only this layer can say so.
+
+import { lockUnsupported } from './lock-unsupported';
+import type { Repo, RepoOptions, Tx } from './repo';
+import type { IdOf } from './types';
+
+export interface TableLocks<Row> {
+  /**
+   * `db.posts.lock(id, async (post, tx) => db.posts.update(id, next(post), { tx }))`: the row, locked
+   * for `fn`, so a read-modify-write loses no update. `fn`'s answer is the answer; a throw rolls back.
+   * Absent or another tenant's is `X_NOT_FOUND`. Nested in `withTransaction` the lock lasts to the
+   * root COMMIT. No wait option: the bound is the role's `statement_timeout`, and a deadlock is
+   * `X_DB_SERIALIZATION_FAILURE`.
+   */
+  lock<R>(
+    id: IdOf<Row>,
+    fn: (row: Row, tx: Tx) => Promise<R> | R,
+    options?: RepoOptions,
+  ): Promise<R>;
+  /**
+   * `fn` alone among callers of `key` in this table and this tenant, for work no one row names. Org
+   * A's key never blocks org B. On a tenant-scoped entity with no actor it is `X_TENANCY_UNSCOPED`.
+   */
+  lockKey<R>(key: string, fn: (tx: Tx) => Promise<R> | R, options?: RepoOptions): Promise<R>;
+}
+
+/** Called as methods and refused in an `async` body, so a class-shaped driver keeps its `this`. */
+export const tableLocks = <Row>(
+  entity: { readonly $name: string },
+  repo: Repo<Row>,
+): TableLocks<Row> => ({
+  lock: async (id, fn, options) => {
+    if (repo.lock === undefined) throw lockUnsupported(entity.$name, 'lock');
+    return repo.lock(id, fn, options);
+  },
+  lockKey: async (key, fn, options) => {
+    if (repo.lockKey === undefined) throw lockUnsupported(entity.$name, 'lockKey');
+    return repo.lockKey(key, fn, options);
+  },
+});

package/src/test-driver.ts

@@ -0,0 +1,90 @@
+// The driver a scaffolded handle takes under test: memory until `setDbClient` installs a client,
+// Postgres through that client while it is. Decided per call, because `database()` resolves each
+// table's repository once, at module load, long before a test file installs its migrated database.
+
+import { asyncContext } from '@ultimat3/core';
+import { dbClientInstalled } from '@ultimat3/db';
+import { type Driver, memoryDriver } from './database';
+import type { EntityCore } from './entity';
+import { testDriverClientChanged } from './errors';
+import { postgresDriver } from './pg-driver';
+import type { Repo, Transactor } from './repo';
+
+type Side = 'memory' | 'postgres';
+
+/**
+ * The side an open `transactor().run` began on. Inside it a repository call takes that side, and a
+ * client installed or cleared meanwhile is refused: following it would split one transaction's
+ * writes across two stores, the one committed or rolled back without the other.
+ */
+const began = asyncContext<Side>('a testDriver() transaction');
+
+const installedSide = (): Side => (dbClientInstalled() ? 'postgres' : 'memory');
+
+const sideFor = (entityName: string): Side => {
+  const now = installedSide();
+  const open = began.get();
+  if (open !== undefined && open !== now) throw testDriverClientChanged(entityName, open);
+  return now;
+};
+
+/**
+ * One repository per entity whose every method asks `pick()` at call time. A plain object of
+ * forwarders rather than a `Proxy`: `observedRepo` spreads the repository, and a spread copies the
+ * values a `Proxy` answers at that moment — the target would be frozen at module load. Keyed off
+ * both repositories, so a method `Repo` gains later forwards with no edit here; `reset` is memory's
+ * alone and stays on the driver.
+ */
+const following = <Row>(name: string, memory: Repo<Row>, postgres: Repo<Row>): Repo<Row> => {
+  const pick = (): Repo<Row> => (sideFor(name) === 'postgres' ? postgres : memory);
+  const forwarded: Record<string, unknown> = {};
+  for (const key of Object.keys(postgres)) {
+    if (typeof Reflect.get(memory, key) !== 'function') continue;
+    forwarded[key] = (...args: unknown[]): unknown => {
+      let target: Repo<Row>;
+      try {
+        target = pick();
+      } catch (refusal) {
+        // A repository call rejects, never throws synchronously — every `Repo` method is async.
+        return Promise.reject(refusal);
+      }
+      const method: unknown = Reflect.get(target, key);
+      // Both sides carried a function under this key when the forwarder was built.
+      return (method as (...a: unknown[]) => unknown).apply(target, args);
+    };
+  }
+  // Built from the keys both repositories carry, each forwarding to the same-named method.
+  return forwarded as unknown as Repo<Row>;
+};
+
+/**
+ * `storeMode(env) === 'memory' ? testDriver() : postgresDriver()` — the scaffolded handle's line.
+ * A test file that never installs a client is exactly the memory driver: no PGlite is loaded, no
+ * statement is sent. One that follows `wiki/Testing.md`'s recipe (`setDbClient(migrated.client)`,
+ * then `setDbClient(undefined)` in `afterAll`) reads and writes its migrated database through the
+ * same `db` the code under test imports — joins and raw SQL included.
+ */
+export const testDriver = (): Driver => {
+  const memory = memoryDriver();
+  const postgres = postgresDriver();
+  const repos = new Map<string, unknown>();
+  return {
+    repo<Row>(entity: EntityCore<Row>): Repo<Row> {
+      const existing = repos.get(entity.$name);
+      // Keyed by entity name and only written from that entity, as `memoryDriver` keys its own.
+      if (existing !== undefined) return existing as Repo<Row>;
+      const created = following(entity.$name, memory.repo(entity), postgres.repo(entity));
+      repos.set(entity.$name, created);
+      return created;
+    },
+    // Memory only: the installed database's rows are the test's own, emptied by its own template.
+    reset: () => memory.reset?.(),
+    transactor: (): Transactor => ({
+      run: (work) => {
+        const side = installedSide();
+        const target = side === 'postgres' ? postgres : memory;
+        return began.run(side, () => target.transactor().run(work));
+      },
+    }),
+  };
+};

package/src/time-bucket.ts

@@ -0,0 +1,147 @@
+// Single responsibility: what a time series is made of — the closed list of units, the zone check,
+// the bucket ceiling, and the one in-memory truncation Postgres' three-argument `date_trunc` is
+// matched against. Both drivers read the rules from here, as `count-by.ts` is read for a grouped
+// count, so a `series` against memory buckets a row exactly where Postgres buckets it.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { assertTimeZone, fromZoned, instant, isValidTimeZone, toZoned } from '@ultimat3/time';
+import { aggregateColumnOf } from './aggregate';
+import { columnFor } from './column';
+import { MAX_GROUPS } from './count-by';
+import type { EntityCore } from './entity';
+import { EntityError } from './entity-error';
+import type { AnyColumn } from './types';
+
+/** Closed. A week starts on Monday, as `date_trunc('week', …)` starts one. */
+export const SERIES_UNITS = ['minute', 'hour', 'day', 'week', 'month'] as const;
+export type SeriesUnit = (typeof SERIES_UNITS)[number];
+
+/** `'count'` per bucket, or one column summed per bucket — `aggregate.ts`'s `sum`, never a float. */
+export type SeriesValue<K extends string = string> = 'count' | { readonly sum: K };
+
+/** The row-agnostic request a driver answers; `ReadBuilder.series` is the typed spelling. */
+export interface SeriesSpec {
+  readonly on: string;
+  readonly unit: SeriesUnit;
+  /** IANA, required: a bucket in the session's zone is a bucket in nobody's. */
+  readonly timeZone: string;
+  readonly value: SeriesValue;
+}
+
+/** One bucket that holds rows. A bucket with none is absent — the range is the caller's. */
+export interface SeriesPoint<V = unknown> {
+  /** The bucket's first instant: local midnight, the local hour, the local Monday… */
+  readonly bucket: Date;
+  readonly value: V;
+}
+
+/** A spec both drivers have judged: the zone canonical, the columns resolved. */
+export interface SeriesPlan {
+  readonly on: string;
+  readonly unit: SeriesUnit;
+  readonly timeZone: string;
+  readonly sum: { readonly property: string; readonly column: AnyColumn } | null;
+}
+
+const UNITS: ReadonlySet<string> = new Set(SERIES_UNITS);
+
+const seriesInvalid = (entityName: string, detail: string, fix: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_SERIES_INVALID',
+    cause: `${entityName}.series(): ${detail}`,
+    fix,
+  });
+
+const timestampColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
+  Object.entries(entity.$columns)
+    .filter(([, column]) => column.$meta.kind === 'timestamptz')
+    .map(([property]) => property);
+
+/**
+ * The spec, judged before any statement exists — by the same function in both drivers, so a
+ * `date()` column or `'EST'` is refused with the same words whichever one is attached.
+ */
+export const seriesPlanOf = <Row>(entity: EntityCore<Row>, spec: SeriesSpec): SeriesPlan => {
+  const name = entity.$name;
+  const [first = 'createdAt'] = timestampColumns(entity);
+  const example = `${name}.series({ on: '${first}', unit: 'day', timeZone: 'Europe/Berlin', value: 'count' })`;
+  if (!UNITS.has(spec.unit)) {
+    throw seriesInvalid(
+      name,
+      `unit '${String(spec.unit)}' is not one of ${SERIES_UNITS.join(', ')}`,
+      `${example}   # unit is one of: ${SERIES_UNITS.join(', ')}`,
+    );
+  }
+  const on: AnyColumn | undefined = columnFor(entity.$columns, spec.on);
+  if (on?.$meta.kind !== 'timestamptz') {
+    throw seriesInvalid(
+      name,
+      on === undefined
+        ? `no column "${spec.on}" on ${name}`
+        : `"${spec.on}" is a ${on.$meta.kind} column, and a bucket is a span of instants`,
+      timestampColumns(entity).length === 0
+        ? `x entities show ${renderFixShellArg(name, '<entity>')} --json   # this entity declares no timestamp() column to bucket by`
+        : `${example}   # on is one of: ${timestampColumns(entity).join(', ')}`,
+    );
+  }
+  if (typeof spec.timeZone !== 'string' || !isValidTimeZone(spec.timeZone)) {
+    throw seriesInvalid(
+      name,
+      `timeZone ${JSON.stringify(String(spec.timeZone))} is not an IANA zone`,
+      `${example}   # an IANA zone such as Europe/Berlin or Asia/Tokyo, never an abbreviation or an offset`,
+    );
+  }
+  const value = spec.value;
+  const sum =
+    value === 'count'
+      ? null
+      : { property: value.sum, column: aggregateColumnOf(entity, 'sum', value.sum) };
+  return { on: spec.on, unit: spec.unit, timeZone: assertTimeZone(spec.timeZone), sum };
+};
+
+const MINUTE_MS = 60_000;
+
+/**
+ * The bucket an instant falls in, as Postgres' `date_trunc(unit, ts, zone)` answers it — measured
+ * on 18, the rule is two rules:
+ *
+ * - `minute`/`hour` truncate the wall clock and keep the instant's OWN offset, so the repeated hour
+ *   of a fall-back day is two buckets, and a `+05:30` zone's hour starts at :30 UTC.
+ * - `day`/`week`/`month` truncate to local midnight and resolve it afresh: a midnight that does
+ *   not exist is read at the offset before the jump (`gap: 'next'`), and one that happens twice at
+ *   the offset after it (`overlap: 'second'`) — Asia/Gaza's 2016-10-29 starts at 22:00Z.
+ */
+export const bucketStart = (at: Date, unit: SeriesUnit, timeZone: string): Date => {
+  const zoned = toZoned(instant(at), timeZone);
+  if (unit === 'minute' || unit === 'hour') {
+    // The wall clock's own fields, subtracted from the instant: the offset never moves, which is
+    // the rule, and a zone off the minute (pre-1972 Monrovia) is read at its real offset.
+    const within = zoned.second * 1000 + zoned.millisecond;
+    return new Date(at.getTime() - within - (unit === 'hour' ? zoned.minute * MINUTE_MS : 0));
+  }
+  const day = unit === 'week' ? zoned.day - (zoned.weekday - 1) : unit === 'month' ? 1 : zoned.day;
+  return fromZoned({ year: zoned.year, month: zoned.month, day, hour: 0, minute: 0 }, timeZone, {
+    gap: 'next',
+    overlap: 'second',
+  });
+};
+
+/**
+ * The points both drivers hand back: ascending by bucket, refused past the ceiling. The statement
+ * asks for one bucket more than `MAX_GROUPS`, and that one is a refusal rather than a dropped tail:
+ * a chart missing its last thousand days reads exactly like a complete one.
+ */
+export const seriesFrom = <Row>(
+  entity: EntityCore<Row>,
+  plan: SeriesPlan,
+  points: readonly SeriesPoint[],
+): readonly SeriesPoint[] => {
+  if (points.length > MAX_GROUPS) {
+    throw seriesInvalid(
+      entity.$name,
+      `more than ${MAX_GROUPS} ${plan.unit} buckets matched — that is a report, not a chart`,
+      `${entity.$name}.andWhere('${plan.on}', 'gte', <from>).series({ on: '${plan.on}', unit: '${plan.unit}', … })   # bound the range, or a wider unit`,
+    );
+  }
+  return [...points].sort((left, right) => left.bucket.getTime() - right.bucket.getTime());
+};

package/src/touch.ts

@@ -0,0 +1,33 @@
+// Single responsibility: what a patch or an upserted row writes beyond what the caller named — the
+// `onUpdateNow()` stamp. Split from `query.ts` for its line ceiling.
+
+import { entityNow } from './clock';
+import type { EntityCore } from './entity';
+import { namedColumns } from './plan';
+import { copyRow } from './sealed';
+
+/**
+ * Columns declared `onUpdateNow()` are written by the framework, never by the caller. One helper,
+ * so `update(id, patch)` and `updateWhere(filter, patch)` stamp the same columns at the same
+ * moment — a second copy is how one of them ends up with a stale `updatedAt`.
+ *
+ * A patch that names nothing is returned untouched. Stamping `updatedAt` onto "the caller named no
+ * columns" would turn that mistake into a real write on any entity that happens to declare the
+ * column, and `X_PATCH_EMPTY` downstream would never see it — so whether the refusal fires would
+ * depend on the schema rather than on the call.
+ */
+export const touch = <Row, Patch>(entity: EntityCore<Row>, patch: Patch): Patch => {
+  if (namedColumns(patch).length === 0) return patch;
+  const stamped: Record<string, unknown> = {};
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (column.$meta.onUpdate !== undefined) stamped[property] = entityNow();
+  }
+  // `copyRow`, never `Object.assign({}, patch)`: a row passed back whole keeps its sealed properties.
+  return Object.assign(copyRow(patch as object), stamped) as Patch;
+};
+
+/** The columns `touch` stamps: an upsert's collision moves them though no caller named them. */
+export const stampedColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
+  Object.entries(entity.$columns)
+    .filter(([, column]) => column.$meta.onUpdate !== undefined)
+    .map(([property]) => property);

package/src/types.ts

@@ -57,6 +57,19 @@ export type SearchWeight = 'A' | 'B' | 'C' | 'D';
 
 export interface ReferenceOptions {
   readonly onDelete?: OnDelete;
+  /**
+   * Why this edge may point into another tenant. Both ends tenant-scoped is a composite same-tenant
+   * key by default; a non-blank reason here makes it a plain one. Stated on an edge that was never
+   * same-tenant it is refused: a reason for nothing.
+   */
+  readonly crossTenant?: string;
+  /**
+   * The parent's `integer()` column the database keeps equal to the number of rows pointing at it,
+   * by a trigger on THIS table in the same transaction as the write (`counter.ts`). Declared here,
+   * on the key, because the child already names its parent — a thunk on the parent naming the child
+   * would make the two declarations each other's type and neither could be inferred.
+   */
+  readonly countedIn?: () => AnyColumn;
 }
 
 /**
@@ -141,6 +154,8 @@ export interface ColumnMeta {
   /** A thunk: schema modules reference each other in a cycle. */
   readonly references?: () => AnyColumn;
   readonly onDelete?: OnDelete;
+  /** `references(target, { crossTenant })`: the reason, stated once, read only at describe time. */
+  readonly crossTenant?: string;
   /**
    * Presence is what puts this column in the entity's generated `tsvector`, and the value is its
    * weight. A modifier and not a column of its own: the vector is derived from every searchable
@@ -161,6 +176,11 @@ export interface ColumnMeta {
    * that seals and opens; everything else reads it to refuse (`sealed-declaration.ts`).
    */
   readonly sealed?: SealedMeta;
+  /**
+   * `references(() => posts.id, { countedIn: () => posts.likeCount })`: the parent integer the
+   * database keeps equal to the number of rows pointing there. `counter.ts` reads it.
+   */
+  readonly countedIn?: () => AnyColumn;
 }
 
 /** What `.sealed(options)` declared, resolved. */
@@ -451,4 +471,6 @@ export interface IndexDef {
    * one fact that this release exists to stop.
    */
   readonly using?: IndexMethod;
+  /** `indexes: [{ concurrently: true }]` — `true` or absent, never `false` (`IndexInit`). */
+  readonly concurrently?: true;
 }

package/src/view-entity.ts

@@ -0,0 +1,78 @@
+// `entity(name, { view: { sql } })`: what a view declaration may not hold, and the record it leaves
+// on the entity. A view is a relation Postgres DERIVES — read like a table, written never — so the
+// refusals here are the declarations that would promise a write, a trigger or an index Postgres
+// has no place for. Writes are refused at the repository seam (`append-only.ts`).
+
+import { EntityError } from './entity-error';
+import type { IndexDef } from './types';
+
+/** `entity(…, { view })`. `materialized` stores the rows; `refreshView()` recomputes them. */
+export interface ViewInit {
+  /** One `select`, the view's whole body. Its output columns are `columns`' physical names. */
+  readonly sql: string;
+  readonly materialized?: boolean;
+}
+
+/** What `$viewQuery` holds: the query and the flag, `null` on every table. */
+export interface ViewQuery {
+  readonly sql: string;
+  readonly materialized: boolean;
+}
+
+const refused = (entityName: string, detail: string, fix: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `entity('${entityName}', { view }): ${detail}`,
+    fix,
+  });
+
+export interface ViewDeclaration {
+  readonly appendOnly: boolean;
+  readonly indexes: readonly IndexDef[];
+  readonly sealed: readonly string[];
+}
+
+/**
+ * The view, judged where it was written. `;` is refused anywhere but the end: the body is spliced
+ * into `create view … as <sql>`, and a second statement there would run with the migration's
+ * privileges under a name nobody reviewed as DDL.
+ */
+export const viewQueryOf = (
+  entityName: string,
+  init: ViewInit | undefined,
+  declared: ViewDeclaration,
+): ViewQuery | null => {
+  if (init === undefined) return null;
+  const sql = init.sql.trim().replace(/;\s*$/, '');
+  if (sql.length === 0 || sql.includes(';')) {
+    throw refused(
+      entityName,
+      sql.length === 0 ? 'the query is blank' : 'the query holds more than one statement',
+      `entity('${entityName}', { view: { sql: 'select … from <table>' }, columns })   # one select, no ;`,
+    );
+  }
+  const materialized = init.materialized === true;
+  if (declared.appendOnly) {
+    throw refused(
+      entityName,
+      'is appendOnly, and nothing writes to a view',
+      `entity('${entityName}', { view: { sql }, columns })   # drop appendOnly: true; the source table carries it`,
+    );
+  }
+  const [sealed] = declared.sealed;
+  if (sealed !== undefined) {
+    throw refused(
+      entityName,
+      `${sealed} is sealed, and a view's rows are computed by Postgres, which cannot open a sealed value`,
+      `entity('${entityName}', { view: { sql }, columns })   # remove .sealed() from ${sealed}; decrypt-and-group is meaningless`,
+    );
+  }
+  if (!materialized && declared.indexes.length > 0) {
+    throw refused(
+      entityName,
+      'declares an index, and Postgres has no index on a plain view',
+      `entity('${entityName}', { view: { sql, materialized: true }, columns })   # or drop the index and .unique()`,
+    );
+  }
+  return { sql, materialized };
+};

package/src/view-issue.ts

@@ -0,0 +1,47 @@
+// Single responsibility: one `$view` key's refusal as a schema issue — its path, a rule from the
+// column's own fact and the column's own sentence — so a form binds it to the field it names.
+// Split from `view.ts` so the projection stays one job.
+
+import { renderThrowable, stringField } from '@ultimat3/core';
+import type { SchemaNode, StandardIssue } from '@ultimat3/schema';
+import type { AnyColumn } from './types';
+
+/** `refuseColumn`'s cause: `column.<rule>: <sentence>`. */
+const COLUMN_CAUSE = /^column\.([a-z-]+): (.+)$/s;
+
+/** The rule a column fact names, from `@ultimat3/schema`'s `SCHEMA_RULES`. */
+function ruleOf(
+  column: AnyColumn,
+  node: SchemaNode,
+  refused: string | undefined,
+): Pick<StandardIssue, 'rule' | 'params'> {
+  const meta = column.$meta;
+  if (refused === 'length' && meta.length !== undefined) {
+    return { rule: 'string.max', params: { max: meta.length } };
+  }
+  if (meta.values !== undefined)
+    return { rule: 'enum', params: { values: meta.values.join(' | ') } };
+  return { rule: 'type', params: { type: node.kind } };
+}
+
+/** A required column with nothing at its key: missing data, never a value the view may invent. */
+export function missingIssue(key: string): StandardIssue {
+  return { path: [key], message: 'is required', rule: 'required' };
+}
+
+/**
+ * What a column's `$parse` threw, at `[key]`. The sentence is the column's own (`expected at most
+ * 200 characters, got 300`) — never the whole `X_INVARIANT_VIOLATED` line, which names the column
+ * a second time and reads as a server fault. A throwable that is not the column's refusal is
+ * rendered whole, through `renderThrowable`, which is total.
+ */
+export function columnIssue(
+  key: string,
+  column: AnyColumn,
+  node: SchemaNode,
+  error: unknown,
+): StandardIssue {
+  const match = COLUMN_CAUSE.exec(stringField(error, 'cause') ?? '');
+  const message = match?.[2] ?? renderThrowable(error);
+  return { path: [key], message, ...ruleOf(column, node, match?.[1]) };
+}