@fougere/core 0.7.0-alpha.0 → 0.8.0-alpha.0

package/src/boot/frame.ts

@@ -2,8 +2,9 @@
  * The compensated realization of a frame — what `Together` becomes when its members do not share
  * an engine.
  */
-import { FieldSet, Role, type SchemaView } from '@fougere/schema';
+import { FieldSet, type SchemaView } from '@fougere/schema';
 import { dequal } from 'dequal';
+import { declares } from '../source.js';
 import type { Logger } from '../builtin/logger.js';
 
 /** One write that landed, and how to take it back. */
@@ -30,13 +31,6 @@ interface Undoable {
 const pick = (row: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> =>
   Object.fromEntries(keys.map((key) => [key, row[key]]));
 
-/** Whether an upsert's conflict can be something other than the primary key. */
-function mayConflictElsewhere(schema: SchemaView): boolean {
-  if ((schema.getUnique() ?? []).length > 0) return true;
-
-  return Object.values(schema.getFields()).some((field) => Role.of(field).isUnique);
-}
-
 /** Refused where it is used, naming the group that makes the inverse ambiguous. */
 function refuseAmbiguousUpsert(entity: string, gesture: string): never {
   throw new Error(
@@ -133,7 +127,7 @@ export function recording<T extends object>(storage: T, entity: string, schema:
 
   if (typeof base.upsert === 'function') {
     recorded.upsert = async function (input, ...rest) {
-      if (mayConflictElsewhere(schema)) refuseAmbiguousUpsert(entity, 'upsert');
+      if (declares(schema, 'unique')) refuseAmbiguousUpsert(entity, 'upsert');
       const undo = await undoUpsert.call(this, [input]);
       const row = await base.upsert!.call(this, input, ...rest);
       journal.push(undo);
@@ -143,7 +137,7 @@ export function recording<T extends object>(storage: T, entity: string, schema:
 
   if (typeof base.upsertAll === 'function') {
     recorded.upsertAll = async function (inputs, ...rest) {
-      if (mayConflictElsewhere(schema)) refuseAmbiguousUpsert(entity, 'upsertAll');
+      if (declares(schema, 'unique')) refuseAmbiguousUpsert(entity, 'upsertAll');
       const undo = await undoUpsert.call(this, inputs);
       const written = await base.upsertAll!.call(this, inputs, ...rest);
       journal.push(undo);

package/src/boot/types.ts

@@ -5,6 +5,7 @@ import type { FrondDescriptor } from '../descriptor/frond.js';
 import type { ScanResult } from '../scan/result.js';
 import type { SchemaView } from '@fougere/schema';
 import type { StorageFactory } from '../storage.js';
+import type { Constraint } from '../source.js';
 import type { AppMiddleware } from '../wire/middleware.js';
 import type { RpcAnswer, Transport } from '../wire/call.js';
 import type { Extension } from './AppLifecycle.js';
@@ -27,6 +28,8 @@ export interface CreateAppOptions {
   sourceOf?: (entityName: string) => string;
   transacts?: (source: string) => boolean;
   transacted?: <R>(source: string, fn: (storageFactory: StorageFactory) => Promise<R>) => Promise<R>;
+  /** Whether that source refuses a constraint at the rows — the boot says so when it does not. */
+  enforces?: (source: string, constraint: Constraint) => boolean;
   /** Builds the cross-source reader a frond gets when it declares `reads:`. */
   sourcesFactory?: (reads: unknown[], frond: string) => Promise<unknown> | unknown;
   /** What this app is built from — required, because producing it is what reads a disk. */

package/src/contract.ts

@@ -7,6 +7,10 @@ import { canonicalInvocation, type InvocationContext } from './wire/Invocation.j
 import type { FrondCall } from './wire/call.js';
 
 export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
+// What a read may ask about one field. Here rather than on the main entry because an
+// adapter reads it to compile a query, and an adapter carries no boot.
+export { comparisonOf, comparisonsIn, unknownIn, COMPARISONS } from './criterion.js';
+export type { Comparison, ComparisonName } from './criterion.js';
 // A receiver turns a refusal into what may cross a process boundary, and it is not
 // core's boot — reaching it through the main entry dragged the scanner into a bundle.
 export { toPublicError } from './wire/http-error.js';

package/src/criterion.ts

@@ -0,0 +1,54 @@
+/** What a read may ask about one field, and how a storage tells the two forms apart. */
+import { type Field, Shapes } from '@fougere/schema';
+
+/**
+ * The comparisons a criterion may name.
+ *
+ * `eq` and `in` are not here: a bare value already means equality and an array already
+ * means membership, and giving them a second spelling would make one criterion sayable
+ * two ways. What is added is what those two could not say at all.
+ */
+export interface Comparison {
+  gte?: unknown;
+  lte?: unknown;
+  gt?: unknown;
+  lt?: unknown;
+  ne?: unknown;
+  /** Both bounds, inclusive — `between: [1500, 4000]`. */
+  between?: [unknown, unknown];
+  contains?: string;
+  notIn?: readonly unknown[];
+  isNull?: boolean;
+}
+
+export const COMPARISONS = ['gte', 'lte', 'gt', 'lt', 'ne', 'between', 'contains', 'notIn', 'isNull'] as const;
+
+export type ComparisonName = (typeof COMPARISONS)[number];
+
+/**
+ * Is this criterion a comparison, or a value that happens to be an object?
+ *
+ * Read off the FIELD, never off the value. `json()` admits any shape, so `{ gte: … }` is
+ * a legal thing to store — telling the two apart by looking at the criterion would make a
+ * stored object unfilterable the day its keys happened to spell an operator. The shape
+ * knows, and it is the only thing that does.
+ */
+export function comparisonOf(field: Field | undefined, asked: unknown): Comparison | undefined {
+  if (asked === null || typeof asked !== 'object' || Array.isArray(asked)) return undefined;
+  // `Shapes.of` answers with `null` already taken out — `optional(json())` is an object.
+  if (!field || Shapes.of(field.shape).base?.type === 'object') return undefined;
+
+  return asked as Comparison;
+}
+
+/** The comparisons a criterion names, in the order the caller wrote them. */
+export function comparisonsIn(comparison: Comparison): [ComparisonName, unknown][] {
+  return Object.entries(comparison).filter(
+    (entry): entry is [ComparisonName, unknown] => (COMPARISONS as readonly string[]).includes(entry[0]),
+  );
+}
+
+/** What a comparison names that this vocabulary does not — a typo, said as one. */
+export function unknownIn(comparison: Comparison): string[] {
+  return Object.keys(comparison).filter((name) => !(COMPARISONS as readonly string[]).includes(name));
+}

package/src/declare.ts

@@ -6,6 +6,7 @@ import type {
 } from './descriptor/frond.js';
 import { DEFAULT_CONVENTIONS } from './scan/conventions.js';
 import { getPresenterFields } from './prefab/presenter.js';
+import type { OperationContract } from './wire/operation.js';
 
 /** A class, as a declaration hands it over: the constructor itself. */
 type Ctor = new (...args: never[]) => unknown;
@@ -24,10 +25,19 @@ export interface DeclaredHandler extends DeclaredSubject {
    * route twice.
    */
   surface?: string;
+  /**
+   * What each method takes and answers — read from SOURCE by the scan, and unreachable
+   * from a class at runtime. A prefab declares its own (`Crud.__ops`) and needs nothing
+   * here; a method someone wrote does, or the route it should serve does not exist.
+   */
+  operations?: ReadonlyMap<string, OperationContract> | Record<string, OperationContract>;
 }
 
 /** A class on its own, or a class with what it asks for. */
-export type Declared = Ctor | DeclaredSubject;
+export type Declared = Ctor | (DeclaredSubject & {
+  /** The container key, when the class's own name cannot be trusted to survive a build. */
+  name?: string;
+});
 
 const ctorOf = (d: Declared): Ctor => (typeof d === 'function' ? d : d.ctor);
 
@@ -49,6 +59,22 @@ function subjectOf(ctor: Ctor, kind: string): { name: string } {
 }
 const depsOf = (d: Declared): string[] => (typeof d === 'function' ? [] : d.deps ?? []);
 
+/**
+ * A Map either way — a statement is read as code, and an object literal is what code
+ * looks like there. What a prefab declares of itself is merged BELOW: a method the author
+ * wrote over `create` is the one that runs, so its contract is the one that answers.
+ */
+function statedOperations(h: Ctor | DeclaredHandler): Map<string, OperationContract> {
+  const declared = typeof h === 'function' ? undefined : h.operations;
+  const own = (ctorOf(h) as { __ops?: Record<string, OperationContract> }).__ops ?? {};
+  const merged = new Map<string, OperationContract>(Object.entries(own));
+  for (const [op, contract] of declared instanceof Map ? declared : Object.entries(declared ?? {})) {
+    merged.set(op, contract as OperationContract);
+  }
+
+  return merged;
+}
+
 /** `PostHandler` answers at `post` — the same rule the scan applies to a file it found. */
 function addressOf(className: string): string {
   const base = className.endsWith('Handler') ? className.slice(0, -7) : className;
@@ -68,6 +94,8 @@ export interface FrondDeclaration {
   surfaces?: Record<string, string[]>;
   /** The import scope this frond answers under. Defaults to the conventional one. */
   scope?: string;
+  /** What `frond.config.ts` states — the third producer of an operation contract. */
+  operationsOverrides?: FrondDescriptor['operationsOverrides'];
 }
 
 /** State a frond without reading a disk. */
@@ -93,7 +121,7 @@ export function frond(name: string, declared: FrondDeclaration = {}): FrondDescr
       // A handler about no stored row is ordinary — the address is not a promise that an
       // entity carries it, which is why this is not looked up.
       entityName: address,
-      operations: new Map(),
+      operations: statedOperations(h),
       deps: depsOf(h),
       filePath: '',
       exposed: true,
@@ -132,6 +160,9 @@ export function frond(name: string, declared: FrondDeclaration = {}): FrondDescr
   });
 
   const providers: ProviderEntry[] = (declared.providers ?? []).map((p) => ({
+    // Written down where a statement says it, read off the class otherwise — the class's
+    // own name is what a bundler is free to rewrite.
+    ...(typeof p === 'function' || !p.name ? {} : { name: p.name }),
     ctor: ctorOf(p),
     deps: depsOf(p),
     filePath: '',
@@ -146,6 +177,7 @@ export function frond(name: string, declared: FrondDeclaration = {}): FrondDescr
   return {
     name,
     source: { path: '', package: `${scope}/${name}` },
+    ...(declared.operationsOverrides ? { operationsOverrides: declared.operationsOverrides } : {}),
     providers,
     entities,
     handlers,

package/src/descriptor/frond.ts

@@ -6,6 +6,15 @@ import type { Fronds } from './Fronds.js';
 
 /** A discovered provider — a class under `services/` or `repositories/`, injected by type. */
 export interface ProviderEntry {
+  /**
+   * The container key — the class name as the SOURCE spells it.
+   *
+   * Read at boot off `ctor.name` for a decade of no consequence, until a bundler lowered
+   * a `static readonly` field and renamed the declaration doing it: the provider
+   * registered as `_Communes` and the handler asking for `Communes` got a container miss.
+   * A name a tool may rewrite is written down, for the same reason `deps` is.
+   */
+  name?: string;
   /** The class constructor (default export of the file). */
   ctor: new (...args: never[]) => unknown;
   /** Constructor dependency type names (from AST scan). */
@@ -14,6 +23,12 @@ export interface ProviderEntry {
   filePath: string;
 }
 
+/**
+ * The key a provider answers under. What the source said, and the class's own name only
+ * where nobody wrote it down — a statement is read as code, and code can say it.
+ */
+export const nameOf = (provider: ProviderEntry): string => provider.name ?? provider.ctor.name;
+
 /** A discovered entity (Entity subclass in entities/ dir). */
 export interface EntityEntry {
   /** Registration key: class name lowercased first char (e.g. 'product'). */

package/src/dispatch/StorageGuard.ts

@@ -1,4 +1,5 @@
 import { Boundary, FieldSet, FieldValueValidator, InputRefusal, type Fields } from '@fougere/schema';
+import { COMPARISONS, comparisonOf, unknownIn } from '../criterion.js';
 import { assertListOptions } from '../storage.js';
 import { ErrorCode, FougereError } from '../wire/errors.js';
 
@@ -11,11 +12,23 @@ interface Writer {
   list?(...args: unknown[]): unknown;
 }
 
+/** What a guard says about a filter it let through. The boot owns the voice. */
+export interface GuardReport {
+  /** The fields this door hands back, when it hands back fewer than the entity has. */
+  view?: Fields;
+  /** Said once per field — a filter is not a write, and a warning per call is noise. */
+  outOfView?: (message: string) => void;
+}
+
 /** Judges storage writes and list options without narrowing the storage interface. */
 export class StorageGuard {
+  /** What has already been said, so a filter in a loop says it once. */
+  private readonly said = new Set<string>();
+
   constructor(
     private readonly fields: Fields,
     private readonly entity: string,
+    private readonly report: GuardReport = {},
   ) {}
 
   guard<T extends object>(storage: T): T {
@@ -56,7 +69,10 @@ export class StorageGuard {
     const list = writer.list;
     if (typeof list === 'function') {
       guarded.list = async function (...args: unknown[]) {
-        assertListOptions(args[0] as object | undefined, validation.entity);
+        const options = args[0] as { where?: Record<string, unknown> } | undefined;
+        assertListOptions(options, validation.entity);
+        if (options?.where) args[0] = { ...options, where: validation.criteria(options.where) };
+
         return list.apply(this, args);
       };
     }
@@ -75,6 +91,91 @@ export class StorageGuard {
     return key === undefined ? `row ${index} of this page` : `row ${primary} ${JSON.stringify(key)}`;
   }
 
+  /**
+   * What a read may ask for. The write door judges what LANDS in a row; this one judges
+   * what a caller says about one — and it was the single entrance to the port with no
+   * judge at all, while `params.filter` from a browser reaches it verbatim.
+   *
+   * A criterion may name a SET, which is the one thing the write door would refuse: an
+   * array is judged member by member, since that is what `IN` binds.
+   */
+  private criteria(where: Record<string, unknown>): Record<string, unknown> {
+    const errors: string[] = [];
+    const parsed: Record<string, unknown> = {};
+
+    for (const [key, asked] of Object.entries(where)) {
+      const field = this.fields[key];
+      if (!field) {
+        errors.push(`${key}: ${InputRefusal.unknownField}`);
+        continue;
+      }
+      // A comparison names its own vocabulary, and a typo in it would otherwise be a
+      // criterion that filters nothing — the silent truncation this door exists to stop.
+      const comparison = comparisonOf(field, asked);
+      if (comparison) {
+        const unknown = unknownIn(comparison);
+        if (unknown.length) {
+          errors.push(`${key}: unknown comparison ${unknown.join(', ')} — one of ${COMPARISONS.join(', ')}`);
+          continue;
+        }
+        parsed[key] = comparison;
+        this.beyondTheView(key);
+        continue;
+      }
+
+      const values = Array.isArray(asked) ? asked : [asked];
+      const each = values.map((value) => this.value(field, value));
+      const refused = each.find((one) => typeof one === 'object' && one !== null && 'error' in one);
+      if (refused) {
+        errors.push(`${key}: ${(refused as { error: string }).error}`);
+        continue;
+      }
+      parsed[key] = Array.isArray(asked) ? each.map(unwrap) : unwrap(each[0]);
+      this.beyondTheView(key);
+    }
+
+    if (errors.length > 0) {
+      throw new FougereError({
+        code: ErrorCode.BAD_REQUEST,
+        message: `Refused as a filter — ${errors.join(', ')}`,
+        entity: this.entity,
+        operation: 'list',
+        details: errors,
+      });
+    }
+
+    return parsed;
+  }
+
+  /**
+   * A filter on a field this door does not hand back.
+   *
+   * `output(schema)` narrows what is RETURNED and has never narrowed what is asked, so a
+   * caller can already sort a hidden column into existence one comparison at a time — and
+   * the admin door copies a browser's filter here verbatim. Said rather than refused: it
+   * is legal today, GraphQL batches a relation on a key a view may not carry, and a
+   * refusal would break that on the way to fixing this.
+   */
+  private beyondTheView(field: string): void {
+    const view = this.report.view;
+    if (!view || view[field] || this.said.has(field)) return;
+    this.said.add(field);
+    this.report.outOfView?.(
+      `${this.entity}.list() filtered on '${field}', which this door does not hand back — `
+      + 'a filter on a hidden field answers questions about it one call at a time.',
+    );
+  }
+
+  /** One value against one field — validated, then decoded the way the wire hands it. */
+  private value(field: Fields[string], asked: unknown): { value: unknown } | { error: string } {
+    if (asked === null || asked === undefined) return { value: asked };
+    const checked = FieldValueValidator.of(field).validate(asked);
+    if ('error' in checked) return checked;
+    if (checked.value === null) return { value: null };
+
+    return Boundary.of(field).decode(checked.value);
+  }
+
   private validated<T>(value: T, operation: string, index?: number): T {
     if (typeof value !== 'object' || value === null) return value;
 
@@ -121,3 +222,6 @@ export class StorageGuard {
     return parsed as T;
   }
 }
+
+const unwrap = (one: { value: unknown } | { error: string }): unknown =>
+  'value' in one ? one.value : undefined;

package/src/index.ts

@@ -85,7 +85,7 @@ export { applyConfig, type ConfigApplication } from './boot/apply.js';
 export { Config } from './builtin/config.js';
 export type { Storage, StorageFactory, ListOptions, ListResult, Together } from './storage.js';
 export { togetherKeyOf, membersOfTogetherKey } from './storage.js';
-export type { Source, SourceConfig, SourceView } from './source.js';
+export type { Constraint, Source, SourceConfig, SourceView } from './source.js';
 export { Sources } from './source.js';
 export { storageOver } from './store.js';
 export type { Store, Values } from './store.js';

package/src/scan/contract.ts

@@ -0,0 +1,80 @@
+/** An operation contract, written down — the half two emitters say the same way. */
+import { ANONYMOUS_SCHEMA_NAME, Card, type SchemaView } from '@fougere/schema';
+
+import type { OperationContract } from '../wire/operation.js';
+
+/** A value that ends up as an import in the module being written. */
+export type Live = object;
+
+/**
+ * What the writer needs of an emitter's imports, and nothing more.
+ *
+ * The two emitters index theirs differently — one by value against a relative path, one
+ * by file against the package specifier a project already uses — and neither is wrong for
+ * the module it writes. What they agree on is this: a value already imported has an
+ * alias, a class can be imported by name, and an entity can be found by its class name.
+ */
+export interface Aliases {
+  aliasOf(value: Live): string | undefined;
+  named(value: Live, filePath: string, name: string): string;
+  /** The entity class this name belongs to — what a `Partial<X>` names as its source. */
+  classNamed(name: string): Live | undefined;
+}
+
+export const lit = (value: unknown): string => JSON.stringify(value ?? null);
+
+/** What a schema slot becomes in the generated module. */
+export function schemaRef(
+  schema: SchemaView | undefined,
+  declaredIn: string,
+  imports: Aliases,
+): string | undefined {
+  if (!schema) return undefined;
+  const known = imports.aliasOf(schema as Live);
+  if (known) return known;
+
+  const name = (schema as { name?: string }).name;
+  if (name && name !== ANONYMOUS_SCHEMA_NAME) return imports.named(schema as Live, declaredIn, name);
+
+  const card = Card.fromSchema(schema);
+  const source = card.origin?.from ?? card.descriptor.title;
+  const from = source ? imports.classNamed(source) : undefined;
+  if (from) return `${imports.aliasOf(from)}.partial()`;
+
+  throw new Error(
+    `A scan cannot be written down: an anonymous schema in ${declaredIn} names no source. `
+    + 'Only `Partial<X>` is derivable here, and it says which X it came from.',
+  );
+}
+
+/** One entry of an operations Map, as its module spells it. */
+export function contractOf(
+  op: string,
+  contract: OperationContract,
+  declaredIn: string,
+  imports: Aliases,
+): string {
+  const parts: string[] = [];
+  const input = schemaRef(contract.input, declaredIn, imports);
+  const output = schemaRef(contract.output, declaredIn, imports);
+  if (input) parts.push(`input: ${input}`);
+  if (output) parts.push(`output: ${output}`);
+  if (contract.binding !== undefined) parts.push(`binding: ${lit(contract.binding)}`);
+  if (contract.description !== undefined) parts.push(`description: ${lit(contract.description)}`);
+  if (contract.cardinality !== undefined) parts.push(`cardinality: ${lit(contract.cardinality)}`);
+  if (contract.signature !== undefined) parts.push(`signature: ${lit(contract.signature)}`);
+
+  return `[${lit(op)}, { ${parts.join(', ')} }]`;
+}
+
+/** The operations of one handler, as the Map its reader builds. */
+export function operationsOf(
+  operations: ReadonlyMap<string, OperationContract>,
+  declaredIn: string,
+  imports: Aliases,
+  indent: string,
+): string {
+  const ops = [...operations].map((entry) => contractOf(entry[0], entry[1], declaredIn, imports));
+
+  return `new Map([\n${indent}  ${ops.join(`,\n${indent}  `)}\n${indent}])`;
+}

package/src/scan/emit.ts

@@ -1,9 +1,9 @@
 /** The scan, written down as a module — what `createApp` is handed where there is no disk. */
 import { dirname, relative } from 'node:path';
-import { ANONYMOUS_SCHEMA_NAME, Card, type SchemaView } from '@fougere/schema';
+import { nameOf } from '../descriptor/frond.js';
 import type { FrondDescriptor, EntityEntry, HandlerEntry, PresenterEntry, CollectorEntry, ProviderEntry, SeedEntry } from '../descriptor/frond.js';
 import type { ScanResult } from './result.js';
-import type { OperationContract } from '../wire/operation.js';
+import { type Aliases, type Live, lit, operationsOf, schemaRef } from './contract.js';
 
 export interface EmitOptions {
   /** Where the generated module will sit. Imports are written relative to it. */
@@ -12,8 +12,6 @@ export interface EmitOptions {
   core?: string;
 }
 
-type Live = object;
-
 /** Is a TypeScript compiler going to read this module? Its name is the only thing that says. */
 const isTypeScript = (outFile: string): boolean => /\.tsx?$/.test(outFile);
 
@@ -24,9 +22,7 @@ function specifierOf(filePath: string, outFile: string): string {
   return rel.startsWith('.') ? rel : `./${rel}`;
 }
 
-const lit = (v: unknown): string => JSON.stringify(v ?? null);
-
-class Imports {
+class Imports implements Aliases {
   private readonly byValue = new Map<Live, string>();
   private readonly lines: string[] = [];
   /** Entity classes by their class name — what a `Partial<X>` names as its source. */
@@ -56,55 +52,23 @@ class Imports {
 
   has(value: Live): boolean { return this.byValue.has(value); }
   aliasOf(value: Live): string | undefined { return this.byValue.get(value); }
+  classNamed(name: string): Live | undefined { return this.byClassName.get(name); }
   render(): string { return this.lines.join('\n'); }
 }
 
-/** What a schema slot becomes in the generated module. */
-function schemaRef(schema: SchemaView | undefined, declaredIn: string, imports: Imports): string | undefined {
-  if (!schema) return undefined;
-  const known = imports.aliasOf(schema as Live);
-  if (known) return known;
-
-  const name = (schema as { name?: string }).name;
-  if (name && name !== ANONYMOUS_SCHEMA_NAME) return imports.named(schema as Live, declaredIn, name);
-
-  const card = Card.fromSchema(schema);
-  const source = card.origin?.from ?? card.descriptor.title;
-  const from = source ? imports.byClassName.get(source) : undefined;
-  if (from) return `${imports.aliasOf(from)}.partial()`;
-
-  throw new Error(
-    `A scan cannot be written down: an anonymous schema in ${declaredIn} names no source. `
-    + 'Only `Partial<X>` is derivable here, and it says which X it came from.',
-  );
-}
-
-function contractOf(op: string, c: OperationContract, declaredIn: string, imports: Imports): string {
-  const parts: string[] = [];
-  const input = schemaRef(c.input, declaredIn, imports);
-  const output = schemaRef(c.output, declaredIn, imports);
-  if (input) parts.push(`input: ${input}`);
-  if (output) parts.push(`output: ${output}`);
-  if (c.binding !== undefined) parts.push(`binding: ${lit(c.binding)}`);
-  if (c.description !== undefined) parts.push(`description: ${lit(c.description)}`);
-  if (c.cardinality !== undefined) parts.push(`cardinality: ${lit(c.cardinality)}`);
-  if (c.signature !== undefined) parts.push(`signature: ${lit(c.signature)}`);
-  return `[${lit(op)}, { ${parts.join(', ')} }]`;
-}
-
 function entityOf(e: EntityEntry, imports: Imports): string {
   return `{ name: ${lit(e.name)}, entityClass: ${imports.aliasOf(e.entityClass as Live)}, `
     + `filePath: ${lit(e.filePath)}, exposed: ${lit(e.exposed)} }`;
 }
 
 function handlerOf(h: HandlerEntry, imports: Imports): string {
-  const ops = [...h.operations].map(([op, c]) => contractOf(op, c, h.filePath, imports));
+  const ops = operationsOf(h.operations, h.filePath, imports, '    ');
   const override = schemaRef(h.outputOverride, h.filePath, imports);
   return `{ name: ${lit(h.name)}, address: ${lit(h.address)}, ctor: ${imports.aliasOf(h.ctor as Live)}, `
     + `deps: ${lit(h.deps)}, filePath: ${lit(h.filePath)}, exposed: ${lit(h.exposed)}, `
     + (h.surface ? `surface: ${lit(h.surface)}, ` : '')
     + (override ? `outputOverride: ${override}, ` : '')
-    + `operations: new Map([\n      ${ops.join(',\n      ')}\n    ]) }`;
+    + `operations: ${ops} }`;
 }
 
 function presenterOf(p: PresenterEntry, imports: Imports): string {
@@ -121,7 +85,8 @@ function collectorOf(c: CollectorEntry, imports: Imports): string {
 }
 
 function providerOf(p: ProviderEntry, imports: Imports): string {
-  return `{ ctor: ${imports.aliasOf(p.ctor as Live)}, deps: ${lit(p.deps)}, filePath: ${lit(p.filePath)} }`;
+  return `{ name: ${lit(nameOf(p))}, ctor: ${imports.aliasOf(p.ctor as Live)}, `
+    + `deps: ${lit(p.deps)}, filePath: ${lit(p.filePath)} }`;
 }
 
 function seedOf(s: SeedEntry, imports: Imports): string {

package/src/scan/scanner.ts

@@ -86,8 +86,18 @@ async function loadDefault(filePath: string): Promise<unknown> {
 
 async function loadClass(filePath: string): Promise<ProviderEntry['ctor']> {
   const ctor = await loadDefault(filePath);
-  if (typeof ctor !== 'function' || !ctor.prototype)
-    throw new Error(`${filePath}: default export is not a class`);
+  // A convention directory holds classes, because a provider is registered under one and
+  // asked for by its type. What is NOT a class — a shared contract, a pure function, a
+  // table of constants — belongs beside them rather than among them, and saying where
+  // costs one line: measured twice on a real project, both times a file that had to move.
+  if (typeof ctor !== 'function' || !ctor.prototype) {
+    throw new Error(
+      `${filePath}: default export is not a class. This directory is scanned for providers, `
+      + 'which are registered under a class name — a contract or a pure function has no key '
+      + `to answer under. Move it beside the directory, at the frond's root, where the scan `
+      + 'reads nothing and an import still reaches it.',
+    );
+  }
   return ctor as ProviderEntry['ctor'];
 }
 
@@ -172,6 +182,9 @@ const handlerMethodsOf = (filePath: string, projectRoot?: string) =>
 
 async function toProvider(filePath: string): Promise<ProviderEntry> {
   const ctor = await loadClass(filePath);
+  // Read here, while the class is the one the source declared. What a bundler does to
+  // that name later is why it is carried rather than asked for again.
+  const name = ctor.name;
   const params = await ctorParamsOf(filePath);
   const deps = params.map((p) => depKeyOf(p.type));
 
@@ -191,10 +204,10 @@ async function toProvider(filePath: string): Promise<ProviderEntry> {
     deps.push(storageKeyOf(lowerFirst((target as { name: string }).name)));
   }
 
-  // No `name` beside `ctor`: a provider registers under `ctor.name`, which is what
-  // `depKeyOf` returns since it reads the type as written. The camelCase field that
-  // used to sit here called itself the registration key and was one nowhere.
-  return { ctor, deps, filePath };
+  // `name` beside `ctor`, and it IS the registration key — what `depKeyOf` returns, since
+  // it reads the type as written. It used to be asked of `ctor.name` at boot, which held
+  // until a bundler lowered a static field and renamed the declaration doing it.
+  return { name, ctor, deps, filePath };
 }
 
 async function toEntityEntry(filePath: string): Promise<EntityEntry | null> {