@fougere/core 0.12.1-alpha.0 → 0.12.4-alpha.0

package/src/EffectiveOperationModel.ts

@@ -1,5 +1,5 @@
 import { lowerFirst, type SchemaView } from '@fougere/schema';
-import { statementDrift } from './boot/statement-drift.js';
+import { statementDrift, unansweredOperations } from './boot/statement-drift.js';
 import { reachedBy, servedBy } from './boot/declared.js';
 import { computeBindingPlan, type BindingPlan } from './wire/binding.js';
 import { targetOf } from './prefab/prefab.js';
@@ -21,6 +21,9 @@ import type { EffectiveOperationOptions } from './EffectiveOperationOptions.js';
 
 type Binding = BindingPlan[number];
 
+/** A contract whose parameters are all bound. */
+type BoundContract = OperationContract & { binding: BindingPlan };
+
 /**
  * Where an op's work goes: the fronds its handler reaches, and how many are a process away.
  *
@@ -47,26 +50,30 @@ function reachOf(
  * boot never has to find a handler again by an order-dependent name lookup.
  */
 export class EffectiveOperationModel {
-  readonly operations: EffectiveOperation[];
-  readonly diagnostics: Diagnostic[];
-  readonly resolutionDiagnostics: Diagnostic[];
-
   constructor(
-    operations: EffectiveOperation[],
-    diagnostics: Diagnostic[],
-    resolutionDiagnostics: Diagnostic[],
+    readonly operations: EffectiveOperation[],
+    readonly diagnostics: Diagnostic[],
+    readonly resolutionDiagnostics: Diagnostic[],
     private readonly byHandler: Map<HandlerEntry, EffectiveOperationsMap>,
-  ) {
-    this.operations = operations;
-    this.diagnostics = diagnostics;
-    this.resolutionDiagnostics = resolutionDiagnostics;
-  }
+  ) {}
 
   forHandler(handler: HandlerEntry): EffectiveOperationsMap {
     return this.byHandler.get(handler) ?? new Map();
   }
 }
 
