@ultimat3/admin 22.14.0 → 23.0.0

package/src/resource.ts

@@ -4,25 +4,33 @@
 // field, but the zero-config result is the one the generator emits and the one the docs show.
 
 import { finiteCount } from '@ultimat3/core';
-import { type AdminColumnFacts, adminColumnsOf } from './entity-columns';
+import { type AdminColumnFacts, adminColumnsOf, adminSealedColumnsOf } from './entity-columns';
 import {
   AdminEntityUnknownError,
   AdminFieldUnsupportedError,
   AdminPolicyMissingError,
+  AdminRepoUnboundError,
 } from './errors';
-import {
-  type AdminField,
-  type AdminFieldType,
-  type AdminWidget,
-  fieldTypeFromColumn,
-  filterable,
-  listable,
-  searchable,
-  sortable,
-  widgetFor,
-} from './fields';
+import type { AdminField } from './fields';
 import { ADMIN_OPERATIONS, type AdminOperation } from './permissions';
 import type { AdminAction, AdminEntity, AdminRepo, AdminRow, AdminSort } from './registry';
+import { type AdminFieldOverride, deriveField, secretField } from './resource-fields';
+import {
+  type AdminFormGroupOptions,
+  type AdminSection,
+  type AdminSectionOptions,
+  layoutOf,
+} from './resource-layout';
+import {
+  type AdminComputedColumn,
+  type AdminComputedColumnOptions,
+  type AdminRowScope,
+  type AdminScope,
+  type AdminScopeOptions,
+  computedColumnsOf,
+  rowScopeOf,
+  scopesOf,
+} from './resource-list';
 
 /** Six columns is what fits a laptop viewport without horizontal scroll. */
 const MAX_LIST_FIELDS = 6;
@@ -30,27 +38,15 @@ const DEFAULT_PAGE_SIZE = 25;
 const LABEL_CANDIDATES = ['name', 'title', 'slug', 'label', 'email'] as const;
 const SORT_CANDIDATES = ['createdAt', 'created_at', 'updatedAt', 'updated_at'] as const;
 
