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

package/src/dispatch/{RemoteRouteResolver.ts → remoteRoutes.ts}

@@ -1,21 +1,19 @@
-import type { RouteAddress } from '../contract/RouteAddress.js';
 import { OperationRoute } from './OperationRoute.js';
-import type { Route } from './Route.js';
 import type { RouteResolver } from './RouteResolver.js';
 
 type RemoteFacade = Record<string, Function>;
 export type RemoteFacadeResolver = (entity: string) => RemoteFacade | undefined;
 
-/** Builds a remote route on the first call, after the remote façade can be resolved. */
-export class RemoteRouteResolver implements RouteResolver {
-  constructor(private readonly facades: RemoteFacadeResolver) {}
-
-  resolve(address: RouteAddress): Route | undefined {
+/** Builds a remote route on the first call, once the remote façade can be resolved. */
+export function remoteRoutes(facades: RemoteFacadeResolver): RouteResolver {
+  return (address) => {
     if (address.surface !== undefined) return undefined;
 
-    const facade = this.facades(address.entity);
+    const facade = facades(address.entity);
     const operation = facade?.[address.operation];
+
     if (typeof operation !== 'function') return undefined;
+
     return new OperationRoute('remote', address, (call) => operation(call.invocation));
-  }
+  };
 }

package/src/dispatch/routeNotFound.ts

@@ -0,0 +1,33 @@
+import type { Call } from '../wire/call.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+import type { Route } from './Route.js';
+import type { RoutePolicy } from './RoutePolicy.js';
+
+/** The operations this dispatcher would have served for the entity the call names. */
+export function servedOperations(
+  call: Call,
+  routes: readonly Route[],
+  policy?: RoutePolicy,
+): readonly string[] {
+  return routes
+    .filter((route) => !policy || policy.accepts(route))
+    .filter((route) => route.address.entity === call.address.entity)
+    .filter((route) => route.kind === 'system' || route.address.surface === call.address.surface)
+    .map((route) => route.address.operation);
+}
+
+/** `Unknown operation 'draft' on 'post'. It serves list, findById.` */
+export function routeNotFound(
+  call: Call,
+  served: readonly string[],
+): FougereError {
+  const { entity, operation } = call.address;
+  const message = entity === 'rpc'
+    ? `Unknown rpc operation '${operation}'. `
+      + (served.length ? `It serves ${served.join(', ')}.` : 'It serves nothing.')
+    : served.length
+      ? `Unknown operation '${operation}' on '${entity}'. It serves ${served.join(', ')}.`
+      : `No route serves '${call.address}'`;
+
+  return new FougereError({ code: ErrorCode.NOT_FOUND, message, entity, operation });
+}

package/src/dispatch/validateInput.ts

@@ -0,0 +1,28 @@
+import { InputValidator, type SchemaView } from '@fougere/schema';
+import type { InvocationContext } from '../wire/Invocation.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+
+/** Validates and decodes the input declared by one operation contract. */
+export function validateInput(
+  schema: SchemaView | undefined,
+  invocation: InvocationContext,
+  entity: string,
+  operation: string,
+): InvocationContext {
+  if (!schema || invocation.input === undefined || invocation.input === null) return invocation;
+
+  const result = InputValidator.of(schema.getFields(), { patch: schema.getOpts().patch })
+    .validate(invocation.input);
+
+  if (!result.success) {
+    throw new FougereError({
+      code: ErrorCode.VALIDATION_FAILED,
+      message: result.errors.map((error) => `${error.path}: ${error.message}`).join(', '),
+      details: result.errors,
+      entity,
+      operation,
+    });
+  }
+
+  return { ...invocation, input: result.data };
+}

package/src/effective-operation.ts

@@ -1,10 +1,4 @@
-/**
- * The operation model after every declaration and convention has been resolved.
- *
- * The scanner produces evidence. This module turns that evidence into the one table
- * boot, check, explain and protocol projections consume. It is deliberately pure: no
- * container, filesystem, migration or handler construction is involved.
- */
+/** 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 { computeBindingPlan, type BindingPlan } from './wire/binding.js';
@@ -232,7 +226,7 @@ export function resolveEffectiveOperations(
           resolutionDiagnostics,
         )) continue;
 
-        // A fact is judged by the entity it names. This used to be patched into the
+        // 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.
         let input = contract.input;
         if (!input) {
@@ -326,9 +320,9 @@ export function resolveEffectiveOperations(
 function groupedCollectors(collectors: readonly CollectorEntry[]): Map<string, CollectorEntry[]> {
   const grouped = new Map<string, CollectorEntry[]>();
   for (const collector of collectors) {
-    const held = grouped.get(collector.typeName) ?? [];
-    held.push(collector);
-    grouped.set(collector.typeName, held);
+    const sameName = grouped.get(collector.typeName) ?? [];
+    sameName.push(collector);
+    grouped.set(collector.typeName, sameName);
   }
   return grouped;
 }
@@ -359,9 +353,9 @@ function normalizeBinding(
   // Array order is never allowed to become semantic authority.
   const byName = new Map<string, Binding[]>();
   for (const binding of contract.binding) {
-    const held = byName.get(binding.name) ?? [];
-    held.push(binding);
-    byName.set(binding.name, held);
+    const sameName = byName.get(binding.name) ?? [];
+    sameName.push(binding);
+    byName.set(binding.name, sameName);
   }
   const expected = new Set(params.map((param) => param.name));
   const invalid = params.filter((param) => (byName.get(param.name)?.length ?? 0) !== 1);
@@ -403,14 +397,14 @@ function validateProvenance(
   const ambiguousInput = diagnostics.some((diagnostic) =>
     diagnostic.code === 'input-contract-ambiguous'
     && diagnostic.subject === `${handler.ctor.name}.${name}`);
-  const body = parameters.filter((parameter) => parameter.binding.source.kind === 'body');
+  const fromInput = parameters.filter((parameter) => parameter.binding.source.kind === 'input');
   const inferredBody = new Set<EffectiveParameter>();
 
   if (!explicitBinding && !ambiguousInput && contract.input) {
-    if (body.length === 1) {
-      inferredBody.add(body[0]!);
-    } else if (body.length > 1) {
-      const matches = body.filter((parameter) =>
+    if (fromInput.length === 1) {
+      inferredBody.add(fromInput[0]!);
+    } else if (fromInput.length > 1) {
+      const matches = fromInput.filter((parameter) =>
         schemaMatches(contract.input!, contract.signature?.params[parameter.position]?.type));
       if (matches.length > 1) {
         diagnostics.push({
@@ -419,7 +413,7 @@ function validateProvenance(
           filePath: handler.filePath,
           frond: frond.name,
           subject: `${handler.ctor.name}.${name}`,
-          message: `Cannot resolve which parameter of ${handler.ctor.name}.${name} receives the body: `
+          message: `Cannot resolve which parameter of ${handler.ctor.name}.${name} receives the input: `
             + `${matches.map((parameter) => `${parameter.name}: ${parameter.type ?? 'unknown'}`).join('; ')} `
             + 'all match the resolved input contract. Declare an explicit binding plan.',
         });
@@ -430,9 +424,9 @@ function validateProvenance(
   }
 
   // A type written with an inline object literal names nothing a collector can register
-  // under, so the parameter IS the body. Only a NAMED type can be the wrong-frond
+  // under, so the parameter IS the input. Only a NAMED type can be the wrong-frond
   // substitution the refusal below exists for.
-  for (const parameter of body) {
+  for (const parameter of fromInput) {
     if (structural(contract.signature?.params[parameter.position]?.type)) inferredBody.add(parameter);
   }
 
@@ -455,7 +449,7 @@ function validateProvenance(
       }
       continue;
     }
-    if (source.kind !== 'body' || explicitBinding || ambiguousInput) continue;
+    if (source.kind !== 'input' || explicitBinding || ambiguousInput) continue;
 
     const typeName = lowerFirst(contract.signature?.params[parameter.position]?.type.name ?? '');
     const elsewhere = fronds.flatMap((candidate) => candidate === frond
@@ -463,12 +457,12 @@ function validateProvenance(
       : candidate.collectors.filter((collector) => collector.typeName === typeName));
     if (elsewhere.length > 0) {
       // verify() supplies the more complete topology diagnostic; do not also call this
-      // an unknown body.
+      // an unknown input.
       continue;
     }
 
-    // An inferred body must be backed by exactly one resolved interpretation. With one
-    // body, the input itself is sufficient evidence; with several, exactly one type may
+    // An inferred input must be backed by exactly one resolved interpretation. With one
+    // input, the value itself is sufficient evidence; with several, exactly one type may
     // match. Explicit plans are authoritative because they state every provenance.
     const recognized = explicitBinding || inferredBody.has(parameter);
     if (recognized) continue;
@@ -596,30 +590,7 @@ function uniqueDiagnostics(diagnostics: readonly ScanDiagnostic[]): ScanDiagnost
   });
 }
 
-/**
- * The contract of every operation a handler serves — the three producers, merged once.
- *
- * This lived inline in `buildFacade`, which made the façade the only thing that could
- * answer "what is this op's contract, really?". Anything else asking — a checker, a
- * client generator, a descriptor — had to redo the merge, and a second opinion that
- * drifts reports nothing wrong while looking at the wrong thing.
- *
- * The order is a claim about authority, not a convenience:
- *
- *   1. a prefab DECLARES what it built (`Crud(E).__ops`) — runtime, so it survives a
- *      scan that resolved nothing;
- *   2. the scan DERIVES from source — a method written in this very file is the
- *      author's own word and beats everything; a method it merely READ on a base
- *      class is a guess about someone else's code, and yields to that code's own
- *      declaration;
- *   3. `frond.config.ts` STATES — the most explicit statement, made by whoever
- *      assembles the app, and the only answer for an op inherited from an installed
- *      base class the workspace-only scan cannot see. Merged per key, so stating a
- *      `binding` alone does not erase an `input` the scan found.
- *
- * Pure: no container, no instance, no disk. The binding plan is resolved here, so
- * nothing downstream ever meets an AST.
- */
+/** The contract of every operation a handler serves — the three producers, merged once. */
 export function resolveContracts(
   handler: Pick<HandlerEntry, 'ctor' | 'operations'>,
   overrides: FrondDescriptor['operationsOverrides'],

package/src/emit.ts

@@ -1,61 +1,13 @@
-/**
- * Announcing a fact — the half of the topology `remotes:` never covered.
- *
- * Every other call in Fougere names **one** recipient: `remotes` names one address per
- * frond, `Facade<T>` resolves one door. `Emit<T>` names a **subject** instead, and the
- * number of readers is not the emitter's business.
- *
- * ```ts
- * constructor(private published: Emit<PostPublished>) {}
- * await this.published({ id, title });          // I say it happened. I do not know who cares.
- *
- * async reindex(fact: Fact<PostPublished>) {}   // any handler, any frond. Nothing to register.
- * ```
- *
- * **It is a resolver, not a channel.** A bus moves messages — it has a queue, an envelope
- * format, a delivery semantic. This has none of that: it answers *who*, then hands over to
- * the call path that already exists. It is `resolve` returning N things instead of one.
- * That is also why temporal decoupling stays out of reach: a resolver holds nothing. The
- * day at-least-once is wanted, a real channel goes UNDER this, in the transport — the
- * dispatch line becomes a publish and a consumer calls the same door on the far side.
- */
+/** Announcing a fact — the half of the topology `remotes:` never covered. */
 import { lowerFirst } from '@fougere/schema';
 
-/**
- * What an emitter injects. Resolved by type, like `Storage<Post>` and `Facade<T>`.
- *
- * The returned promise settles when the fact has been **dispatched**, never when it has
- * been handled: a subscriber's failure is its own. The `EventBus` this replaces did
- * `await Promise.all(handlers)` and handed their rejections back, which made a publication
- * hostage to its own indexer.
- */
+/** What an emitter injects. */
 export type Emit<T> = (fact: T) => Promise<void>;
 
-/**
- * What a subscriber accepts — and what it PROMISES about itself.
- *
- * Not merely "I subscribe". Push is the strict mode and pull is a special case of it: an
- * op written for push is correct when called directly, the reverse is false. So this
- * wrapper commits the operation to three things its author must honour, because no type
- * can check them:
- *
- * 1. **replayable** — delivery is at-least-once the day a broker sits underneath;
- * 2. **no reader for its return** — nobody receives what it hands back;
- * 3. **owner of its failures** — they reach a log, never the emitter.
- *
- * It is the identity at runtime. The scan reads the written name, which is the whole
- * mechanism: `binding.ts` sees `Fact<X>` and binds the parameter as a fact instead of
- * letting it fall through to "everything else — body".
- */
+/** What a subscriber accepts — and what it PROMISES about itself. */
 export type Fact<T> = T;
 
-/**
- * The container key of an emission — THE one place that spells the format.
- *
- * Its dual is right below, because the boot reads the fact back out of a handler's `deps`
- * to know which emissions to register. A key and the way to undo it belong together: the
- * pair that is split is the pair that drifts.
- */
+/** The container key of an emission — THE one place that spells the format. */
 export function emitKeyOf(fact: string): string {
   return `${lowerFirst(fact)}Emit`;
 }
@@ -69,17 +21,7 @@ export function factOfEmitKey(key: string): string | undefined {
     : undefined;
 }
 
-/**
- * What a set of handlers ANNOUNCES — `Emit<T>` read back out of their dependencies.
- *
- * Two readers, which is exactly why it is a function and not a line: the boot registers one
- * emission value per name, and the identity card publishes the same set. Spelled twice they
- * would drift the day an emission stops being a constructor dependency.
- *
- * The dual — what a handler ACCEPTS — is not here, because it is not read the same way: a
- * `Fact<T>` parameter is a fact about one operation, and `computeBindingPlan` has already
- * written it into the plan (`app.listensTo()`).
- */
+/** What a set of handlers ANNOUNCES — `Emit<T>` read back out of their dependencies. */
 export function factsAnnouncedBy(handlers: readonly { deps: readonly string[] }[]): string[] {
   return [...new Set(
     handlers

package/src/entry/facade.ts

@@ -0,0 +1,44 @@
+import { Call } from '../wire/call.js';
+import type { PartialInvocation } from '../wire/Invocation.js';
+import { RouteAddress } from '../wire/RouteAddress.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+
+type Operation = (...args: any[]) => unknown;
+
+/** Facade for a contract whose operation names are only known at discovery. */
+export function dynamicOperations(operation: (name: string) => Operation): Record<string, Operation> {
+  const isOperationName = (name: string | symbol): name is string =>
+    typeof name === 'string'
+    && name !== 'then'
+    && name !== 'toJSON'
+    && !Object.hasOwn(Object.prototype, name);
+
+  return new Proxy({}, {
+    get: (_target, name) => (isOperationName(name) ? operation(name) : undefined),
+    has: (_target, name) => isOperationName(name),
+    getOwnPropertyDescriptor: (_target, name) => (isOperationName(name)
+      ? { value: operation(name), writable: false, enumerable: true, configurable: true }
+      : undefined),
+  });
+}
+
+/** Turns facade method calls into canonical dispatches. */
+export function facadeOperations(
+  dispatcher: DispatchPort,
+  entity: string,
+  operationNames?: Iterable<string>,
+  surface?: string,
+): Record<string, Operation> {
+  const operation = (name: string): Operation => (invocation) => dispatcher.dispatch(new Call(
+    new RouteAddress({
+      entity,
+      operation: name,
+      ...(surface !== undefined ? { surface } : {}),
+    }),
+    invocation,
+  ));
+
+  return operationNames
+    ? Object.fromEntries([...operationNames].map((name) => [name, operation(name)]))
+    : dynamicOperations(operation);
+}

package/src/entry/transport.ts

@@ -0,0 +1,16 @@
+import { Call } from '../wire/call.js';
+import { RouteAddress } from '../wire/RouteAddress.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+import type { Transport } from '../wire/call.js';
+
+/** Adapts the historical transport signature to the canonical dispatch port. */
+export function createTransportEntry(dispatcher: DispatchPort, surface?: string): Transport {
+  return (legacy, invocation) => dispatcher.dispatch(new Call(
+    new RouteAddress({
+      entity: legacy.entity,
+      operation: legacy.op,
+      ...(surface !== undefined ? { surface } : {}),
+    }),
+    invocation,
+  ));
+}

package/src/frond-config.ts

@@ -5,45 +5,11 @@ import type { BindingPlan } from './wire/binding.js';
 
 // ── Types ────────────────────────────────────────
 
-/**
- * Per-operation override. Config takes precedence over conventions (isReadOp, facade lookup).
- *
- * Two families of keys, and they act at different depths:
- *
- * - **Resolution** (`kind`, `handler`, `method`) — intent and implementation, resolved
- *   once into core's `EffectiveOperation`; every local or remote door consumes it.
- * - **Projection** (`graphql`) — protocol vocabulary, read only by that adapter.
- * - **Contract** (`input`, `output`, `binding`) — what the op IS. Read by the façade,
- *   and this is the third producer of an {@link OperationContract}: a prefab DECLARES its
- *   ops (`Crud.__ops`), the scan DERIVES them from source, config STATES them outright.
- *   The façade cannot tell the three apart.
- *
- * Stating a contract here makes the scan optional rather than load-bearing. Two cases it
- * answers that nothing else does:
- * - a method inherited from an **installed** base class — the scan resolves nothing there
- *   (workspace-only heritage) and says nothing, so the op silently misses the façade;
- * - an operation inherited from a declaration unavailable to the project's type checker.
- *
- * Config wins over both other producers — it is the most explicit statement, made by
- * whoever assembles the app. Precedence: CLI > frond config > fougere config > scan >
- * conventions.
- */
+/** Per-operation override. */
 export interface OperationOverride {
-  /**
-   * Force operation kind, over the naming convention (`isReadOp`).
-   *
-   * The convention reads the NAME, which is a weak signal — an app naming its reads in
-   * domain terms (`ofBook`, `roots`, `bySlug`) matches no prefix and every one of them is
-   * published as a mutation and a POST. This is the only place that fixes it.
-   */
+  /** Force operation kind, over the naming convention (`isReadOp`). */
   kind?: 'query' | 'command';
-  /**
-   * The GraphQL root field this op answers to. Defaults to the method name.
-   *
-   * A GraphQL root is flat, so two handlers naming a method `ofBook` claim one field and
-   * the build is refused, naming both. Nothing is renamed for you: the root vocabulary is
-   * the app's, and a derived name would move the day a distant frond gained an entity.
-   */
+  /** The GraphQL root field this op answers to. */
   graphql?: string;
   /**
    * Handler class to delegate to (overrides the default `{Entity}Handler` lookup).
@@ -52,22 +18,12 @@ export interface OperationOverride {
   handler?: EntityConstructor;
   /** Method name on `handler` (defaults to the operation name). */
   method?: string;
-  /**
-   * CASL ability check (e.g. 'archive Post'). **Declared, not implemented** — no
-   * reader interprets it today, in any adapter. Kept as the named slot for the
-   * question rather than silently dropped, but do not rely on it: a config that
-   * states a policy is not enforced anywhere.
-   *
-   * Wiring it means adopting a rules engine, which is precisely what the design
-   * turns down: an identity-dependent right is judged INSIDE the operation
-   * (`publish` reads `post.authorId !== user.id`), and a door-dependent one is a
-   * surface. Neither needs a second vocabulary evaluated by a second engine.
-   */
+  /** CASL ability check (e.g. */
   policy?: string;
 
   // ── The contract itself — see the note above ──
 
-  /** What judges the input. The view carries its own mode (`partial()` → patch). */
+  /** 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
@@ -82,18 +38,7 @@ export interface OperationOverride {
 export interface FrondConfig {
   /** Class names exposed as the frond's public contract (all surfaces). */
   expose?: string[];
-  /**
-   * The entities this frond may read ACROSS sources, by name.
-   *
-   * It is not a permission checked after the fact: the list IS the environment a
-   * cross-source query runs in — a source holding none of these is never opened, so
-   * its tables do not exist in that connection. `facadeFor` excludes an entity with no
-   * door on purpose ("it would publish the auth tables to anyone who asks"), and a SQL
-   * door at app scope would hand them over; this is what keeps it shut.
-   *
-   * Declaring it is what makes `Reads` injectable here. A frond that declares none
-   * asks for none, and nothing is attached on its behalf.
-   */
+  /** The entities this frond may read ACROSS sources, by name. */
   reads?: string[];
   /** Per-surface entity lists. Overrides default deduction for each named surface. */
   surfaces?: Record<string, string[]>;
@@ -105,15 +50,7 @@ export interface FrondConfig {
 
 // ── Helper ───────────────────────────────────────
 
-/**
- * Define a frond configuration (typed identity helper).
- *
- * ```ts
- * // fronds/auth/frond.config.ts
- * import { defineFrond } from '@fougere/core'
- * export default defineFrond({ expose: ['User', 'AuthHandler'] })
- * ```
- */
+/** Define a frond configuration (typed identity helper). */
 export function defineFrond(config: FrondConfig): FrondConfig {
   return config;
 }

package/src/identity-keys.ts

@@ -1,14 +1,4 @@
-/**
- * Making keys and issuing grants — the half of identity that runs at a DEPLOYMENT.
- *
- * It sits on the Node entry because it is the CLI speaking: `fougere keys` generates a
- * pair, `fougere grant` binds a name to one, and both happen once, on a machine with a
- * filesystem. Neither is reachable from a request path, so nothing here is on any hot
- * path and `generateKeyPairSync` — the one gesture WebCrypto could not replace without
- * changing what a key IS — never has to leave `node:crypto`.
- *
- * The verifying half is elsewhere (`identity.ts`) because it runs per call, everywhere.
- */
+/** Making keys and issuing grants — the half of identity that runs at a DEPLOYMENT. */
 import { createPrivateKey, createPublicKey, generateKeyPairSync, sign } from 'node:crypto';
 import { b64url } from './crypto/encoding.js';
 
@@ -22,11 +12,8 @@ export function generateKeyPair(): { privateKey: string; publicKey: string } {
 }
 
 /**
- * Bind a name to a public key, signed by the root — the whole of what a receiver
- * needs to recognize a frond it has never seen.
- *
- * `ttlDays` bounds the damage of a leaked frond key without a revocation list:
- * re-issuing is a deployment, which is the same gesture that leaked it.
+ * Bind a name to a public key, signed by the root — the whole of what a receiver needs to
+ * recognize a frond it has never seen.
  */
 export function issueGrant(
   rootPrivateKey: string,