+/** What one handler's operations are resolved against. */
+interface Resolving {
+  fronds: readonly FrondDescriptor[];
+  frond: FrondDescriptor;
+  handler: HandlerEntry;
+  schemas: Map<string, SchemaView>;
+  served: Map<string, string>;
+  collectorsByType: Map<string, CollectorEntry[]>;
+  options: EffectiveOperationOptions;
+  diagnostics: Diagnostic[];
+}
+
 /** Resolve the complete operation model without starting the application. */
 export function resolveEffectiveOperations(
   fronds: readonly FrondDescriptor[],
@@ -74,211 +81,41 @@ export function resolveEffectiveOperations(
 ): EffectiveOperationModel {
   const operations: EffectiveOperation[] = [];
   const byHandler = new Map<HandlerEntry, EffectiveOperationsMap>();
-  const resolutionDiagnostics: Diagnostic[] = [];
   const scanDiagnostics = [...(options.diagnostics ?? [])];
   const schemas = new Map(
     fronds.flatMap((frond) => frond.entities.map((entity) => [entity.name, entity.entityClass] as const)),
   );
-  /** Every address a frond answers, so a dependency naming one is read as the crossing it is. */
   const served = servedBy(fronds);
 
-  // Input ambiguity is produced where schemas are available (the scanner), but it is a
-  // resolution failure. Lift it into the same refusal table as kind/binding/topology.
-  resolutionDiagnostics.push(...scanDiagnostics.filter((diagnostic) =>
-    diagnostic.code === 'input-contract-ambiguous'));
+  // Input ambiguity is found by the scanner, where schemas are, but it is a resolution failure.
+  const diagnostics = scanDiagnostics.filter((diagnostic) => diagnostic.code === 'input-contract-ambiguous');
 
   for (const frond of fronds) {
     const collectorsByType = groupedCollectors(frond.collectors);
-    for (const [typeName, collectors] of collectorsByType) {
-      if (collectors.length < 2) continue;
-      resolutionDiagnostics.push({
-        severity: 'blocking',
-        code: 'collector-ambiguous',
-        filePath: collectors[0]!.filePath,
-        frond: frond.name,
-        subject: typeName,
-        message: `Frond '${frond.name}' declares ${collectors.length} collectors for '${typeName}' — `
-          + `${collectors.map((collector) => collector.ctor.name).sort().join(', ')}. `
-          + 'Exactly one collector must own a parameter type.',
-      });
-    }
+    refuseAmbiguousCollectors(frond, collectorsByType, diagnostics);
 
     const collectorNames = new Set(frond.collectors.map((collector) => collector.typeName));
     for (const handler of frond.handlers) {
       const effective = new Map<string, EffectiveOperation>();
       byHandler.set(handler, effective);
       const contracts = resolveContracts(handler, frond.operationsOverrides, collectorNames);
-      // A statement wins over the scan on purpose; saying so out loud is what keeps the
-      // win from hiding a rename. Compared here, where both readings are in hand.
-      resolutionDiagnostics.push(...statementDrift(frond, handler));
-
-      for (const [name, rawContract] of contracts) {
-        const subject = `${handler.ctor.name}.${name}`;
-        const contract = normalizeBinding(rawContract, handler, frond, name, resolutionDiagnostics);
-        if (!contract) continue;
-
-        // An operation answers DATA — what JSON keeps. A DECLARED output is converted by its
-        // fields, so `created()` leaves as an ISO string and nothing is asked of it here; an
-        // undeclared one has nothing to convert it, so it must already be data. Measured
-        // 2026-09-18: `{ at: new Date(0) }` reaches a local caller as a `Date` and a remote one
-        // as a string, and an object carrying methods loses them on both sides, differently.
-        if (!contract.output && contract.signature?.notData) {
-          resolutionDiagnostics.push({
-            severity: 'blocking',
-            code: 'operation-output-not-data',
-            filePath: handler.filePath,
-            frond: frond.name,
-            subject,
-            message: `${subject}() answers ${contract.signature.notData}, which carries methods.\n`
-              + '  An operation answers data — what JSON keeps.\n'
-              + '  Declare the output as an entity, whose fields convert it, or answer what it produces.',
-          });
-          continue;
-        }
-
-        const override = frond.operationsOverrides?.[name];
-        const inference = inferOperationKind(name);
-        const inferredKinds = new Set<OperationKind>();
-        if (inference.kind) inferredKinds.add(inference.kind);
-        if (inference.queryMatches.length > 0) inferredKinds.add('query');
-        if (inference.commandMatches.length > 0) inferredKinds.add('command');
-        const kind = override?.kind
-          ?? (inferredKinds.size === 1 ? [...inferredKinds][0] : undefined);
-        if (!kind) {
-          const ambiguous = inferredKinds.size > 1;
-          resolutionDiagnostics.push({
-            severity: 'blocking',
-            code: ambiguous ? 'operation-kind-ambiguous' : 'operation-kind-unknown',
-            filePath: handler.filePath,
-            frond: frond.name,
-            subject,
-            message: ambiguous
-              ? `Cannot resolve the kind of ${subject}: its name carries query evidence `
-                + `(${inference.queryMatches.join(', ')}) and command evidence `
-                + `(${inference.commandMatches.join(', ')}). `
-                + `Declare operations.${name}.kind.`
-              : `Cannot resolve the kind of ${subject}: '${name}' leads with no known verb. `
-                + `Rename it to lead with one, or declare operations.${name}.kind in `
-                + `frond.config.ts.\n  query:   ${knownVerbs().query.join(', ')}`
-                + `\n  command: ${knownVerbs().command.join(', ')}`,
-          });
-          continue;
-        }
-
-        const implementation = implementationOf(frond, handler, name, resolutionDiagnostics);
-        if (!implementation) continue;
-
-        const params = contract.signature?.params ?? [];
-        const parameters = contract.binding.map((binding, position) => {
-          const param = params[position];
-          const undefinable = binding.optional
-            || param?.optional === true
-            || param?.type.undefined === true;
-          return {
-            position,
-            name: param?.name ?? binding.name,
-            type: param?.type.raw ?? null,
-            optional: undefinable,
-            nullable: param?.type.nullable === true,
-            undefinable,
-            binding,
-          } satisfies EffectiveParameter;
-        });
-
-        if (!validateProvenance(
-          fronds,
-          frond,
-          handler,
-          name,
-          contract,
-          parameters,
-          collectorsByType,
-          resolutionDiagnostics,
-        )) continue;
-
-        // A fact is validated by the entity it names. This used to be patched into the
-        // facade after resolution, leaving check/explain with a different input.
-        const announced = contract.binding.find((binding) =>
-          binding.source.kind === 'fact' || binding.source.kind === 'pipe');
-        const fact = announced?.source.kind === 'fact' || announced?.source.kind === 'pipe'
-          ? schemas.get(announced.source.factName)
-          : undefined;
-        const input = contract.input ?? fact;
-
-        // An op that FINISHES a fact answers the fact, so its answer is the fact's shape:
-        // derived here, where its input already is. Left to the ordinary projection it
-        // came back stripped — measured, the subscriber got a value with no `id`.
-        const output = announced?.source.kind === 'pipe' && fact
-          ? { schema: fact, closed: false }
-          : effectiveOutput(frond, handler, name, contract);
-        const className = handler.ctor.name.endsWith('Handler')
-          ? handler.ctor.name.slice(0, -'Handler'.length)
-          : handler.ctor.name;
-        const surface = handler.surface ? `/${handler.surface}` : '/default';
-        const remote = options.remotes?.[frond.name];
-        const op: EffectiveOperation = {
-          ...contract,
-          ...(input ? { input } : {}),
-          ...(output.schema ? { output: output.schema } : {}),
-          id: `${frond.name}${surface}/${className}.${name}`,
-          operation: `${className}.${name}`,
-          name,
-          kind,
-          kindSource: override?.kind
-            ? 'explicit'
-            : 'convention',
-          handler: {
-            className: handler.ctor.name,
-            address: handler.address,
-            filePath: handler.filePath,
-          },
-          implementation,
-          binding: contract.binding,
-          parameters,
-          collectors: parameters.flatMap((parameter) => {
-            if (parameter.binding.source.kind !== 'collector') return [];
-            const collector = collectorsByType.get(parameter.binding.source.typeName)?.[0];
-            return collector ? [{
-              parameter: parameter.name,
-              typeName: collector.typeName,
-              className: collector.ctor.name,
-              frond: frond.name,
-              filePath: collector.filePath,
-            }] : [];
-          }),
-          contexts: parameters
-            .filter((parameter) => parameter.binding.source.kind === 'context')
-            .map((parameter) => parameter.name),
-          placement: {
-            frond: frond.name,
-            runtime: remote ? 'remote' : 'local',
-            ...(remote ? { remote } : {}),
-          },
-          reach: reachOf(handler.deps, frond.name, served, options.remotes ?? {}),
-          exposure: {
-            surfaces: servedSurfaces(frond, handler).map((surface) => surface ?? 'default'),
-            adapters: exposedAdapters(handler, options.adapters),
-          },
-          outputClosed: output.closed,
-          semantics: EFFECTIVE_OPERATION_SEMANTICS,
-        };
+      // A statement wins over the scan on purpose; saying so is what keeps the win from hiding a rename.
+      diagnostics.push(...statementDrift(frond, handler));
+      diagnostics.push(...unansweredOperations(frond, handler, contracts.keys()));
+
+      const resolving: Resolving = { fronds, frond, handler, schemas, served, collectorsByType, options, diagnostics };
+      for (const [name, contract] of contracts) {
+        const op = resolveOperation(resolving, name, contract);
+        if (!op) continue;
         effective.set(name, op);
         operations.push(op);
       }
     }
   }
 
-  // Topology and DI are part of the same effective program. A dependency targeting an
-  // actually remote frond is a refusal, not the warning appropriate to a future split.
-  for (const misplaced of verify({ fronds })) {
-    const remoteBoundary = options.remotes?.[misplaced.frond] !== undefined
-      || options.remotes?.[misplaced.dependsOn.frond] !== undefined;
-    resolutionDiagnostics.push(remoteBoundary && misplaced.code === 'cross-frond-dependency'
-      ? { ...misplaced, severity: 'blocking' }
-      : misplaced);
-  }
+  diagnostics.push(...placementRefusals(fronds, options));
+  const resolution = uniqueDiagnostics(diagnostics);
 
-  const resolution = uniqueDiagnostics(resolutionDiagnostics);
   return new EffectiveOperationModel(
     operations,
     uniqueDiagnostics([...scanDiagnostics, ...resolution]),
@@ -287,6 +124,193 @@ export function resolveEffectiveOperations(
   );
 }
 
+function refuseAmbiguousCollectors(
+  frond: FrondDescriptor,
+  collectorsByType: Map<string, CollectorEntry[]>,
+  diagnostics: Diagnostic[],
+): void {
+  for (const [typeName, collectors] of collectorsByType) {
+    if (collectors.length < 2) continue;
+    diagnostics.push({
+      severity: 'blocking',
+      code: 'collector-ambiguous',
+      filePath: collectors[0]!.filePath,
+      frond: frond.name,
+      subject: typeName,
+      message: `Frond '${frond.name}' declares ${collectors.length} collectors for '${typeName}' — `
+        + `${collectors.map((collector) => collector.ctor.name).sort().join(', ')}. `
+        + 'Exactly one collector must own a parameter type.',
+    });
+  }
+}
+
+/** One operation, or nothing when a refusal was written for it. */
+function resolveOperation(resolving: Resolving, name: string, rawContract: OperationContract): EffectiveOperation | undefined {
+  const { fronds, frond, handler, schemas, served, collectorsByType, options, diagnostics } = resolving;
+  const contract = normalizeBinding(rawContract, handler, frond, name, diagnostics);
+  if (!contract || !answersData(resolving, name, contract)) return undefined;
+
+  const kind = kindOf(resolving, name);
+  if (!kind) return undefined;
+
+  const implementation = implementationOf(frond, handler, name, diagnostics);
+  if (!implementation) return undefined;
+
+  const parameters = parametersOf(contract);
+  if (!validateProvenance(fronds, frond, handler, name, contract, parameters, collectorsByType, diagnostics)) {
+    return undefined;
+  }
+
+  // A fact is validated by the entity it names, and an op that FINISHES one answers its shape —
+  // left to the ordinary projection, the subscriber got a value with no `id`.
+  const announced = contract.binding.find((binding) => binding.source.kind === 'fact' || binding.source.kind === 'pipe');
+  const fact = announced?.source.kind === 'fact' || announced?.source.kind === 'pipe'
+    ? schemas.get(announced.source.factName)
+    : undefined;
+  const input = contract.input ?? fact;
+  const output = announced?.source.kind === 'pipe' && fact
+    ? { schema: fact, closed: false }
+    : effectiveOutput(frond, handler, name, contract);
+
+  const className = handler.ctor.name.replace(/Handler$/, '');
+  const surface = handler.surface ? `/${handler.surface}` : '/default';
+  const remote = options.remotes?.[frond.name];
+
+  return {
+    ...contract,
+    ...(input ? { input } : {}),
+    ...(output.schema ? { output: output.schema } : {}),
+    id: `${frond.name}${surface}/${className}.${name}`,
+    operation: `${className}.${name}`,
+    name,
+    kind,
+    kindSource: frond.operationsOverrides?.[name]?.kind ? 'explicit' : 'convention',
+    handler: { className: handler.ctor.name, address: handler.address, filePath: handler.filePath },
+    implementation,
+    binding: contract.binding,
+    parameters,
+    collectors: collectorsOf(parameters, collectorsByType, frond),
+    contexts: parameters
+      .filter((parameter) => parameter.binding.source.kind === 'context')
+      .map((parameter) => parameter.name),
+    placement: { frond: frond.name, runtime: remote ? 'remote' : 'local', ...(remote ? { remote } : {}) },
+    reach: reachOf(handler.deps, frond.name, served, options.remotes ?? {}),
+    exposure: {
+      surfaces: servedSurfaces(frond, handler).map((surface) => surface ?? 'default'),
+      adapters: exposedAdapters(handler, options.adapters),
+    },
+    outputClosed: output.closed,
+    semantics: EFFECTIVE_OPERATION_SEMANTICS,
+  };
+}
+
+/**
+ * An operation answers DATA — what JSON keeps. A declared output is converted by its fields; an
+ * undeclared one has nothing to convert it. Measured 2026-09-18: `{ at: new Date(0) }` reaches a
+ * local caller as a `Date` and a remote one as a string.
+ */
+function answersData({ frond, handler, diagnostics }: Resolving, name: string, contract: OperationContract): boolean {
+  if (contract.output || !contract.signature?.notData) return true;
+
+  const subject = `${handler.ctor.name}.${name}`;
+  diagnostics.push({
+    severity: 'blocking',
+    code: 'operation-output-not-data',
+    filePath: handler.filePath,
+    frond: frond.name,
+    subject,
+    message: `${subject}() answers ${contract.signature.notData}, which carries methods.\n`
+      + '  An operation answers data — what JSON keeps.\n'
+      + '  Declare the output as an entity, whose fields convert it, or answer what it produces.',
+  });
+
+  return false;
+}
+
+/** Stated in `frond.config.ts`, or read off the verb the name leads with — never guessed between two. */
+function kindOf({ frond, handler, diagnostics }: Resolving, name: string): OperationKind | undefined {
+  const stated = frond.operationsOverrides?.[name]?.kind;
+  if (stated) return stated;
+
+  const inference = inferOperationKind(name);
+  const inferred = new Set<OperationKind>();
+  if (inference.kind) inferred.add(inference.kind);
+  if (inference.queryMatches.length > 0) inferred.add('query');
+  if (inference.commandMatches.length > 0) inferred.add('command');
+  if (inferred.size === 1) return [...inferred][0];
+
+  const subject = `${handler.ctor.name}.${name}`;
+  const ambiguous = inferred.size > 1;
+  diagnostics.push({
+    severity: 'blocking',
+    code: ambiguous ? 'operation-kind-ambiguous' : 'operation-kind-unknown',
+    filePath: handler.filePath,
+    frond: frond.name,
+    subject,
+    message: ambiguous
+      ? `Cannot resolve the kind of ${subject}: its name carries query evidence `
+        + `(${inference.queryMatches.join(', ')}) and command evidence `
+        + `(${inference.commandMatches.join(', ')}). `
+        + `Declare operations.${name}.kind.`
+      : `Cannot resolve the kind of ${subject}: '${name}' leads with no known verb. `
+        + `Rename it to lead with one, or declare operations.${name}.kind in `
+        + `frond.config.ts.\n  query:   ${knownVerbs().query.join(', ')}`
+        + `\n  command: ${knownVerbs().command.join(', ')}`,
+  });
+
+  return undefined;
+}
+
+function parametersOf(contract: BoundContract): EffectiveParameter[] {
+  const params = contract.signature?.params ?? [];
+
+  return contract.binding.map((binding, position) => {
+    const param = params[position];
+    const undefinable = binding.optional || param?.optional === true || param?.type.undefined === true;
+
+    return {
+      position,
+      name: param?.name ?? binding.name,
+      type: param?.type.raw ?? null,
+      optional: undefinable,
+      nullable: param?.type.nullable === true,
+      undefinable,
+      binding,
+    };
+  });
+}
+
+function collectorsOf(
+  parameters: readonly EffectiveParameter[],
+  collectorsByType: Map<string, CollectorEntry[]>,
+  frond: FrondDescriptor,
+): EffectiveOperation['collectors'] {
+  return parameters.flatMap((parameter) => {
+    if (parameter.binding.source.kind !== 'collector') return [];
+    const collector = collectorsByType.get(parameter.binding.source.typeName)?.[0];
+
+    return collector ? [{
+      parameter: parameter.name,
+      typeName: collector.typeName,
+      className: collector.ctor.name,
+      frond: frond.name,
+      filePath: collector.filePath,
+    }] : [];
+  });
+}
+
+/** A dependency on a frond that actually runs elsewhere is a refusal, not the warning a future split deserves. */
+function placementRefusals(fronds: readonly FrondDescriptor[], options: EffectiveOperationOptions): Diagnostic[] {
+  return verify({ fronds }).map((misplaced) => {
+    const remoteBoundary = options.remotes?.[misplaced.frond] !== undefined
+      || options.remotes?.[misplaced.dependsOn.frond] !== undefined;
+
+    return remoteBoundary && misplaced.code === 'cross-frond-dependency'
+      ? { ...misplaced, severity: 'blocking' as const }
+      : misplaced;
+  });
+}
+
 function groupedCollectors(collectors: readonly CollectorEntry[]): Map<string, CollectorEntry[]> {
   const grouped = new Map<string, CollectorEntry[]>();
   for (const collector of collectors) {
@@ -294,6 +318,7 @@ function groupedCollectors(collectors: readonly CollectorEntry[]): Map<string, C
     sameName.push(collector);
     grouped.set(collector.typeName, sameName);
   }
+
   return grouped;
 }
 
@@ -303,7 +328,7 @@ function normalizeBinding(
   frond: FrondDescriptor,
   name: string,
   diagnostics: Diagnostic[],
-): (OperationContract & { binding: BindingPlan }) | undefined {
+): BoundContract | undefined {
   const params = contract.signature?.params ?? [];
   if (!contract.binding) {
     if (params.length === 0) return { ...contract, binding: [] };
@@ -315,6 +340,7 @@ function normalizeBinding(
       subject: `${handler.ctor.name}.${name}`,
       message: `${handler.ctor.name}.${name} declares ${params.length} parameter(s) and has no binding plan.`,
     });
+
     return undefined;
   }
   if (params.length === 0) return { ...contract, binding: contract.binding };
@@ -341,8 +367,10 @@ function normalizeBinding(
         + `${invalid.length ? `Invalid: ${invalid.map((param) => param.name).join(', ')}. ` : ''}`
         + `${extras.length ? `Unknown: ${extras.join(', ')}.` : ''}`,
     });
+
     return undefined;
   }
+
   return {
     ...contract,
     binding: params.map((param) => byName.get(param.name)![0]!),
@@ -387,6 +415,7 @@ function validateProvenance(
             + `${matches.map((parameter) => `${parameter.name}: ${parameter.type ?? 'unknown'}`).join('; ')} `
             + 'all match the resolved input contract. Declare an explicit binding plan.',
         });
+
         return false;
       }
       if (matches.length === 1) inferredBody.add(matches[0]!);
