@fougere/core 0.9.3-alpha.0 → 0.11.0-alpha.0

package/src/EffectiveOperation.ts

@@ -0,0 +1,62 @@
+import { EFFECTIVE_OPERATION_SEMANTICS } from './EffectiveOperationSemantics.js';
+import { type BindingPlan } from './wire/binding.js';
+import { type OperationContract } from './wire/OperationContract.js';
+import { type OperationKind } from './wire/OperationKind.js';
+import type { EffectiveParameter } from './EffectiveParameter.js';
+import type { EffectiveCollector } from './EffectiveCollector.js';
+
+export interface EffectiveOperation extends OperationContract {
+  /** Stable qualified identity: `blog/public/Post.publish`. */
+  id: string;
+  /** Human-facing identity independent of placement: `Post.publish`. */
+  operation: string;
+  name: string;
+  kind: OperationKind;
+  kindSource: 'explicit' | 'convention';
+  handler: {
+    className: string;
+    address: string;
+    filePath: string;
+  };
+  /** The class and method that execute after an optional operation override. */
+  implementation: {
+    className: string;
+    address: string;
+    method: string;
+    filePath: string;
+  };
+  /** Every valid operation has a plan, including the empty plan. */
+  binding: BindingPlan;
+  parameters: EffectiveParameter[];
+  collectors: EffectiveCollector[];
+  contexts: string[];
+  placement: {
+    frond: string;
+    runtime: 'local' | 'remote';
+    remote?: string;
+  };
+  /**
+   * What running this op reaches, and how much of that crosses a process.
+   *
+   * `placement` says where the op ANSWERS; this says where it GOES. The pair is what every
+   * number a process hard-codes is really a function of — how often a trace is sampled, where
+   * a latency histogram's bounds should sit, what a load threshold may assume. An op that
+   * answers here and hops twice is not the same subject as one that answers here and hops none.
+   *
+   * Read from the handler, never from the op: a dependency is declared on the constructor, so
+   * the crossing belongs to the CLASS. Every op of one handler reaches the same fronds, and
+   * saying otherwise would dress a structural fact as a precise effect.
+   */
+  reach: {
+    fronds: { frond: string; runtime: 'local' | 'remote' }[];
+    /** How many of them are a process away — zero when everything it reaches runs here. */
+    hops: number;
+  };
+  exposure: {
+    surfaces: string[];
+    adapters: string[];
+  };
+  /** Whether output is an explicitly closed per-operation view. */
+  outputClosed: boolean;
+  semantics: typeof EFFECTIVE_OPERATION_SEMANTICS;
+}

package/src/{effective-operation.ts → EffectiveOperationModel.ts}

@@ -1,103 +1,26 @@
-/** The operation model after every declaration and convention has been resolved. */
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 import { statementDrift } 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';
-import type { CollectorEntry, FrondDescriptor, HandlerEntry } from './descriptor/frond.js';
+import { EFFECTIVE_OPERATION_SEMANTICS } from './EffectiveOperationSemantics.js';
+import type { CollectorEntry } from './descriptor/CollectorEntry.js';
+import type { FrondDescriptor } from './descriptor/FrondDescriptor.js';
+import type { HandlerEntry } from './descriptor/HandlerEntry.js';
 import { servedSurfaces } from './descriptor/surface.js';
-import type { ScanDiagnostic } from './scan.js';
+import type { Diagnostic } from './diagnostic.js';
 import { verify } from './verify.js';
-import {
-  inferOperationKind,
-  type OperationContract,
-  type OperationKind,
-  type OperationsMap,
-  type TypeRef,
-  knownVerbs,
-} from './wire/operation.js';
+import { inferOperationKind, knownVerbs, type OperationContract } from './wire/OperationContract.js';
+import { type OperationKind } from './wire/OperationKind.js';
+import { type OperationsMap } from './wire/OperationsMap.js';
+import { type TypeRef } from './wire/TypeRef.js';
+import type { EffectiveParameter } from './EffectiveParameter.js';
+import type { EffectiveOperation } from './EffectiveOperation.js';
+import type { EffectiveOperationsMap } from './EffectiveOperationsMap.js';
+import type { EffectiveOperationOptions } from './EffectiveOperationOptions.js';
 
 type Binding = BindingPlan[number];
 
