@ultimat3/admin 22.15.0 → 24.0.0

package/src/relations.ts

@@ -0,0 +1,240 @@
+// A resource read AS A TARGET: the label of each row another resource references, and the lookup
+// a picker searches. Both are reads of the target — decided by its `list` gate, narrowed by its
+// row scope, audited under its name — and both are batched: one statement per target resource per
+// page, never one per row and never one per cell.
+
+import { finiteCount } from '@ultimat3/core';
+import { expectedQueryLoop } from '@ultimat3/db';
+import type { AuditEntry } from './audit';
+import type { AdminDecision } from './authz';
+import { type CrudCtx, decideOperation } from './crud';
+import { checkedFilter } from './list-filters';
+import { rowWhere } from './list-scope';
+import { type AdminPage, fetchPage } from './pagination';
+import type { AdminRow } from './registry';
+import { rowId } from './registry';
+import { type AdminResource, repoOf } from './resource';
+
+/** One row of a target, as a picker offers it and a reference cell shows it. */
+export interface AdminOption {
+  readonly id: string;
+  readonly label: string;
+}
+
+/**
+ * A target with at most this many visible rows is offered whole, as a `<select>`. One more and
+ * the picker is a search: an option list nobody can scan is not a control.
+ */
+export const LOOKUP_SELECT_MAX = 50;
+
+/**
+ * The most ids one label read names — the list's own page-size ceiling. A page naming more is read
+ * in chunks of this many, never cut at it: a 200-row list with two columns on one target names up
+ * to 400 ids, and the ids past the cut were drawn as raw ids with no error anywhere.
+ */
+const MAX_LABEL_IDS = 200;
+
+/** The row's label-field value when it is text, else its id — never a blank cell. */
+export function labelOf(
+  row: AdminRow,
+  resource: Pick<AdminResource, 'labelField' | 'idField'>,
+): string {
+  const value = row[resource.labelField];
+  if (typeof value === 'string' && value !== '') return value;
+  return rowId(row, resource.idField);
+}
+
+const optionOf = (resource: AdminResource, row: AdminRow): AdminOption => ({
+  id: rowId(row, resource.idField),
+  label: labelOf(row, resource),
+});
+
+const readEntry = (resource: AdminResource, ctx: CrudCtx, decision: AdminDecision) =>
+  ctx.audit.append({
+    requestId: ctx.requestId,
+    actor: ctx.actor,
+    operation: 'list',
+    kind: 'operation',
+    entity: resource.name,
+    entityId: null,
+    permission: decision.permission,
+    outcome: 'allowed',
+    reason: decision.reason,
+  });
+
+export interface AdminLookupRequest {
+  /** Matched against the target's label, by its label filter's default operator. */
+  readonly term?: string;
+  readonly cursor?: string | null;
+  readonly limit?: number;
+}
+
+export type AdminLookupResult =
+  | {
+      readonly ok: true;
+      readonly options: readonly AdminOption[];
+      readonly page: AdminPage<AdminRow>;
+      readonly audit: AuditEntry;
+    }
+  | { readonly ok: false; readonly decision: AdminDecision };
+
+/**
+ * The one lookup of a target resource: `contains` on its label, keyset-paged in the resource's own
+ * default order, behind the same `list` gate and the same row scope as its list screen. Every
+ * filter and every input that references the resource asks this — an app writes no endpoint.
+ */
+export async function adminLookup(
+  resource: AdminResource,
+  ctx: CrudCtx,
+  request: AdminLookupRequest = {},
+): Promise<AdminLookupResult> {
+  const decision = decideOperation(resource, 'list', ctx);
+  if (!decision.allowed) return { ok: false, decision };
+  const term = request.term?.trim() ?? '';
+  const where = [
+    ...rowWhere(resource, ctx.actor),
+    // Through the validator, like any caller's filter: a label that takes no `contains` (an id)
+    // is matched exactly, and one that is no filter at all is refused by name.
+    ...(term === '' ? [] : [checkedFilter(resource, { field: resource.labelField, value: term })]),
+  ];
+  const page = await fetchPage(resource, {
+    ...(request.cursor === undefined ? {} : { cursor: request.cursor }),
+    // At least 1, and finite: a `NaN` here is a page that is never trimmed and never ends.
+    limit: finiteCount('adminLookup', 'limit', request.limit ?? LOOKUP_SELECT_MAX, 1),
+    ...(where.length === 0 ? {} : { where }),
+  });
+  return {
+    ok: true,
+    options: page.rows.map((row) => optionOf(resource, row)),
+    page,
+    audit: await readEntry(resource, ctx, decision),
+  };
+}
+
+/** What one page needs of one target: the ids its cells show, and whether a control picks from it. */
+export interface RelationNeed {
+  readonly ids: ReadonlySet<string>;
+  /** A filter or an input on the page picks a row of this target. */
+  readonly pick: boolean;
+}
+
+export interface RelationData {
+  /** id → label, for every id the page shows that this actor may see. */
+  readonly labels: ReadonlyMap<string, string>;
+  /**
+   * Every row of the target, when there are at most `LOOKUP_SELECT_MAX` — the `<select>`. `null`
+   * when there are more (the picker is the lookup screen) or when nothing on the page picks.
+   */
+  readonly options: readonly AdminOption[] | null;
+}
+
+const NOTHING: RelationData = { labels: new Map(), options: null };
+
+async function relationOf(
+  resource: AdminResource,
+  ctx: CrudCtx,
+  need: RelationNeed,
+): Promise<RelationData> {
+  if (!need.pick && need.ids.size === 0) return NOTHING;
+  const decision = decideOperation(resource, 'list', ctx);
+  // Not an event: the actor asked for another resource's page, and a label they may not read is
+  // an id shown as an id. The refusal they would get by opening the target is logged there.
+  if (!decision.allowed) return NOTHING;
+
+  const repo = repoOf(resource);
+  const visible = rowWhere(resource, ctx.actor);
+  const labels = new Map<string, string>();
+  let options: readonly AdminOption[] | null = null;
+  let wanted = [...need.ids];
+
+  if (need.pick) {
+    // One over the ceiling: the extra row is how "small enough for a select" is learned without
+    // a count, which on a large table is the slow query this probe exists to avoid.
+    const rows = await repo.list({
+      ...(visible.length === 0 ? {} : { where: visible }),
+      sort: resource.defaultSort,
+      limit: LOOKUP_SELECT_MAX + 1,
+    });
+    for (const row of rows) labels.set(rowId(row, resource.idField), labelOf(row, resource));
+    if (rows.length <= LOOKUP_SELECT_MAX) {
+      // The whole target is in hand, so every label the page needs is too: no second read.
+      options = rows
+        .map((row) => optionOf(resource, row))
+        .sort((a, b) => (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+      wanted = [];
+    } else {
+      wanted = wanted.filter((id) => !labels.has(id));
+    }
+  }
+
+  const chunks: string[][] = [];
+  for (let at = 0; at < wanted.length; at += MAX_LABEL_IDS) {
+    chunks.push(wanted.slice(at, at + MAX_LABEL_IDS));
+  }
+  // One statement per chunk, and only past the ceiling: a page's ids are known up front, so this
+  // is a bounded batch, not a read per row — and declared as one.
+  await expectedQueryLoop(
+    'admin labels read a page’s referenced ids in chunks under the `in` ceiling',
+    async () => {
+      for (const chunk of chunks) {
+        const rows = await repo.list({
+          where: [...visible, { field: resource.idField, op: 'in', value: chunk }],
+          sort: resource.defaultSort,
+          limit: chunk.length,
+        });
+        for (const row of rows) labels.set(rowId(row, resource.idField), labelOf(row, resource));
+      }
+    },
+  );
+
+  await readEntry(resource, ctx, decision);
+  return { labels, options };
+}
+
+/**
+ * Everything one page needs from the resources it references, keyed by target name. One statement
+ * per target — two for a picked target too large for a `<select>` — whatever the page's row count
+ * and however many columns point at the same target.
+ */
+export async function relationsFor(
+  resources: readonly AdminResource[],
+  ctx: CrudCtx,
+  needs: ReadonlyMap<string, RelationNeed>,
+): Promise<ReadonlyMap<string, RelationData>> {
+  const targets = resources.filter((resource) => needs.has(resource.name));
+  const read = await Promise.all(
+    targets.map((resource) => relationOf(resource, ctx, needs.get(resource.name) ?? NO_NEED)),
+  );
+  return new Map(targets.map((resource, index) => [resource.name, read[index] ?? NOTHING]));
+}
+
+const NO_NEED: RelationNeed = { ids: new Set(), pick: false };
+
+/**
+ * What a set of rows and fields needs: per target resource, the ids the rows hold in the fields
+ * that reference it, and whether any of `picked` — a filter, a form input — picks from it.
+ */
+export function relationNeeds(
+  rows: readonly AdminRow[],
+  shown: readonly { readonly name: string; readonly relation?: { readonly entity: string } }[],
+  picked: readonly { readonly relation?: { readonly entity: string } }[],
+): ReadonlyMap<string, RelationNeed> {
+  const needs = new Map<string, { ids: Set<string>; pick: boolean }>();
+  const need = (entity: string): { ids: Set<string>; pick: boolean } => {
+    const held = needs.get(entity) ?? { ids: new Set<string>(), pick: false };
+    needs.set(entity, held);
+    return held;
+  };
+  for (const field of shown) {
+    if (field.relation === undefined) continue;
+    const held = need(field.relation.entity);
+    for (const row of rows) {
+      const value = row[field.name];
+      if (value !== null && value !== undefined && value !== '') held.ids.add(String(value));
+    }
+  }
+  for (const field of picked) {
+    if (field.relation !== undefined) need(field.relation.entity).pick = true;
+  }
+  return needs;
+}

package/src/renderers.tsx

@@ -0,0 +1,89 @@
+// The six renderers a computed column names, and the one dispatch that draws a computed cell. A
+// closed set on purpose: each maps a VALUE SHAPE to an `@ultimat3/ui` component, so a column says
+// what its value is and never how it is drawn. A seventh shape is a component the app passes.
+
+import { safeUrl } from '@ultimat3/core';
+import { t } from '@ultimat3/i18n';
+import { Badge, Money, RelativeTime, TONES, type Tone } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import { jsonText } from './json-text';
+import type { AdminRow } from './registry';
+import type { AdminComputedColumn, AdminRenderer } from './resource-list';
+import { assertMoney, type WidgetContext } from './widget-value';
+
+/** What `truncate` keeps. One line of a laptop-width table cell. */
+export const TRUNCATE_AT = 80;
+
+const isTone = (value: unknown): value is Tone => (TONES as readonly unknown[]).includes(value);
+
+const bag = (value: unknown): Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : {};
+
+const text = (value: unknown): string =>
+  typeof value === 'string' ? value : typeof value === 'number' ? String(value) : '';
+
+const empty = (): JSX.Element => <span>{t('admin.value.empty')}</span>;
+
+type Render = (value: unknown, column: AdminComputedColumn, ctx: WidgetContext) => JSX.Element;
+
+/**
+ * | renderer | value |
+ * |---|---|
+ * | `badge` | text, or `{ label, tone }` |
+ * | `relative-time` | a `Date` or an ISO instant |
+ * | `money` | `{ minor, currency }` — a float is refused, as everywhere |
+ * | `truncate` | text, cut at `TRUNCATE_AT` with the whole value on `title` |
+ * | `link` | `{ href, label }` — the href through `safeUrl` |
+ * | `json` | anything — keys sorted, a bigint as its digits (`json-text.ts`) |
+ */
+const RENDERERS: Readonly<Record<AdminRenderer, Render>> = {
+  badge: (value) => {
+    const tone = bag(value)['tone'];
+    const label = typeof value === 'object' ? text(bag(value)['label']) : text(value);
+    return label === '' ? empty() : <Badge tone={isTone(tone) ? tone : 'neutral'}>{label}</Badge>;
+  },
+  'relative-time': (value, _column, ctx) =>
+    value instanceof Date || typeof value === 'string' ? (
+      <RelativeTime value={value} locale={ctx.locale} timeZone={ctx.timeZone} />
+    ) : (
+      empty()
+    ),
+  money: (value, column, ctx) => {
+    // The guard names what it refuses; a computed column has no entity field to name.
+    const money = assertMoney({ entity: 'columns', name: column.name }, value);
+    return money === null ? empty() : <Money value={money} locale={ctx.locale} />;
+  },
+  truncate: (value) => {
+    const whole = text(value);
+    if (whole === '') return empty();
+    return whole.length <= TRUNCATE_AT ? (
+      <span>{whole}</span>
+    ) : (
+      <span title={whole}>{`${whole.slice(0, TRUNCATE_AT)}…`}</span>
+    );
+  },
+  link: (value) => {
+    const href = safeUrl(text(bag(value)['href']), 'href');
+    const label = text(bag(value)['label']);
+    if (label === '') return empty();
+    return href === null ? <span>{label}</span> : <a href={href}>{label}</a>;
+  },
+  json: (value) =>
+    value === undefined ? empty() : <pre class="x-admin-json">{jsonText(value)}</pre>,
+};
+
+/** The same table as a Map: a name that is not one of the six draws an empty cell. */
+const RENDER: ReadonlyMap<string, Render> = new Map(Object.entries(RENDERERS));
+
+/** One computed cell. */
+export function ComputedCell(props: {
+  readonly column: AdminComputedColumn;
+  readonly row: AdminRow;
+  readonly ctx: WidgetContext;
+}): JSX.Element {
+  const value = props.column.value(props.row);
+  const render = props.column.render;
+  return typeof render === 'function'
+    ? render({ value, row: props.row, ctx: props.ctx })
+    : (RENDER.get(render)?.(value, props.column, props.ctx) ?? empty());
+}

package/src/repo-entity.ts

@@ -0,0 +1,195 @@
+// The ONE adapter from an entity's typed handle — `database()`'s `db.<entity>` — to `AdminRepo`.
+// Verbs, the keyset bound and filters are translated here and nowhere else; tenancy, soft delete,
+// sealing and invariants stay the handle's, so this file adds no predicate of its own.
+
+import { isUltimateError } from '@ultimat3/core';
+import { getEntity, invariantViolated } from '@ultimat3/entity';
+import { adminColumnsOf } from './entity-columns';
+import { seekPage } from './keyset-seek';
+import type {
+  AdminDb,
+  AdminEntity,
+  AdminFilter,
+  AdminListQuery,
+  AdminRepo,
+  AdminRow,
+  AdminTable,
+  AdminTableRead,
+} from './registry';
+
+type TableOperator = Parameters<AdminTableRead['andWhere']>[1];
+
+/**
+ * `contains` is the admin's word for it; `like` with both wildcards is what a driver runs. A Map,
+ * so an operator that is not one of the seven answers `undefined` rather than a prototype member.
+ */
+const OPERATOR_OF: ReadonlyMap<AdminFilter['op'], TableOperator> = new Map([
+  ['eq', 'eq'],
+  ['neq', 'neq'],
+  ['contains', 'like'],
+  ['gt', 'gt'],
+  ['gte', 'gte'],
+  ['lt', 'lt'],
+  ['lte', 'lte'],
+  ['in', 'in'],
+  ['is-null', 'is-null'],
+]);
+
+/** `%` and `_` are wildcards to `LIKE`; a `contains` matches the text an operator typed. */
+const literal = (text: string): string => text.replace(/[\\%_]/g, (wild) => `\\${wild}`);
+
+/**
+ * A comparison value, in the shape the column holds. An instant travels as ISO text — in a URL, in
+ * a cursor — and the handle is given the `Date`: Postgres would cast the text, the memory driver
+ * compares a `Date` to a string by its characters, and a keyset over `createdAt` (the admin's
+ * default sort) then answers page one for every page. An `integer` travels as text in a cursor
+ * too, and the memory driver's `eq` holds `'7'` and `7` to be two values where Postgres binds one.
+ */
+type Typed = (field: string, value: unknown) => unknown;
+
+const typedBy = (entity: AdminEntity): Typed => {
+  const kinds = new Map(adminColumnsOf(entity).map((column) => [column.name, column.kind]));
+  return (field, value) => {
+    if (typeof value !== 'string') return value;
+    const kind = kinds.get(field);
+    if (kind === 'integer') {
+      const count = Number(value);
+      return value.trim() !== '' && Number.isSafeInteger(count) ? count : value;
+    }
+    if (kind !== 'timestamptz') return value;
+    const at = new Date(value);
+    return Number.isNaN(at.getTime()) ? value : at;
+  };
+};
+
+const predicate =
+  (typed: Typed) =>
+  (read: AdminTableRead, filter: AdminFilter): AdminTableRead => {
+    if (filter.op === 'contains') {
+      return read.andWhere(filter.field, 'like', `%${literal(String(filter.value))}%`);
+    }
+    // One admin operator, two of the handle's: `false` asks for the rows that HAVE a value.
+    if (filter.op === 'is-null') {
+      return read.andWhere(filter.field, filter.value === false ? 'is-not-null' : 'is-null');
+    }
+    return read.andWhere(
+      filter.field,
+      OPERATOR_OF.get(filter.op) ?? 'eq',
+      typed(filter.field, filter.value),
+    );
+  };
+
+const filtered = (
+  read: AdminTableRead,
+  where: readonly AdminFilter[],
+  typed: Typed,
+): AdminTableRead => where.reduce(predicate(typed), read);
+
+/**
+ * One entity + its table → one `AdminRepo`.
+ *
+ * A row is never spread and never re-parsed here. The handle parses an insert against the entity
+ * and asserts every invariant over the stored row merged under a patch, so a second parse would be
+ * a second opinion — and a row's sealed properties are non-enumerable, so a spread would drop the
+ * very values a whole-row write then needs.
+ */
+export function adminRepoFor(entity: AdminEntity, table: AdminTable): AdminRepo<AdminRow> {
+  const idField = entity.$primaryKey[0] ?? 'id';
+  const idColumn = Object.hasOwn(entity.$columns, idField) ? entity.$columns[idField] : undefined;
+  const typed = typedBy(entity);
+  const columns = adminColumnsOf(entity);
+  /**
+   * `AdminRepo` carries `id: string` — a URL param, untyped by nature. The primary key column's
+   * OWN `$parse` is what earns the crossing: `/posts/nope` is judged here, at the door, instead
+   * of reaching the driver as a comparison Postgres answers with a cast error.
+   */
+  const idOf = (id: string): string => {
+    const parsed = idColumn?.$parse === undefined ? id : idColumn.$parse(id);
+    if (typeof parsed !== 'string') {
+      throw invariantViolated(entity.$name, idField, `expected a string id, got ${typeof parsed}`);
+    }
+    return parsed;
+  };
+  /**
+   * The same crossing for a READ, where an id that is not one is simply a row that does not exist:
+   * `/posts/nope` is the admin's 404, not `X_INVARIANT_VIOLATED` — the operator mistyped a URL and
+   * violated nothing. A write keeps the throw: it is reached only after a read found the row.
+   */
+  const readableId = (id: string): string | undefined => {
+    try {
+      return idOf(id);
+    } catch (error) {
+      if (isUltimateError(error) && error.code === 'X_INVARIANT_VIOLATED') return undefined;
+      throw error;
+    }
+  };
+
+  return {
+    async list(query: AdminListQuery): Promise<readonly AdminRow[]> {
+      const base = filtered(table, query.where ?? [], typed);
+      const sortField = query.sort.field;
+      const facts = columns.find((column) => column.name === sortField);
+      return seekPage(
+        query,
+        {
+          field: sortField,
+          idField,
+          nullable: facts?.nullable ?? true,
+          instant: facts?.kind === 'timestamptz',
+          typed: (value) => typed(sortField, value),
+        },
+        async (where, order, limit) => {
+          const read = where.reduce(
+            (chain, term) =>
+              term.value === undefined
+                ? chain.andWhere(term.field, term.op)
+                : chain.andWhere(term.field, term.op, term.value),
+            base,
+          );
+          // The tie-break, always: a page boundary on a partial order repeats or drops a row.
+          const sorted = order.by === 'pair' ? read.orderBy(sortField, order.direction) : read;
+          return [...(await sorted.orderBy(idField, order.direction).limit(limit).all())];
+        },
+      );
+    },
+    // `async`, so a refused id arrives as a rejection: these return promises, and a caller that
+    // chains `.catch()` instead of `await`ing would never see a synchronous throw.
+    find: async (id) => {
+      const key = readableId(id);
+      return key === undefined ? null : table.where({ [idField]: key }).one();
+    },
+    create: async (input) => table.insert(input),
+    update: async (id, patch) => table.update(idOf(id), patch),
+    destroy: async (id) => table.delete(idOf(id)),
+    count: async (where) => filtered(table, where ?? [], typed).count(),
+  };
+}
+
+/**
+ * The handle's tables, by the ENTITY they serve. `database({ posts })` keys a table by the app's
+ * own spelling, which need not be the entity's `$name` — so the name is read off the table's own
+ * plan rather than off the key it happens to sit under.
+ */
+export function adminTablesOf(db: AdminDb): ReadonlyMap<string, AdminTable> {
+  return new Map(Object.values(db).map((table) => [table.plan().entity, table]));
+}
+
+/**
+ * Every entity the handle serves that the admin can address — what an app passes as `entities`
+ * when its admin is "all of my tables": `defineAdmin({ entities: adminEntitiesOf(db), db })`. The
+ * handle's set is the one `x g entity` adds to, so a new entity is a new admin resource with no
+ * second registration.
+ *
+ * An entity keyed on more than one column is left out: a route id and an `AdminRepo` id carry one
+ * string. Name it in `entities` yourself and `defineAdmin` refuses it out loud
+ * (`X_ADMIN_FIELD_UNSUPPORTED`) — this helper is "everything that can be a screen", not a claim
+ * that everything is. Handle order, which is the order the app declared.
+ */
+export function adminEntitiesOf(db: AdminDb): readonly AdminEntity[] {
+  const found: AdminEntity[] = [];
+  for (const name of adminTablesOf(db).keys()) {
+    const declared = getEntity(name)?.core;
+    if (declared !== undefined && declared.$primaryKey.length === 1) found.push(declared);
+  }
+  return found;
+}

package/src/resource-fields.ts

@@ -0,0 +1,116 @@
+// One column → one admin field. Everything a list cell, a detail row, a form input, a filter and
+// an MCP tool schema need is decided here, once, from the column's facts and the app's override —
+// and a sealed column is derived by a function of its own, whose every read flag is false.
+
+import type { AdminColumnFacts } from './entity-columns';
+import {
+  type AdminField,
+  type AdminFieldType,
+  type AdminWidget,
+  fieldTypeFromColumn,
+  filterable,
+  filterKindFor,
+  listable,
+  searchable,
+  sortable,
+  widgetFor,
+} from './fields';
+import type { AdminEntity } from './registry';
+
+export interface AdminFieldOverride {
+  readonly type?: AdminFieldType;
+  readonly widget?: AdminWidget;
+  readonly labelKey?: string;
+  /** Out of every surface: list, detail, form, MCP schema. */
+  readonly hidden?: boolean;
+  readonly inList?: boolean;
+  readonly readOnly?: boolean;
+  readonly required?: boolean;
+  readonly sensitive?: boolean;
+  readonly filterable?: boolean;
+  readonly sortable?: boolean;
+  readonly searchable?: boolean;
+  readonly currency?: string;
+  readonly values?: readonly string[];
+  /** The resource a foreign key points at, when the entity's own `references()` is not it. */
+  readonly relation?: { readonly entity: string };
+  /** i18n key of the hint under the form control, rendered through `t()`. */
+  readonly hintKey?: string;
+  /** The field is a form input on one side only: set at `create`, or editable from `update`. */
+  readonly on?: 'create' | 'update';
+}
+
+export function deriveField(
+  entity: AdminEntity,
+  column: AdminColumnFacts,
+  override: AdminFieldOverride | undefined,
+): AdminField {
+  const name = column.name;
+  const type = override?.type ?? fieldTypeFromColumn(entity.$name, name, column);
+  const widget = override?.widget ?? widgetFor(type);
+  const generated = column.generated || column.primaryKey;
+  // `sensitive` is the ADMIN's word for "keep this out of the list, the form and every audit
+  // diff" (an email, a phone number) and it has no entity source, so it is declared here or it is
+  // absent. A column the entity itself seals (`.sealed()`) never reaches this function at all —
+  // `secretField` below derives it. A currency belongs to the value rather than the column.
+  const sensitive = override?.sensitive ?? false;
+  const currency = override?.currency;
+  const values = override?.values ?? column.values;
+  const relation =
+    override?.relation ??
+    (column.references === undefined ? undefined : { entity: column.references.entity });
+  // The handle scopes every read and write by this column, so the acting actor's tenant is the
+  // only value it can hold: it is not an input, not a list column, and not a filter.
+  const tenant = entity.$tenantColumn === name;
+  const filterKind = tenant ? undefined : filterKindFor(type, column);
+
+  return {
+    entity: entity.$name,
+    name,
+    type,
+    widget,
+    labelKey: override?.labelKey ?? `admin.${entity.$name}.field.${name}`,
+    required: override?.required ?? (!column.nullable && !generated && !tenant),
+    readOnly: override?.readOnly ?? (generated || tenant),
+    sensitive,
+    inList: override?.inList ?? (listable(type) && !sensitive && !tenant),
+    filterable: filterKind !== undefined && (override?.filterable ?? filterable(type, column)),
+    ...(filterKind === undefined ? {} : { filterKind }),
+    sortable: override?.sortable ?? sortable(type, column),
+    // Generated columns are excluded from search: an id is found by exact lookup, and a
+    // `contains` over a uuid column is a scan that returns nothing useful.
+    searchable: override?.searchable ?? (searchable(type, column) && !sensitive && !generated),
+    ...(values === undefined ? {} : { values }),
+    ...(currency === undefined ? {} : { currency }),
+    ...(relation === undefined ? {} : { relation }),
+    ...(override?.hintKey === undefined ? {} : { hintKey: override.hintKey }),
+    ...(override?.on === undefined ? {} : { on: override.on }),
+  };
+}
+
+/**
+ * A sealed column as the form sees it: a password-style input, required only on create, and
+ * nothing else. Every read flag is false by construction, not by an override an app could flip.
+ */
+export function secretField(
+  entity: AdminEntity,
+  column: AdminColumnFacts,
+  override: AdminFieldOverride | undefined,
+): AdminField {
+  return {
+    entity: entity.$name,
+    name: column.name,
+    type: 'secret',
+    widget: 'secret-input',
+    labelKey: override?.labelKey ?? `admin.${entity.$name}.field.${column.name}`,
+    required: !column.nullable,
+    readOnly: false,
+    sensitive: true,
+    inList: false,
+    filterable: false,
+    sortable: false,
+    searchable: false,
+    ...(override?.hintKey === undefined ? {} : { hintKey: override.hintKey }),
+    ...(override?.on === undefined ? {} : { on: override.on }),
+  };
+}