-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[];
-  readonly relation?: { readonly entity: string; readonly labelField?: string };
-}
-
 export interface AdminResourceOptions<Row extends AdminRow = AdminRow> {
   readonly repo?: AdminRepo<Row>;
   readonly path?: string;
+  /**
+   * The noun this resource's permissions are named after — `<permission>:read|write|delete`.
+   * Default: the entity's name. Several resources that are one subject to an operator share one
+   * (the jobs screens are all `job:read`), so a role map grants a subject once, not per table.
+   */
+  readonly permission?: string;
   readonly titleKey?: string;
   readonly group?: string;
   /**
@@ -62,6 +58,35 @@ export interface AdminResourceOptions<Row extends AdminRow = AdminRow> {
   readonly fields?: Readonly<Record<string, AdminFieldOverride>>;
   /** Explicit list columns, in order. Omit to let the derivation pick. */
   readonly listFields?: readonly string[];
+  /**
+   * Computed list columns, drawn after `listFields` in declaration order:
+   * `age: { value: (row) => row.createdAt, render: 'relative-time' }`. `render` is one of the six
+   * built-in renderers or a component. A name that is also an entity column is refused.
+   */
+  readonly columns?: Readonly<Record<string, AdminComputedColumnOptions<Row>>>;
+  /**
+   * Named predicates, drawn as tabs: `open: { where: [...] }`, `mine: { where: (actor) => [...] }`.
+   * At most one `default: true`; `count: true` is one extra query per tab that asks for it.
+   */
+  readonly scopes?: Readonly<Record<string, AdminScopeOptions>>;
+  /**
+   * The rows this ACTOR may see at all. Applied to every read of the resource — list, search,
+   * detail, lookup, labels, MCP — so it is the one place a second audience is declared.
+   */
+  readonly rows?: AdminRowScope;
+  /**
+   * The detail page, as titled groups of fields. A field named in none falls into a default
+   * section drawn last, so a column added to the entity is never hidden by this list.
+   */
+  readonly sections?: readonly AdminSectionOptions[];
+  /** The same arrangement for the create and edit form. Independent of `sections`. */
+  readonly formGroups?: readonly AdminFormGroupOptions[];
+  /**
+   * `hasMany` relations of the entity, by name — `['comments']` — drawn on the detail page as the
+   * RELATED resource's own list (its columns, its row scope, its policy) filtered to this row.
+   * The names are `@ultimat3/entity`'s: the one a preload names.
+   */
+  readonly related?: readonly string[];
   readonly defaultSort?: AdminSort;
   readonly pageSize?: number;
   readonly operations?: readonly AdminOperation[];
@@ -81,6 +106,8 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
    * the framework can own (axiom 8) — `path:` is how an app spells its own.
    */
   readonly path: string;
+  /** The permission noun — `<permission>:read` lists it. The entity's name unless declared. */
+  readonly permission: string;
   readonly titleKey: string;
   readonly group: string;
   readonly idField: string;
@@ -90,8 +117,31 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
   readonly fields: readonly AdminField[];
   readonly listFields: readonly AdminField[];
   readonly formFields: readonly AdminField[];
+  /**
+   * The entity's `.sealed()` columns, as WRITE-ONLY inputs: a form posts them, nothing reads them.
+   * Deliberately a list of its own and in none of the others — `fields`, `listFields`,
+   * `formFields`, `filters` and `searchFields` are all read back by column name somewhere, and a
+   * sealed property answers that read with its plaintext.
+   */
+  readonly secretFields: readonly AdminField[];
+  /**
+   * The label field first — a list's search box is its `contains` filter — then every field the
+   * derivation offers. What a URL's `f.<field>` may name, and nothing else.
+   */
   readonly filters: readonly AdminField[];
   readonly searchFields: readonly AdminField[];
+  /** Computed list columns, in declaration order. */
+  readonly columns: readonly AdminComputedColumn[];
+  /** Declared scopes, in tab order. Empty for a resource that declares none. */
+  readonly scopes: readonly AdminScope[];
+  /** `rows`, validated per call. Absent for a resource every permitted actor sees whole. */
+  readonly rowScope?: AdminRowScope;
+  /** The detail page's groups. Always at least one: undeclared fields have a default section. */
+  readonly sections: readonly AdminSection[];
+  /** The form's groups, over `formFields` and `secretFields` both. */
+  readonly formGroups: readonly AdminSection[];
+  /** Declared `related` relation names, in order. `related.ts` resolves each against the admin. */
+  readonly related: readonly string[];
   readonly defaultSort: AdminSort;
   readonly pageSize: number;
   readonly operations: readonly AdminOperation[];
@@ -100,48 +150,6 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
   field(name: string): AdminField;
 }
 