-export interface EffectiveParameter {
-  /** Position in the TypeScript signature. Never used to infer provenance. */
-  position: number;
-  name: string;
-  type: string | null;
-  optional: boolean;
-  nullable: boolean;
-  /** `?` and `| undefined` both mean canonical absence. */
-  undefinable: boolean;
-  /** The resolved provenance of this parameter. */
-  binding: Binding;
-}
-
-export interface EffectiveCollector {
-  parameter: string;
-  typeName: string;
-  className: string;
-  frond: string;
-  filePath: string;
-}
-
-export interface EffectiveOperation extends OperationContract {
-  /** Stable qualified identity: `blog/public/Post.publish`. */
-  id: string;
-  /** Human-facing identity independent of placement: `Post.publish`. */
-  operation: string;
-  name: string;
-  kind: OperationKind;
-  kindSource: 'explicit' | 'convention';
-  handler: {
-    className: string;
-    address: string;
-    filePath: string;
-  };
-  /** The class and method that execute after an optional operation override. */
-  implementation: {
-    className: string;
-    address: string;
-    method: string;
-    filePath: string;
-  };
-  /** Every valid operation has a plan, including the empty plan. */
-  binding: BindingPlan;
-  parameters: EffectiveParameter[];
-  collectors: EffectiveCollector[];
-  contexts: string[];
-  placement: {
-    frond: string;
-    runtime: 'local' | 'remote';
-    remote?: string;
-  };
-  /**
-   * What running this op reaches, and how much of that crosses a process.
-   *
-   * `placement` says where the op ANSWERS; this says where it GOES. The pair is what every
-   * number a process hard-codes is really a function of — how often a trace is sampled, where
-   * a latency histogram's bounds should sit, what a load threshold may assume. An op that
-   * answers here and hops twice is not the same subject as one that answers here and hops none.
-   *
-   * Read from the handler, never from the op: a dependency is declared on the constructor, so
-   * the crossing belongs to the CLASS. Every op of one handler reaches the same fronds, and
-   * saying otherwise would dress a structural fact as a precise effect.
-   */
-  reach: {
-    fronds: { frond: string; runtime: 'local' | 'remote' }[];
-    /** How many of them are a process away — zero when everything it reaches runs here. */
-    hops: number;
-  };
-  exposure: {
-    surfaces: string[];
-    adapters: string[];
-  };
-  /** Whether output is an explicitly closed per-operation view. */
-  outputClosed: boolean;
-  semantics: typeof EFFECTIVE_OPERATION_SEMANTICS;
-}
-
-export type EffectiveOperationsMap = Map<string, EffectiveOperation>;
-
 /**
  * Where an op's work goes: the fronds its handler reaches, and how many are a process away.
  *
@@ -118,19 +41,6 @@ function reachOf(
   return { fronds, hops: fronds.filter((one) => one.runtime === 'remote').length };
 }
 
-/** The absence rules every door normalises to before the handler is invoked. */
-export const EFFECTIVE_OPERATION_SEMANTICS = Object.freeze({
-  optional: 'undefined' as const,
-  undefined: 'absence' as const,
-  null: 'explicit-value' as const,
-  jsonObjectUndefined: 'omitted' as const,
-});
-
-export interface EffectiveOperationOptions {
-  diagnostics?: readonly ScanDiagnostic[];
-  remotes?: Record<string, string>;
-  adapters?: Record<string, boolean | undefined>;
-}
 
 /**
  * One resolved program. The handler map preserves object identity from the scan, so the
@@ -138,13 +48,13 @@ export interface EffectiveOperationOptions {
  */
 export class EffectiveOperationModel {
   readonly operations: EffectiveOperation[];
-  readonly diagnostics: ScanDiagnostic[];
-  readonly resolutionDiagnostics: ScanDiagnostic[];
+  readonly diagnostics: Diagnostic[];
+  readonly resolutionDiagnostics: Diagnostic[];
 
   constructor(
     operations: EffectiveOperation[],
-    diagnostics: ScanDiagnostic[],
-    resolutionDiagnostics: ScanDiagnostic[],
+    diagnostics: Diagnostic[],
+    resolutionDiagnostics: Diagnostic[],
     private readonly byHandler: Map<HandlerEntry, EffectiveOperationsMap>,
   ) {
     this.operations = operations;
@@ -164,7 +74,7 @@ export function resolveEffectiveOperations(
 ): EffectiveOperationModel {
   const operations: EffectiveOperation[] = [];
   const byHandler = new Map<HandlerEntry, EffectiveOperationsMap>();
-  const resolutionDiagnostics: ScanDiagnostic[] = [];
+  const resolutionDiagnostics: Diagnostic[] = [];
   const scanDiagnostics = [...(options.diagnostics ?? [])];
   const schemas = new Map(
     fronds.flatMap((frond) => frond.entities.map((entity) => [entity.name, entity.entityClass] as const)),
@@ -341,19 +251,12 @@ export function resolveEffectiveOperations(
 
   // 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 violation of verify({ fronds })) {
-    const remoteBoundary = options.remotes?.[violation.frond] !== undefined
-      || options.remotes?.[violation.dependsOn.frond] !== undefined;
-    resolutionDiagnostics.push({
-      severity: remoteBoundary && violation.rule === 'cross-frond-dependency'
-        ? 'blocking'
-        : violation.severity,
-      code: violation.rule,
-      filePath: violation.filePath,
-      frond: violation.frond,
-      subject: violation.subject,
-      message: violation.message,
-    });
+  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);
   }
 
   const resolution = uniqueDiagnostics(resolutionDiagnostics);
@@ -380,7 +283,7 @@ function normalizeBinding(
   handler: HandlerEntry,
   frond: FrondDescriptor,
   name: string,
-  diagnostics: ScanDiagnostic[],
+  diagnostics: Diagnostic[],
 ): (OperationContract & { binding: BindingPlan }) | undefined {
   const params = contract.signature?.params ?? [];
   if (!contract.binding) {
@@ -435,7 +338,7 @@ function validateProvenance(
   contract: OperationContract & { binding: BindingPlan },
   parameters: EffectiveParameter[],
   localCollectors: Map<string, CollectorEntry[]>,
-  diagnostics: ScanDiagnostic[],
+  diagnostics: Diagnostic[],
 ): boolean {
   let valid = true;
   const declared = (handler.ctor as { __ops?: Record<string, OperationContract> }).__ops?.[name];
@@ -543,7 +446,7 @@ function implementationOf(
   frond: FrondDescriptor,
   handler: HandlerEntry,
   name: string,
-  diagnostics: ScanDiagnostic[],
+  diagnostics: Diagnostic[],
 ): EffectiveOperation['implementation'] | undefined {
   const override = frond.operationsOverrides?.[name];
   const candidates = override?.handlerName
@@ -616,7 +519,7 @@ function exposedAdapters(
     .sort();
 }
 
-function uniqueDiagnostics(diagnostics: readonly ScanDiagnostic[]): ScanDiagnostic[] {
+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');

package/src/EffectiveOperationOptions.ts

@@ -0,0 +1,7 @@
+import type { Diagnostic } from './diagnostic.js';
+
+export interface EffectiveOperationOptions {
+  diagnostics?: readonly Diagnostic[];
+  remotes?: Record<string, string>;
+  adapters?: Record<string, boolean | undefined>;
+}

package/src/EffectiveOperationSemantics.ts

@@ -0,0 +1,7 @@
+/** The absence rules every facade normalises to before the handler is invoked. */
+export const EFFECTIVE_OPERATION_SEMANTICS = Object.freeze({
+  optional: 'undefined' as const,
+  undefined: 'absence' as const,
+  null: 'explicit-value' as const,
+  jsonObjectUndefined: 'omitted' as const,
+});

package/src/EffectiveOperationsMap.ts

@@ -0,0 +1,3 @@
+import type { EffectiveOperation } from './EffectiveOperation.js';
+
+export type EffectiveOperationsMap = Map<string, EffectiveOperation>;

package/src/EffectiveParameter.ts

@@ -0,0 +1,13 @@
+import type { Binding } from './Binding.js';
+export interface EffectiveParameter {
+  /** Position in the TypeScript signature. Never used to infer provenance. */
+  position: number;
+  name: string;
+  type: string | null;
+  optional: boolean;
+  nullable: boolean;
+  /** `?` and `| undefined` both mean canonical absence. */
+  undefinable: boolean;
+  /** The resolved provenance of this parameter. */
+  binding: Binding;
+}

package/src/EntityNode.ts

@@ -0,0 +1,6 @@
+export interface EntityNode {
+  name: string;
+  frond: string;
+  refs: string[];       // entity names this entity references
+  referencedBy: string[]; // entity names that reference this entity
+}

package/src/{config-loader.ts → FougereConfig.ts}

@@ -1,17 +1,18 @@
 import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
-import type { AuthConfig } from './boot/auth.js';
-import type { LogLevel } from './builtin/logger.js';
-import type { ConventionsInput } from './conventions.js';
+import type { AuthConfig } from './boot/AuthConfig.js';
+import type { LogLevel } from './builtin/LogLevel.js';
+import type { ConventionsInput } from './ConventionsInput.js';
+import type { NameOf } from './NameOf.js';
+import type { PortChoice } from './PortChoice.js';
 import { getModuleLoader } from './loader.js';
-
-// ── Types ────────────────────────────────────────
+import type { AdapterConfig } from './AdapterConfig.js';
 
 export interface FougereConfig {
   /** Database configuration — the DEFAULT source, the one an entity lands in unnamed. */
   db?: 'sqlite' | { dialect: 'sqlite'; path?: string } | false;
   /** The other places rows live — a name, an engine, and the entities it holds. */
-  sources?: Record<string, { dialect?: 'sqlite'; path?: string; entities: string[] }>;
+  sources?: Record<string, { dialect?: 'sqlite'; path?: string; entities: NameOf<'entity'>[] }>;
   /**
    * The names the scan reads instead of deriving them — the import scope, the fronds directory,
    * the seven convention directories.
@@ -19,28 +20,22 @@ export interface FougereConfig {
   conventions?: ConventionsInput;
   /** How much every logger says. */
   logLevel?: LogLevel;
-  /** Remote fronds — frondName → base URL. */
+  /**
+   * Remote fronds — frondName → base URL.
+   *
+   * The KEY is not narrowed to `NameOf<'frond'>`, and that is a choice: constraining it means
+   * making every key optional, which puts `| undefined` on the values and changes what six
+   * readers here already treat as present. The name is checked at boot instead.
+   */
   remotes?: Record<string, string>;
   /** What answers a port — a name, or the chain from the outside in. */
-  ports?: Record<string, string | readonly string[]>;
+  ports?: PortChoice;
   /** Auth declaration — picks a provider package and forwards options to it. */
   auth?: AuthConfig;
   /** Which protocol adapters this app serves. */
   adapters?: AdapterConfig;
 }
 
-/** Protocol adapters, by the name of the package that provides them. */
-export interface AdapterConfig {
-  /** `@fougere/adapter-rest` — REST under `/api/{frond}/{plural}`. */
-  rest?: boolean;
-  /** `@fougere/adapter-graphql` — a GraphQL schema over the same operations. */
-  graphql?: boolean;
-  /** A surface of your own; the framework only records that you declared it. */
-  [adapter: string]: boolean | undefined;
-}
-
-// ── Loading ──────────────────────────────────────
-
 const CONFIG_FILES = ['fougere.config.ts', 'fougere.config.js', 'fougere.config.mjs'];
 
 async function loadConfigFrom(dir: string, fresh?: boolean): Promise<FougereConfig> {

package/src/FougereNames.ts

@@ -0,0 +1,2 @@
+/** The names the scan found, per kind. Augmented from the generated file, empty otherwise. */
+export interface FougereNames {}

package/src/FougerePorts.ts

@@ -0,0 +1,7 @@
+/**
+ * Each port, and the classes that extend it — a RELATION, not two lists.
+ *
+ * Two unions would accept `ports: { Payment: 'FileStorage' }`: both names exist, and nothing
+ * would say that one does not answer the other. What the boot refuses, the type refuses first.
+ */
+export interface FougerePorts {}

package/src/{frond-config.ts → FrondConfig.ts}

@@ -1,55 +1,17 @@
 import { resolve } from 'node:path';
+import type { NameOf } from './NameOf.js';
 import { existsSync } from 'node:fs';
-import type { EntityConstructor, SchemaView } from '@fougere/schema';
-import type { BindingPlan } from './wire/binding.js';
-
-// ── Types ────────────────────────────────────────
-
-/** Per-operation override. */
-export interface OperationOverride {
-  /** Force operation kind, over the naming convention (`isReadOp`). */
-  kind?: 'query' | 'command';
-  /** The GraphQL root field this op answers to. */
-  graphql?: string;
-  /**
-   * Where this op answers over REST — the dual of `graphql:`, and the frond's to say for
-   * the same reason: how an operation is CALLED belongs beside it, not in whatever host
-   * mounts the router. The prefix stays the host's: naming is the frond's, mounting is not.
-   */
-  rest?: { method?: string; path?: string; status?: number };
-  /**
-   * Handler class to delegate to (overrides the default `{Entity}Handler` lookup).
-   * Class name is used to resolve from DI. E.g. `ArchiveHandler` → `app.resolve('ArchiveHandler')`.
-   */
-  handler?: EntityConstructor;
-  /** Method name on `handler` (defaults to the operation name). */
-  method?: string;
-  /** CASL ability check (e.g. */
-  policy?: string;
-
-  // ── The contract itself — see the note above ──
-
-  /** What validates the input. The view carries its own mode (`partial()` → patch). */
-  input?: SchemaView;
-  /**
-   * Where each argument is read from — states what the scan would otherwise derive
-   * from the method signature. An empty array is meaningful: "this op takes nothing".
-   */
-  binding?: BindingPlan;
-
-  /** Per-operation output view, below prefab declarations and above handler/entity defaults. */
-  output?: SchemaView;
-}
+import type { OperationOverride } from './OperationOverride.js';
 
 export interface FrondConfig {
   /** Class names exposed as the frond's public contract (all surfaces). */
-  expose?: string[];
+  expose?: (NameOf<'handler'> | NameOf<'entity'>)[];
   /** The entities this frond may read ACROSS sources, by name. */
-  reads?: string[];
+  reads?: NameOf<'entity'>[];
   /** Per-surface entity lists. Overrides default deduction for each named surface. */
-  surfaces?: Record<string, string[]>;
+  surfaces?: Record<string, NameOf<'entity'>[]>;
   /** Interface → implementation bindings for DI (e.g. { Database: 'SqliteDatabase' }). */
-  bindings?: Record<string, string>;
+  bindings?: Record<string, NameOf<'provider'>>;
   /**
    * The ops that FINISH a fact, in the order they run — by class name, keyed by fact.
    *
@@ -57,13 +19,13 @@ export interface FrondConfig {
    * fact itself and it has one owner. Without it two links refuse: nothing would say which
    * ran first, and scan order is not an answer.
    */
-  pipes?: Record<string, string[]>;
+  pipes?: Record<NameOf<'entity'>, NameOf<'handler'>[]>;
   /**
    * How far a middleware reaches, by class name. A middleware answers for its own frond
    * without being named here; `'app'` is the exception, and it is stated by the frond
    * that decides for the others.
    */
-  middlewares?: Record<string, 'frond' | 'app'>;
+  middlewares?: Record<NameOf<'middleware'>, 'frond' | 'app'>;
   /** Per-operation overrides. Key = operation name (method name on a handler). */
   operations?: Record<string, OperationOverride>;
 }

package/src/{declare.ts → FrondDeclaration.ts}

@@ -1,44 +1,22 @@
-/** A frond stated by its author, for an app that will not scan. */
 import { lowerFirst, type SchemaView } from '@fougere/schema';
-import type {
-  CollectorEntry, EntityEntry, FrondDescriptor, HandlerEntry, MiddlewareEntry,
-  PresenterEntry, ProviderEntry, SeedEntry,
-} from './descriptor/frond.js';
-import { DEFAULT_CONVENTIONS } from './conventions.js';
+import type { CollectorEntry } from './descriptor/CollectorEntry.js';
+import type { EntityEntry } from './descriptor/EntityEntry.js';
+import type { FrondDescriptor } from './descriptor/FrondDescriptor.js';
+import type { HandlerEntry } from './descriptor/HandlerEntry.js';
+import type { MiddlewareEntry } from './descriptor/MiddlewareEntry.js';
+import type { PresenterEntry } from './descriptor/PresenterEntry.js';
+import type { ProviderEntry } from './descriptor/ProviderEntry.js';
+import type { SeedEntry } from './descriptor/SeedEntry.js';
+import { DEFAULT_CONVENTIONS } from './Conventions.js';
 import { getPresenterFields } from './prefab/presenter.js';
-import type { OperationContract } from './wire/operation.js';
+import type { OperationContract } from './wire/OperationContract.js';
+import type { DeclaredSubject } from './DeclaredSubject.js';
+import type { DeclaredHandler } from './DeclaredHandler.js';
+import type { Declared } from './Declared.js';
 
 /** A class, as a declaration hands it over: the constructor itself. */
 type Ctor = new (...args: never[]) => unknown;
 
-/** What a subject needs beyond its class, when its constructor names a frame or a port. */
-export interface DeclaredSubject {
-  ctor: Ctor;
-  deps?: string[];
-}
-
-/** A handler, and the surface it answers on when it is not the default one. */
-export interface DeclaredHandler extends DeclaredSubject {
-  /**
-   * The scan reads this from the directory (`handlers/public/`), so a statement has to say it: two
-   * handlers over one entity collide on their address otherwise, and the refusal names the same
-   * 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 & {
-  /** 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);
 
 /**
@@ -57,6 +35,7 @@ function subjectOf(ctor: Ctor, kind: string): { name: string } {
 
   return subject;
 }
+
 const depsOf = (d: Declared): string[] => (typeof d === 'function' ? [] : d.deps ?? []);
 
 /**

package/src/FrondIdentity.ts

@@ -0,0 +1,7 @@
+/** What a deployment hands a frond that CALLS: its own key, and the root's word for it. */
+export interface FrondIdentity {
+  /** The frond's private key, PEM (PKCS#8). */
+  privateKey: string;
+  /** The root's statement binding this frond's name to its public key. */
+  grant: string;
+}

package/src/NameOf.ts

@@ -0,0 +1,12 @@
+import type { FougereNames } from './FougereNames.js';
+
+/**
+ * One kind's union, or `string` where nothing was generated.
+ *
+ * A conditional and never `Partial<FougereNames>`: an un-augmented interface makes that
+ * `Partial<{}>`, which in TypeScript means "anything non-nullish" — the silent hole `adapters:`
+ * already has. Falling back to `string` is what a config had before this file existed.
+ */
+export type NameOf<K extends string> = FougereNames extends Record<K, infer Found extends string>
+  ? Found
+  : string;

package/src/OperationOverride.ts

@@ -0,0 +1,38 @@
+import type { EntityConstructor, SchemaView } from '@fougere/schema';
+import type { BindingPlan } from './wire/binding.js';
+
+/** Per-operation override. */
+export interface OperationOverride {
+  /** Force operation kind, over the naming convention (`isReadOp`). */
+  kind?: 'query' | 'command';
+  /** The GraphQL root field this op answers to. */
+  graphql?: string;
+  /**
+   * Where this op answers over REST — the dual of `graphql:`, and the frond's to say for
+   * the same reason: how an operation is CALLED belongs beside it, not in whatever host
+   * mounts the router. The prefix stays the host's: naming is the frond's, mounting is not.
+   */
+  rest?: { method?: string; path?: string; status?: number };
+  /**
+   * Handler class to delegate to (overrides the default `{Entity}Handler` lookup).
+   * Class name is used to resolve from DI. E.g. `ArchiveHandler` → `app.resolve('ArchiveHandler')`.
+   */
+  handler?: EntityConstructor;
+  /** Method name on `handler` (defaults to the operation name). */
+  method?: string;
+  /** CASL ability check (e.g. */
+  policy?: string;
+
+  // ── The contract itself — see the note above ──
+
+  /** What validates the input. The view carries its own mode (`partial()` → patch). */
+  input?: SchemaView;
+  /**
+   * Where each argument is read from — states what the scan would otherwise derive
+   * from the method signature. An empty array is meaningful: "this op takes nothing".
+   */
+  binding?: BindingPlan;
+
+  /** Per-operation output view, below prefab declarations and above handler/entity defaults. */
+  output?: SchemaView;
+}

package/src/PortChoice.ts

@@ -0,0 +1,13 @@
+import type { FougerePorts } from './FougerePorts.js';
+import type { AnswerFor } from './AnswerFor.js';
+
+/**
+ * The ports of this app, each mapped to what may answer it.
+ *
+ * `keyof FougerePorts` is `never` before generation, and a mapped type over `never` is `{}` —
+ * which would refuse every key rather than accept any. So the empty case widens to the plain
+ * record the config had, and only a generated file narrows it.
+ */
+export type PortChoice = keyof FougerePorts extends never
+  ? Record<string, string | readonly string[]>
+  : { [Port in keyof FougerePorts]?: AnswerFor<Port & string> | readonly AnswerFor<Port & string>[] };