@@ -448,6 +477,7 @@ function validateProvenance(
         + 'local collector or resolved input schema. Declare an explicit binding.',
     });
   }
+
   return valid;
 }
 
@@ -458,6 +488,7 @@ function structural(type: TypeRef | undefined): boolean {
 function schemaMatches(schema: SchemaView, type: TypeRef | undefined): boolean {
   const names = new Set([schema.name, schema.derivation?.sourceName].filter(Boolean));
   if (type?.name && names.has(type.name)) return true;
+
   return type?.generics?.some((generic) => generic.name && names.has(generic.name)) ?? false;
 }
 
@@ -481,6 +512,7 @@ function implementationOf(
       message: `Operation ${handler.ctor.name}.${name} names handler '${override?.handlerName}', `
         + `but ${candidates.length} matching handlers were found.`,
     });
+
     return undefined;
   }
   const implementation = candidates[0]!;
@@ -498,8 +530,10 @@ function implementationOf(
       message: `Operation ${handler.ctor.name}.${name} resolves to `
         + `${implementation.ctor.name}.${method}, but that method does not exist.`,
     });
+
     return undefined;
   }
+
   return {
     className: implementation.ctor.name,
     address: implementation.address,
@@ -524,6 +558,7 @@ function effectiveOutput(
   const target = targetOf(handler.ctor) as { name?: string } | undefined;
   const address = target?.name ? lowerFirst(target.name) : handler.address;
   const entity = frond.entities.find((candidate) => candidate.name === address);
+
   return { ...(entity ? { schema: entity.entityClass } : {}), closed: false };
 }
 
@@ -532,6 +567,7 @@ function exposedAdapters(
   adapters: Record<string, boolean | undefined> | undefined,
 ): string[] {
   if (handler.exposed === false && !handler.surface) return [];
+
   return Object.entries(adapters ?? {})
     .filter(([, enabled]) => enabled === true)
     .map(([adapter]) => adapter)
@@ -540,16 +576,18 @@ function exposedAdapters(
 
 function uniqueDiagnostics(diagnostics: readonly Diagnostic[]): Diagnostic[] {
   const seen = new Set<string>();
+
   return diagnostics.filter((diagnostic) => {
     const key = [diagnostic.code, diagnostic.filePath, diagnostic.subject, diagnostic.message].join('\0');
     if (seen.has(key)) return false;
     seen.add(key);
+
     return true;
   });
 }
 
 /** The contract of every operation a handler serves — the three producers, merged once. */
-export function resolveContracts(
+function resolveContracts(
   handler: Pick<HandlerEntry, 'ctor' | 'operations'>,
   overrides: FrondDescriptor['operationsOverrides'],
   collectorTypeNames: Set<string>,

package/src/FougereConfig.ts

@@ -1,6 +1,6 @@
 import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
-import type { AuthConfig } from './boot/AuthConfig.js';
+import type { Extension } from './boot/Extension.js';
 import type { LogLevel } from './builtin/LogLevel.js';
 import type { ConventionsInput } from './ConventionsInput.js';
 import type { NameOf } from './NameOf.js';
@@ -29,28 +29,28 @@ export interface FougereConfig {
   fronds?: FrondsStated;
   /** What answers a port — a name, or the chain from the outside in. */
   ports?: PortChoice;
-  /** Auth declaration — picks a provider package and forwards options to it. */
-  auth?: AuthConfig;
+  /** The auth provider — an extension, which brings the frond its rows live in. */
+  auth?: Extension;
   /** Which protocol adapters this app serves. */
   adapters?: AdapterConfig;
 }
 
 const CONFIG_FILES = ['fougere.config.ts', 'fougere.config.js', 'fougere.config.mjs'];
 
+/** The config file a directory holds, if it holds one. */
+export function configFileIn(dir: string): string | undefined {
+  return CONFIG_FILES.map((file) => resolve(dir, file)).find((path) => existsSync(path));
+}
+
 async function loadConfigFrom(dir: string, fresh?: boolean): Promise<FougereConfig> {
-  const loader = getModuleLoader();
-  for (const file of CONFIG_FILES) {
-    const path = resolve(dir, file);
-    if (existsSync(path)) {
-      // A module is cached by its specifier, so a second load of an EDITED file hands
-      // back what was read the first time — measured, and it made re-reading a config
-      // return the config already in force. The loader owns its own cache, so it is the
-      // one told; the old module stays in memory, re-reading being for a change.
-      const mod = await loader(path, fresh ? { fresh } : undefined);
-      return ((mod as { default?: FougereConfig }).default ?? mod) as FougereConfig;
-    }
-  }
-  return {};
+  const path = configFileIn(dir);
+  if (!path) return {};
+
+  // A module is cached by its specifier, so a second load of an EDITED file hands back what
+  // was read the first time. The loader owns its own cache, so it is the one told.
+  const mod = await getModuleLoader()(path, fresh ? { fresh } : undefined);
+
+  return ((mod as { default?: FougereConfig }).default ?? mod) as FougereConfig;
 }
 
 /** Load the root fougere.config.{ts,js,mjs} from the given directory. */
@@ -92,5 +92,6 @@ function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): Fou
 export async function loadCascadedConfig(workspaceRoot: string, appRoot: string): Promise<FougereConfig> {
   const base = await loadConfig(workspaceRoot);
   if (resolve(workspaceRoot) === resolve(appRoot)) return base;
+
   return mergeGlobal(base, await loadConfig(appRoot));
 }

package/src/FrondConfig.ts

@@ -44,8 +44,10 @@ export async function loadFrondConfig(frondPath: string): Promise<FrondConfig |
     const path = resolve(frondPath, file);
     if (existsSync(path)) {
       const mod = await import(path);
+
       return mod.default ?? mod;
     }
   }
+
   return undefined;
 }

package/src/FrondDeclaration.ts

@@ -1,4 +1,5 @@
 import { lowerFirst, type SchemaView } from '@fougere/schema';
+import { addressOf } from './wire/Facade.js';
 import type { CollectorEntry } from './descriptor/CollectorEntry.js';
 import type { EntityEntry } from './descriptor/EntityEntry.js';
 import type { FrondDescriptor } from './descriptor/FrondDescriptor.js';
@@ -54,13 +55,6 @@ function statedOperations(h: Ctor | DeclaredHandler): Map<string, OperationContr
   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;
-
-  return lowerFirst(base);
-}
-
 /** What a declaration states about one frond. Everything else is derived from the classes. */
 export interface FrondDeclaration {
   entities?: SchemaView[];