-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;
-  // An entity has no notion of a secret column, and a currency belongs to the value rather
-  // than the column, so both are admin-side declarations or they are absent. Never guessed.
-  const sensitive = override?.sensitive ?? false;
-  const currency = override?.currency;
-  const values = override?.values ?? column.values;
-  const relation =
-    override?.relation ??
-    // The FK's value IS the target column's value, so that column is the honest default label.
-    (column.references === undefined
-      ? undefined
-      : { entity: column.references.entity, labelField: column.references.column });
-
-  return {
-    entity: entity.$name,
-    name,
-    type,
-    widget,
-    labelKey: override?.labelKey ?? `admin.${entity.$name}.field.${name}`,
-    required: override?.required ?? (!column.nullable && !generated),
-    readOnly: override?.readOnly ?? generated,
-    sensitive,
-    inList: override?.inList ?? (listable(type) && !sensitive),
-    filterable: override?.filterable ?? filterable(type, column),
-    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 }),
-  };
-}
-
 /**
  * The declared key wins — but a composite one is refused outright, never silently reduced to
  * its first member: a route id and an `AdminRepo` id both carry exactly one string, so two rows
@@ -230,6 +238,18 @@ function pickListFields(
   return [...label, ...rest].slice(0, MAX_LIST_FIELDS);
 }
 
+/**
+ * The label first, whether or not it is indexed: a list's search box IS the label's `contains`
+ * filter, and a list an operator cannot search by name is the one they leave for a SQL console.
+ * Only a text label qualifies — a `contains` over a uuid is a database error, not an empty result.
+ */
+function filtersOf(fields: readonly AdminField[], labelField: string): readonly AdminField[] {
+  const label = fields.filter(
+    (field) => field.name === labelField && field.filterKind === 'text' && !field.sensitive,
+  );
+  return [...label, ...fields.filter((field) => field.filterable && !label.includes(field))];
+}
+
 function assertActionsHavePolicies(actions: readonly AdminAction[]): void {
   for (const action of actions) {
     // Widened because the registry is JSON at the boundary: a hand-written action object
@@ -264,10 +284,18 @@ export function adminResource<Row extends AdminRow = AdminRow>(
   const labelField = labelFieldOf(entity, fields, idField, opts.labelField);
   const actions = opts.actions ?? [];
   assertActionsHavePolicies(actions);
+  const declared = { name: entity.$name, entity };
+  const rowScope = rowScopeOf(declared, opts.rows);
+
+  const formFields = fields.filter((field) => !field.readOnly && !field.sensitive);
+  const secretFields = adminSealedColumnsOf(entity)
+    .filter((column) => overrides[column.name]?.hidden !== true)
+    .map((column) => secretField(entity, column, overrides[column.name]));
 
   const resource: AdminResource<Row> = {
     name: entity.$name,
     path: opts.path ?? `/${entity.$name}`,
+    permission: opts.permission ?? entity.$name,
     titleKey: opts.titleKey ?? `admin.${entity.$name}.title`,
     group: opts.group ?? 'admin.group.data',
     idField,
@@ -275,9 +303,35 @@ export function adminResource<Row extends AdminRow = AdminRow>(
     entity,
     fields,
     listFields: pickListFields(fields, labelField, opts.listFields, entity.$name),
-    formFields: fields.filter((field) => !field.readOnly && !field.sensitive),
-    filters: fields.filter((field) => field.filterable),
+    formFields,
+    secretFields,
+    filters: filtersOf(fields, labelField),
     searchFields: fields.filter((field) => field.searchable),
+    columns: computedColumnsOf(declared, opts.columns),
+    scopes: scopesOf(declared, opts.scopes, opts.repo),
+    ...(rowScope === undefined ? {} : { rowScope }),
+    sections: layoutOf(
+      {
+        entity: entity.$name,
+        option: 'sections',
+        // What the detail page draws: every field but a `sensitive` one. A sealed column is in no
+        // list a reader iterates, so it cannot be named here either.
+        fields: fields.filter((field) => !field.sensitive),
+        excluded:
+          'is not a field the detail page draws (hidden, sensitive, sealed, or not a column)',
+      },
+      opts.sections,
+    ),
+    formGroups: layoutOf(
+      {
+        entity: entity.$name,
+        option: 'formGroups',
+        fields: [...formFields, ...secretFields],
+        excluded: 'is not a form input (read-only, generated, sensitive, hidden, or not a column)',
+      },
+      opts.formGroups,
+    ),
+    related: opts.related ?? [],
     defaultSort: opts.defaultSort ?? defaultSortOf(fields, idField),
     // Refused here rather than at the first listing, because `pagination.ts` clamps with
     // `Math.max(1, Math.min(x, 200))` and neither of those validates: a `NaN` survives both, so
@@ -306,11 +360,7 @@ export function adminResource<Row extends AdminRow = AdminRow>(
 /** The bound repo, or the one error that says which resource forgot it. */
 export function repoOf<Row extends AdminRow>(resource: AdminResource<Row>): AdminRepo<Row> {
   if (resource.repo === undefined) {
-    throw new AdminEntityUnknownError({
-      entity: resource.name,
-      known: [],
-      cause: `resource "${resource.name}" has no repo bound, so the admin cannot read or write rows`,
-    });
+    throw new AdminRepoUnboundError({ entity: resource.name, handles: [] });
   }
   return resource.repo;
 }

package/src/route-config.ts

@@ -0,0 +1,71 @@
+// The one bridge from the admin's route table to @ultimat3/render's: the `defineRoute` config
+// every admin route is served under, and the declaration that puts those routes in the framework's
+// one route list. No screen is reached from here, so `defineAdmin()` can declare its routes
+// without loading a view — `routes.ts` binds each route to its screen.
+
+import { t } from '@ultimat3/i18n';
+import {
+  defineRoute,
+  type RouteConfig,
+  type RouteGuard,
+  registerMountedRoutes,
+} from '@ultimat3/render';
+import type { AdminRoute } from './admin';
+import { AdminPageUnguardedError } from './errors';
+
+/** What `RouteDescriptor.file` reads for an admin route: the package, since no app file is one. */
+export const ADMIN_ROUTE_FILE = '@ultimat3/admin';
+
+export interface AdminRouteDefinition {
+  /** The coarse gate — the SAME object `config.policy` carries. */
+  readonly policy: RouteGuard;
+  readonly config: RouteConfig;
+}
+
+/**
+ * The author never writes this `defineRoute` call, so the author cannot omit its `policy` —
+ * which is the whole mechanism. The coarse gate is `permissions[0]` (always `admin:read`, put
+ * there by `permissionsForOperation`/`pagePermissions`); the rest of the pair is decided per
+ * request, in `crud.ts` for a resource screen and in `guardedScreen()` for every other one.
+ * An empty list is refused here too: `render: 'ssr'` with no policy is a public dashboard.
+ */
+export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
+  const permission = route.permissions[0];
+  if (permission === undefined) throw new AdminPageUnguardedError({ path: route.path });
+  const policy: RouteGuard = { permission };
+  return {
+    policy,
+    config: defineRoute({
+      // One mode for every admin route, never an author's choice. `ssr` renders the rows behind
+      // the guard, once per request, and `hydrate: 'never'` means the screen ships no JS at all:
+      // every control on an admin screen is a link or a native form, so there is nothing to
+      // hydrate. `never` is a REFUSAL and not just a default — an `island()` rendered on this
+      // route throws `X_ISLAND_NOT_HYDRATED` (`@ultimat3/render`'s `island-collector.ts`), and no
+      // admin module declares one.
+      render: 'ssr',
+      offline: 'network-only',
+      hydrate: 'never',
+      policy,
+      // Never indexed and never followed, whatever the screen answers — a list, a refusal, a 404:
+      // an admin URL in a search result is a row id handed to a crawler.
+      meta: () => ({ title: t(route.titleKey), robots: { index: false, follow: false } }),
+    }),
+  };
+}
+
+/**
+ * Declare an admin's routes to the framework's route table — as MOUNTED routes, each with every
+ * permission that gates it — so `x routes`, the `/_x` routes panel, the manifest and `sw.js` list
+ * them from the one projection everything else is listed from. Keyed by base path: re-declaring
+ * the admin (a save under `x dev`) replaces its set.
+ */
+export function mountAdminRoutes(basePath: string, routes: readonly AdminRoute[]): void {
+  registerMountedRoutes(
+    { key: basePath, by: 'defineAdmin', file: ADMIN_ROUTE_FILE, surface: 'app' },
+    routes.map((route) => ({
+      path: route.path,
+      config: adminRouteDefinition(route).config,
+      permissions: route.permissions,
+    })),
+  );
+}

package/src/routes.ts

@@ -1,83 +1,56 @@
-// The one bridge from the admin's route table to @ultimat3/render, and the one place a policy
-// is composed onto an admin page. Every admin route is `ssr`: it is behind auth, so its guard runs
-// on the server, there is nothing to prerender and nothing a CDN may hold — and `network-only`
-// keeps a stale org's rows out of a service worker cache.
+// The one place a route gets its SCREEN, and the matcher a host asks per request. The config a
+// route is served under — `ssr`, gated, `network-only` — is `route-config.ts`'s; this file binds
+// it to what renders there.
 
-import { t } from '@ultimat3/i18n';
-import { defineRoute, type RouteGuard } from '@ultimat3/render';
+import { compilePattern, type RouteConfig, type RouteGuard } from '@ultimat3/render';
 import type { AdminApp, AdminRoute } from './admin';
-import { AdminPagePathInvalidError, AdminPageUnguardedError } from './errors';
-import { guardedPage } from './page-guard';
-import type { AdminPageComponent } from './pages';
+import { AdminPagePathInvalidError } from './errors';
+import { adminRouteDefinition } from './route-config';
+import type { AdminRouteRequest, AdminRouteResponse } from './screen-frame';
+import { screenFor } from './screens';
 
 export interface AdminRouteConfig {
   readonly path: string;
   readonly view: AdminRoute['view'];
   readonly entity: string | null;
   readonly permissions: readonly string[];
-  /** The GUARDED component of a custom page; `null` for a generated view. */
-  readonly component: AdminPageComponent | null;
   /**
    * The coarse gate, already composed — the SAME object `config.policy` carries. It is here, and
-   * not read back off `config`, because `RouteConfig.policy` is optional: a host that serves an
-   * admin URL from its own file has to be able to take the gate without proving it exists.
+   * not read back off `config`, because `RouteConfig.policy` is optional.
    */
   readonly policy: RouteGuard;
-  readonly config: ReturnType<typeof defineRoute>;
+  readonly config: RouteConfig;
+  /**
+   * Answer one request to this route — a GET, or the form the screen posted back at itself — as
+   * a status and a framed body, or the redirect a write that worked earns. Never absent: a
+   * generated view renders its rows and a custom page is wrapped, so no route of the table is a
+   * path with nothing behind it. The screen decides before it renders; a host only serialises.
+   */
+  respond(request: AdminRouteRequest): Promise<AdminRouteResponse>;
 }
 
-/**
- * The author never writes this `defineRoute` call, so the author cannot omit its `policy` —
- * which is the whole mechanism. The coarse gate is `permissions[0]` (always `admin:read`, put
- * there by `permissionsForOperation`/`pagePermissions`); the rest of the pair is decided per
- * request by `decideAll`, in `crud.ts` for a generated view and in `page-guard.tsx` for a page.
- * An empty list is refused here too: `render: 'ssr'` with no policy is a public dashboard.
- */
-export function adminRouteConfig(route: AdminRoute): AdminRouteConfig {
-  const permission = route.permissions[0];
-  if (permission === undefined) throw new AdminPageUnguardedError({ path: route.path });
-  const policy: RouteGuard = { permission };
-
+/** One route of the table, with its gate, its served config and its screen. */
+export function adminRouteConfig(app: AdminApp, route: AdminRoute): AdminRouteConfig {
+  const { policy, config } = adminRouteDefinition(route);
   return {
     path: route.path,
     view: route.view,
     entity: route.entity,
     permissions: route.permissions,
-    component: route.component === undefined ? null : guardedPage(route, route.component),
+    respond: screenFor(app, route),
     policy,
-    config: defineRoute({
-      // One mode for every admin route, never an author's choice. A generated view was `spa` — a
-      // shell the browser was supposed to fill — until `spa` was deleted: nothing ever built the
-      // client bundle it preloaded and `renderSpa` never read the route's component, so every
-      // generated view served an empty `<div id="x-root">`. `ssr` renders the same rows behind the
-      // same guard, once per request, and `hydrate: 'never'` means the screen ships no JS at all:
-      // an admin view is a pure function of its props (no `createSignal`, no local state), so
-      // there is nothing to hydrate. `never` is a REFUSAL and not just a default — an `island()`
-      // rendered on this route throws `X_ISLAND_NOT_HYDRATED` (`@ultimat3/render`'s
-      // `island-collector.ts`), and no admin module declares one.
-      render: 'ssr',
-      offline: 'network-only',
-      hydrate: 'never',
-      policy,
-      meta: () => ({ title: t(route.titleKey) }),
-    }),
+    config,
   };
 }
 
-/** Hand these to the router. Auth stays the host app's: see `AdminApp.auth`. */
+/** Every route of the table, each with its screen. Auth stays the host app's: see `AdminApp.auth`. */
 export function adminRoutes(app: AdminApp): readonly AdminRouteConfig[] {
-  return app.routes.map(adminRouteConfig);
+  return app.routes.map((route) => adminRouteConfig(app, route));
 }
 
 /**
- * The one route the admin declares for `path` — the lookup a host performs when it serves an admin
- * URL from its own file rather than from `adminRoutes()`.
- *
- * It exists because the alternative is what the deployed demo shipped: a page file typing
- * `policy: { permission: 'admin:read' }` beside a route table that separately declared
- * `permissionsForOperation(...)` for the same URL. Two declarations of one URL's authz agree until
- * one of them is edited, and nothing was ever going to notice. Reading the gate from here means
- * there is one declaration and one reader.
+ * The one route the admin declares for `path` — a read of the table, for a caller that wants a
+ * route's gate or its screen without matching a URL.
  *
  * A path the table does not declare is refused rather than answered with a default: a mount with
  * no route is a screen whose permissions nothing composed, which is exactly the shape `pages:`
@@ -95,5 +68,33 @@ export function adminRouteFor(app: AdminApp, path: string): AdminRouteConfig {
         'or declare this one in `pages:` on defineAdmin()',
     });
   }
-  return adminRouteConfig(route);
+  return adminRouteConfig(app, route);
+}
+
+export interface AdminRouteMatch {
+  readonly route: AdminRouteConfig;
+  readonly params: Readonly<Record<string, string>>;
+}
+
+/**
+ * The route a REQUEST's pathname names, with its params — what a host mounting the admin under
+ * one catch-all asks per request. `null` is "no admin screen lives there", which the host answers
+ * 404. The most specific pattern wins, so `/posts/new` is the create form and never the detail
+ * of a row called `new`. Matched against the table as it is NOW, so a page added in a save is
+ * served without the host re-reading anything.
+ */
+export function adminRouteMatch(app: AdminApp, pathname: string): AdminRouteMatch | null {
+  let best: { route: AdminRoute; params: Record<string, string>; specificity: number } | null =
+    null;
+  for (const route of app.routes) {
+    const pattern = compilePattern(route.path);
+    const found = pattern.regex.exec(pathname);
+    if (found === null || (best !== null && best.specificity >= pattern.specificity)) continue;
+    const params: Record<string, string> = {};
+    pattern.keys.forEach((key, index) => {
+      params[key] = decodeURIComponent(found[index + 1] ?? '');
+    });
+    best = { route, params, specificity: pattern.specificity };
+  }
+  return best === null ? null : { route: adminRouteConfig(app, best.route), params: best.params };
 }

package/src/row-scope-write.ts

@@ -0,0 +1,130 @@
+// `rows`, applied to a WRITE: the row a create or an update would leave behind must satisfy the
+// acting actor's row scope, or the write is refused before the repo is asked for it. The one place
+// this package evaluates a predicate itself — a row that does not exist yet cannot be asked of the
+// repo, which is how every READ answers the same question (`list-scope.ts`, `findRow`).
+
+import type { AdminActor, AdminDecision } from './authz';
+import type { AdminFilter, AdminRow } from './registry';
+import type { AdminResource } from './resource';
+
+/** The key a write whose result would sit outside the actor's row scope is refused with. */
+export const ROW_OUT_OF_SCOPE_REASON = 'admin.error.row-out-of-scope';
+
+export interface OutsideRowScope {
+  readonly field: string;
+  readonly op: AdminFilter['op'];
+  /**
+   * `false` when the predicate could not be decided exactly here — an ordering over text is a
+   * collation's to answer — and the write is refused for that reason rather than for a mismatch.
+   */
+  readonly decidable: boolean;
+}
+
+const absent = (value: unknown): boolean => value === null || value === undefined;
+
+/** An instant as milliseconds, whichever of the two shapes it travels in; `undefined` otherwise. */
+const instantOf = (value: unknown): number | undefined => {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T/.test(value)) return undefined;
+  const at = Date.parse(value);
+  return Number.isNaN(at) ? undefined : at;
+};
+
+/** Equal as the column's value: a `Date` against the ISO text a filter carries is one instant. */
+const equal = (held: unknown, wanted: unknown): boolean => {
+  if (held instanceof Date || wanted instanceof Date) {
+    const a = instantOf(held);
+    return a !== undefined && a === instantOf(wanted);
+  }
+  return typeof held === 'object' ? false : String(held) === String(wanted);
+};
+
+/** `-1 | 0 | 1` for two numbers or two instants; `undefined` for anything a collation orders. */
+const ordered = (held: unknown, wanted: unknown): number | undefined => {
+  const pair =
+    typeof held === 'number' && typeof wanted === 'number'
+      ? ([held, wanted] as const)
+      : held instanceof Date
+        ? ([instantOf(held), instantOf(wanted)] as const)
+        : undefined;
+  const [a, b] = pair ?? [];
+  if (a === undefined || b === undefined || Number.isNaN(a) || Number.isNaN(b)) return undefined;
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+
+/** `true` in scope, `false` out of it, `undefined` when this file cannot say. */
+function satisfies(row: AdminRow, filter: AdminFilter): boolean | undefined {
+  const held = Object.hasOwn(row, filter.field) ? row[filter.field] : undefined;
+  if (filter.op === 'is-null') return absent(held) === (filter.value !== false);
+  // SQL's three-valued logic: a NULL on either side matches nothing, `neq` included.
+  if (absent(held) || absent(filter.value)) return false;
+  switch (filter.op) {
+    case 'eq':
+      return equal(held, filter.value);
+    case 'neq':
+      return !equal(held, filter.value);
+    case 'in':
+      return Array.isArray(filter.value) && filter.value.some((one) => equal(held, one));
+    case 'contains':
+      // `LIKE` is case-sensitive and collation-free for a literal substring.
+      return typeof held === 'string' ? held.includes(String(filter.value)) : undefined;
+    default: {
+      const order = ordered(held, filter.value);
+      if (order === undefined) return undefined;
+      if (filter.op === 'gt') return order > 0;
+      if (filter.op === 'gte') return order >= 0;
+      if (filter.op === 'lt') return order < 0;
+      return order <= 0;
+    }
+  }
+}
+
+/** The first predicate `row` does not satisfy, or `null` when it satisfies every one. */
+export function outsideRowScope(
+  row: AdminRow,
+  where: readonly AdminFilter[],
+): OutsideRowScope | null {
+  for (const filter of where) {
+    const verdict = satisfies(row, filter);
+    if (verdict === true) continue;
+    return { field: filter.field, op: filter.op, decidable: verdict !== undefined };
+  }
+  return null;
+}
+
+/**
+ * What a write would leave, judged against the acting actor's scope. `null` for a resource that
+ * declares no `rows` — and for an actor whose scope is the empty conjunction, who sees every row.
+ *
+ * `touched` narrows an UPDATE to the predicates over the fields it writes: the stored row is
+ * already inside the scope (the repo said so when it was loaded), so only a field the patch
+ * changes can move it out — and a predicate this file cannot decide is then never asked about a
+ * column nobody touched.
+ */
+export function writeOutsideScope(
+  resource: AdminResource,
+  actor: AdminActor,
+  candidate: AdminRow,
+  touched?: readonly string[],
+): OutsideRowScope | null {
+  if (resource.rowScope === undefined) return null;
+  const scope = resource.rowScope(actor);
+  return outsideRowScope(
+    candidate,
+    touched === undefined ? scope : scope.filter((filter) => touched.includes(filter.field)),
+  );
+}
+
+/** The refusal a write outside the scope is answered and audited with. */
+export function outOfScopeDecision(permission: string, outside: OutsideRowScope): AdminDecision {
+  return {
+    allowed: false,
+    permission,
+    reason: ROW_OUT_OF_SCOPE_REASON,
+    trace: [
+      outside.decidable
+        ? `rows: ${outside.field} ${outside.op} is not satisfied by the row this write would leave`
+        : `rows: ${outside.field} ${outside.op} cannot be decided before the write, so it is refused`,
+    ],
+  };
+}