@ultimat3/admin 22.14.0 → 23.0.0

package/src/layout.tsx

@@ -1,11 +1,18 @@
-// The admin shell: skip link, header, permission-filtered nav, main region. Landmarks and a
-// visible focus order are the accessibility contract; the theme attributes come from the
-// token system, so nothing here knows a colour.
+// The admin shell: skip link, sidebar (brand, who is acting, search, permission-filtered nav, the
+// way back to the app), main region. Landmarks and a visible focus order are the accessibility
+// contract; the theme attributes come from the token system, so nothing here knows a colour.
+// Every control is a link or a native form — the shell ships no script.
 
-import { type Locale, registeredLocales, t } from '@ultimat3/i18n';
-import { LocaleSwitcher, ThemeToggle } from '@ultimat3/ui';
+// why: `*.module.scss` is typed by ONE ambient declaration, and it is `@ultimat3/ui`'s. A copy
+// here would be a `.d.ts` in `src/`, which the package-shape gate reads as a build artifact.
+/// <reference path="../../ui/src/scss.d.ts" />
+
+import { t } from '@ultimat3/i18n';
+import { Input } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import type { AdminApp } from './admin';
+import styles from './admin.module.scss';
+import type { AdminActor } from './authz';
 import type { NavGroup } from './nav';
 
 export interface AdminLayoutProps {
@@ -13,26 +20,36 @@ export interface AdminLayoutProps {
   /** Already filtered by `app.navFor(ctx)`. The layout does not decide visibility. */
   readonly nav: readonly NavGroup[];
   readonly currentPath: string;
-  readonly onSearch?: (term: string) => void;
-  readonly onLocaleChange?: (locale: Locale) => void;
+  /** Who is acting. Absent or anonymous reads as "not signed in" — never as an empty line. */
+  readonly actor?: AdminActor | null;
+  /** The screen's heading, already translated. One `<h1>` per screen, and this is it. */
+  readonly title?: string;
   readonly children: JSX.Element;
 }
 
+/** The one rendering of "who am I acting as", so no two screens can disagree about it. */
+export const actorLabel = (actor: AdminActor | null | undefined): string =>
+  actor === null || actor === undefined || actor.id === 'anonymous'
+    ? t('admin.actor.anonymous')
+    : t('admin.actor.signedIn', { id: actor.id, roles: (actor.roles ?? []).join(', ') });
+
 export function AdminLayout(props: AdminLayoutProps): JSX.Element {
   const theme = props.app.theme;
+  const base = props.app.basePath;
   return (
     <div
-      class="x-admin"
+      class={styles['shell']}
+      data-admin=""
       data-theme={theme['data-theme']}
       data-density={theme['data-density']}
       style={theme.style}
     >
-      <a class="x-admin-skip" href="#x-admin-main">
-        {t('admin.a11y.skip-to-content')}
-      </a>
+      <aside class={styles['side']}>
+        <a class={styles['skip']} href="#x-admin-main">
+          {t('admin.a11y.skip-to-content')}
+        </a>
 
-      <header class="x-admin-header">
-        <a class="x-admin-brand" href={props.app.basePath}>
+        <a class={styles['brand']} href={base}>
           {props.app.branding.logo === undefined ? null : (
             <img
               src={props.app.branding.logo.src}
@@ -42,19 +59,16 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           )}
           <span>{t(props.app.branding.nameKey)}</span>
         </a>
+        <p class={styles['actor']}>{actorLabel(props.actor)}</p>
 
-        <search class="x-admin-search">
-          <form
-            onSubmit={(event: SubmitEvent) => {
-              event.preventDefault();
-              const field = (event.currentTarget as HTMLFormElement).elements.namedItem('term');
-              props.onSearch?.(field instanceof HTMLInputElement ? field.value : '');
-            }}
-          >
-            <label class="x-admin-visually-hidden" for="x-admin-search-input">
+        {/* A native GET at the search route: the term rides the URL, so a result page is a link
+            an operator can send and the form needs no handler. */}
+        <search class={styles['search']}>
+          <form method="get" action={`${base}/search`}>
+            <label class={styles['hidden']} for="x-admin-search-input">
               {t('admin.search.label')}
             </label>
-            <input
+            <Input
               id="x-admin-search-input"
               name="term"
               type="search"
@@ -63,27 +77,18 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           </form>
         </search>
 
-        <div class="x-admin-header-tools">
-          {/* The locales with a catalog: an option nobody translated is a broken page. */}
-          <LocaleSwitcher locales={registeredLocales()} onLocaleChange={props.onLocaleChange} />
-          <ThemeToggle />
-        </div>
-      </header>
-
-      <div class="x-admin-body">
-        <nav class="x-admin-nav" aria-label={t('admin.nav.label')}>
+        <nav class={styles['group']} aria-label={t('admin.nav.label')}>
           {props.nav.map((group) => (
-            <section>
-              <h2>{t(group.labelKey)}</h2>
-              <ul>
+            <section class={styles['group']}>
+              <h2 class={styles['groupTitle']}>{t(group.labelKey)}</h2>
+              <ul class={styles['navList']}>
                 {group.items.map((item) => (
                   <li>
                     <a
-                      href={`${props.app.basePath}${item.href}`}
+                      class={styles['navLink']}
+                      href={`${base}${item.href}`}
                       aria-current={
-                        props.currentPath === `${props.app.basePath}${item.href}`
-                          ? 'page'
-                          : undefined
+                        props.currentPath === `${base}${item.href}` ? 'page' : undefined
                       }
                     >
                       {t(item.labelKey)}
@@ -95,10 +100,17 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           ))}
         </nav>
 
-        <main id="x-admin-main" class="x-admin-main" tabindex={-1}>
-          {props.children}
-        </main>
-      </div>
+        {/* The way out. The admin's route table never points back at the app, so without this an
+            operator who opened the dashboard has no link home and edits the URL bar. */}
+        <a class={styles['navLink']} href="/">
+          {t('admin.backToApp')}
+        </a>
+      </aside>
+
+      <main id="x-admin-main" class={styles['main']} tabindex={-1}>
+        {props.title === undefined ? null : <h1 class={styles['title']}>{props.title}</h1>}
+        {props.children}
+      </main>
     </div>
   );
 }

package/src/list-columns.tsx

@@ -0,0 +1,53 @@
+// The columns a resource's table has, wherever it is drawn: its own list page, and the related
+// card on another resource's detail page. One definition — the link that opens the row, the
+// derived list fields, the computed columns — so a related list IS the resource's list and never
+// a second table somebody declared beside it.
+
+import { t } from '@ultimat3/i18n';
+import type { Column } from '@ultimat3/ui';
+import { type AdminRow, computedRow, rowId } from './registry';
+import { ComputedCell } from './renderers';
+import type { AdminResource } from './resource';
+import type { WidgetContext } from './widget-value';
+import { Widget } from './widgets';
+
+export interface ResourceColumnsInput {
+  readonly resource: AdminResource;
+  readonly ctx: WidgetContext;
+  /** The URL of one row's detail page. */
+  readonly hrefOf: (id: string) => string;
+  /** A list field to leave out — the foreign key a related card is already filtered by. */
+  readonly omit?: string;
+}
+
+export function resourceColumns(input: ResourceColumnsInput): readonly Column<AdminRow>[] {
+  const { resource, ctx } = input;
+  const idOf = (row: AdminRow): string => rowId(row, resource.idField);
+  const sealed = resource.secretFields.map((field) => field.name);
+  return [
+    // A real link, not a row click handler: the detail view has to survive a middle-click, a
+    // keyboard, and a crawler that never runs an onClick.
+    {
+      key: 'open',
+      header: t('admin.list.open'),
+      cell: (row) => <a href={input.hrefOf(idOf(row))}>{idOf(row)}</a>,
+    },
+    ...resource.listFields
+      .filter((field) => field.name !== input.omit)
+      .map((field) => ({
+        key: field.name,
+        header: t(field.labelKey),
+        sortable: field.sortable,
+        cell: (row: AdminRow) => (
+          <Widget field={field} value={row[field.name]} ctx={ctx} mode="read" />
+        ),
+      })),
+    ...resource.columns.map((column) => ({
+      key: column.name,
+      header: t(column.labelKey),
+      cell: (row: AdminRow) => (
+        <ComputedCell column={column} row={computedRow(row, sealed)} ctx={ctx} />
+      ),
+    })),
+  ];
+}

package/src/list-filter-bar.tsx

@@ -0,0 +1,207 @@
+// The filter bar: one control per derived filter, in one native GET form. Submitting it IS the
+// navigation — every input is named for the URL parameter it sets (`list-filters.ts`), an empty
+// one is no parameter, and the list's scope and sort ride along hidden. No script, no handler.
+
+import { t } from '@ultimat3/i18n';
+import { Button, Field, type FieldControl, Input, Link, Select } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import styles from './admin.module.scss';
+import type { AdminField, AdminFilterKind } from './fields';
+import { filterParam } from './list-filters';
+import { SCOPE_PARAM, SORT_PARAM } from './list-request';
+import type { AdminListRequest } from './list-scope';
+import type { AdminFilter, FilterOp } from './registry';
+import type { AdminResource } from './resource';
+import type { WidgetContext } from './widget-value';
+import { optionLabel } from './widgets';
+
+export interface AdminFilterBarProps {
+  readonly resource: AdminResource;
+  /** The list as it was asked for: what each control is prefilled from. */
+  readonly request: AdminListRequest;
+  readonly ctx: WidgetContext;
+  /** The bare list URL — the form's `action`, and where Clear goes with the scope kept. */
+  readonly action: string;
+  readonly clearHref: string;
+  /** This page's own URL: where a lookup screen sends the operator back with the id chosen. */
+  readonly returnTo: string;
+}
+
+/** The operators a shape's CONTROLS write. Any other active filter rides the form hidden. */
+const CONTROL_OPS: Readonly<Record<AdminFilterKind, readonly FilterOp[]>> = {
+  text: ['contains'],
+  exact: ['eq'],
+  choice: ['eq'],
+  boolean: ['eq'],
+  range: ['gte', 'lte'],
+  reference: ['eq'],
+};
+
+/** Read through a Map: an unknown shape draws no control rather than a prototype member. */
+const CONTROLS: ReadonlyMap<string, readonly FilterOp[]> = new Map(Object.entries(CONTROL_OPS));
+
+const controlOps = (field: AdminField): readonly FilterOp[] =>
+  field.filterKind === undefined ? [] : (CONTROLS.get(field.filterKind) ?? []);
+
+const written = (value: AdminFilter['value'] | undefined): readonly string[] =>
+  value === undefined || value === null ? [] : typeof value === 'object' ? value : [String(value)];
+
+const wiring = (control: FieldControl): { id: string; 'aria-describedby': string | undefined } => ({
+  id: control.id,
+  'aria-describedby': control['aria-describedby'],
+});
+
+export function AdminFilterBar(props: AdminFilterBarProps): JSX.Element | null {
+  const { resource, request } = props;
+  if (resource.filters.length === 0) return null;
+  const active = request.filters ?? [];
+  const current = (field: AdminField, op: FilterOp): string =>
+    written(active.find((one) => one.field === field.name && one.op === op)?.value)[0] ?? '';
+
+  const any = { value: '', label: t('admin.filter.any') };
+
+  const control = (field: AdminField, own: FieldControl): JSX.Element => {
+    const name = filterParam(field, controlOps(field)[0] ?? 'eq');
+    const value = current(field, controlOps(field)[0] ?? 'eq');
+    switch (field.filterKind) {
+      case 'boolean':
+        return (
+          <Select
+            {...wiring(own)}
+            name={name}
+            value={value}
+            options={[
+              any,
+              { value: 'true', label: t('admin.value.true') },
+              { value: 'false', label: t('admin.value.false') },
+            ]}
+          />
+        );
+      case 'choice':
+        return field.values === undefined ? (
+          <Input {...wiring(own)} name={name} value={value} />
+        ) : (
+          <Select
+            {...wiring(own)}
+            name={name}
+            value={value}
+            // The entity's own values, labelled by the catalog where it has them: no option list
+            // is written in the app.
+            options={[
+              any,
+              ...field.values.map((one) => ({ value: one, label: optionLabel(field, one) })),
+            ]}
+          />
+        );
+      case 'range': {
+        const type =
+          field.type === 'date' ? 'date' : field.type === 'timestamptz' ? 'datetime-local' : 'text';
+        // `datetime-local` shows minutes; the stored filter is the ISO instant it was parsed to.
+        const shown = (op: FilterOp): string =>
+          field.type === 'timestamptz' ? current(field, op).slice(0, 16) : current(field, op);
+        return (
+          <span class={styles['range']}>
+            <Input
+              {...wiring(own)}
+              name={filterParam(field, 'gte')}
+              type={type}
+              inputmode={field.type === 'number' ? 'decimal' : undefined}
+              aria-label={t('admin.filter.from', { field: t(field.labelKey) })}
+              value={shown('gte')}
+            />
+            <Input
+              name={filterParam(field, 'lte')}
+              type={type}
+              inputmode={field.type === 'number' ? 'decimal' : undefined}
+              aria-label={t('admin.filter.to', { field: t(field.labelKey) })}
+              // An instant is typed in UTC and says so beside the box, as the edit form does.
+              suffix={field.type === 'timestamptz' ? 'UTC' : undefined}
+              value={shown('lte')}
+            />
+          </span>
+        );
+      }
+      case 'reference': {
+        const entity = field.relation?.entity ?? '';
+        const options = props.ctx.optionsFor?.(entity) ?? null;
+        if (options !== null) {
+          return (
+            <Select
+              {...wiring(own)}
+              name={name}
+              value={value}
+              options={[any, ...options.map((one) => ({ value: one.id, label: one.label }))]}
+            />
+          );
+        }
+        // Too many rows for a select: the id is typed, or found on the target's lookup screen,
+        // which links back here with this parameter set.
+        const lookup = props.ctx.lookupHref?.(entity) ?? null;
+        const find =
+          lookup === null
+            ? null
+            : `${lookup}?${new URLSearchParams({ return: props.returnTo, as: name }).toString()}`;
+        return (
+          <span class={styles['range']}>
+            <Input {...wiring(own)} name={name} value={value} />
+            {find === null ? null : <a href={find}>{t('admin.filter.find')}</a>}
+          </span>
+        );
+      }
+      default:
+        return (
+          <Input
+            {...wiring(own)}
+            name={name}
+            type={field.filterKind === 'text' ? 'search' : 'text'}
+            value={value}
+          />
+        );
+    }
+  };
+
+  // A filter the URL carries that no control above writes (`f.status.in`, `f.stock.gt`): kept, so
+  // submitting the form narrows the list the operator is looking at instead of widening it.
+  const carried = active.filter((one) => {
+    const field = resource.filters.find((known) => known.name === one.field);
+    return field !== undefined && !controlOps(field).includes(one.op);
+  });
+
+  return (
+    <search>
+      <form class={styles['filters']} method="get" action={props.action}>
+        {request.scope === undefined || request.scope === null ? null : (
+          <input type="hidden" name={SCOPE_PARAM} value={request.scope} />
+        )}
+        {request.sort === undefined ? null : (
+          <input
+            type="hidden"
+            name={SORT_PARAM}
+            value={`${request.sort.field}:${request.sort.direction}`}
+          />
+        )}
+        {carried.flatMap((one) => {
+          const field = resource.filters.find((known) => known.name === one.field);
+          return field === undefined
+            ? []
+            : written(one.value).map((value) => (
+                <input type="hidden" name={filterParam(field, one.op)} value={value} />
+              ));
+        })}
+        {resource.filters.map((field) => (
+          <Field label={t(field.labelKey)}>{(own) => control(field, own)}</Field>
+        ))}
+        <div class={styles['actions']}>
+          <Button type="submit" variant="secondary">
+            {t('admin.filter.apply')}
+          </Button>
+          {active.length === 0 ? null : (
+            <Link appearance="button" variant="ghost" tone="neutral" href={props.clearHref}>
+              {t('admin.filter.clear')}
+            </Link>
+          )}
+        </div>
+      </form>
+    </search>
+  );
+}

package/src/list-filters.ts

@@ -0,0 +1,217 @@
+// What a resource's filters ARE. Per filter shape: the operators a caller may name and the
+// control the filter bar draws. One validator — the URL parser, the MCP list tool and a `scopes:`
+// or `rows:` declaration all pass through it — so a predicate the admin sends a repo is one the
+// resource derived, on a column that is not sealed, with a value of the column's own type.
+
+import { adminColumnsOf, adminSealedColumnsOf } from './entity-columns';
+import { AdminFilterInvalidError } from './errors';
+import type { AdminField, AdminFilterKind } from './fields';
+import { type AdminFilter, FILTER_OPS, type FilterOp } from './registry';
+import type { AdminResource } from './resource';
+
+/** The URL prefix of a filter parameter: `f.<field>` or `f.<field>.<op>`. */
+export const FILTER_PREFIX = 'f.';
+
+/** Per shape, the operators it answers. The FIRST is what a bare `f.<field>=` means. */
+const OPS_BY_KIND: Readonly<Record<AdminFilterKind, readonly FilterOp[]>> = {
+  text: ['contains', 'eq', 'neq', 'is-null'],
+  exact: ['eq', 'neq', 'in', 'is-null'],
+  choice: ['eq', 'neq', 'in', 'is-null'],
+  boolean: ['eq'],
+  range: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'is-null'],
+  reference: ['eq', 'neq', 'in', 'is-null'],
+};
+
+/** The same table as a Map: a shape that is not one of the six has no operators, not a prototype's. */
+const OPS: ReadonlyMap<string, readonly FilterOp[]> = new Map(Object.entries(OPS_BY_KIND));
+
+/** The operators one field's filter answers; empty for a field with no filter shape. */
+export function filterOpsOf(field: AdminField): readonly FilterOp[] {
+  return field.filterKind === undefined ? [] : (OPS.get(field.filterKind) ?? []);
+}
+
+/** The parameter one filter is spelled as: the default operator is left off. */
+export function filterParam(field: AdminField, op: FilterOp): string {
+  return op === filterOpsOf(field)[0]
+    ? `${FILTER_PREFIX}${field.name}`
+    : `${FILTER_PREFIX}${field.name}.${op}`;
+}
+
+/** Every parameter spelling a resource answers — what a refusal names. */
+export function knownFilterParams(resource: AdminResource): readonly string[] {
+  return resource.filters.map((field) => `${FILTER_PREFIX}${field.name}`);
+}
+
+const isOp = (value: string): value is FilterOp =>
+  (FILTER_OPS as readonly string[]).includes(value);
+
+/** A value for a cause line: what was typed when it is text, its type when it is not. */
+const shown = (value: unknown): string =>
+  typeof value === 'string' ? `"${value}"` : `a ${value === null ? 'null' : typeof value}`;
+
+const TRUTH: ReadonlyMap<unknown, boolean> = new Map<unknown, boolean>([
+  ['true', true],
+  ['false', false],
+  [true, true],
+  [false, false],
+]);
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const LOCAL_MINUTE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
+/** An instant names its offset. A bare local time has no zone, and the admin never invents one. */
+const ZONED = /(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * A typed instant → the ISO string a driver compares. `datetime-local` posts `YYYY-MM-DDTHH:mm`
+ * and the control says UTC beside the box — the same contract the edit form states — and a bare
+ * date is that day's first instant in UTC.
+ */
+const instantOf = (raw: string): string | undefined => {
+  const text = DATE.test(raw)
+    ? `${raw}T00:00:00.000Z`
+    : LOCAL_MINUTE.test(raw)
+      ? `${raw}:00.000Z`
+      : raw;
+  if (!ZONED.test(text)) return undefined;
+  const at = new Date(text);
+  return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+};
+
+interface Refusal {
+  readonly cause: string;
+}
+
+type Scalar = string | number | boolean;
+
+/** One value, as the column's own type — or why it is not one. */
+function scalarOf(field: AdminField, raw: unknown): Scalar | Refusal {
+  switch (field.filterKind) {
+    case 'boolean': {
+      const truth = TRUTH.get(raw);
+      return truth ?? { cause: `takes true or false, got ${shown(raw)}` };
+    }
+    case 'range': {
+      if (field.type === 'number') {
+        const parsed = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : NaN;
+        return raw !== '' && Number.isFinite(parsed)
+          ? parsed
+          : { cause: `takes a number, got ${shown(raw)}` };
+      }
+      if (typeof raw !== 'string') return { cause: `takes a date as text, got ${shown(raw)}` };
+      if (field.type === 'date') {
+        return DATE.test(raw) ? raw : { cause: `takes a YYYY-MM-DD date, got ${shown(raw)}` };
+      }
+      return (
+        instantOf(raw) ?? {
+          cause: `takes a UTC instant (YYYY-MM-DDTHH:mm, or ISO-8601 with an offset), got ${shown(raw)}`,
+        }
+      );
+    }
+    case 'choice': {
+      if (typeof raw !== 'string') return { cause: `takes one of its values, got ${shown(raw)}` };
+      // An enum names its values; a locale or a zone column has no list to hold one against.
+      if (field.values !== undefined && !field.values.includes(raw)) {
+        return { cause: `takes one of ${field.values.join(', ')} — got ${shown(raw)}` };
+      }
+      return raw;
+    }
+    default:
+      if (typeof raw === 'string') return raw;
+      return typeof raw === 'number' && Number.isFinite(raw)
+        ? String(raw)
+        : { cause: `takes text, got ${shown(raw)}` };
+  }
+}
+
+const isRefusal = (value: unknown): value is Refusal =>
+  typeof value === 'object' && value !== null && 'cause' in value;
+
+const filterValueOf = (
+  field: AdminField,
+  op: FilterOp,
+  raw: unknown,
+): AdminFilter['value'] | Refusal => {
+  if (op === 'in') {
+    const list: readonly unknown[] = Array.isArray(raw) ? raw : [raw];
+    const out: string[] = [];
+    for (const one of list) {
+      const scalar = scalarOf(field, one);
+      if (isRefusal(scalar)) return scalar;
+      out.push(String(scalar));
+    }
+    return out;
+  }
+  // A scalar operator given a repeated parameter reads the LAST one, as a form field does.
+  const last: unknown = Array.isArray(raw) ? raw[raw.length - 1] : raw;
+  if (op === 'is-null') {
+    return TRUTH.get(last) ?? { cause: `takes true or false, got ${shown(last)}` };
+  }
+  return scalarOf(field, last);
+};
+
+export interface AskedFilter {
+  readonly field: string;
+  /** Absent is the field's default operator — `contains` for text, `eq` for everything else. */
+  readonly op?: string;
+  readonly value: unknown;
+}
+
+/**
+ * One filter a CALLER asked for — a URL parameter, an MCP argument — checked against what the
+ * resource derives. Refused by name: the field when it is not a filter, the operator when the
+ * field's shape has no meaning for it, the value when it is not the column's type.
+ */
+export function checkedFilter(resource: AdminResource, asked: AskedFilter): AdminFilter {
+  const spelled = `${FILTER_PREFIX}${asked.field}${asked.op === undefined ? '' : `.${asked.op}`}`;
+  const refuse = (cause: string, known: readonly string[]): never => {
+    throw new AdminFilterInvalidError({ entity: resource.name, asked: spelled, cause, known });
+  };
+  const field = resource.filters.find((known) => known.name === asked.field);
+  if (field === undefined) {
+    return refuse('is not a filter of this resource', knownFilterParams(resource));
+  }
+  const ops = filterOpsOf(field);
+  const op = asked.op ?? ops[0];
+  if (op === undefined || !isOp(op) || !ops.includes(op)) {
+    return refuse(
+      `names an operator "${field.name}" does not answer`,
+      ops.map((known) => filterParam(field, known)),
+    );
+  }
+  const value = filterValueOf(field, op, asked.value);
+  if (isRefusal(value)) return refuse(value.cause, [filterParam(field, op)]);
+  return { field: field.name, op, value };
+}
+
+/**
+ * Predicates the APP declared — a scope's `where`, a resource's `rows` — held to a narrower rule
+ * than a caller's: any column of the entity may be named (the app knows which of its columns are
+ * indexed), but never one that is not a column and never a sealed one, whose ciphertext no
+ * predicate can be written against.
+ */
+export function declaredFilters(
+  resource: Pick<AdminResource, 'name' | 'entity'>,
+  where: readonly AdminFilter[],
+  declaredAs: string,
+): readonly AdminFilter[] {
+  // Through the one flattener: it is the only reader of a column's declaration, and its two lists
+  // are exactly the two answers this needs — what may be named, and what is sealed.
+  const open = adminColumnsOf(resource.entity).map((column) => column.name);
+  const sealed = adminSealedColumnsOf(resource.entity).map((column) => column.name);
+  for (const filter of where) {
+    const refuse = (cause: string, known: readonly string[]): never => {
+      throw new AdminFilterInvalidError({
+        entity: resource.name,
+        asked: `${declaredAs}: ${filter.field} ${filter.op}`,
+        cause,
+        known,
+      });
+    };
+    if (sealed.includes(filter.field)) {
+      refuse('names a sealed column, which no predicate can read', open);
+    }
+    if (!open.includes(filter.field)) refuse('names a field that is not a column', open);
+    if (!isOp(filter.op)) refuse('names an operator the admin does not have', FILTER_OPS);
+  }
+  return where;
+}